aws-cft-tools 0.1.0

data/USAGE.adoc

@@ -0,0 +1,404 @@
+# Using `aws-cft`
+
+## Deploy
+
+```
+aws-cft deploy [OPTIONS]
+```
+
+Ensure stacks in AWS are up to date with the templates in the repository. This will create any missing
+stacks.
+
+### Options
+
+`-e`, `--environment ENVIRONMENT` ::
+set environment on which to operate
+
+`-r`, `--role ROLE` ::
+set role filter
+
+`-j`, `--jobs INTEGER` ::
+maximum number of parallel stacks to build simultaneously (default: 1)
+
+`-c`, `--[no-]check` ::
+only do non-destructive operations to check validity of request
+
+`-f`, `--file FILE` ::
+set configuration file relative to the project root (default: ".aws_cft")
+
+`-n`, `--[no-]noop` ::
+only do operations that do not require modifying AWS
+
+`-p`, `--profile PROFILE` ::
+set profile (default: "default")
+
+`-R`, `--region REGION` ::
+set AWS region (default: "us-east-1")
+
+`-t`, `--root DIRECTORY` ::
+set infrastructure project root
+
+`-T`, `--tag NAME:VALUE` ::
+require a tag have the given value (may be given more than once)
+
+`-v`, `--[no-]verbose` ::
+verbose narration of actions
+
+`--version` ::
+Show version
+
+`-h`, `--help` ::
+print help
+
+### Notes
+
+Stacks are built or updated in dependency order. If a template imports the outputs of another template,
+then the importing template will not be updated or created until after the exporting template is
+updated or created.
+
+When restricting the deployed templates to those with a particular role, the list of selected templates
+is expanded to include any templates on which the set of selected templates depend. For example, if
+template A has the role we wish to deploy, but it depends on template B, and template B depends on
+template C, then templates A, B, and C will be selected for updating or creating.
+
+**N.B.:** Using the `-j` option to deploy templates in parallel can cause the script to run into request
+limits in AWS. If AWS does refuse a request because of throttling, the script will exit with an error.
+Try running it again with a lower number of simultaneous jobs.
+
+**N.B.:** If you interrupt the script while it is deploying templates (without the `-c` or `-n` options),
+then none of the changes will be rolled back. Any stacks in-progress will continue to completion since
+the script only watches for completion once the build has been triggered.
+
+**N.B.** If you interrupt the script while it is checking on changesets (the `-c` option), then none of the
+changesets that are in-progress will be removed. You may have some "orphan" changesets to clean up by hand.
+
+#### Recommended Deployment Strategy
+
+When preparing to deploy new or updated templates, you can get an idea of what will happen by running
+the `deploy` command in the following sequence (replace `[OPTIONS]` with the options you need to manage
+select the right profile, environment, and/or roles):
+
+`aws-cft deploy [OPTIONS] -v -n` ::
+Review the proposed list of templates and make sure they are being updated or created as expected.
+
+`aws-cft deploy [OPTIONS] -v -c` ::
+Review the proposed list of changes for each stack and make sure there are no surprise replacements or deletions.
+
+`aws-cft deploy [OPTIONS] -v` ::
+Finally, execute the deployment and make the changes to the templates.
+
+### Examples
+
+List templates to be updated/created in dependency order using the `lower` AWS credentials in the
+`us-east-1` region, but don't make any changes in AWS:
+
+```shell
+% aws-cft deploy -p lower -t ~/Code/infrastructure -R us-east-1 -v -n
+```
+
+## Diff
+
+```
+aws-cft diff [OPTIONS]
+```
+
+Report on templates with no corresponding stack, stacks with no corresponding template, and the
+differences between the template source if the template has a corresponding stack.
+
+### Options
+
+`--[no-]-color` ::
+colorize output (default: true)
+
+`-e`, `--environment ENVIRONMENT` ::
+set environment on which to operate
+
+`-r`, `--role ROLE` ::
+set role filter
+
+`-c`, `--[no-]check` ::
+only do non-destructive operations to check validity of request
+
+`-f`, `--file FILE` ::
+set configuration file relative to the project root (default: ".aws_cft")
+
+`-n`, `--[no-]noop` ::
+only do operations that do not require modifying AWS
+
+`-p`, `--profile PROFILE` ::
+set profile (default: "default")
+
+`-R`, `--region REGION` ::
+set AWS region (default: "us-east-1")
+
+`-t`, `--root DIRECTORY` ::
+set infrastructure project root
+
+`-T`, `--tag NAME:VALUE` ::
+require a tag have the given value (may be given more than once)
+
+`-v`, `--[no-]verbose` ::
+verbose narration of actions
+
+`--version` ::
+Show version
+
+`-h`, `--help` ::
+print help
+
+## Hosts
+
+```
+aws-cft hosts [OPTIONS]
+```
+
+Lists EC2 instances matching the criteria. Useful for discovering IP addresses of bastion hosts.
+
+### Options
+
+`-e`, `--environment ENVIRONMENT` ::
+set environment on which to operate
+
+`-r`, `--role ROLE` ::
+set role filter
+
+`-c`, `--[no-]check` ::
+only do non-destructive operations to check validity of request
+
+`-f`, `--file FILE` ::
+set configuration file relative to the project root (default: ".aws_cft")
+
+`-n`, `--[no-]noop` ::
+only do operations that do not require modifying AWS
+
+`-p`, `--profile PROFILE` ::
+set profile (default: "default")
+
+`-R`, `--region REGION` ::
+set AWS region (default: "us-east-1")
+
+`-t`, `--root DIRECTORY` ::
+set infrastructure project root
+
+`-T`, `--tag NAME:VALUE` ::
+require a tag have the given value (may be given more than once)
+
+`-v`, `--[no-]verbose` ::
+verbose narration of actions
+
+`--version` ::
+Show version
+
+`-h`, `--help` ::
+print help
+
+## Images
+
+```
+aws-cft images [OPTIONS]
+```
+
+Lists AMIs matching the criteria. Useful for discovering the AMIs for a particular role and environment.
+
+### Options
+
+`-e`, `--environment ENVIRONMENT` ::
+set environment on which to operate
+
+`-r`, `--role ROLE` ::
+set role filter
+
+`-f`, `--file FILE` ::
+set configuration file relative to the project root (default: ".aws_cft")
+
+`-n`, `--[no-]noop` ::
+only do operations that do not require modifying AWS
+
+`-p`, `--profile PROFILE` ::
+set profile (default: "default")
+
+`-R`, `--region REGION` ::
+set AWS region (default: "us-east-1")
+
+`-t`, `--root DIRECTORY` ::
+set infrastructure project root
+
+`-T`, `--tag NAME:VALUE` ::
+require a tag have the given value (may be given more than once)
+
+`-v`, `--[no-]verbose` ::
+verbose narration of actions
+
+`--version` ::
+Show version
+
+`-h`, `--help` ::
+print help
+
+## Init
+
+```
+aws-cft init [OPTIONS]
+```
+
+Creates an empty set of directories and basic `.aws_cft` configuration file for a new repository.
+
+### Options
+
+`-c`, `--[no-]check` ::
+only do non-destructive operations to check validity of request
+
+`-f`, `--file FILE` ::
+set configuration file relative to the project root (default: ".aws_cft")
+
+`-n`, `--[no-]noop` ::
+only do operations that do not require modifying AWS
+
+`-p`, `--profile PROFILE` ::
+set profile (default: "default")
+
+`-R`, `--region REGION` ::
+set AWS region (default: "us-east-1")
+
+`-t`, `--root DIRECTORY` ::
+set infrastructure project root
+
+`-T`, `--tag NAME:VALUE` ::
+require a tag have the given value (may be given more than once)
+
+`-v`, `--[no-]verbose` ::
+verbose narration of actions
+
+`--version` ::
+Show version
+
+`-h`, `--help` ::
+print help
+
+### Notes
+
+The `-t` or `--root` option specifies the directory to be initialized. This defaults to the current
+directory in which the command is run. The `-f` or `--file` option specifies the name of the configuration
+file, which defaults to `.aws_cft`.
+
+This command creates the following directory and file structure:
+
+* cloudformation/
+** parameters/
+*** applications/
+*** data-resources/
+*** data-services/
+*** networks/
+*** security/
+*** vpcs/
+** templates/
+*** applications/
+*** data-resources/
+*** data-services/
+*** networks/
+*** security/
+*** vpcs/
+* .aws_cft
+
+## Retract
+
+```
+aws-cft retract [OPTIONS]
+```
+
+Remove stacks matching a set of templates. This will not remove stacks that are known dependencies for
+stacks that are not marked for retraction.
+
+### Options
+
+`-e`, `--environment ENVIRONMENT` ::
+set environment on which to operate
+
+`-r`, `--role ROLE` ::
+set role filter
+
+`-c`, `--[no-]check` ::
+only do non-destructive operations to check validity of request
+
+`-f`, `--file FILE` ::
+set configuration file relative to the project root (default: ".aws_cft")
+
+`-n`, `--[no-]noop` ::
+only do operations that do not require modifying AWS
+
+`-p`, `--profile PROFILE` ::
+set profile (default: "default")
+
+`-R`, `--region REGION` ::
+set AWS region (default: "us-east-1")
+
+`-t`, `--root DIRECTORY` ::
+set infrastructure project root
+
+`-T`, `--tag NAME:VALUE` ::
+require a tag have the given value (may be given more than once)
+
+`-v`, `--[no-]verbose` ::
+verbose narration of actions
+
+`--version` ::
+Show version
+
+`-h`, `--help` ::
+print help
+
+### Notes
+
+Stacks are removed in reverse dependency order. If a template imports the outputs of another template,
+then the importing template will be removed before the exporting template is removed.
+
+When restricting retracted templates to those with a particular role, the list of selected templates
+is reduced by any templates on which non-selected templates depend. For example, if templates A and B have
+the role we wish to retract, and template C depends on template B, then only template A will be selected
+for retraction.
+
+## Stacks
+
+```
+aws-cft stacks [OPTIONS]
+```
+
+Lists stacks matching the  criteria.
+
+### Options
+
+`-e`, `--environment ENVIRONMENT` ::
+set environment on which to operate
+
+`-r`, `--role ROLE` ::
+set role filter
+
+`-c`, `--[no-]check` ::
+only do non-destructive operations to check validity of request
+
+`-f`, `--file FILE` ::
+set configuration file relative to the project root (default: ".aws_cft")
+
+`-n`, `--[no-]noop` ::
+only do operations that do not require modifying AWS
+
+`-p`, `--profile PROFILE` ::
+set profile (default: "default")
+
+`-R`, `--region REGION` ::
+set AWS region (default: "us-east-1")
+
+`-t`, `--root DIRECTORY` ::
+set infrastructure project root
+
+`-T`, `--tag NAME:VALUE` ::
+require a tag have the given value (may be given more than once)
+
+`-v`, `--[no-]verbose` ::
+verbose narration of actions
+
+`--version` ::
+Show version
+
+`-h`, `--help` ::
+print help

