aws-cft-tools 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 32c8025214a49ca0ed274d45c3c6ee266dcbfb71
+  data.tar.gz: 135e9ef53e1081cc471bf095dd3a5e218364162e
+SHA512:
+  metadata.gz: bae7aae8cdc869ed5fcf53e9dd8e8419765d6ed475f8035ed482fbbdb9042a185df1323639a2263ef52e0169d0607a55ba11fe473eb0667a6327e4f28f016579
+  data.tar.gz: 8f06dceea86f02f3be1b3507a09da24d257484160437eb9d109c044965e3652084937bd6eadff37e7f64da92bf2534520ccc52a7aa17fdd599d2c560e71b9715

data/.editorconfig

@@ -0,0 +1,10 @@
+# EditorConfig is awesome: http://EditorConfig.org
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_size = 2
+indent_style = space
+trim_trailing_whitespace = true

data/.gitignore

@@ -0,0 +1,52 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+Gemfile.lock
+.ruby-version
+.ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+.rspec_status

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,19 @@
+---
+require: rubocop-rspec
+
+Metrics/BlockLength:
+  Exclude:
+    - 'aws-cft-tools.gemspec'
+    - 'example/**/*'
+    - 'exe/aws-cft'
+    - 'spec/**/*'
+
+Metrics/LineLength:
+  Max: 108
+  Details: >-
+    Long lines require scrolling left/right when reviewing in GitHub. Keep lines below
+    108 characters to avoid this. Be kind to your fellow reviewers.
+
+Style/FileName:
+  Exclude:
+    - 'lib/aws-cft-tools.rb'

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.4.1
+before_install: gem install bundler -v 1.15.3

data/.yardopts

@@ -0,0 +1 @@
+lib/**/*.rb - README.md CONTRIBUTING.md LICENSE BEST-PRACTICES.md USAGE.adoc

data/BEST-PRACTICES.md

