The missing CloudFormation CLI.
Official
cfncliis not designed to manage stacks at this point.
[TOC]
awscfncli helps build and manage AWS CloudFormation stacks.
Highlights:
- Manage stacks in different accounts and regions use single YAML config file.
- Cross-stack parameter reference works cross-region and cross-account.
- Organize stack using stages and blueprints.
- Automatically package and upload template resources.
- Push button SAM deployment using
stack synccommand. - Display and track stack events in the CLI.
- List stack resources, outputs and exports in the CLI.
Install from pypi:
pip install --user --pre awscfncli2
When install globally, use pipx is recommended:
pipx install awscfncli2
cfn-cli [OPTIONS...] COMMAND SUBCOMMAND [ARGS...]
To view a list of available subcommands, use:
cfn-cli COMMAND --help
Options:
-f, --file: Specify an alternate config file.-s, --stack: Specify stacks to operate on, defined bySTAGE_NAME.STACK_NAME, default value is*, which means all stacks in all stages.--profile: Override AWS profile specified in the config or environment variableAWS_PROFILE.--region: Override AWS region specified in the config.--artifact-store: Override bucket used for template transform/packaging specified in the config.--verbose: Be more verbose.
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.
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.
Use --help to see help on a particular command.
generate- Generate sample configuration file.status- Print stack status and resources.validate- Validate template file.stack- Stack operations.sync-Apply changes using ChangeSetsdeploy- Deploy new stacks.update- Update existing stacks.tail- Print stack events.delete- Delete stacks.cancel- Cancel stack update.
drift- Drift detection.detect- Detect stack drifts.diff- Show stack resource drifts.
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:
-
Commands and sub commands:
> cfn-cli drift d<TAB><TAB> detect (Detect stack drifts.) diff (Show stack resource drifts.) -
Options and parameters:
> cfn-cli stack deploy --<TAB> <TAB> --disable-rollback (Disable rollback if stack creation failed. You can specify ei…) --help (Show this message and exit.) --ignore-existing (Don't exit with error if the stack already exists.) --no-wait (Exit immediately after deploy is started.) --on-failure (Determines what action will be taken if stack creation fails. This …) --timeout-in-minutes (The amount of time in minutes that can pass before the stac…) -
Parameter choices:
> cfn-cli stack deploy --on-failure <TAB> <TAB> DELETE DO_NOTHING ROLLBACK -
Dynamic complete for
--profileby search profile name inawscliconfig:> cfn-cli -p <TAB><TAB> default prod staging -
Dynamic complete for
--stackby search stack name incfn-cliconfig:> cfn-cli -s <TAB><TAB> Develop.ApiBackend-Develop (ApiBackend-Develop) Production.ApiBackend-Production (ApiBackend-Production) Staging.ApiBackend-Staging (ApiBackend-Staging)
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:
BodyS3Locationproperty for theAWS::ApiGateway::RestApiresourceCodeproperty for theAWS::Lambda::FunctionresourceCodeUriproperty for theAWS::Serverless::FunctionresourceContentUriproperty for theAWS::Serverless::LayerVersionresourceDefinitionS3Locationproperty for theAWS::AppSync::GraphQLSchemaresourceRequestMappingTemplateS3Locationproperty for theAWS::AppSync::ResolverresourceResponseMappingTemplateS3Locationproperty for theAWS::AppSync::ResolverresourceDefinitionUriproperty for theAWS::Serverless::ApiresourceLocationparameter for theAWS::IncludetransformSourceBundleproperty for theAWS::ElasticBeanstalk::ApplicationVersionresourceTemplateURLproperty for theAWS::CloudFormation::StackresourceCommand.ScriptLocationproperty for theAWS::Glue::Jobresource
To package a template build by
awssamcli, pointTemplateparameter tosam buildoutput.
awscfncli uses a YAML config file to manage which stacks to deploy and how to deploy them. By default,
it is cfn-cli.yml.
The config is composed of the following elements, Version, Stages
and Blueprints.
Version(required): Version of cfn-cli config, support 2 and 3 now.Stages(required): Definition of the stack to be deployed.Blueprints(optional): Template of the stack.
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: 10A 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.
- Attributes introduced by
awscfncli:Profile: Profile name of your aws credentialRegion: Eg. us-east-1Package: Automatically package your template or notArtifactStore: Name of S3 bucket to store packaged filesOrder: Deployment order of stacksExtends: Extend a blueprint
- Attributes introduced by
boto3:- Please refer to Boto3 Create Stack
Blueprint serves as a template of a common stack. A stack could extends a stack and override its attributes with its own attributes.
-
Inheritance behaviors:
- scalar value: replace
- dict value: update
- list value: extend
-
Special attributes:
Capabilities: replace
For example, please refer to Blueprints Example
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.
- Stage Order
- Stack Order
Stages:
Stage1:
Order: 1
Stack1:
Order: 1
Stack2:
Order: 2
Stage2:
Order: 2For examples, please refer to Order Example
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.
Generally only major version changes cli and config syntax, and support of last config version is gaunteered.
stack describeis depecated, usestatusinstead.syncnow defaults to--confirm, use--no-confirmto overwrite this.
cfnis renamed tocfn-clito avoid conflict withtroposphere.templatecommand is removed.changesetcommand is removed, replaced bysynccommand.- Because config file supports multiple stages and stacks, stack selector must be specified when you want to operate a subset of stacks.
"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.
New configuration file supports multiple stages and stacks, to convert an 0.x configure file to current version, do following:
- Add following block to the head of conf file and indent the rest properly:
Version: 3
Stages:
Default:
<< old config file >>- Change any
TemplateURLorTemplateBodyparameter toTemplate:
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]
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent