Home

Welcome to the cfn-square wiki!

Documentation

cfn-square derives from cfn-sphere. The original decision to split from cfn-sphere was based on our need to introduce change set functionality. cfn-square documentation should be read in conjunction with the original documentation. The documentation here will detail where cfn-square has diverged from cfn-sphere.

--profile flag

You can pass the --profile flag rather than use roleshell/awsume/etc.

SAM templates

Serverless Application Model templates are supported. This uses aws cloudformation package to upload artifacts before updating stacks - artifacts such as Lambda code, API Gateway definitions, etc.

region: eu-west-1
package-bucket: my-artifacts-bucket # New config value
stacks:
    stTestSam-AppTest1:
        # Package bucket can also be overridden per stack, e.g:
        # package-bucket: my-apptest1-artifacts
        template-url: apps/test1/template.yaml # A test app created with `sam init -o apps -n test1`

Change sets

There are two commands to deal with change sets:

Create change set

cf create_change_set /tmp/cf/stacks.yml -y

The output of the command is similar to sync, it will show the params being used, and print a table detailing the changes. The table correlates to what you would see in the AWS console if you viewed the change set. The last line of output is the ARN of the change set. Use this to execute the change set when ready.

Execute change set

cf execute_change_set arn:aws:cloudformation:eu-west-1:1234567890:changeSet/some-cf-stack/ecd5077f –y

The above command executes a given change set. The argument passed should be the ARN of the change set, which is returned when creating a change set. The command will initiate the change set and then loop into stack updates as per the sync command.

Transform

cf [sync|create_change_set] [-t|--context] [-n|--dry_run]

Placeholders in cfn YAML are replaced with the parameters in the context YAML if either the -t (or --context) command line switch is supplied. The dry-run switch is added so that one can examine final transformed parameter output.

company.yaml:

---
company: acme

dev.yaml

---
env: dev

dev01.yaml

---
include:
  - company.yaml
  - dev.yaml

meow: SomethingSomething
woof: ThisIsaReplacement
env_number: '01'

stack.yaml:

region: eu-west-1
stacks:
    st[meow]-S3Bucket[woof]:
        template-url: s3-bucket.template
        timeout: 300
        parameters:
           pPurpose: 'purpose'
           pProjectName: 'projectname'
           pCompanyName: '[company]'
           pEnvironmentName: '[env]'
           pEnvironmentNumber: '[env_number]'

In this example, the context yaml (dev01.yaml) includes two other yaml files (company.yaml and dev.yaml) and the main CFN Square YAML (stack.yaml) is contains placeholder of [meow], [woof], [company], [env] and [env_number].

To sync with context:

cf sync --context dev01.yaml stack.yaml -y

And the output:

+-----------------------+-------------+
|       Parameter       |    Value    |
+-----------------------+-------------+
|      pCompanyName     |     acme    |
|    pEnvironmentName   |     dev     |
|   pEnvironmentNumber  |      01     |
|      pProjectName     | projectname |
|        pPurpose       |   purpose   |
+-----------------------+-------------+