humidifier-reservoir 0.0.1 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
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>