AWS CloudFormation

Executes an operation on an AWS CloudFormation stack. A stack is a collection of AWS resources that you can manage as a single unit. The resources in a stack are defined by the stack's AWS CloudFormation template. A change set creates a comparison that can be viewed without altering the original stack. For information about the types of AWS CloudFormation actions that can be performed on stacks and change sets, see the ActionMode parameter.

To construct an error message for an AWS CloudFormation action where a stack operation has failed, CodePipeline calls the AWS 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.

Action type

• Category: Deploy

• Owner: AWS

• Provider: CloudFormation

• Version: 1

Configuration parameters

ActionMode

Required: Yes

ActionMode is the name of the action AWS 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, AWS 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, AWS CloudFormation deletes it, and then creates a new one.

• CREATE_UPDATE creates the stack if it doesn't exist. If the stack exists, AWS 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, AWS CloudFormation deletes the stack, and then creates a new stack. If the stack isn't in a failed state, AWS CloudFormation updates it.

  The stack is in a failed state when any of the following status types are displayed in AWS 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 AWS 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 shows an entry with both the CAPABILITY_IAM and CAPABILITY_AUTO_EXPAND properties.

For more information about Capabilities, see the properties under UpdateStack in the AWS 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_SET_REPLACE and CHANGE_SET_EXECUTE. For all other action modes, this property is ignored.

RoleArn

Required: Conditional

The RoleArn is the ARN of the IAM service role that AWS 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.

Note

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_UPDATE

• REPLACE_ON_FAILURE

• DELETE_ONLY

• CHANGE_SET_REPLACE

Note

AWS 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 AWS 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_UPDATE

• REPLACE_ON_FAILURE

• CHANGE_SET_REPLACE

For all other action modes, this property is ignored.

Note

The AWS CloudFormation template file containing the template body has a minimum length of 1 byte and a maximum length of 1 MB. For AWS CloudFormation deployment actions in CodePipeline, the maximum input artifact size is always 256 MB. For more information, see Quotas in AWS CodePipeline and AWS CloudFormation Limits.

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 AWS 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).

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 in the AWS CloudFormation User Guide.

Note

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 AWS CloudFormation Artifacts.

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 AWS 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 AWS CloudFormation Artifacts.

  • To provide the artifact for a Lambda function to be deployed as part of the AWS 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 AWS CloudFormation stack.

  For more information about the outputs section you can create for your AWS CloudFormation action, see Outputs.

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 AWS 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. 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 AWS CloudFormation deployment actions.

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 – This reference chapter in the AWS CloudFormation User Guide provides more descriptions and examples for these CodePipeline parameters.

• AWS CloudFormation API Reference – The CreateStack parameter in the AWS CloudFormation API Reference describes stack parameters for AWS CloudFormation templates.