# Amazon CloudFormation deploy action reference
Executes an operation on an Amazon CloudFormation stack. A stack is a collection of Amazon resources that you can manage as a single unit. The resources in a stack are defined by the stack's Amazon CloudFormation template. A change set creates a comparison that can be viewed without altering the original stack. For information about the types of Amazon CloudFormation actions that can be performed on stacks and change sets, see the `ActionMode` parameter.
**Note:** The CodePipeline action for Amazon CloudFormation is not available in the China (Beijing) and China (Ningxia) Regions. To reference other available actions, see [Product and service integrations with CodePipeline](integrations.md).
To construct an error message for an Amazon CloudFormation action where a stack operation has failed, CodePipeline calls the Amazon CloudFormation `DescribeStackEvents` API. If an action IAM role has permission to access that API, the details about the first failed resource will be included in the CodePipeline error message. Otherwise, if the role policy does not have the appropriate permission, CodePipeline will ignore accessing the API and show a generic error message instead. To do this, the `cloudformation:DescribeStackEvents` permission must be added to the service role or other IAM roles for the pipeline.
If you do not want the resource details surfaced in the pipeline error messages, you can revoke this permission for the action IAM role by removing the `cloudformation:DescribeStackEvents` permission.
**Topics**
+ [Action type](#action-reference-CloudFormation-type)
+ [Configuration parameters](#action-reference-CloudFormation-config)
+ [Input artifacts](#action-reference-CloudFormation-input)
+ [Output artifacts](#action-reference-CloudFormation-output)
+ [Output variables](#action-reference-CloudFormation-variables)
+ [Service role permissions: Amazon CloudFormation action](#edit-role-cloudformation)
+ [Action declaration](#action-reference-CloudFormation-example)
+ [See also](#action-reference-CloudFormation-links)
## Action type
+ Category: `Deploy`
+ Owner: `AWS`
+ Provider: `CloudFormation`
+ Version: `1`
## Configuration parameters
**ActionMode**
Required: Yes
`ActionMode` is the name of the action Amazon CloudFormation performs on a stack or change set. The following action modes are available:
+ `CHANGE_SET_EXECUTE` executes a change set for the resource stack that is based on a set of specified resource updates. With this action, Amazon CloudFormation starts to alter the stack.
+ `CHANGE_SET_REPLACE` creates the change set, if it doesn't exist, based on the stack name and template that you submit. If the change set exists, Amazon CloudFormation deletes it, and then creates a new one.
+ `CREATE_UPDATE` creates the stack if it doesn't exist. If the stack exists, Amazon CloudFormation updates the stack. Use this action to update existing stacks. Unlike `REPLACE_ON_FAILURE`, if the stack exists and is in a failed state, CodePipeline won't delete and replace the stack.
+ `DELETE_ONLY` deletes a stack. If you specify a stack that doesn't exist, the action is completed successfully without deleting a stack.
+ `REPLACE_ON_FAILURE` creates a stack, if it doesn't exist. If the stack exists and is in a failed state, Amazon CloudFormation deletes the stack, and then creates a new stack. If the stack isn't in a failed state, Amazon CloudFormation updates it.
The stack is in a failed state when any of the following status types are displayed in Amazon CloudFormation:
+ `ROLLBACK_FAILED`
+ `CREATE_FAILED`
+ `DELETE_FAILED`
+ `UPDATE_ROLLBACK_FAILED`
Use this action to automatically replace failed stacks without recovering or troubleshooting them.
**Important**
We recommend that you use `REPLACE_ON_FAILURE` for testing purposes only because it might delete your stack.
**StackName**
Required: Yes
`StackName` is the name of an existing stack or a stack that you want to create.
**Capabilities**
Required: Conditional
Use of `Capabilities` acknowledges that the template might have the capabilities to create and update some resources on its own, and that these capabilities are determined based on the types of resources in the template.
This property is required if you have IAM resources in your stack template or you create a stack directly from a template containing macros. In order for the Amazon CloudFormation action to successfully operate in this way, you must explicitly acknowledge that you would like it to do so with one of the following capabilities:
+ `CAPABILITY_IAM`
+ `CAPABILITY_NAMED_IAM`
+ `CAPABILITY_AUTO_EXPAND`
You can specify more than one capability by using a comma (no space) between capabilities. The example in [Action declaration](#action-reference-CloudFormation-example) shows an entry with both the CAPABILITY\$1IAM and CAPABILITY\$1AUTO\$1EXPAND properties.
For more information about `Capabilities`, see the properties under [UpdateStack](https://docs.amazonaws.cn/AWSCloudFormation/latest/APIReference/API_UpdateStack.html) in the *Amazon CloudFormation API Reference*.
**ChangeSetName**
Required: Conditional
`ChangeSetName` is the name of an existing change set or a new change set that you want to create for the specified stack.
This property is required for the following action modes: CHANGE\$1SET\$1REPLACE and CHANGE\$1SET\$1EXECUTE. For all other action modes, this property is ignored.
**RoleArn**
Required: Conditional
The `RoleArn` is the ARN of the IAM service role that Amazon CloudFormation assumes when it operates on resources in the specified stack. `RoleArn` is not applied when executing a change set. If you do not use CodePipeline to create the change set, make sure that the change set or stack has an associated role.
This role must be in the same account as the role for the action that is running, as configured in the action declaration `RoleArn`.
This property is required for the following action modes:
+ CREATE\$1UPDATE
+ REPLACE\$1ON\$1FAILURE
+ DELETE\$1ONLY
+ CHANGE\$1SET\$1REPLACE
Amazon CloudFormation is given an S3-signed URL to the template; therefore, this `RoleArn` does not need permission to access the artifact bucket. However, the action `RoleArn` *does* need permission to access the artifact bucket, in order to generate the signed URL.
**TemplatePath**
Required: Conditional
`TemplatePath` represents the Amazon CloudFormation template file. You include the file in an input artifact to this action. The file name follows this format:
`Artifactname::TemplateFileName`
`Artifactname` is the input artifact name as it appears in CodePipeline. For example, a source stage with the artifact name of `SourceArtifact` and a `template-export.json` file name creates a `TemplatePath` name, as shown in this example:
```
"TemplatePath": "SourceArtifact::template-export.json"
```
This property is required for the following action modes:
+ CREATE\$1UPDATE
+ REPLACE\$1ON\$1FAILURE
+ CHANGE\$1SET\$1REPLACE
For all other action modes, this property is ignored.
The Amazon CloudFormation template file containing the template body has a minimum length of 1 byte and a maximum length of 1 MB. For Amazon CloudFormation deployment actions in CodePipeline, the maximum input artifact size is always 256 MB. For more information, see [Quotas in Amazon CodePipeline](limits.md) and [Amazon CloudFormation Limits](https://docs.amazonaws.cn/AWSCloudFormation/latest/UserGuide/cloudformation-limits.html).
**OutputFileName**
Required: No
Use `OutputFileName` to specify an output file name, such as `CreateStackOutput.json`, that CodePipeline adds to the pipeline output artifact for this action. The JSON file contains the contents of the `Outputs` section from the Amazon CloudFormation stack.
If you don't specify a name, CodePipeline doesn't generate an output file or artifact.
**ParameterOverrides**
Required: No
Parameters are defined in your stack template and allow you to provide values for them at the time of stack creation or update. You can use a JSON object to set parameter values in your template. (These values override those set in the template configuration file.) For more information about using parameter overrides, see [Configuration Properties (JSON Object)](https://docs.amazonaws.cn/AWSCloudFormation/latest/UserGuide/continuous-delivery-codepipeline-action-reference.html#w4363ab1c13c13b9).
We recommend that you use the template configuration file for most of your parameter values. Use parameter overrides only for values that aren't known until the pipeline is running. For more information, see [Using Parameter Override Functions with CodePipeline Pipelines](https://docs.amazonaws.cn/AWSCloudFormation/latest/UserGuide/continuous-delivery-codepipeline-parameter-override-functions.html) in the *Amazon CloudFormation User Guide*.
All parameter names must be present in the stack template.
**TemplateConfiguration**
Required: No
`TemplateConfiguration` is the template configuration file. You include the file in an input artifact to this action. It can contain template parameter values and a stack policy. For more information about the template configuration file format, see [Amazon CloudFormation Artifacts](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/continuous-delivery-codepipeline-cfn-artifacts.html).
The template configuration file name follows this format:
`Artifactname::TemplateConfigurationFileName`
`Artifactname` is the input artifact name as it appears in CodePipeline. For example, a source stage with the artifact name of `SourceArtifact` and a `test-configuration.json` file name creates a `TemplateConfiguration` name as shown in this example:
```
"TemplateConfiguration": "SourceArtifact::test-configuration.json"
```
## Input artifacts
+ **Number of artifacts:** `0 to 10`
+ **Description:** As input, the Amazon CloudFormation action optionally accepts artifacts for these purposes:
+ To provide the stack template file to execute. (See the `TemplatePath` parameter.)
+ To provide the template configuration file to use. (See the `TemplateConfiguration` parameter.) For more information about the template configuration file format, see [Amazon CloudFormation Artifacts](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/continuous-delivery-codepipeline-cfn-artifacts.html).
+ To provide the artifact for a Lambda function to be deployed as part of the Amazon CloudFormation stack.
## Output artifacts
+ **Number of artifacts:** `0 to 1`
+ **Description:** If the `OutputFileName` parameter is specified, there is an output artifact produced by this action that contains a JSON file with the specified name. The JSON file contains the contents of the Outputs section from the Amazon CloudFormation stack.
For more information about the outputs section you can create for your Amazon CloudFormation action, see [Outputs](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/outputs-section-structure.html).
## Output variables
When configured, this action produces variables that can be referenced by the action configuration of a downstream action in the pipeline. You configure an action with a namespace to make those variables available to the configuration of downstream actions.
For Amazon CloudFormation actions, variables are produced from any values designated in the `Outputs` section of a stack template. Note that the only CloudFormation action modes that generate outputs are those that result in creating or updating a stack, such as stack creation, stack updates, and change set execution. The corresponding action modes that generate variables are:
+ `CHANGE_SET_EXECUTE`
+ `CHANGE_SET_REPLACE`
+ `CREATE_UPDATE`
+ `REPLACE_ON_FAILURE`
For more information, see [Variables reference](reference-variables.md). For a tutorial that shows you how to create a pipeline with a CloudFormation deployment action in a pipeline that uses CloudFormation output variables, see [Tutorial: Create a pipeline that uses variables from Amazon CloudFormation deployment actions](tutorials-cloudformation-action.md).
## Service role permissions: Amazon CloudFormation action
When CodePipeline runs the action, the CodePipeline service role policy requires the following permissions, appropriately scoped down to the pipeline resource ARN in order to maintain access with least privilege. For example, add the following to your policy statement:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowCFNStackAccess",
"Effect": "Allow",
"Action": [
"cloudformation:CreateStack",
"cloudformation:UpdateStack",
"cloudformation:DeleteStack",
"cloudformation:DescribeStacks",
"cloudformation:DescribeStackResources",
"cloudformation:DescribeStackEvents",
"cloudformation:GetTemplate",
"cloudformation:DescribeChangeSet",
"cloudformation:CreateChangeSet",
"cloudformation:DeleteChangeSet",
"cloudformation:ExecuteChangeSet"
],
"Resource": [
"arn:aws-cn:cloudformation:*:111122223333:stack/[[cfnDeployStackNames]]/*"
]
},
{
"Sid": "ValidateTemplate",
"Effect": "Allow",
"Action": [
"cloudformation:ValidateTemplate"
],
"Resource": "*"
},
{
"Sid": "AllowIAMPassRole",
"Effect": "Allow",
"Action": [
"iam:PassRole"
],
"Resource": [
"arn:aws-cn:iam::111122223333:role/[[cfnExecutionRoles]]"
],
"Condition": {
"StringEqualsIfExists": {
"iam:PassedToService": [
"cloudformation.amazonaws.com"
]
}
}
}
]
}
```
------
Note that the `cloudformation:DescribeStackEvents` permission is optional. It allows the Amazon CloudFormation action to show a more detailed error message. This permission can be revoked from the IAM role if you don't want resource details surfaced in the pipeline error messages.
## Action declaration
------
#### [ YAML ]
```
Name: ExecuteChangeSet
ActionTypeId:
Category: Deploy
Owner: AWS
Provider: CloudFormation
Version: '1'
RunOrder: 2
Configuration:
ActionMode: CHANGE_SET_EXECUTE
Capabilities: CAPABILITY_NAMED_IAM,CAPABILITY_AUTO_EXPAND
ChangeSetName: pipeline-changeset
ParameterOverrides: '{"ProjectId": "my-project","CodeDeployRole": "CodeDeploy_Role_ARN"}'
RoleArn: CloudFormation_Role_ARN
StackName: my-project--lambda
TemplateConfiguration: 'my-project--BuildArtifact::template-configuration.json'
TemplatePath: 'my-project--BuildArtifact::template-export.yml'
OutputArtifacts: []
InputArtifacts:
- Name: my-project-BuildArtifact
```
------
#### [ JSON ]
```
{
"Name": "ExecuteChangeSet",
"ActionTypeId": {
"Category": "Deploy",
"Owner": "AWS",
"Provider": "CloudFormation",
"Version": "1"
},
"RunOrder": 2,
"Configuration": {
"ActionMode": "CHANGE_SET_EXECUTE",
"Capabilities": "CAPABILITY_NAMED_IAM,CAPABILITY_AUTO_EXPAND",
"ChangeSetName": "pipeline-changeset",
"ParameterOverrides": "{\"ProjectId\": \"my-project\",\"CodeDeployRole\": \"CodeDeploy_Role_ARN\"}",
"RoleArn": "CloudFormation_Role_ARN",
"StackName": "my-project--lambda",
"TemplateConfiguration": "my-project--BuildArtifact::template-configuration.json",
"TemplatePath": "my-project--BuildArtifact::template-export.yml"
},
"OutputArtifacts": [],
"InputArtifacts": [
{
"Name": "my-project-BuildArtifact"
}
]
},
```
------
## See also
The following related resources can help you as you work with this action.
+ [Configuration Properties Reference](https://docs.amazonaws.cn/AWSCloudFormation/latest/UserGuide/continuous-delivery-codepipeline-action-reference.html) – This reference chapter in the *Amazon CloudFormation User Guide* provides more descriptions and examples for these CodePipeline parameters.
+ [Amazon CloudFormation API Reference](https://docs.amazonaws.cn/AWSCloudFormation/latest/APIReference/) – The [CreateStack](https://docs.amazonaws.cn/AWSCloudFormation/latest/APIReference/API_CreateStack.html) parameter in the *Amazon CloudFormation API Reference* describes stack parameters for Amazon CloudFormation templates.