data/aws-cft-tools.gemspec

@@ -0,0 +1,53 @@
+# coding: utf-8
+# frozen_string_literal: true
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'aws_cft_tools/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'aws-cft-tools'
+  spec.version       = AwsCftTools::VERSION
+  spec.authors       = ['Small Business Administration']
+  spec.email         = ['help@certify.sba.gov']
+
+  spec.summary       = 'Tools for managing CloudFormation Templates'
+  spec.description   = 'Tools for managing a cloud deployment in AWS with state held in AWS.'
+  spec.homepage      = 'https://github.com/USSBA/aws-cft-tools'
+  spec.license       = 'Apache2'
+
+  spec.required_ruby_version = '>= 2.4.0'
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  # if spec.respond_to?(:metadata)
+  #   spec.metadata['allowed_push_host'] = "TODO: Set to 'http://mygemserver.com'"
+  # else
+  #   raise 'RubyGems 2.0 or newer is required to protect against ' \
+  #     'public gem pushes.'
+  # end
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'aws-sdk', '~> 2.9.22'
+  spec.add_dependency 'clamp', '~> 1.1.2'
+  spec.add_dependency 'table_print', '~> 1.5.6'
+  spec.add_dependency 'cloudformation-ruby-dsl', '~> 1.4.6'
+  spec.add_dependency 'diffy', '~> 3.2.0'
+
+  spec.add_development_dependency 'asciidoctor', '~> 1.5.6'
+  spec.add_development_dependency 'bundler', '~> 1.15'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rubocop', '~> 0.49.1'
+  spec.add_development_dependency 'rubocop-rspec', '~> 1.15.1'
+  spec.add_development_dependency 'rubycritic'
+  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'webmock', '~> 3.0.1'
+  spec.add_development_dependency 'yard', '~> 0.9.9'
+end