Skip to content

Latest commit

 

History

History
280 lines (230 loc) · 6.66 KB

README.md

File metadata and controls

280 lines (230 loc) · 6.66 KB
Raw

cfparams

Wrangle CloudFormation parameters.

Reads expected parameter keys from a CloudFormation template, accepts values from command line or YAML file, emits JSON suitable for aws cloudformation *-stack --parameters="..." commands. Supports the use of default and previous values.

Installation Instructions

  • If you use Homebrew, you can simply run: brew install cultureamp/tap/cfparams (only in the Culture Amp organization at the moment, sorry).
  • Alternatively, if you want the latest version, download the executable directly from the release page
  • Rename and move the cfparams executable to your path, e.g: mv cfparams /usr/local/bin (or move to your favourite spot and symlink).
  • To check whether your installation is successful, run the command cfparams and the output would be similar to: 
    $ cfparams
CloudFormation template or tags file required
    e.g: --template=cloudformation.yaml
    e.g: --tags=tags-foo.yaml
  • If it still doesn't work you may need to hash -r to clear the path cache or restart the shell

Example use-cases

CloudFormation template excerpt describing an ECS service to be provisioned onto an existing ECS cluster.

# cfn.yaml excerpt
Parameters:
  Greeting:
    Type: String
    Description: greeting message to send
    Default: Hello
  Recipient:
    Description: name of the greeting recipient
    Type: String
  ImageRepo:
    Type: String
    Description: repository of Docker image to run
    Default: "123.dkr.ecr.us-east-1.amazonaws.com/greeting"
  ImageTag:
    Type: String
    Description: tag of Docker image to run
    Default: latest
  Cluster:
    Description: ECS cluster ID to run service on
    Type: String

Creating ECS service CloudFormation stack

Launching the CloudFormation stack for the first time. Accept some defaults from the template, specify all other parameters.

params="$(
  cfparams --template=cfn.yaml --accept-defaults --no-previous \
    Recipient=world ImageTag=v1 Cluster=nanoservices
)"
  • --template loads supported Parameters from a CloudFormation template.
  • --accept-defaults omits keys that have a default in the CloudFormation template.
  • --no-previous means fail if a key has no default in the template and isn't specified on the command line. Without this option, those keys will be auto-filled as "UsePreviousValue": true.

Resulting JSON:

[
  {"ParameterKey": "Recipient", "ParameterValue": "world"},
  {"ParameterKey": "ImageTag", "ParameterValue": "v1"},
  {"ParameterKey": "Cluster", "ParameterValue": "nanoservices"}
]
aws cloudformation create-stack \
  --stack-name=greeting \
  --template-body=file://cfn.yaml \
  --parameters="$params"

Deploying a new version of the app

Deploying a new version of the app, e.g. from CI. Only ImageTag should change, all other parameters use previous value.

params="$(cfparams --template=cfn.yaml ImageTag=v2)"

Resulting JSON:

[
  {"ParameterKey": "Greeting", "UsePreviousValue": true},
  {"ParameterKey": "Recipient", "UsePreviousValue": true},
  {"ParameterKey": "ImageRepo", "UsePreviousValue": true},
  {"ParameterKey": "ImageTag", "ParameterValue": "v2"},
  {"ParameterKey": "Cluster", "UsePreviousValue": true}
]

Update stack:

aws cloudformation update-stack \
  --stack-name=greeting \
  --use-previous-template \
  --parameters="$params"

Updating the CloudFormation stack

Changing the stack, for example introducing a FooHost parameter.

 # cfn.yaml excerpt
 Parameters:
+  FooHost:
+    Type: String
+    Description: API key to access Foo service
   Greeting:
params="$(cfparams --template=cfn-foohost.yaml FooHost=foo.example.com)"

Resulting JSON:

[
  {"ParameterKey": "FooHost", "ParameterValue": "foo.example.com"},
  {"ParameterKey": "Greeting", "UsePreviousValue": true},
  {"ParameterKey": "Recipient", "UsePreviousValue": true},
  {"ParameterKey": "ImageRepo", "UsePreviousValue": true},
  {"ParameterKey": "ImageTag", "UsePreviousValue": true},
  {"ParameterKey": "Cluster", "UsePreviousValue": true}
]
name="greeting-update-$(date +%Y%m%d-%H%M%S)"

aws cloudformation create-change-set \
  --stack-name=greeting \
  --change-set-name="$name" \
  --use-previous-template \
  --parameters="$(cfparams --template=cfn.yaml FooHost=foo.example.com)"

# review Change Set here

aws cloudformation execute-change-set \
  --stack-name=greeting \
  --change-set-name="$name"

Introducing version-controlled parameters files

Now we introduce some version-controlled files to the subset of parameters that make sense to exist in the codebase. ImageTag is not included in this file.

# parameters-staging.yaml
FooHost: foo.local
Greeting: Howdy
Recipient: team
Cluster: staging
# parameters-production.yaml
FooHost: foo.example.com
Greeting: Hello
Recipient: world
Cluster: production
params="$(
  cfparams --template=cfn-foohost.yaml --parameters=parameters-staging.yaml \
    ImageTag=v3 Greeting=Bonjour
)

Resulting JSON:

[
  {"ParameterKey": "FooHost", "ParameterValue": "foo.local"},
  {"ParameterKey": "Greeting", "ParameterValue": "Howdy"},
  {"ParameterKey": "Recipient", "ParameterValue": "team"},
  {"ParameterKey": "ImageRepo", "UsePreviousValue": true},
  {"ParameterKey": "ImageTag", "ParameterValue": "v3"},
  {"ParameterKey": "Cluster", "ParameterValue": "staging"}
]

Bonus feature: Stack Tags

CloudFormation stacks can be tagged, and those tags flow into all taggable resources the stack creates. As with --parameters, the aws cloudformation commands expect these in an awkward format. cfparams --tags file.yaml helps.

aws cloudformation create-stack \
  ... \
  --tags "$(cfparams --tags=tags-production.yaml)" \
  ...
# tags-production.yaml
Name: Widgets as a Service
asset: widget-api
workload: production
cfparams --tags=tags-production.yaml
[
  {
    "Key": "Name",
    "Value": "Widgets as a Service"
  },
  {
    "Key": "asset",
    "Value": "widget-api"
  },
  {
    "Key": "workload",
    "Value": "production"
  }
]

Tags can also be overridden and added to on the command line, just like parameters can:

#tags-test.yaml
asset: buildkite
workload: delivery
buildkite-group: build-test
> cfparams --tags=tags-test.yaml buildkite-group=build-pylons message=extra-tag
[
  {
    "Key": "buildkite-group",
    "Value": "build-pylons"
  },
  {
    "Key": "message",
    "Value": "extra-tag"
  },
  {
    "Key": "asset",
    "Value": "buildkite"
  },
  {
    "Key": "workload",
    "Value": "delivery"
  }
]