aws_as_code 1.0.4 → 1.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 34986215f72ee84f1599cc865e45c8b4c636ec13
-  data.tar.gz: 28cb66d30979987662eb0600c35916d24b9ab5ef
+  metadata.gz: c2b846a3091b5d51d22c08d3fac3251bbe31e9e1
+  data.tar.gz: 162f56da70060281885207a6fde5c43880fc3d05
 SHA512:
-  metadata.gz: 7bed8edaea455f663b21a2e4d8e323000b8f0f1d8d5d6145b9bbc957fb0d8f015724fec6e6c185d6c90a51576749d67355e1208f897ebd2805dbc07206768709
-  data.tar.gz: d39f89b30c383220530e0fceb9b4383f01c344e705463b8ab05d1852f9edf9e7f4fd6feaa4e2a1c3b3b358ea6465f1e0877167bfa3cd8c04ee1d45b46bc0a332
+  metadata.gz: bc3a4b25c816e7f7dac74f8c2f3c4684d19859992ad0836f75ac09e9366bae1a7f84f20ef6ced57ce5876205d51ba35f85e47dcfa8e62a565a5de4508b3e80b7
+  data.tar.gz: 35aefa249b8a751f2ae50e3dea7a160107d3dfb493fee74190e9645202d99f91e869d77d9da657a31ee2d22c2cb1ce2c8190a687cc87c440947754e31e56ace1

data/.rubocop.yml

@@ -1,5 +1,5 @@
 AllCops:
-  TargetRubyVersion: 2.2
+  TargetRubyVersion: 2.3
   Include:
   - "**/*.gemspec"
   - "**/Gemfile"

data/README.md

@@ -1,8 +1,17 @@
-# Aws::As::Code
+# AwsAsCode
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/aws/as/code`. To experiment with that code, run `bin/console` for an interactive prompt.
+This gem is built upon a
+great [cfndsl](https://github.com/stevenjack/cfndsl) CloudFormation
+DSL language in order to automate routine tasks related to CF stack
+updates:
+- compilation of multiple associated templates;
+- a sensible convention around the way compiled templates are uploaded
+  and stored on S3;
+- a simple wrapper around AWS SDK allowing you to apply stack changes
+  immediately after they have been compiled and uploaded to S3.
 
-TODO: Delete this and the text above, and describe your gem
+This gem provides a command-line utility; normally you don't need to
+use it as a library.
 
 ## Installation
 
@@ -22,26 +31,339 @@ Or install it yourself as:
 
 ## Usage
 
+`bundle exec aws-as-code [command] [option...]`
+
+### Commands
+
+#### `create`
+Processes (compiles and uploads) CF templates and attempts to create a
+new stack using them.
+
 ```
 bundle exec aws-as-code create \
