The following command line examples demonstrate how to perform individual CloudFormation actions with the AWS CLI and PowerShell. These examples include only the most commonly used actions. For a complete list, see cloudformation in the AWS CLI Command Reference.
The examples in this guide use the convention of a backslash (\) to indicate that a long command line continues on the next line.
Topics
- Cancel a stack update
- Continue rolling back an update
- Create a stack
- Create a stack that includes transforms
- Delete a stack
- Describe stack events
- Describe a stack resource
- Describe stack resources
- Describe stacks
- Get a template
- List stack resources
- List stacks
- Update a stack
- Validate your template
- Upload local artifacts to an S3 bucket with the AWS CLI
Cancel a stack update
Use the cancel-update-stack
command to cancel a stack update. For more
information, see Cancel a stack update.
- AWS CLI
-
To cancel a stack update that is in progress
The following
cancel-update-stack
command cancels a stack update on themyteststack
stack:aws cloudformation cancel-update-stack --stack-name
myteststack
-
For API details, see CancelUpdateStack
in AWS CLI Command Reference.
-
Continue rolling back an update
Use the continue-update-rollback
command to continue rolling back an
update. For more information, see Continue rolling back an
update.
- AWS CLI
-
To retry an update rollback
The following
continue-update-rollback
example resumes a rollback operation from a previously failed stack update.aws cloudformation continue-update-rollback \ --stack-name
my-stack
This command produces no output.
-
For API details, see ContinueUpdateRollback
in AWS CLI Command Reference.
-
Create a stack
Use the create-stack
command to create a stack. You must provide the
stack name, the location of a valid template, and any input parameters. The parameter
key names are case sensitive. If you mistype a parameter key name, CloudFormation doesn't
create the stack and reports that the template doesn't contain that parameter.
By default, the describe-stacks
command returns parameter values. To
prevent sensitive parameter values such as passwords from being returned, include a
NoEcho
property set to TRUE
in your CloudFormation
template.
Important
Using the NoEcho
attribute does not mask any information stored in the following:
-
The
Metadata
template section. CloudFormation does not transform, modify, or redact any information you include in theMetadata
section. For more information, see CloudFormation template Metadata syntax. -
The
Outputs
template section. For more information, see CloudFormation template Outputs syntax. -
The
Metadata
attribute of a resource definition. For more information, see Metadata attribute.
We strongly recommend you do not use these mechanisms to include sensitive information, such as passwords or secrets.
Important
Rather than embedding sensitive information directly in your CloudFormation templates, we recommend you use dynamic parameters in the stack template to reference sensitive information that is stored and managed outside of CloudFormation, such as in the AWS Systems Manager Parameter Store or AWS Secrets Manager.
For more information, see the Do not embed credentials in your templates best practice.
The following examples show how to create a new stack with the specified name, template, and input parameters.
- AWS CLI
-
To create an AWS CloudFormation stack
The following
create-stacks
command creates a stack with the namemyteststack
using thesampletemplate.json
template:aws cloudformation create-stack --stack-name
myteststack
--template-bodyfile://sampletemplate.json
--parametersParameterKey=KeyPairName,ParameterValue=TestKey
ParameterKey=SubnetIDs,ParameterValue=SubnetID1\\,SubnetID2Output:
{ "StackId": "arn:aws:cloudformation:us-east-1:123456789012:stack/myteststack/466df9e0-0dff-08e3-8e2f-5088487c4896" }
For more information, see Stacks in the AWS CloudFormation User Guide.
-
For API details, see CreateStack
in AWS CLI Command Reference.
-
Alternatively, you can specify the AWS Systems Manager location of a template file.
The following create-stack
command creates a stack with the
name myteststack
using an AWS Systems Manager document for the template
URL.
aws cloudformation create-stack --stack-name
myteststack
\ --template-url"ssm-doc://arn:aws:ssm:us-east-1:123456789012:document/documentName"
Output:
{
"StackId": "arn:aws:cloudformation:us-east-1:123456789012:stack/myteststack/466df9e0-0dff-08e3-8e2f-5088487c4896"
}
Create a stack that includes transforms
Use the deploy
command to create a stack that includes transforms.
To create a stack from a template that includes transforms, you must use a change set.
Instead of creating a change set and then initiating it, use the deploy
command to combine these steps into a single command.
The following deploy
command creates a stack with the
specified name, template, and input parameters.
aws cloudformation deploy --stack-name
myteststack
\ --template/path_to_template/my-template.json
\ --parameter-overridesKey1=Value1 Key2=Value2
Delete a stack
Use the delete-stack
command to delete a stack. For more information, see
Delete a stack from the CloudFormation console.
- AWS CLI
-
To delete a stack
The following
delete-stack
example deletes the specified stack.aws cloudformation delete-stack \ --stack-name
my-stack
This command produces no output.
-
For API details, see DeleteStack
in AWS CLI Command Reference.
-
If the deletion fails and returns a DELETE_FAILED
state, you can choose
to delete the stack by force using the --deletion-mode
option. These are
the following values that can be used with deletion-mode
:
-
STANDARD
: Deletes the stack normally. This is the default deletion mode. -
FORCE_DELETE_STACK
: Deletes the stack and skips all resources that are failing to delete.
The following delete-stack
command force deletes the
stack using the
myteststack
FORCE_DELETE_STACK
value with the
deletion-mode
parameter:
aws cloudformation delete-stack --stack-name
myteststack
\ --deletion-mode FORCE_DELETE_STACK
This command produces no output.
After using FORCE_DELETE_STACK
, you can use the
list-stack-resources
command to list the resources that were skipped
during the stack deletion process. The retained resources will show a DELETE_SKIPPED
status. For more information, see List stack resources.
Describe stack events
Use the describe-stack-events
command to describe stack events. For more
information, see Monitor stack progress.
- AWS CLI
-
To describe stack events
The following
describe-stack-events
example displays the 2 most recent events for the specified stack.aws cloudformation describe-stack-events \ --stack-name
my-stack
\ --max-items2
{
"StackEvents":[
{
"StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/my-stack/d0a825a0-e4cd-xmpl-b9fb-061c69e99204", "EventId": "4e1516d0-e4d6-xmpl-b94f-0a51958a168c", "StackName": "my-stack", "LogicalResourceId": "my-stack", "PhysicalResourceId": "arn:aws:cloudformation:us-west-2:123456789012:stack/my-stack/d0a825a0-e4cd-xmpl-b9fb-061c69e99204", "ResourceType": "AWS::CloudFormation::Stack", "Timestamp": "2019-10-02T05:34:29.556Z", "ResourceStatus":"UPDATE_COMPLETE"
},
{
"StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/my-stack/d0a825a0-e4cd-xmpl-b9fb-061c69e99204", "EventId": "4dd3c810-e4d6-xmpl-bade-0aaf8b31ab7a", "StackName": "my-stack", "LogicalResourceId": "my-stack", "PhysicalResourceId": "arn:aws:cloudformation:us-west-2:123456789012:stack/my-stack/d0a825a0-e4cd-xmpl-b9fb-061c69e99204", "ResourceType": "AWS::CloudFormation::Stack", "Timestamp": "2019-10-02T05:34:29.127Z", "ResourceStatus":"UPDATE_COMPLETE_CLEANUP_IN_PROGRESS"
}
],
"NextToken":"eyJOZXh0VG9XMPLiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAyfQ=="
}
-
For API details, see DescribeStackEvents
in AWS CLI Command Reference.
-
Describe a stack resource
- AWS CLI
-
To get information about a stack resource
The following
describe-stack-resource
example displays details for the resource namedMyFunction
in the specified stack.aws cloudformation describe-stack-resource \ --stack-name
MyStack
\ --logical-resource-idMyFunction
Output:
{ "StackResourceDetail": { "StackName": "MyStack", "StackId": "arn:aws:cloudformation:us-east-2:123456789012:stack/MyStack/d0a825a0-e4cd-xmpl-b9fb-061c69e99204", "LogicalResourceId": "MyFunction", "PhysicalResourceId": "my-function-SEZV4XMPL4S5", "ResourceType": "AWS::Lambda::Function", "LastUpdatedTimestamp": "2019-10-02T05:34:27.989Z", "ResourceStatus": "UPDATE_COMPLETE", "Metadata": "{}", "DriftInformation": { "StackResourceDriftStatus": "IN_SYNC" } } }
-
For API details, see DescribeStackResource
in AWS CLI Command Reference.
-
Describe stack resources
- AWS CLI
-
To get information about a stack resource
The following
describe-stack-resources
example displays details for the resources in the specified stack.aws cloudformation describe-stack-resources \ --stack-name
my-stack
Output:
{ "StackResources": [ { "StackName": "my-stack", "StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/my-stack/d0a825a0-e4cd-xmpl-b9fb-061c69e99204", "LogicalResourceId": "bucket", "PhysicalResourceId": "my-stack-bucket-1vc62xmplgguf", "ResourceType": "AWS::S3::Bucket", "Timestamp": "2019-10-02T04:34:11.345Z", "ResourceStatus": "CREATE_COMPLETE", "DriftInformation": { "StackResourceDriftStatus": "IN_SYNC" } }, { "StackName": "my-stack", "StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/my-stack/d0a825a0-e4cd-xmpl-b9fb-061c69e99204", "LogicalResourceId": "function", "PhysicalResourceId": "my-function-SEZV4XMPL4S5", "ResourceType": "AWS::Lambda::Function", "Timestamp": "2019-10-02T05:34:27.989Z", "ResourceStatus": "UPDATE_COMPLETE", "DriftInformation": { "StackResourceDriftStatus": "IN_SYNC" } }, { "StackName": "my-stack", "StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/my-stack/d0a825a0-e4cd-xmpl-b9fb-061c69e99204", "LogicalResourceId": "functionRole", "PhysicalResourceId": "my-functionRole-HIZXMPLEOM9E", "ResourceType": "AWS::IAM::Role", "Timestamp": "2019-10-02T04:34:06.350Z", "ResourceStatus": "CREATE_COMPLETE", "DriftInformation": { "StackResourceDriftStatus": "IN_SYNC" } } ] }
-
For API details, see DescribeStackResources
in AWS CLI Command Reference.
-
Describe stacks
- AWS CLI
-
To describe AWS CloudFormation stacks
The following
describe-stacks
command shows summary information for themyteststack
stack:aws cloudformation describe-stacks --stack-name
myteststack
Output:
{ "Stacks": [ { "StackId": "arn:aws:cloudformation:us-east-1:123456789012:stack/myteststack/466df9e0-0dff-08e3-8e2f-5088487c4896", "Description": "AWS CloudFormation Sample Template S3_Bucket: Sample template showing how to create a publicly accessible S3 bucket. **WARNING** This template creates an S3 bucket. You will be billed for the AWS resources used if you create a stack from this template.", "Tags": [], "Outputs": [ { "Description": "Name of S3 bucket to hold website content", "OutputKey": "BucketName", "OutputValue": "myteststack-s3bucket-jssofi1zie2w" } ], "StackStatusReason": null, "CreationTime": "2013-08-23T01:02:15.422Z", "Capabilities": [], "StackName": "myteststack", "StackStatus": "CREATE_COMPLETE", "DisableRollback": false } ] }
For more information, see Stacks in the AWS CloudFormation User Guide.
-
For API details, see DescribeStacks
in AWS CLI Command Reference.
-
Get a template
- AWS CLI
-
To view the template body for an AWS CloudFormation stack
The following
get-template
command shows the template for themyteststack
stack:aws cloudformation get-template --stack-name
myteststack
Output:
{ "TemplateBody": { "AWSTemplateFormatVersion": "2010-09-09", "Outputs": { "BucketName": { "Description": "Name of S3 bucket to hold website content", "Value": { "Ref": "S3Bucket" } } }, "Description": "AWS CloudFormation Sample Template S3_Bucket: Sample template showing how to create a publicly accessible S3 bucket. **WARNING** This template creates an S3 bucket. You will be billed for the AWS resources used if you create a stack from this template.", "Resources": { "S3Bucket": { "Type": "AWS::S3::Bucket", "Properties": { "AccessControl": "PublicRead" } } } } }
-
For API details, see GetTemplate
in AWS CLI Command Reference.
-
List stack resources
- AWS CLI
-
To list resources in a stack
The following command displays the list of resources in the specified stack.
aws cloudformation list-stack-resources \ --stack-name
my-stack
Output:
{ "StackResourceSummaries": [ { "LogicalResourceId": "bucket", "PhysicalResourceId": "my-stack-bucket-1vc62xmplgguf", "ResourceType": "AWS::S3::Bucket", "LastUpdatedTimestamp": "2019-10-02T04:34:11.345Z", "ResourceStatus": "CREATE_COMPLETE", "DriftInformation": { "StackResourceDriftStatus": "IN_SYNC" } }, { "LogicalResourceId": "function", "PhysicalResourceId": "my-function-SEZV4XMPL4S5", "ResourceType": "AWS::Lambda::Function", "LastUpdatedTimestamp": "2019-10-02T05:34:27.989Z", "ResourceStatus": "UPDATE_COMPLETE", "DriftInformation": { "StackResourceDriftStatus": "IN_SYNC" } }, { "LogicalResourceId": "functionRole", "PhysicalResourceId": "my-functionRole-HIZXMPLEOM9E", "ResourceType": "AWS::IAM::Role", "LastUpdatedTimestamp": "2019-10-02T04:34:06.350Z", "ResourceStatus": "CREATE_COMPLETE", "DriftInformation": { "StackResourceDriftStatus": "IN_SYNC" } } ] }
-
For API details, see ListStackResources
in AWS CLI Command Reference.
-
List stacks
Use the list-stacks
command to list stacks. To list only stacks with the
specified status codes, include the --stack-status-filter
option. You can
specify one or more stack status codes for the --stack-status-filter
option. For more information, see Stack status
codes.
- AWS CLI
-
To list AWS CloudFormation stacks
The following
list-stacks
command shows a summary of all stacks that have a status ofCREATE_COMPLETE
:aws cloudformation list-stacks --stack-status-filter
CREATE_COMPLETE
Output:
[ { "StackId": "arn:aws:cloudformation:us-east-1:123456789012:stack/myteststack/466df9e0-0dff-08e3-8e2f-5088487c4896", "TemplateDescription": "AWS CloudFormation Sample Template S3_Bucket: Sample template showing how to create a publicly accessible S3 bucket. **WARNING** This template creates an S3 bucket. You will be billed for the AWS resources used if you create a stack from this template.", "StackStatusReason": null, "CreationTime": "2013-08-26T03:27:10.190Z", "StackName": "myteststack", "StackStatus": "CREATE_COMPLETE" } ]
-
For API details, see ListStacks
in AWS CLI Command Reference.
-
Update a stack
Use the update-stack
command to directly update a stack. You specify the
stack, and parameter values and capabilities that you want to update, and, if you want
use an updated template, the name of the template. For more information, see Update stacks directly.
- AWS CLI
-
To update AWS CloudFormation stacks
The following
update-stack
command updates the template and input parameters for themystack
stack:aws cloudformation update-stack --stack-name
mystack
--template-urlhttps://s3.amazonaws.com/sample/updated.template
--parametersParameterKey=KeyPairName,ParameterValue=SampleKeyPair
ParameterKey=SubnetIDs,ParameterValue=SampleSubnetID1\\,SampleSubnetID2The following
update-stack
command updates just theSubnetIDs
parameter value for themystack
stack. If you don't specify a parameter value, the default value that is specified in the template is used:aws cloudformation update-stack --stack-name
mystack
--template-urlhttps://s3.amazonaws.com/sample/updated.template
--parametersParameterKey=KeyPairName,UsePreviousValue=true
ParameterKey=SubnetIDs,ParameterValue=SampleSubnetID1\\,UpdatedSampleSubnetID2The following
update-stack
command adds two stack notification topics to themystack
stack:aws cloudformation update-stack --stack-name
mystack
--use-previous-template --notification-arns"arn:aws:sns:use-east-1:123456789012:mytopic1"
"arn:aws:sns:us-east-1:123456789012:mytopic2"
For more information, see AWS CloudFormation stack updates in the AWS CloudFormation User Guide.
-
For API details, see UpdateStack
in AWS CLI Command Reference.
-
Note
To remove all notifications, specify for []
for the
--notification-arns
option.
Validate your template
Use the validate-template
command to check your template file for syntax
errors.
During validation, CloudFormation first checks if the template is valid JSON. If it isn't, CloudFormation checks if the template is valid YAML. If both checks fail, CloudFormation returns a template validation error.
- AWS CLI
-
To validate an AWS CloudFormation template
The following
validate-template
command validates thesampletemplate.json
template:aws cloudformation validate-template --template-body
file://sampletemplate.json
Output:
{ "Description": "AWS CloudFormation Sample Template S3_Bucket: Sample template showing how to create a publicly accessible S3 bucket. **WARNING** This template creates an S3 bucket. You will be billed for the AWS resources used if you create a stack from this template.", "Parameters": [], "Capabilities": [] }
For more information, see Working with AWS CloudFormation Templates in the AWS CloudFormation User Guide.
-
For API details, see ValidateTemplate
in AWS CLI Command Reference.
-
The following is an example response that produces a validation error.
{
"ResponseMetadata": {
"RequestId": "4ae33ec0-1988-11e3-818b-e15a6df955cd"
},
"Errors": [
{
"Message": "Template format error: JSON not well-formed. (line 11, column 8)",
"Code": "ValidationError",
"Type": "Sender"
}
],
"Capabilities": [],
"Parameters": []
}
A client error (ValidationError) occurred: Template format error: JSON not well-formed. (line 11, column 8)
Note
The validate-template
command is designed to check only the syntax of
your template. It does not ensure that the property values that you have specified
for a resource are valid for that resource. Nor does it determine the number of
resources that will exist when the stack is created.
To check the operational validity, you need to attempt to create the stack. There is no sandbox or test area for AWS CloudFormation stacks, so you are charged for the resources you create during testing.
Example availability
Can't find what you need? Request a new example by using the Provide feedback link at the bottom of this page.