aws-cft-tools 0.1.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (68) hide show
  1. checksums.yaml +7 -0
  2. data/.editorconfig +10 -0
  3. data/.gitignore +52 -0
  4. data/.rspec +2 -0
  5. data/.rubocop.yml +19 -0
  6. data/.travis.yml +5 -0
  7. data/.yardopts +1 -0
  8. data/BEST-PRACTICES.md +136 -0
  9. data/CONTRIBUTING.md +38 -0
  10. data/Gemfile +8 -0
  11. data/LICENSE +15 -0
  12. data/README.md +118 -0
  13. data/Rakefile +17 -0
  14. data/USAGE.adoc +404 -0
  15. data/aws-cft-tools.gemspec +53 -0
  16. data/bin/console +15 -0
  17. data/bin/setup +8 -0
  18. data/code.json +24 -0
  19. data/exe/aws-cft +176 -0
  20. data/lib/aws-cft-tools.rb +3 -0
  21. data/lib/aws_cft_tools.rb +31 -0
  22. data/lib/aws_cft_tools/aws_enumerator.rb +55 -0
  23. data/lib/aws_cft_tools/change.rb +66 -0
  24. data/lib/aws_cft_tools/client.rb +84 -0
  25. data/lib/aws_cft_tools/client/base.rb +40 -0
  26. data/lib/aws_cft_tools/client/cft.rb +93 -0
  27. data/lib/aws_cft_tools/client/cft/changeset_management.rb +109 -0
  28. data/lib/aws_cft_tools/client/cft/stack_management.rb +85 -0
  29. data/lib/aws_cft_tools/client/ec2.rb +136 -0
  30. data/lib/aws_cft_tools/client/templates.rb +84 -0
  31. data/lib/aws_cft_tools/deletion_change.rb +43 -0
  32. data/lib/aws_cft_tools/dependency_tree.rb +109 -0
  33. data/lib/aws_cft_tools/dependency_tree/nodes.rb +71 -0
  34. data/lib/aws_cft_tools/dependency_tree/variables.rb +37 -0
  35. data/lib/aws_cft_tools/errors.rb +25 -0
  36. data/lib/aws_cft_tools/runbook.rb +166 -0
  37. data/lib/aws_cft_tools/runbook/report.rb +30 -0
  38. data/lib/aws_cft_tools/runbooks.rb +16 -0
  39. data/lib/aws_cft_tools/runbooks/common/changesets.rb +30 -0
  40. data/lib/aws_cft_tools/runbooks/common/templates.rb +38 -0
  41. data/lib/aws_cft_tools/runbooks/deploy.rb +107 -0
  42. data/lib/aws_cft_tools/runbooks/deploy/reporting.rb +50 -0
  43. data/lib/aws_cft_tools/runbooks/deploy/stacks.rb +109 -0
  44. data/lib/aws_cft_tools/runbooks/deploy/templates.rb +37 -0
  45. data/lib/aws_cft_tools/runbooks/deploy/threading.rb +37 -0
  46. data/lib/aws_cft_tools/runbooks/diff.rb +28 -0
  47. data/lib/aws_cft_tools/runbooks/diff/context.rb +86 -0
  48. data/lib/aws_cft_tools/runbooks/diff/context/reporting.rb +87 -0
  49. data/lib/aws_cft_tools/runbooks/hosts.rb +43 -0
  50. data/lib/aws_cft_tools/runbooks/images.rb +43 -0
  51. data/lib/aws_cft_tools/runbooks/init.rb +86 -0
  52. data/lib/aws_cft_tools/runbooks/retract.rb +69 -0
  53. data/lib/aws_cft_tools/runbooks/retract/templates.rb +44 -0
  54. data/lib/aws_cft_tools/runbooks/stacks.rb +43 -0
  55. data/lib/aws_cft_tools/stack.rb +83 -0
  56. data/lib/aws_cft_tools/template.rb +177 -0
  57. data/lib/aws_cft_tools/template/dsl_context.rb +14 -0
  58. data/lib/aws_cft_tools/template/file_system.rb +62 -0
  59. data/lib/aws_cft_tools/template/metadata.rb +144 -0
  60. data/lib/aws_cft_tools/template/properties.rb +129 -0
  61. data/lib/aws_cft_tools/template_set.rb +120 -0
  62. data/lib/aws_cft_tools/template_set/array_methods.rb +63 -0
  63. data/lib/aws_cft_tools/template_set/closure.rb +77 -0
  64. data/lib/aws_cft_tools/template_set/dependencies.rb +55 -0
  65. data/lib/aws_cft_tools/template_set/each_slice_state.rb +58 -0
  66. data/lib/aws_cft_tools/version.rb +8 -0
  67. data/rubycritic.reek +3 -0
  68. metadata +321 -0
