Home

Awesome

AWS CloudFormation CLI

The missing CloudFormation CLI.

Official cfncli is not designed to manage stacks at this point.

[TOC]

Introduction

awscfncli helps build and manage AWS CloudFormation stacks.

Highlights:

Install

Install from pypi:

pip install --user --pre awscfncli2

When install globally, use pipx is recommended:

pipx install awscfncli2

Usage

Quickstart

cfn-cli [OPTIONS...] COMMAND SUBCOMMAND [ARGS...]

To view a list of available subcommands, use:

cfn-cli COMMAND --help

Options:

Options can also be specified using environment variables:

CFN_STACK=Default.Table1 cfn-cli stack deploy

By default, cfn-cli tries to locate cfn-cli.yml or cfn-cli.yaml file in current directory, override this use -f.

Stack Selector

Individual stack can be selected using full qualified name:

cfn-cli -s Default.Table2 status

Or, select stacks use Unix globs:

cfn-cli -s Default.Table* status
cfn-cli -s Def*.Table1 status

If . is missing from stack selector, cfn-cli will assume stage name * is specified.

Commands

Use --help to see help on a particular command.

Auto Completion

Auto completion is supported by click_completion, supported shells are: bash, zsh , fish and Powershell.

To install auto completion, run this in target shell:

> cfn-cli --install-completion
fish completion installed in /Users/Bob/.config/fish/completions/cfn-cli.fish

Supported completion:

Automatic Packaging

If a template contains property which requires a S3 url or text block, Set stack Package parameter to True tells cfn-cli to package the resource automatically and upload to a S3 artifact bucket, and S3 object location is inserted into the resource location.

This feature is particular useful when your property is a lambda source code, SQL statements or some kind of configuration.

By default, the artifact bucket is awscfncli-${AWS_ACCOUNT_ID}-${AWS_RERION}, and it will be created automatically on first run. Override the default bucket using ArtifactStore parameter.

The following resource property are supported by awscfncli and official aws cloudformation package command:

To package a template build by awssamcli, point Template parameter to sam build output.

Configuration

awscfncli uses a YAML config file to manage which stacks to deploy and how to deploy them. By default, it is cfn-cli.yml.

Anatomy

The config is composed of the following elements, Version, Stages and Blueprints.

The following is a simple example of a typical config:

Version: 3

Stages:
  Default:
    DDB:
      Template: DynamoDB_Table.yaml
      Region: us-east-1
      Parameters:
        HashKeyElementName: id
    DDB2ndIdx:
      Template: DynamoDB_Secondary_Indexes.yaml
      Region: us-east-1
      StackPolicy: stack_policy.json
      ResourceTypes:
        - AWS::DynamoDB::Table
      Parameters:
        ReadCapacityUnits: 10

A stage could have multiple stacks. In the above example, Stage Default have two stacks DDB and DDB2ndIdx. Stack name could be customized and should contain only alpha and numbers.

Each stack may have the following attributes.

Blueprints and Inheritance

Blueprint serves as a template of a common stack. A stack could extends a stack and override its attributes with its own attributes.

For example, please refer to Blueprints Example

Stages and Ordering

Stage and stacks could be deployed according to the order you specified. Order numbers are positive integers. cfn-cli will deploy stacks in stages with lower order first and in each stage stacks with lower order will be deployed first.

    Stages:
        Stage1:
            Order: 1
            Stack1:
                Order: 1
            Stack2:
                Order: 2
        Stage2:
            Order: 2

For examples, please refer to Order Example

Cross Stack Reference

In many cases, a stack's input parameter depends on output from other stacks during deployment. Cross stack reference allows stacks collect their inputs from outputs form other stacks, including stacks deployed to other region and account.

An stack parameter can reference ouputs of another stack in same configuration file by using the following syntax:

Stack1:
    Parameters:
        VpcId: ${StageName.StackName.OutputName}

This feature make managing related cross-account and/or cross-region stacks much easier. See VPC peering and CodePipeline for example.

Note: Take care of the order of deployment so eferenced stack is deployed first.

Breaking Changes in 3.0

Generally only major version changes cli and config syntax, and support of last config version is gaunteered.

CLI

Breaking Changes in 2.1

CLI

Config

"Cross stack reference" feature requires version 3:

Version: 3
Stages:
  Default:
    ...

Parameter NotificationARNs, ResourceTypes, RollbackConfiguration are supported now but no changes is required if old config file is not using them.

Breaking Changes in 2.0

New configuration file supports multiple stages and stacks, to convert an 0.x configure file to current version, do following:

  1. Add following block to the head of conf file and indent the rest properly:
Version: 3
Stages:
  Default:
    << old config file >>
  1. Change any TemplateURL or TemplateBody parameter to Template:

Old:

Stack:
  TemplateURL:          https://s3.amazonaws.com/...
  Region:               us-east-1
  StackName:            SampleIAMUsersGroupsAndPolicies
  Capabilities:         [CAPABILITY_IAM]

New:

Version: 2
Stages:
  Default:
    Stack:
      Template:          https://s3.amazonaws.com/...
      Region:               us-east-1
      StackName:            SampleIAMUsersGroupsAndPolicies
      Capabilities:         [CAPABILITY_IAM]