-       --ruby-dir=cfn \
-       --json-dir=cfn-compiled \
-       --bucket=my-cfn-bucket \
-       --template=environment \
-       --stack=master
+  --bucket=projectname-prod-cloudformation \
+  --version="$VERSION" \
+  --stack-params=ApiKey:KEY ApiSecret:SECRET
+```
+
+#### `update`
+Processes (compiles and uploads) CF templates and applies changes to an
+existing stack (keeping all existing stack parameters which are not explicitly
+overridden in the command line)
+
+```
+bundle exec aws-as-code update \
+  --bucket=projectname-prod-cloudformation \
+  --version="$VERSION" \
+  --stack-params=ApiSecret:NEWSECRET
+```
+
+#### `compile`
+Compiles CF templates from `ruby-dir` using configuration from
+`config-dir` and stores them locally in `json-dir`
+
+```
+bundle exec aws-as-code compile \
+  --bucket=projectname-prod-cloudformation \
+  --version="$VERSION"
+```
+
+Mainly used for debugging purposes.
+
+#### `upload`
+Uploads CF templates from `json-dir` to `bucket` on S3.
+
+```
+bundle exec aws-as-code upload \
+  --bucket=projectname-prod-cloudformation \
+  --version="$VERSION"
+```
+
+Mainly used for debugging purposes
+
+#### `do-update`
+Applies changes to the existing stack using currently uploaded templates.
+
+```
+bundle exec aws-as-code do-update \
+  --bucket=projectname-prod-cloudformation \
+  --version="$VERSION"
+```
+
+Mainly used for debugging purposes
+
+#### `do-create`
+Creates a new stack using templates already uploaded to S3
+
+```
+bundle exec aws-as-code do-create \
+  --bucket=projectname-prod-cloudformation \
+  --version="$VERSION"
+```
+
+Mainly used for debugging purposes
+
+### Options
+
+#### `--config-dir`
+
+Directory with configuration files.
+
+Default value: `cfn`
+
+#### `--ruby-dir`
+
+Directory with CloudFormation templates written in Ruby DSL
+
+Default value: `cfn`
+
+#### `--json-dir`
+
+Directory to put compiled JSON CF templates to
+
+Default value: `cfn-compiled`
+
+#### `--bucket`
+
+S3 bucket used to store compiled templates.
+
+*Required*
+
+#### `--template`
+
+Filename of the stack root template.
+
+Default value: `environment`
+
+#### `--stack`
+
+Name of the stack to create or update (also used as a part of the
+uploaded template name to help distinguish stack templates compiled
+from the same source but using different configurations)
+
+Default value: `master`
+
+#### `--stack-params`
+
+A list of stack parameters in the key-value form.
+
+```
+--stack-params=ApiKey:KEY ApiSecret:SECRET
 ```
 
-## Development
+Optional. If not provided for `update` task, all parameters will be
+kept as-is. If not provided for `create` task, no parameters will be
+passed to the stack (if stack requires any parameters, then stack
+creation will fail).
 
-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.
+#### `--version`
 
-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).
+Stack definition version. If you're using a version system, it's
+highly recommended to use the latest commit hash as a version.
 
-## Contributing
+*Required*
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/aws_as_code. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+## Configuration files
 
+`aws-as-code` expects to find two configuration files in `config-dir`:
+- parameters.yml
+- settings.yml
 
-## License
+### `parameters.yml`
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+Contains the list of stack parameters configurable through the
+CloudFormation AWS console.
+
+Format:
+
+```
+<PARAMETER NAME>:
+  Type: "String" | "Number" | "CommaDelimitedList"
+  Default: <DEFAULT VALUE>
+  _ext:
+    env: <ENVIRONMENT VARIABLE NAME>
+    services: <LIST OF SERVICE NAMES THIS PARAMETER IS PASSED TO>
+```
+
+Example:
+
+```
+GoogleAnalyticsId:
+  Type: String
+  Default: UA-66947010-2
+  _ext:
+    env: GOOGLE_ANALYTICS_ID
+    services:
+      - web
+
+MailerUrl:
+  Type: String
+  Default: test://localhost
+  _ext:
+    secure: true
+    env: MAILER_URL
+    services:
+      - web
+      - queue
+```
+
+Keep in mind that AWS has a
+[hard cap of 60 parameters](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cloudformation-limits.html)
+available to your stack. If a value is not sensitive and doesn't need to be
+reconfigured on the fly, consider using `settings.yml` instead!
+
+From the example above, `GoogleAnalyticsId` *can* be moved to
+`settings.yml`, while `MailerUrl` *cannot*, as it contains some
+sensitive information such as SMTP username and password.
+
+### `settings.yml`
+
+Contains the list of non-sensitive environment-specific settings
+
+Settings can be referenced from the tempalte definition using the
+`setting('<SETTING NAME>')` DSL extension
+
+Format:
+```
+<SETTING NAME>:
+  <STACK NAME>: <VALUE>
+  <STACK NAME>: <VALUE>
+  _default: <DEFAULT VALUE>
+```
+
+Example:
+```
+es_instance_type:
+  master: t2.small.elasticsearch
+  _default: t2.small.elasticsearch
+es_instance_count:
+  master: 2
+  _default: 1
+web_tasks_count:
+  master: 4
+  _default: 1
+```
+
+## DSL extensions
+
+### `env_ebs_options(env = nil)`
+Generates a list of ElasticBeanstalk confugration options passing the
+list of stack parameters to the ElasticBeanstalk environment.
+
+Example:
+
+```
+ElasticBeanstalk_Environment "Service" do
+  Description "Sample app"
+  ApplicationName Ref "Application"
+  VersionLabel Ref "CurrentVersion"
+  OptionSettings [
+    {
+      Namespace: "aws:elasticbeanstalk:environment",
+      OptionName: "EnvironmentType",
+      Value: "SingleInstance"
+    }
+  ] + env_ebs_options("web")
+  SolutionStackName "SOLUTION"
+end
+```
+
+### `env_passthrough(env = nil)`
+Generates a list of stack parameters passing the list input parameters specific
+to a selected environment `env` to a nested stack.
+
+Example:
+
+```
+CloudFormation_Stack "Services" do
+  Parameters Hash[
+               VPC: FnGetAtt("Network", "Outputs.VPC"),
+             ].merge(env_passthrough)
+  TemplateURL template_url "services"
+  TimeoutInMinutes 20
+end
+```
+
+### `inputs(env = nil)`
+Generates a list of stack input declarations for the environment `env`.
+
+Example:
+
+```
+CloudFormation do
+  inputs("web")
+
+  Parameter "SubnetA" do
+    String()
+  end
+  ...
+```
+
+### `params(env = nil)`
+Returns a list of parameters for environment `env`
+
+### `setting(key)`
+Returns the value of the setting `key` from `settings.yml`
+
+Example:
+
+```
+Resource "Lambda" do
+  Type "AWS::Lambda::Function"
+  Property "Description", "Sample lambda"
+  Property "Handler", "main.handler"
+  Property "Code",
+           S3Bucket: setting("lambda_source"),
+           S3Key: FnJoin(
+             "",
+             [
+               "lambda/", ENV["VERSION"], ".zip"
+             ]
+           )
+  Property "Runtime", "nodejs6.10"
+  Property "Timeout", "3"
+  Property "Role", setting("role")
+end
+```
+
+### `template_url`
+
+Returns a full S3 URL (including dynamically generated version) of another template.
+
+Example:
+
+```
+CloudFormation do
+  inputs
+
+  CloudFormation_Stack "Network" do
+    TemplateURL template_url "network"
+    TimeoutInMinutes 10
+  end
+end
+```
+
+## Examples
+
+### Deploying stack changes from CircleCI
+
+Assuming that AWS credentials (secret, key and default region) are
+available in the build environment and this user has all the required
+permissions to perform the required stack updates.
+
+#### `circle.yml`
+```
+deployment:
+  production:
+    branch: master
+    commands:
+      - >
+        bundle exec aws-as-code update \
+          --template=environment \
+          --config-dir=core \
+          --ruby-dir=core/cfn \
+          --json-dir=tmp/cfn \
+          --bucket=projectname-prod-cloudformation \
+          --stack="$CIRCLE_BRANCH" \
+          --version="$CIRCLE_SHA1"
+```

data/exe/aws-as-code

@@ -7,10 +7,10 @@ require "thor"
 require "cfndsl"
 require "ostruct"
 
-DEFAULT_RUBY_DIR = "cfn".freeze
-DEFAULT_JSON_DIR = "cfn-compiled".freeze
-DEFAULT_STACK = "master".freeze
-DEFAULT_TEMPLATE = "environment".freeze
+DEFAULT_RUBY_DIR = "cfn"
+DEFAULT_JSON_DIR = "cfn-compiled"
+DEFAULT_STACK = "master"
+DEFAULT_TEMPLATE = "environment"
 
 # Main CLI application for aws-as-code gem
 class AwsAsCodeCli < Thor

data/lib/aws_as_code/concerns/aws_task_helpers.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module AwsAsCode
   module Concerns
     module AwsTaskHelpers

data/lib/aws_as_code/dsl/cache_instances.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 CACHE_INSTANCE_CLASSES = %w(
   cache.t2.micro
   cache.t2.small

data/lib/aws_as_code/dsl/ec2_instances.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 EC2_INSTANCE_CLASSES = %w(
   c3.2xlarge
   c3.4xlarge

data/lib/aws_as_code/dsl/rds_instances.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 RDS_INSTANCE_CLASSES = %w(
   db.m3.medium
   db.m3.large

data/lib/aws_as_code/stack_state_semaphore.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "term/ansicolor"
 
 module AwsAsCode

data/lib/aws_as_code/task/compile.rb

@@ -1,8 +1,9 @@
+# frozen_string_literal: true
+
 require "cfndsl"
 require "yaml"
 require "fileutils"
 
-# frozen_string_literal: true
 module AwsAsCode
   module Task
     # Compiles all input templates and puts

data/lib/aws_as_code/task/update.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module AwsAsCode
   module Task
     class Update < Base

data/lib/aws_as_code/task/upload.rb

@@ -1,7 +1,8 @@
+# frozen_string_literal: true
+
 require "aws-sdk"
 require "pathname"
 
-# frozen_string_literal: true
 module AwsAsCode
   module Task
     class Upload < Base

data/lib/aws_as_code/version.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module AwsAsCode
-  VERSION = "1.0.4".freeze
+  VERSION = "1.0.5"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: aws_as_code
 version: !ruby/object:Gem::Version
-  version: 1.0.4
+  version: 1.0.5
 platform: ruby
 authors:
 - Konstantin Burnaev
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-04-02 00:00:00.000000000 Z
+date: 2017-07-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cfndsl