@@ -0,0 +1,136 @@
+# Best Practices
+
+## Environment-Dependent Settings
+
+It's common to use mappings to manage settings that depend on the deployment environment when using only
+CloudFormation templates. When adding a new environment, the template has to be modified to accommodate the
+new environment.
+
+While we don't get away from this completely -- the template has to list the environment as an allowed
+value -- the goal is to minimize the changes to templates when deploying to a new environment.
+
+By putting environment-dependent settings in a YAML parameters file that sits alongside the CloudFormation
+template, we can leverage the YAML dictionary merging features to extract common settings across environments.
+This lets us avoid
+[magic numbers](<https://en.wikipedia.org/wiki/Magic_number_(programming)#Unnamed_numerical_constants>)
+as well.
+
+For example, if we have a template setting up an auto scaling group with instance sizing dependent on
+the environment, and with two AWS accounts (e.g., a lower and an upper account) and deployments in two
+regions, we can create a parameters file like so:
+
+```yaml
+---
+Lower: &Lower
+  InstanceType: m3.medium
+Upper: &Upper
+  InstanceType: m4.large
+USEast1: &USEast1
+  Foo: bar
+USWest1: &USWest1
+  Foo: baz
+
+Lower-us-east-1: &Lower-us-east-1
+  <<: *Lower
+  <<: *USEast1
+  AmiId: ami-abcdef12
+Upper-us-east-1: &Upper-us-east-1
+  <<: *Upper
+  <<: *USEast1
+  AmiId: ami-123456ab
+
+Lower-us-west-1: &Lower-us-west-1
+  <<: *Lower
+  <<: *USWest1
+  AmiId: ami-cdef1234
+Upper-us-west-1: &Upper-us-west-1
+  <<: *Upper
+  <<: *USWest1
+  AmiId: ami-34cdef12
+
+dev:
+  <<: *Lower-<%= ENV['AWS_REGION'] %>
+  SpotPrice: 0.02
+qa:
+  <<: *Lower-<%= ENV['AWS_REGION'] %>
+  SpotPrice: 0.04
+demo:
+  <<: *Lower-<%= ENV['AWS_REGION'] %>
+  SpotPrice: 0.06
+staging:
+  <<: *Upper-<%= ENV['AWS_REGION'] %>
+production:
+  <<: *Upper-<%= ENV['AWS_REGION'] %>
+```
+
+We use `Lower` and `Upper` to capture cross-region parameters that are dependent on the account, and
+`USEast1` and `USWest` to capture cross-account parameters that are dependent on the region. The
+`Lower-us-east-1` and similarly named dictionaries capture settings that are dependent on both the region
+and account while inheriting from the cross-region and cross-account settings.
+
+Finally, we use the environment variable specifying the region to which we are deploying to select the
+proper account/region set of settings to import into the environment settings.
+
+## Template Dependencies
+
+Most template interdependencies can be discovered by looking at the list of `Output`s and `Fn::ImportValue`s.
+But sometimes, one template builds out a feature in a VPC (e.g., peering) that another template has to have
+in order to finish its build (e.g., fetching Chef cookbooks through a peering connection). In these
+situations, the template with the dependency should note the required templates in a `Metadata` section:
+
+```yaml
+---
+Metadata:
+  DependsOn:
+    Templates:
+      - relative-path-to/template.yaml
+```
+
+These dependencies are harmless if they replicate what can be discovered by examining the other contents of
+the template, but it's best to rely on the implicit dependencies from the `Output`s and `Fn::ImportValue`s.
+
+## Multiple AWS Accounts
+
+Common practice separates development and testing environments from pre-production and
+production environments. The easiest way to manage templates and parameters is to ensure that
+all environments across accounts have unique names. For example, rather than have a
+`devops` environment in each of the accounts when there might be account-dependent
+resource references, you can incorporate the account into the environment's name
+(e.g., `lower-devops` and `upper-devops`).
+
+In the parameter files, you can use YAML aliases and references to aggregate common
+parameter settings for environments across accounts that share the same purpose.
+
+If you are working with environments that share the same name but reside in different
+accounts, you can use an environment variable to select the account and use YAML aliases
+and references to pull in the account-specific settings:
+
+```yaml
+---
+devops-lower: &devops-lower
+  ImageId: ami-abcdef12
+
+devops-upper: &devops-upper
+  ImageId: ami-34cdef12
+
+devops:
+  <<: *devops-<%= ENV['AWS_ACCOUNT'] || begin
+      raise AwsCftTools::IncompleteEnvironmentError,
+            'Please rerun with `AWS_ACCOUNT=lower ...` or `AWS_ACCOUNT=upper ...`'
+    end
+  %>
+```
+
+## Authentication to AWS
+
+The `aws-cft` command supports the `-p` or `--profile` option to select an AWS profile. This makes
+it easy to get up and running with multiple AWS accounts. Best practice here is to make sure none
+of your profiles are labeled `default`. If there isn't a default profile, then you must select a
+profile each time you run the `aws-cft` command. This helps prevent accidentally running a job in
+the wrong account.
+
+Because the tools use the AWS SDK's standard authentication mechanism, you can avoid selecting a
+profile by storing your account credentials in environment variables. This lets you use tools such
+as [aws-vault](https://github.com/99designs/aws-vault) to manage credentials without having them
+stored in cleartext in a file that might get checked into a source code repository or otherwise
+leaked.

data/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing
+
+## Developing in the Open
+
+Developing in the open creates a healthier working environment, a more collaborative process,
+and just better software.
+
+We welcome contributions.
+
+The aws-cft-tools team handles development of this project in the open. As such, we use Github
+to keep track of project development. We may not accept contributions if they introduce operational
+complexity or don't align with the goals of the project. All contributions are subject to the license and in no way imply compensation for contributions.
+
+## Feedback
+
+To provide feedback on the code, please create an issue on GitHub. For other issues, please contact
+the [Certify Help Desk](mailto:help@certify.sba.gov).
+
+## How to Contribute
+
+To contribute, simple create a pull request:
+
+1. Fork this repository
+2. Create a feature branch on which to work (`git checkout -b my-new-feature`)
+3. Commit your work (we like commits that explain your thought process)
+4. Submit a pull request
+5. If there is an issue associated with your pull request, then link that issue.
+
+For documentation changes, you can edit the file directly on GitHub and select the option to create a pull
+request with your own branch.
+
+## Tests and Continuous Integration
+
+All pull requests must pass our continuous integration (CI) tests in order to be accepted.
+We use [rubocop](https://github.com/bbatsov/rubocop) with a style guide to enforce style on Ruby
+projects as part of the CI tests.
+
+The agency reserves the right to change this policy at any time.

data/Gemfile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in aws-cft-tools.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,15 @@
+aws-cft-tools: Tools for managing CloudFormation Templates
+
+Copyright (c) 2017 Small Business Administration
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this software and associated documentation files except
+in compliance with the License. You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -0,0 +1,118 @@
+# AwsCftTools
+
+CloudFormation and related services provide a way to manage infrastructure state in "the cloud." This
+gem and its included command (`aws-cft`) build on top of this state management system to create an
+infrastructure management solution native to the AWS environment.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'aws-cft-tools'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install aws-cft-tools
+
+## Usage
+
+The `aws-cft` command provides access to a number of run books that manage different tasks.
+
+- `aws-cft deploy` to deploy CloudFormation templates
+- `aws-cft diff` to see differences between local and deployed CloudFormation templates
+- `aws-cft hosts` to list running EC2 instances
+- `aws-cft images` to list available AMIs
+- `aws-cft init` to initialize a new infrastructure project
+- `aws-cft retract` to remove deployed CloudFormation templates
+- `aws-cft stacks` to list CloudFormation stacks
+
+See [`USAGE.adoc`](USAGE.adoc) for more details.
+
+### Template organization
+
+CloudFormation templates are managed in any number of directories that correspond to infrastructure
+layers. For example, `vpcs`, `networks`, `security`, and `applications`. The layers are completely
+arbitrary.
+
+Templates also belong to a "role" based on their participation in the infrastructure.  The role is defined
+with metadata in the template:
+
+```yaml
+Metadata:
+  Role: foo
+```
+
+Templates are deployed or retracted based on their dependency order. The scripts try to discover this
+by examining the values exported by one template and imported by another. When this fails to describe
+the proper dependencies of a template, you can add an explicit dependency in the template's `Metadata`:
+
+```yaml
+Metadata:
+  DependsOn:
+    Templates:
+      - relative_path_to/template.yaml
+```
+
+This follows the pattern for listing explicit dependencies between resources in a template.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the
+tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version,
+update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git
+tag for the version, push git commits and tags, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
+
+## Building Gem for Local Use
+
+```shell
+bundle install --deployment --without development test
+gem build ./aws-cft-tools.gemspec
+```
+
+## Minimum IAM Policy to run initial script
+
+```json
+{
+  "Sid": "aws-cft",
+  "Effect": "Allow",
+  "Action": [
+    "ec2:DescribeInstances",
+    "ec2:DescribeTags",
+    "ec2:DescribeImages",
+    "ec2:DescribeImageAttribute"
+  ],
+  "Resource": [ "*" ]
+}
+```
+
+## Security Policy
+
+Please do not submit an issue on GitHub for a security vulnerability. Please contact the development team
+through the Certify Help Desk at [help@certify.sba.gov](mailto:help@certify.sba.gov).
+
+Be sure to include all the pertinent information.
+
+## License
+
+Aws-cft-tools is licensed permissively under the Apache License v2.0.
+A copy of that license is distributed with this software.
+
+## Contributing
+
+We welcome contributions. Please read [`CONTRIBUTING.md`](CONTRIBUTING.md) for how to contribute.
+
+We strive for a welcoming and inclusive environment for the aws-cft-tools project.
+
+Please follow this guidelines in all interactions:
+
+1. Be Respectful: use welcoming and inclusive language.
+2. Assume best intentions: seek to understand others' opinions.

data/Rakefile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubycritic/rake_task'
+require 'yard'
+
+RubyCritic::RakeTask.new do |task|
+  # Glob pattern to match source files. Defaults to FileList['.'].
+  task.paths = FileList['lib/**/*.rb']
+end
+
+RSpec::Core::RakeTask.new(:spec)
+
+YARD::Rake::YardocTask.new
+
+task default: :spec