humidifier-reservoir 0.0.1 → 0.1.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (32) hide show
  1. checksums.yaml +4 -4
  2. data/.rubocop.yml +6 -3
  3. data/.yardopts +7 -0
  4. data/README.md +1 -0
  5. data/Rakefile +1 -0
  6. data/docs/Humidifier/Reservoir/BaseMapper.html +457 -0
  7. data/docs/Humidifier/Reservoir/CLI.html +331 -0
  8. data/docs/Humidifier/Reservoir/Config.html +678 -0
  9. data/docs/Humidifier/Reservoir/Error.html +136 -0
  10. data/docs/Humidifier/Reservoir/Mapping.html +447 -0
  11. data/docs/Humidifier/Reservoir/Stack.html +688 -0
  12. data/docs/Humidifier/Reservoir.html +500 -0
  13. data/docs/Humidifier.html +117 -0
  14. data/docs/_index.html +207 -0
  15. data/docs/class_list.html +51 -0
  16. data/docs/css/common.css +1 -0
  17. data/docs/css/full_list.css +58 -0
  18. data/docs/css/style.css +492 -0
  19. data/docs/file.LICENSE.html +93 -0
  20. data/docs/file.README.html +251 -0
  21. data/docs/file_list.html +61 -0
  22. data/docs/frames.html +17 -0
  23. data/docs/index.html +251 -0
  24. data/docs/js/app.js +248 -0
  25. data/docs/js/full_list.js +216 -0
  26. data/docs/js/jquery.js +4 -0
  27. data/docs/method_list.html +315 -0
  28. data/docs/top-level-namespace.html +110 -0
  29. data/humidifier-reservoir.gemspec +11 -8
  30. data/lib/humidifier/reservoir/version.rb +1 -1
  31. data/lib/humidifier/reservoir.rb +1 -1
  32. metadata +84 -26
