Skip to content

StackConfig Reference

Jump to bottom Edit New page
Marco Hoyer edited this page Aug 2, 2018 · 27 revisions

Index

General

Cfn-Sphere uses stack configuration files as single source of truth about stacks and their templates and parameters. You can use several stack configuration files depending on your needs.

Characteristics of stacks being configured in one stack-configuration file:

  • create/update happens in one cfn-sphere transaction
  • cfn-sphere respects dependencies and order of the stacks by tracking parameter references

Automatic Tagging

If the stack configuration file is located in a git repository cfn-sphere tags the stacks with: config-git-repository: <remote URL of the master branch>.

The StackConfig file

Example contents of stacks.yml file:

region: eu-west-1
tags:
  owner: 'foobar'
stacks:
  myapp:
    template-url: templates/my-app.yml
    timeout: 1200
    parameters:
      dockerImage: 'my-image'
      dockerImageVersion: 100
      databaseConnectionString: '|Ref|myapp-persistence.databaseConnectionString'
  myapp-persistence:
    template-url: templates/my-app-persistence.yml
    parameters:
      rdsInstanceType: 't2.micro'
      multiAzDeployment: false

File Reference:

Stacks.yml reference

Key Description Required Options Example
region The region Cfn-Sphere will use for API interactions. In fact the region your resources will live in. Yes eu-west-1
tags Tags for all stacks No key:value pairs responsible-team: rst
service-role iAM Role to be used to process the stacks No role arn
stack-policy-url S3 URL containing a stack policy to apply No s3 url s3://my-bucket/my-policy.json
on_failure Defines action to be applied on creation failure. No 'DO_NOTHING','ROLLBACK','DELETE' ROLLBACK
disable_rollback Disable rollback if stack creation fails. No true, false false
stacks Stacks to be defined in format: name:properties Yes see below

Stack definition reference

Key Description Required Options Example
template-url Url to the CloudFormation template file Yes a relative (to the stacks.yml file) or absolute file path or S3 Url templates/my-template.yml or /var/templates/my-template.yml or s3://my-bucket/my-template.yml
timeout The time in seconds Cfn-Sphere will poll on CloudFormation stack events during create/update actions. Consider to increase this value if you have stacks needing long time to complete. No 600 1200
parameters Parameters for the stack as described in template No key:value pairs myApiKey: superSecret123
tags Tags for the stack No key:value pairs responsible-team: rst
service-role iAM Role to be used to process the stacks No role arn
stack-policy-url S3 URL containing a stack policy to apply No s3 url s3://my-bucket/my-policy.json
on_failure Defines action to be applied on creation failure. No 'DO_NOTHING','ROLLBACK','DELETE' ROLLBACK
disable_rollback Disable rollback if stack creation fails. No true, false false

Cross-Stack referencing

One very powerful feature of Cfn-Sphere is the ability to link stacks by referencing one stacks output as parameter for another stack. This enables users to cut down templates to smaller functional pieces to simplify template reuse and mitigate impact of stack update problems. In the example stack-config file above, there are two stacks defined. One is intended to contain all resources to run an application while the other should only contain it's persistent components. Cfn-Sphere links these stacks by referencing the databaseConnectionString output from myapp-persistence stack as parameter in the myapp stack.

databaseConnectionString: '|Ref|myapp-persistence.databaseConnectionString'

If the referenced stack is defined in the same stack-configuration file, Cfn-Sphere also handles dependencies between the stacks and automatically computes a processing order as described in Stack-Dependency-Management.

Parameter Macros

Cfn-Sphere implements several macros to support common use-cases which can be used as parameter values in the stack-configuration file.

File content referencing

One might want to get a parameter value from a files content. Be it a plain text file or a json/yaml file. This can help to integrate cfn-sphere with other tools like CI servers.

Example on how to get the content of a file as value for dockerImageVersion:

region: eu-west-1
stacks:
  myapp:
    template-url: templates/my-app.yml
    parameters:
      dockerImage: 'my-image'
      dockerImageVersion: "|File|latest-version.txt"

Example on how to get a specific field from a json file:

region: eu-west-1
stacks:
  myapp:
    template-url: templates/my-app.yml
    parameters:
      dockerImage: 'my-image'
      dockerImageVersion: "|File|latest-version.json|<jmespath pattern>"

You can use any jmespath pattern to query the data you would like to have. Imagine the following content of account-config.json:

{
  "id": "12345",
  "name": "my-account"
}

You can get the account id from it with |File|account-config.json|id

KMS encrypted parameters

KMS is very nice to ensure that there are no plain text credentials in any config file. One can encrypt something with KMS and put the cypher text into the stack configuration. The AWS iAM user/role used to execute cfn-sphere needs "kms:Decrypt" permission for the key used for encryption.

Example:

region: eu-west-1
stacks:
  myapp:
    template-url: templates/my-app.yml
    parameters:
      dockerImage: 'my-image'
      dockerImageVersion: 100
      restApiKey: '|kms|<cyphertext>'

SSM parameters

AWS SSM (Systems Manager) offers a key-value store feature for config variables. These can be referenced in cfn-sphere stack config as follows. Cfn-Sphere will fetch the referenced value on every sync executed on the stack config.

Example:

region: eu-west-1
stacks:
  myapp:
    template-url: templates/my-app.yml
    parameters:
      dockerImage: 'my-image'
      dockerImageVersion: 100
      restApiKey: '|ssm|my-service/prod/restApiKey'

Latest Taupage AMI

To make sure that a stack always uses the latest Taupage base AMI, one can fill a corresponding parameter with |LatestTaupageAmi|. This resolves to the id of the latest AMI available with name matching "Taupage-AMI-". Example:

region: eu-west-1
stacks:
  myapp:
    template-url: templates/my-app.yml
    parameters:
      dockerImage: 'my-image'
      dockerImageVersion: 100
      baseAmiId: '|LatestTaupageAmi|'

Keep Or Use Parameter Value

There might be a situation where general infrastructure changes are a manual step and application deployments are automated in a CLD pipeline. One common implementation of this is to trigger CloudFormation updates only changing a parameter for the applications version. The causes trouble with Cfn-Sphere considering the stack-configuration file as it's single source of truth. In fact Cfn-Sphere would overwrite the newer value of a parameter with whatever is stored in the config file. To overcome this limitation, one can use the |KeepOrUse| macro. This will use the given default value for stack creations and the last value for any update action on the stack.

Example:

region: eu-west-1
stacks:
  myapp:
    template-url: templates/my-app.yml
    parameters:
      dockerImage: 'my-image'
      dockerImageVersion: '|KeepOrUse|120'
      baseAmiId: '|LatestTaupageAmi|'
Add a custom footer
Add a custom sidebar
Clone this wiki locally