@@ -0,0 +1,404 @@
1
+ # Using `aws-cft`
2
+
3
+ ## Deploy
4
+
5
+ ```
6
+ aws-cft deploy [OPTIONS]
7
+ ```
8
+
9
+ Ensure stacks in AWS are up to date with the templates in the repository. This will create any missing
10
+ stacks.
11
+
12
+ ### Options
13
+
14
+ `-e`, `--environment ENVIRONMENT` ::
15
+ set environment on which to operate
16
+
17
+ `-r`, `--role ROLE` ::
18
+ set role filter
19
+
20
+ `-j`, `--jobs INTEGER` ::
21
+ maximum number of parallel stacks to build simultaneously (default: 1)
22
+
23
+ `-c`, `--[no-]check` ::
24
+ only do non-destructive operations to check validity of request
25
+
26
+ `-f`, `--file FILE` ::
27
+ set configuration file relative to the project root (default: ".aws_cft")
28
+
29
+ `-n`, `--[no-]noop` ::
30
+ only do operations that do not require modifying AWS
31
+
32
+ `-p`, `--profile PROFILE` ::
33
+ set profile (default: "default")
34
+
35
+ `-R`, `--region REGION` ::
36
+ set AWS region (default: "us-east-1")
37
+
38
+ `-t`, `--root DIRECTORY` ::
39
+ set infrastructure project root
40
+
41
+ `-T`, `--tag NAME:VALUE` ::
42
+ require a tag have the given value (may be given more than once)
43
+
44
+ `-v`, `--[no-]verbose` ::
45
+ verbose narration of actions
46
+
47
+ `--version` ::
48
+ Show version
49
+
50
+ `-h`, `--help` ::
51
+ print help
52
+
53
+ ### Notes
54
+
55
+ Stacks are built or updated in dependency order. If a template imports the outputs of another template,
56
+ then the importing template will not be updated or created until after the exporting template is
57
+ updated or created.
58
+
59
+ When restricting the deployed templates to those with a particular role, the list of selected templates
60
+ is expanded to include any templates on which the set of selected templates depend. For example, if
61
+ template A has the role we wish to deploy, but it depends on template B, and template B depends on
62
+ template C, then templates A, B, and C will be selected for updating or creating.
63
+
64
+ **N.B.:** Using the `-j` option to deploy templates in parallel can cause the script to run into request
65
+ limits in AWS. If AWS does refuse a request because of throttling, the script will exit with an error.
66
+ Try running it again with a lower number of simultaneous jobs.
67
+
68
+ **N.B.:** If you interrupt the script while it is deploying templates (without the `-c` or `-n` options),
69
+ then none of the changes will be rolled back. Any stacks in-progress will continue to completion since
70
+ the script only watches for completion once the build has been triggered.
71
+
72
+ **N.B.** If you interrupt the script while it is checking on changesets (the `-c` option), then none of the
73
+ changesets that are in-progress will be removed. You may have some "orphan" changesets to clean up by hand.
74
+
75
+ #### Recommended Deployment Strategy
76
+
77
+ When preparing to deploy new or updated templates, you can get an idea of what will happen by running
78
+ the `deploy` command in the following sequence (replace `[OPTIONS]` with the options you need to manage
79
+ select the right profile, environment, and/or roles):
80
+
81
+ `aws-cft deploy [OPTIONS] -v -n` ::
82
+ Review the proposed list of templates and make sure they are being updated or created as expected.
83
+
84
+ `aws-cft deploy [OPTIONS] -v -c` ::
85
+ Review the proposed list of changes for each stack and make sure there are no surprise replacements or deletions.
86
+
87
+ `aws-cft deploy [OPTIONS] -v` ::
88
+ Finally, execute the deployment and make the changes to the templates.
89
+
90
+ ### Examples
91
+
92
+ List templates to be updated/created in dependency order using the `lower` AWS credentials in the
93
+ `us-east-1` region, but don't make any changes in AWS:
94
+
95
+ ```shell
96
+ % aws-cft deploy -p lower -t ~/Code/infrastructure -R us-east-1 -v -n
97
+ ```
98
+
99
+ ## Diff
100
+
101
+ ```
102
+ aws-cft diff [OPTIONS]
103
+ ```
104
+
105
+ Report on templates with no corresponding stack, stacks with no corresponding template, and the
106
+ differences between the template source if the template has a corresponding stack.
107
+
108
+ ### Options
109
+
110
+ `--[no-]-color` ::
111
+ colorize output (default: true)
112
+
113
+ `-e`, `--environment ENVIRONMENT` ::
114
+ set environment on which to operate
115
+
116
+ `-r`, `--role ROLE` ::
117
+ set role filter
118
+
119
+ `-c`, `--[no-]check` ::
120
+ only do non-destructive operations to check validity of request
121
+
122
+ `-f`, `--file FILE` ::
123
+ set configuration file relative to the project root (default: ".aws_cft")
124
+
125
+ `-n`, `--[no-]noop` ::
126
+ only do operations that do not require modifying AWS
127
+
128
+ `-p`, `--profile PROFILE` ::
129
+ set profile (default: "default")
130
+
131
+ `-R`, `--region REGION` ::
132
+ set AWS region (default: "us-east-1")
133
+
134
+ `-t`, `--root DIRECTORY` ::
135
+ set infrastructure project root
136
+
137
+ `-T`, `--tag NAME:VALUE` ::
138
+ require a tag have the given value (may be given more than once)
139
+
140
+ `-v`, `--[no-]verbose` ::
141
+ verbose narration of actions
142
+
143
+ `--version` ::
144
+ Show version
145
+
146
+ `-h`, `--help` ::
147
+ print help
148
+
149
+ ## Hosts
150
+
151
+ ```
152
+ aws-cft hosts [OPTIONS]
153
+ ```
154
+
155
+ Lists EC2 instances matching the criteria. Useful for discovering IP addresses of bastion hosts.
156
+
157
+ ### Options
158
+
159
+ `-e`, `--environment ENVIRONMENT` ::
160
+ set environment on which to operate
161
+
162
+ `-r`, `--role ROLE` ::
163
+ set role filter
164
+
165
+ `-c`, `--[no-]check` ::
166
+ only do non-destructive operations to check validity of request
167
+
168
+ `-f`, `--file FILE` ::
169
+ set configuration file relative to the project root (default: ".aws_cft")
170
+
171
+ `-n`, `--[no-]noop` ::
172
+ only do operations that do not require modifying AWS
173
+
174
+ `-p`, `--profile PROFILE` ::
175
+ set profile (default: "default")
176
+
177
+ `-R`, `--region REGION` ::
178
+ set AWS region (default: "us-east-1")
179
+
180
+ `-t`, `--root DIRECTORY` ::
181
+ set infrastructure project root
182
+
183
+ `-T`, `--tag NAME:VALUE` ::
184
+ require a tag have the given value (may be given more than once)
185
+
186
+ `-v`, `--[no-]verbose` ::
187
+ verbose narration of actions
188
+
189
+ `--version` ::
190
+ Show version
191
+
192
+ `-h`, `--help` ::
193
+ print help
194
+
195
+ ## Images
196
+
197
+ ```
198
+ aws-cft images [OPTIONS]
199
+ ```
200
+
201
+ Lists AMIs matching the criteria. Useful for discovering the AMIs for a particular role and environment.
202
+
203
+ ### Options
204
+
205
+ `-e`, `--environment ENVIRONMENT` ::
206
+ set environment on which to operate
207
+
208
+ `-r`, `--role ROLE` ::
209
+ set role filter
210
+
211
+ `-f`, `--file FILE` ::
212
+ set configuration file relative to the project root (default: ".aws_cft")
213
+
214
+ `-n`, `--[no-]noop` ::
215
+ only do operations that do not require modifying AWS
216
+
217
+ `-p`, `--profile PROFILE` ::
218
+ set profile (default: "default")
219
+
220
+ `-R`, `--region REGION` ::
221
+ set AWS region (default: "us-east-1")
222
+
223
+ `-t`, `--root DIRECTORY` ::
224
+ set infrastructure project root
225
+
226
+ `-T`, `--tag NAME:VALUE` ::
227
+ require a tag have the given value (may be given more than once)
228
+
229
+ `-v`, `--[no-]verbose` ::
230
+ verbose narration of actions
231
+
232
+ `--version` ::
233
+ Show version
234
+
235
+ `-h`, `--help` ::
236
+ print help
237
+
238
+ ## Init
239
+
240
+ ```
241
+ aws-cft init [OPTIONS]
242
+ ```
243
+
244
+ Creates an empty set of directories and basic `.aws_cft` configuration file for a new repository.
245
+
246
+ ### Options
247
+
248
+ `-c`, `--[no-]check` ::
249
+ only do non-destructive operations to check validity of request
250
+
251
+ `-f`, `--file FILE` ::
252
+ set configuration file relative to the project root (default: ".aws_cft")
253
+
254
+ `-n`, `--[no-]noop` ::
255
+ only do operations that do not require modifying AWS
256
+
257
+ `-p`, `--profile PROFILE` ::
258
+ set profile (default: "default")
259
+
260
+ `-R`, `--region REGION` ::
261
+ set AWS region (default: "us-east-1")
262
+
263
+ `-t`, `--root DIRECTORY` ::
264
+ set infrastructure project root
265
+
266
+ `-T`, `--tag NAME:VALUE` ::
267
+ require a tag have the given value (may be given more than once)
268
+
269
+ `-v`, `--[no-]verbose` ::
270
+ verbose narration of actions
271
+
272
+ `--version` ::
273
+ Show version
274
+
275
+ `-h`, `--help` ::
276
+ print help
277
+
278
+ ### Notes
279
+
280
+ The `-t` or `--root` option specifies the directory to be initialized. This defaults to the current
281
+ directory in which the command is run. The `-f` or `--file` option specifies the name of the configuration
282
+ file, which defaults to `.aws_cft`.
283
+
284
+ This command creates the following directory and file structure:
285
+
286
+ * cloudformation/
287
+ ** parameters/
288
+ *** applications/
289
+ *** data-resources/
290
+ *** data-services/
291
+ *** networks/
292
+ *** security/
293
+ *** vpcs/
294
+ ** templates/
295
+ *** applications/
296
+ *** data-resources/
297
+ *** data-services/
298
+ *** networks/
299
+ *** security/
300
+ *** vpcs/
301
+ * .aws_cft
302
+
303
+ ## Retract
304
+
305
+ ```
306
+ aws-cft retract [OPTIONS]
307
+ ```
308
+
309
+ Remove stacks matching a set of templates. This will not remove stacks that are known dependencies for
310
+ stacks that are not marked for retraction.
311
+
312
+ ### Options
313
+
314
+ `-e`, `--environment ENVIRONMENT` ::
315
+ set environment on which to operate
316
+
317
+ `-r`, `--role ROLE` ::
318
+ set role filter
319
+
320
+ `-c`, `--[no-]check` ::
321
+ only do non-destructive operations to check validity of request
322
+
323
+ `-f`, `--file FILE` ::
324
+ set configuration file relative to the project root (default: ".aws_cft")
325
+
326
+ `-n`, `--[no-]noop` ::
327
+ only do operations that do not require modifying AWS
328
+
329
+ `-p`, `--profile PROFILE` ::
330
+ set profile (default: "default")
331
+
332
+ `-R`, `--region REGION` ::
333
+ set AWS region (default: "us-east-1")
334
+
335
+ `-t`, `--root DIRECTORY` ::
336
+ set infrastructure project root
337
+
338
+ `-T`, `--tag NAME:VALUE` ::
339
+ require a tag have the given value (may be given more than once)
340
+
341
+ `-v`, `--[no-]verbose` ::
342
+ verbose narration of actions
343
+
344
+ `--version` ::
345
+ Show version
346
+
347
+ `-h`, `--help` ::
348
+ print help
349
+
350
+ ### Notes
351
+
352
+ Stacks are removed in reverse dependency order. If a template imports the outputs of another template,
353
+ then the importing template will be removed before the exporting template is removed.
354
+
355
+ When restricting retracted templates to those with a particular role, the list of selected templates
356
+ is reduced by any templates on which non-selected templates depend. For example, if templates A and B have
357
+ the role we wish to retract, and template C depends on template B, then only template A will be selected
358
+ for retraction.
359
+
360
+ ## Stacks
361
+
362
+ ```
363
+ aws-cft stacks [OPTIONS]
364
+ ```
365
+
366
+ Lists stacks matching the criteria.
367
+
368
+ ### Options
369
+
370
+ `-e`, `--environment ENVIRONMENT` ::
371
+ set environment on which to operate
372
+
373
+ `-r`, `--role ROLE` ::
374
+ set role filter
375
+
376
+ `-c`, `--[no-]check` ::
377
+ only do non-destructive operations to check validity of request
378
+
379
+ `-f`, `--file FILE` ::
380
+ set configuration file relative to the project root (default: ".aws_cft")
381
+
382
+ `-n`, `--[no-]noop` ::
383
+ only do operations that do not require modifying AWS
384
+
385
+ `-p`, `--profile PROFILE` ::
386
+ set profile (default: "default")
387
+
388
+ `-R`, `--region REGION` ::
389
+ set AWS region (default: "us-east-1")
390
+
391
+ `-t`, `--root DIRECTORY` ::
392
+ set infrastructure project root
393
+
394
+ `-T`, `--tag NAME:VALUE` ::
395
+ require a tag have the given value (may be given more than once)
396
+
397
+ `-v`, `--[no-]verbose` ::
398
+ verbose narration of actions
399
+
400
+ `--version` ::
401
+ Show version
402
+
403
+ `-h`, `--help` ::
404
+ print help
@@ -0,0 +1,53 @@
1
+ # coding: utf-8
2
+ # frozen_string_literal: true
3
+
4
+ lib = File.expand_path('../lib', __FILE__)
5
+ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
6
+ require 'aws_cft_tools/version'
7
+
8
+ Gem::Specification.new do |spec|
9
+ spec.name = 'aws-cft-tools'
10
+ spec.version = AwsCftTools::VERSION
11
+ spec.authors = ['Small Business Administration']
12
+ spec.email = ['help@certify.sba.gov']
13
+
14
+ spec.summary = 'Tools for managing CloudFormation Templates'
15
+ spec.description = 'Tools for managing a cloud deployment in AWS with state held in AWS.'
16
+ spec.homepage = 'https://github.com/USSBA/aws-cft-tools'
17
+ spec.license = 'Apache2'
18
+
19
+ spec.required_ruby_version = '>= 2.4.0'
20
+
21
+ # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
22
+ # to allow pushing to a single host or delete this section to allow pushing to any host.
23
+ # if spec.respond_to?(:metadata)
24
+ # spec.metadata['allowed_push_host'] = "TODO: Set to 'http://mygemserver.com'"
25
+ # else
26
+ # raise 'RubyGems 2.0 or newer is required to protect against ' \
27
+ # 'public gem pushes.'
28
+ # end
29
+
30
+ spec.files = `git ls-files -z`.split("\x0").reject do |f|
31
+ f.match(%r{^(test|spec|features)/})
32
+ end
33
+ spec.bindir = 'exe'
34
+ spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
35
+ spec.require_paths = ['lib']
36
+
37
+ spec.add_dependency 'aws-sdk', '~> 2.9.22'
38
+ spec.add_dependency 'clamp', '~> 1.1.2'
39
+ spec.add_dependency 'table_print', '~> 1.5.6'
40
+ spec.add_dependency 'cloudformation-ruby-dsl', '~> 1.4.6'
41
+ spec.add_dependency 'diffy', '~> 3.2.0'
42
+
43
+ spec.add_development_dependency 'asciidoctor', '~> 1.5.6'
44
+ spec.add_development_dependency 'bundler', '~> 1.15'
45
+ spec.add_development_dependency 'rake', '~> 10.0'
46
+ spec.add_development_dependency 'rspec', '~> 3.0'
47
+ spec.add_development_dependency 'rubocop', '~> 0.49.1'
48
+ spec.add_development_dependency 'rubocop-rspec', '~> 1.15.1'
49
+ spec.add_development_dependency 'rubycritic'
50
+ spec.add_development_dependency 'simplecov'
51
+ spec.add_development_dependency 'webmock', '~> 3.0.1'
52
+ spec.add_development_dependency 'yard', '~> 0.9.9'
53
+ end