data/docs/file.README.html ADDED
@@ -0,0 +1,251 @@
1
+ <!DOCTYPE html>
2
+ <html>
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>
7
+ File: README
8
+
9
+ &mdash; Humidifier::Reservoir
10
+
11
+ </title>
12
+
13
+ <link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
14
+
15
+ <link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />
16
+
17
+ <script type="text/javascript" charset="utf-8">
18
+ pathId = "README";
19
+ relpath = '';
20
+ </script>
21
+
22
+
23
+ <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
24
+
25
+ <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
26
+
27
+
28
+ </head>
29
+ <body>
30
+ <div class="nav_wrap">
31
+ <iframe id="nav" src="file_list.html?1"></iframe>
32
+ <div id="resizer"></div>
33
+ </div>
34
+
35
+ <div id="main" tabindex="-1">
36
+ <div id="header">
37
+ <div id="menu">
38
+
39
+ <a href="_index.html">Index</a> &raquo;
40
+ <span class="title">File: README</span>
41
+
42
+ </div>
43
+
44
+ <div id="search">
45
+
46
+ <a class="full_list_link" id="class_list_link"
47
+ href="class_list.html">
48
+
49
+ <svg width="24" height="24">
50
+ <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
51
+ <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
52
+ <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
53
+ </svg>
54
+ </a>
55
+
56
+ </div>
57
+ <div class="clear"></div>
58
+ </div>
59
+
60
+ <div id="content"><div id='filecontents'>
61
+ <h1 id="label-Humidifier-3A-3AReservoir">Humidifier::Reservoir</h1>
62
+
63
+ <p><a href="https://travis-ci.org/localytics/humidifier-reservoir"><img
64
+ src="https://travis-ci.org/localytics/humidifier-reservoir.svg?branch=master"></a>
65
+ <a
66
+ href="https://coveralls.io/github/localytics/humidifier-reservoir?branch=master"><img
67
+ src="https://coveralls.io/repos/github/localytics/humidifier-reservoir/badge.svg?branch=master&t=GKTl7x"></a>
68
+ <a href="https://rubygems.org/gems/humidifier-reservoir"><img
69
+ src="https://img.shields.io/gem/v/humidifier-reservoir.svg"></a></p>
70
+
71
+ <p><code>Reservoir</code> is a plugin for the <a
72
+ href="https://github.com/localytics/humidifier">humidifier</a> gem that
73
+ allows you to specify CloudFormation resources in <a
74
+ href="http://yaml.org/">yaml</a> syntax, while still allowing you to take
75
+ advantage of the flexibility of <code>humidifier</code>.</p>
76
+
77
+ <h2 id="label-Installation">Installation</h2>
78
+
79
+ <p>Add this line to your application&#39;s Gemfile:</p>
80
+
81
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>humidifier-reservoir</span><span class='tstring_end'>&#39;</span></span>
82
+ </code></pre>
83
+
84
+ <p>And then execute:</p>
85
+
86
+ <pre class="code ruby"><code class="ruby">$ bundle</code></pre>
87
+
88
+ <p>Or install it yourself as:</p>
89
+
90
+ <pre class="code ruby"><code class="ruby">$ gem install humidifier-reservoir</code></pre>
91
+
92
+ <h2 id="label-Usage">Usage</h2>
93
+
94
+ <h3 id="label-CLI">CLI</h3>
95
+
96
+ <p><code>Reservoir</code> is meant to be run as a CLI tool. First, build a
97
+ ruby script that executes the <code>Humidifier::Reservoir::CLI</code>
98
+ class, like so:</p>
99
+
100
+ <pre class="code ruby"><code class="ruby"><span class='comment'>#!/usr/bin/env ruby
101
+ </span><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>humidifier/reservoir</span><span class='tstring_end'>&#39;</span></span>
102
+
103
+ <span class='const'><span class='object_link'><a href="Humidifier.html" title="Humidifier (module)">Humidifier</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Humidifier/Reservoir.html" title="Humidifier::Reservoir (module)">Reservoir</a></span></span><span class='period'>.</span><span class='id identifier rubyid_configure'><span class='object_link'><a href="Humidifier/Reservoir.html#configure-class_method" title="Humidifier::Reservoir.configure (method)">configure</a></span></span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_config'>config</span><span class='op'>|</span>
104
+ <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_stack_path'>stack_path</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>stacks</span><span class='tstring_end'>&#39;</span></span>
105
+ <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_stack_prefix'>stack_prefix</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>reservoir-</span><span class='tstring_end'>&#39;</span></span>
106
+
107
+ <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_map'>map</span> <span class='symbol'>:users</span><span class='comma'>,</span> <span class='label'>to:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>AWS::IAM::User</span><span class='tstring_end'>&#39;</span></span>
108
+ <span class='kw'>end</span>
109
+
110
+ <span class='const'><span class='object_link'><a href="Humidifier.html" title="Humidifier (module)">Humidifier</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Humidifier/Reservoir.html" title="Humidifier::Reservoir (module)">Reservoir</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Humidifier/Reservoir/CLI.html" title="Humidifier::Reservoir::CLI (class)">CLI</a></span></span><span class='period'>.</span><span class='id identifier rubyid_start'>start</span><span class='lparen'>(</span><span class='const'>ARGV</span><span class='rparen'>)</span>
111
+ </code></pre>
112
+
113
+ <p>This configuration specifies that the directories containing the
114
+ specifications for each stack are contained under a “stacks” directory, the
115
+ stack names should be prefixed with a “reservoir-” signifier, and that
116
+ <code>users.yml</code> files should map to IAM users.</p>
117
+
118
+ <h3 id="label-Resource+files">Resource files</h3>
119
+
120
+ <p>Inside of the above-configured <code>stacks</code> directory, create a
121
+ subdirectory for each CloudFormation stack that you wish to manage in code.
122
+ With the above configuration, we can create YAML files in the form of
123
+ <code>users.yml</code> for each stack, which will specify IAM users to
124
+ create. The file format looks like the below:</p>
125
+
126
+ <pre class="code ruby"><code class="ruby">EngUser:
127
+ path: /reservoir/
128
+ user_name: EngUser
129
+ groups:
130
+ - Engineering
131
+ - Testing
132
+ - Deployment
133
+
134
+ AdminUser:
135
+ path: /reservoir/
136
+ user_name: AdminUser
137
+ groups:
138
+ - Management
139
+ - Administration</code></pre>
140
+
141
+ <p>The top-level keys are the logical resource names that will be displayed in
142
+ the CloudFormation screen. They point to a map of key/value pairs that will
143
+ be passed on to <code>humidifier</code>. Any <code>humidifier</code> (and
144
+ therefore any CloudFormation) attribute may be specified. For more
145
+ information on CloudFormation templates and which attributes may be
146
+ specified, see both the <a
147
+ href="http://localytics.github.io/humidifier">humidifier docs</a> and the
148
+ <a
149
+ href="http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-guide.html">CloudFormation
150
+ docs</a>.</p>
151
+
152
+ <h3 id="label-Mappers">Mappers</h3>
153
+
154
+ <p>Oftentimes, specifying these attributes can become repetitive, e.g., each
155
+ user should automatically receive the same “path” attribute. Other times,
156
+ you may want custom logic to execute depending on which AWS environment
157
+ you&#39;re running in. Finally, you may want to reference resources in the
158
+ same or other stacks.</p>
159
+
160
+ <p><code>Reservoir</code>&#39;s solution for this is to allow customized
161
+ “mapper” classes to take the user-provided attributes and transform them
162
+ into the attributes that CloudFormation expects. Consider the following
163
+ example for mapping a user:</p>
164
+
165
+ <pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>UserMapper</span> <span class='op'>&lt;</span> <span class='const'><span class='object_link'><a href="Humidifier.html" title="Humidifier (module)">Humidifier</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Humidifier/Reservoir.html" title="Humidifier::Reservoir (module)">Reservoir</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Humidifier/Reservoir/BaseMapper.html" title="Humidifier::Reservoir::BaseMapper (class)">BaseMapper</a></span></span>
166
+ <span class='const'>GROUPS</span> <span class='op'>=</span> <span class='lbrace'>{</span>
167
+ <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>eng</span><span class='tstring_end'>&#39;</span></span> <span class='op'>=&gt;</span> <span class='qwords_beg'>%w[</span><span class='tstring_content'>Engineering</span><span class='words_sep'> </span><span class='tstring_content'>Testing</span><span class='words_sep'> </span><span class='tstring_content'>Deployment</span><span class='words_sep'>]</span><span class='comma'>,</span>
168
+ <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>admin</span><span class='tstring_end'>&#39;</span></span> <span class='op'>=&gt;</span> <span class='qwords_beg'>%w[</span><span class='tstring_content'>Management</span><span class='words_sep'> </span><span class='tstring_content'>Administration</span><span class='words_sep'>]</span>
169
+ <span class='rbrace'>}</span>
170
+
171
+ <span class='id identifier rubyid_defaults'>defaults</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_logical_name'>logical_name</span><span class='op'>|</span>
172
+ <span class='lbrace'>{</span> <span class='label'>path:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>/reservoir/</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='label'>user_name:</span> <span class='id identifier rubyid_logical_name'>logical_name</span> <span class='rbrace'>}</span>
173
+ <span class='kw'>end</span>
174
+
175
+ <span class='id identifier rubyid_attribute'>attribute</span> <span class='symbol'>:group</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_group'>group</span><span class='op'>|</span>
176
+ <span class='id identifier rubyid_groups'>groups</span> <span class='op'>=</span> <span class='const'>GROUPS</span><span class='lbracket'>[</span><span class='id identifier rubyid_group'>group</span><span class='rbracket'>]</span>
177
+ <span class='id identifier rubyid_groups'>groups</span><span class='period'>.</span><span class='id identifier rubyid_any?'>any?</span> <span class='op'>?</span> <span class='lbrace'>{</span> <span class='label'>groups:</span> <span class='const'>GROUPS</span><span class='lbracket'>[</span><span class='id identifier rubyid_group'>group</span><span class='rbracket'>]</span> <span class='rbrace'>}</span> <span class='op'>:</span> <span class='lbrace'>{</span><span class='rbrace'>}</span>
178
+ <span class='kw'>end</span>
179
+ <span class='kw'>end</span>
180
+
181
+ <span class='const'><span class='object_link'><a href="Humidifier.html" title="Humidifier (module)">Humidifier</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Humidifier/Reservoir.html" title="Humidifier::Reservoir (module)">Reservoir</a></span></span><span class='period'>.</span><span class='id identifier rubyid_configure'><span class='object_link'><a href="Humidifier/Reservoir.html#configure-class_method" title="Humidifier::Reservoir.configure (method)">configure</a></span></span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_config'>config</span><span class='op'>|</span>
182
+ <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_map'>map</span> <span class='symbol'>:users</span><span class='comma'>,</span> <span class='label'>to:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>AWS::IAM::User</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='label'>using:</span> <span class='const'>UserMapper</span>
183
+ <span class='kw'>end</span>
184
+ </code></pre>
185
+
186
+ <p>This means that by default, all entries in the <code>users.yml</code> files
187
+ will get a <code>/reservoir/</code> path, the <code>user_name</code>
188
+ attribute will be set based on the logical name that was provided for the
189
+ resource, and you can additionally specify a <code>group</code> attribute,
190
+ even though it is not native to CloudFormation. With this
191
+ <code>group</code> attribute, it will actually map to the
192
+ <code>groups</code> attribute that CloudFormation expects.</p>
193
+
194
+ <p>With this new mapper in place, we can simplify our YAML file to:</p>
195
+
196
+ <pre class="code ruby"><code class="ruby">EngUser:
197
+ group: eng
198
+
199
+ AdminUser:
200
+ group: admin</code></pre>
201
+
202
+ <h3 id="label-Deployment">Deployment</h3>
203
+
204
+ <p>Now that you&#39;ve configured your CLI, your resources, and your mappers,
205
+ you can use the CLI to display, validate, and deploy your infrastructure to
206
+ CloudFormation. Run your script without any arguments to get the help
207
+ message and explanations for each command.</p>
208
+
209
+ <p>Each command has an <code>--aws-profile</code> (or <code>-p</code>) option
210
+ for specifying which profile to authenticate against when querying AWS. You
211
+ should ensure that this profile has the correct permissions for creating
212
+ whatever resources are going to part of your stack. You can also rely on
213
+ the <code>AWS_*</code> environment variables, or the EC2 instance profile
214
+ if you&#39;re deploying from an instance. For more information, see the <a
215
+ href="http://docs.aws.amazon.com/sdkforruby/api/">AWS docs</a> under the
216
+ “Configuration” section.</p>
217
+
218
+ <h2 id="label-Development">Development</h2>
219
+
220
+ <p>After checking out the repo, run <code>bin/setup</code> to install
221
+ dependencies. Then, run <code>rake test</code> to run the tests. You can
222
+ also run <code>bin/console</code> for an interactive prompt that will allow
223
+ you to experiment.</p>
224
+
225
+ <p>To install this gem onto your local machine, run <code>bundle exec rake
226
+ install</code>. To release a new version, update the version number in
227
+ <code>version.rb</code>, and then run <code>bundle exec rake
228
+ release</code>, which will create a git tag for the version, push git
229
+ commits and tags, and push the <code>.gem</code> file to <a
230
+ href="https://rubygems.org">rubygems.org</a>.</p>
231
+
232
+ <h2 id="label-Contributing">Contributing</h2>
233
+
234
+ <p>Bug reports and pull requests are welcome on GitHub at <a
235
+ href="https://github.com/localytics/humidifier-reservoir">github.com/localytics/humidifier-reservoir</a>.</p>
236
+
237
+ <h2 id="label-License">License</h2>
238
+
239
+ <p>The gem is available as open source under the terms of the <a
240
+ href="http://opensource.org/licenses/MIT">MIT License</a>.</p>
241
+ </div></div>
242
+
243
+ <div id="footer">
244
+ Generated on Sun Oct 1 09:25:22 2017 by
245
+ <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
246
+ 0.9.9 (ruby-2.4.1).
247
+ </div>
248
+
249
+ </div>
250
+ </body>
251
+ </html>
data/docs/file_list.html ADDED
@@ -0,0 +1,61 @@
1
+ <!DOCTYPE html>
2
+ <html>
3
+ <head>
4
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
5
+ <meta charset="utf-8" />
6
+
7
+ <link rel="stylesheet" href="css/full_list.css" type="text/css" media="screen" charset="utf-8" />
8
+
9
+ <link rel="stylesheet" href="css/common.css" type="text/css" media="screen" charset="utf-8" />
10
+
11
+
12
+
13
+ <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
14
+
15
+ <script type="text/javascript" charset="utf-8" src="js/full_list.js"></script>
16
+
17
+
18
+ <title>File List</title>
19
+ <base id="base_target" target="_parent" />
20
+ </head>
21
+ <body>
22
+ <div id="content">
23
+ <div class="fixed_header">
24
+ <h1 id="full_list_header">File List</h1>
25
+ <div id="full_list_nav">
26
+
27
+ <span><a target="_self" href="class_list.html">
28
+ Classes
29
+ </a></span>
30
+
31
+ <span><a target="_self" href="method_list.html">
32
+ Methods
33
+ </a></span>
34
+
35
+ <span><a target="_self" href="file_list.html">
36
+ Files
37
+ </a></span>
38
+
39
+ </div>
40
+
41
+ <div id="search">Search: <input type="text" /></div>
42
+ </div>
43
+
44
+ <ul id="full_list" class="file">
45
+
46
+
47
+ <li id="object_README" class="odd">
48
+ <div class="item"><span class="object_link"><a href="index.html" title="README">README</a></span></div>
49
+ </li>
50
+
51
+
52
+ <li id="object_LICENSE" class="even">
53
+ <div class="item"><span class="object_link"><a href="file.LICENSE.html" title="LICENSE">LICENSE</a></span></div>
54
+ </li>
55
+
56
+
57
+
58
+ </ul>
59
+ </div>
60
+ </body>
61
+ </html>
data/docs/frames.html ADDED
@@ -0,0 +1,17 @@
1
+ <!DOCTYPE html>
2
+ <html>
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <title>Humidifier::Reservoir</title>
6
+ </head>
7
+ <script type="text/javascript" charset="utf-8">
8
+ var match = unescape(window.location.hash).match(/^#!(.+)/);
9
+ var name = match ? match[1] : 'index.html';
10
+ name = name.replace(/^(\w+):\/\//, '').replace(/^\/\//, '');
11
+ window.top.location = name;
12
+ </script>
13
+ <noscript>
14
+ <h1>Oops!</h1>
15
+ <h2>YARD requires JavaScript!</h2>
16
+ </noscript>
17
+ </html>
data/docs/index.html ADDED
@@ -0,0 +1,251 @@
1
+ <!DOCTYPE html>
2
+ <html>
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>
7
+ File: README
8
+
9
+ &mdash; Humidifier::Reservoir
10
+
11
+ </title>
12
+
13
+ <link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
14
+
15
+ <link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />
16
+
17
+ <script type="text/javascript" charset="utf-8">
18
+ pathId = "README";
19
+ relpath = '';
20
+ </script>
21
+
22
+
23
+ <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
24
+
25
+ <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
26
+
27
+
28
+ </head>
29
+ <body>
30
+ <div class="nav_wrap">
31
+ <iframe id="nav" src="class_list.html?1"></iframe>
32
+ <div id="resizer"></div>
33
+ </div>
34
+
35
+ <div id="main" tabindex="-1">
36
+ <div id="header">
37
+ <div id="menu">
38
+
39
+ <a href="_index.html">Index</a> &raquo;
40
+ <span class="title">File: README</span>
41
+
42
+ </div>
43
+
44
+ <div id="search">
45
+
46
+ <a class="full_list_link" id="class_list_link"
47
+ href="class_list.html">
48
+
49
+ <svg width="24" height="24">
50
+ <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
51
+ <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
52
+ <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
53
+ </svg>
54
+ </a>
55
+
56
+ </div>
57
+ <div class="clear"></div>
58
+ </div>
59
+
60
+ <div id="content"><div id='filecontents'>
61
+ <h1 id="label-Humidifier-3A-3AReservoir">Humidifier::Reservoir</h1>
62
+
63
+ <p><a href="https://travis-ci.org/localytics/humidifier-reservoir"><img
64
+ src="https://travis-ci.org/localytics/humidifier-reservoir.svg?branch=master"></a>
65
+ <a
66
+ href="https://coveralls.io/github/localytics/humidifier-reservoir?branch=master"><img
67
+ src="https://coveralls.io/repos/github/localytics/humidifier-reservoir/badge.svg?branch=master&t=GKTl7x"></a>
68
+ <a href="https://rubygems.org/gems/humidifier-reservoir"><img
69
+ src="https://img.shields.io/gem/v/humidifier-reservoir.svg"></a></p>
70
+
71
+ <p><code>Reservoir</code> is a plugin for the <a
72
+ href="https://github.com/localytics/humidifier">humidifier</a> gem that
73
+ allows you to specify CloudFormation resources in <a
74
+ href="http://yaml.org/">yaml</a> syntax, while still allowing you to take
75
+ advantage of the flexibility of <code>humidifier</code>.</p>
76
+
77
+ <h2 id="label-Installation">Installation</h2>
78
+
79
+ <p>Add this line to your application&#39;s Gemfile:</p>
80
+
81
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>humidifier-reservoir</span><span class='tstring_end'>&#39;</span></span>
82
+ </code></pre>
83
+
84
+ <p>And then execute:</p>
85
+
86
+ <pre class="code ruby"><code class="ruby">$ bundle</code></pre>
87
+
88
+ <p>Or install it yourself as:</p>
89
+
90
+ <pre class="code ruby"><code class="ruby">$ gem install humidifier-reservoir</code></pre>
91
+
92
+ <h2 id="label-Usage">Usage</h2>
93
+
94
+ <h3 id="label-CLI">CLI</h3>
95
+
96
+ <p><code>Reservoir</code> is meant to be run as a CLI tool. First, build a
97
+ ruby script that executes the <code>Humidifier::Reservoir::CLI</code>
98
+ class, like so:</p>
99
+
100
+ <pre class="code ruby"><code class="ruby"><span class='comment'>#!/usr/bin/env ruby
101
+ </span><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>humidifier/reservoir</span><span class='tstring_end'>&#39;</span></span>
102
+
103
+ <span class='const'><span class='object_link'><a href="Humidifier.html" title="Humidifier (module)">Humidifier</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Humidifier/Reservoir.html" title="Humidifier::Reservoir (module)">Reservoir</a></span></span><span class='period'>.</span><span class='id identifier rubyid_configure'><span class='object_link'><a href="Humidifier/Reservoir.html#configure-class_method" title="Humidifier::Reservoir.configure (method)">configure</a></span></span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_config'>config</span><span class='op'>|</span>
104
+ <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_stack_path'>stack_path</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>stacks</span><span class='tstring_end'>&#39;</span></span>
105
+ <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_stack_prefix'>stack_prefix</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>reservoir-</span><span class='tstring_end'>&#39;</span></span>
106
+
107
+ <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_map'>map</span> <span class='symbol'>:users</span><span class='comma'>,</span> <span class='label'>to:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>AWS::IAM::User</span><span class='tstring_end'>&#39;</span></span>
108
+ <span class='kw'>end</span>
109
+
110
+ <span class='const'><span class='object_link'><a href="Humidifier.html" title="Humidifier (module)">Humidifier</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Humidifier/Reservoir.html" title="Humidifier::Reservoir (module)">Reservoir</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Humidifier/Reservoir/CLI.html" title="Humidifier::Reservoir::CLI (class)">CLI</a></span></span><span class='period'>.</span><span class='id identifier rubyid_start'>start</span><span class='lparen'>(</span><span class='const'>ARGV</span><span class='rparen'>)</span>
111
+ </code></pre>
112
+
113
+ <p>This configuration specifies that the directories containing the
114
+ specifications for each stack are contained under a “stacks” directory, the
115
+ stack names should be prefixed with a “reservoir-” signifier, and that
116
+ <code>users.yml</code> files should map to IAM users.</p>
117
+
118
+ <h3 id="label-Resource+files">Resource files</h3>
119
+
120
+ <p>Inside of the above-configured <code>stacks</code> directory, create a
121
+ subdirectory for each CloudFormation stack that you wish to manage in code.
122
+ With the above configuration, we can create YAML files in the form of
123
+ <code>users.yml</code> for each stack, which will specify IAM users to
124
+ create. The file format looks like the below:</p>
125
+
126
+ <pre class="code ruby"><code class="ruby">EngUser:
127
+ path: /reservoir/
128
+ user_name: EngUser
129
+ groups:
130
+ - Engineering
131
+ - Testing
132
+ - Deployment
133
+
134
+ AdminUser:
135
+ path: /reservoir/
136
+ user_name: AdminUser
137
+ groups:
138
+ - Management
139
+ - Administration</code></pre>
140
+
141
+ <p>The top-level keys are the logical resource names that will be displayed in
142
+ the CloudFormation screen. They point to a map of key/value pairs that will
143
+ be passed on to <code>humidifier</code>. Any <code>humidifier</code> (and
144
+ therefore any CloudFormation) attribute may be specified. For more
145
+ information on CloudFormation templates and which attributes may be
146
+ specified, see both the <a
147
+ href="http://localytics.github.io/humidifier">humidifier docs</a> and the
148
+ <a
149
+ href="http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-guide.html">CloudFormation
150
+ docs</a>.</p>
151
+
152
+ <h3 id="label-Mappers">Mappers</h3>
153
+
154
+ <p>Oftentimes, specifying these attributes can become repetitive, e.g., each
155
+ user should automatically receive the same “path” attribute. Other times,
156
+ you may want custom logic to execute depending on which AWS environment
157
+ you&#39;re running in. Finally, you may want to reference resources in the
158
+ same or other stacks.</p>
159
+
160
+ <p><code>Reservoir</code>&#39;s solution for this is to allow customized
161
+ “mapper” classes to take the user-provided attributes and transform them
162
+ into the attributes that CloudFormation expects. Consider the following
163
+ example for mapping a user:</p>
164
+
165
+ <pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>UserMapper</span> <span class='op'>&lt;</span> <span class='const'><span class='object_link'><a href="Humidifier.html" title="Humidifier (module)">Humidifier</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Humidifier/Reservoir.html" title="Humidifier::Reservoir (module)">Reservoir</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Humidifier/Reservoir/BaseMapper.html" title="Humidifier::Reservoir::BaseMapper (class)">BaseMapper</a></span></span>
166
+ <span class='const'>GROUPS</span> <span class='op'>=</span> <span class='lbrace'>{</span>
167
+ <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>eng</span><span class='tstring_end'>&#39;</span></span> <span class='op'>=&gt;</span> <span class='qwords_beg'>%w[</span><span class='tstring_content'>Engineering</span><span class='words_sep'> </span><span class='tstring_content'>Testing</span><span class='words_sep'> </span><span class='tstring_content'>Deployment</span><span class='words_sep'>]</span><span class='comma'>,</span>
168
+ <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>admin</span><span class='tstring_end'>&#39;</span></span> <span class='op'>=&gt;</span> <span class='qwords_beg'>%w[</span><span class='tstring_content'>Management</span><span class='words_sep'> </span><span class='tstring_content'>Administration</span><span class='words_sep'>]</span>
169
+ <span class='rbrace'>}</span>
170
+
171
+ <span class='id identifier rubyid_defaults'>defaults</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_logical_name'>logical_name</span><span class='op'>|</span>
172
+ <span class='lbrace'>{</span> <span class='label'>path:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>/reservoir/</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='label'>user_name:</span> <span class='id identifier rubyid_logical_name'>logical_name</span> <span class='rbrace'>}</span>
173
+ <span class='kw'>end</span>
174
+
175
+ <span class='id identifier rubyid_attribute'>attribute</span> <span class='symbol'>:group</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_group'>group</span><span class='op'>|</span>
176
+ <span class='id identifier rubyid_groups'>groups</span> <span class='op'>=</span> <span class='const'>GROUPS</span><span class='lbracket'>[</span><span class='id identifier rubyid_group'>group</span><span class='rbracket'>]</span>
177
+ <span class='id identifier rubyid_groups'>groups</span><span class='period'>.</span><span class='id identifier rubyid_any?'>any?</span> <span class='op'>?</span> <span class='lbrace'>{</span> <span class='label'>groups:</span> <span class='const'>GROUPS</span><span class='lbracket'>[</span><span class='id identifier rubyid_group'>group</span><span class='rbracket'>]</span> <span class='rbrace'>}</span> <span class='op'>:</span> <span class='lbrace'>{</span><span class='rbrace'>}</span>
178
+ <span class='kw'>end</span>
179
+ <span class='kw'>end</span>
180
+
181
+ <span class='const'><span class='object_link'><a href="Humidifier.html" title="Humidifier (module)">Humidifier</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Humidifier/Reservoir.html" title="Humidifier::Reservoir (module)">Reservoir</a></span></span><span class='period'>.</span><span class='id identifier rubyid_configure'><span class='object_link'><a href="Humidifier/Reservoir.html#configure-class_method" title="Humidifier::Reservoir.configure (method)">configure</a></span></span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_config'>config</span><span class='op'>|</span>
182
+ <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_map'>map</span> <span class='symbol'>:users</span><span class='comma'>,</span> <span class='label'>to:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>AWS::IAM::User</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='label'>using:</span> <span class='const'>UserMapper</span>
183
+ <span class='kw'>end</span>
184
+ </code></pre>
185
+
186
+ <p>This means that by default, all entries in the <code>users.yml</code> files
187
+ will get a <code>/reservoir/</code> path, the <code>user_name</code>
188
+ attribute will be set based on the logical name that was provided for the
189
+ resource, and you can additionally specify a <code>group</code> attribute,
190
+ even though it is not native to CloudFormation. With this
191
+ <code>group</code> attribute, it will actually map to the
192
+ <code>groups</code> attribute that CloudFormation expects.</p>
193
+
194
+ <p>With this new mapper in place, we can simplify our YAML file to:</p>
195
+
196
+ <pre class="code ruby"><code class="ruby">EngUser:
197
+ group: eng
198
+
199
+ AdminUser:
200
+ group: admin</code></pre>
201
+
202
+ <h3 id="label-Deployment">Deployment</h3>
203
+
204
+ <p>Now that you&#39;ve configured your CLI, your resources, and your mappers,
205
+ you can use the CLI to display, validate, and deploy your infrastructure to
206
+ CloudFormation. Run your script without any arguments to get the help
207
+ message and explanations for each command.</p>
208
+
209
+ <p>Each command has an <code>--aws-profile</code> (or <code>-p</code>) option
210
+ for specifying which profile to authenticate against when querying AWS. You
211
+ should ensure that this profile has the correct permissions for creating
212
+ whatever resources are going to part of your stack. You can also rely on
213
+ the <code>AWS_*</code> environment variables, or the EC2 instance profile
214
+ if you&#39;re deploying from an instance. For more information, see the <a
215
+ href="http://docs.aws.amazon.com/sdkforruby/api/">AWS docs</a> under the
216
+ “Configuration” section.</p>
217
+
218
+ <h2 id="label-Development">Development</h2>
219
+
220
+ <p>After checking out the repo, run <code>bin/setup</code> to install
221
+ dependencies. Then, run <code>rake test</code> to run the tests. You can
222
+ also run <code>bin/console</code> for an interactive prompt that will allow
223
+ you to experiment.</p>
224
+
225
+ <p>To install this gem onto your local machine, run <code>bundle exec rake
226
+ install</code>. To release a new version, update the version number in
227
+ <code>version.rb</code>, and then run <code>bundle exec rake
228
+ release</code>, which will create a git tag for the version, push git
229
+ commits and tags, and push the <code>.gem</code> file to <a
230
+ href="https://rubygems.org">rubygems.org</a>.</p>
231
+
232
+ <h2 id="label-Contributing">Contributing</h2>
233
+
234
+ <p>Bug reports and pull requests are welcome on GitHub at <a
235
+ href="https://github.com/localytics/humidifier-reservoir">github.com/localytics/humidifier-reservoir</a>.</p>
236
+
237
+ <h2 id="label-License">License</h2>
238
+
239
+ <p>The gem is available as open source under the terms of the <a
240
+ href="http://opensource.org/licenses/MIT">MIT License</a>.</p>
241
+ </div></div>
242
+
243
+ <div id="footer">
244
+ Generated on Sun Oct 1 09:25:22 2017 by
245
+ <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
246
+ 0.9.9 (ruby-2.4.1).
247
+ </div>
248
+
249
+ </div>
250
+ </body>
251
+ </html>