"Deploy AWS CloudFormation stack" action reference

The following is the action definition YAML reference for the Deploy AWS CloudFormation stack action. To learn how to use this action, see Adding the "Deploy AWS CloudFormation stack" action.

Note

Most of the YAML properties that follow have corresponding UI elements in the visual editor. To look up a UI element, use Ctrl+F. The element will be listed with its associated YAML property.


# The workflow definition starts here.
# See Top-level properties for details.
        
Name: MyWorkflow
SchemaVersion: 1.0 
Actions:

# The action definition starts here.    
  DeployCloudFormationStack:  
    Identifier: aws/cfn-deploy@v1
    DependsOn:
      - build-action
    Compute:  
      Type: EC2 | Lambda
      Fleet: fleet-name
    Timeout: timeout-minutes
    Environment:
      Name: environment-name
      Connections:
        - Name: account-connection-name
          Role: DeployRole
    Inputs:
      Sources:
        - source-name-1
      Artifacts:
        - CloudFormation-artifact
    Configuration:
      name: stack-name
      region: us-west-2
      template: template-path
      role-arn: arn:aws:iam::123456789012:role/StackRole        
      capabilities: CAPABILITY_IAM,CAPABILITY_NAMED_IAM,CAPABILITY_AUTO_EXPAND
      parameter-overrides: KeyOne=ValueOne,KeyTwo=ValueTwo | path-to-JSON-file
      no-execute-changeset: 1|0
      fail-on-empty-changeset: 1|0
      disable-rollback: 1|0
      termination-protection: 1|0
      timeout-in-minutes: minutes
      notification-arns: arn:aws:sns:us-east-1:123456789012:MyTopic,arn:aws:sns:us-east-1:123456789012:MyOtherTopic
      monitor-alarm-arns: arn:aws:cloudwatch::123456789012:alarm/MyAlarm,arn:aws:cloudwatch::123456789012:alarm/MyOtherAlarm
      monitor-timeout-in-minutes: minutes       
      tags: '[{"Key":"MyKey1","Value":"MyValue1"},{"Key":"MyKey2","Value":"MyValue2"}]'

DeployCloudFormationStack

(Required)

Specify the name of the action. All action names must be unique within the workflow. Action names are limited to alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (_). Spaces are not allowed. You cannot use quotation marks to enable special characters and spaces in action names.

Default: DeployCloudFormationStack_nn.

Corresponding UI: Configuration tab/Action display name

Identifier

(DeployCloudFormationStack/Identifier)

(Required)

Identifies the action. Do not change this property unless you want to change the version. For more information, see Working with action versions.

Default: aws/cfn-deploy@v1.

Corresponding UI: Workflow diagram/DeployCloudFormationStack_nn/aws/cfn-deploy@v1 label

DependsOn

(DeployCloudFormationStack/DependsOn)

(Optional)

Specify an action, action group, or gate that must run successfully in order for this action to run.

For more information about the 'depends on' functionality, see Configuring actions to depend on other actions.

Corresponding UI: Inputs tab/Depends on - optional

Compute

(DeployCloudFormationStack/Compute)

(Optional)

The computing engine used to run your workflow actions. You can specify compute either at the workflow level or at the action level, but not both. When specified at the workflow level, the compute configuration applies to all actions defined in the workflow. At the workflow level, you can also run multiple actions on the same instance. For more information, see Sharing compute across actions.

Corresponding UI: none

Type

(DeployCloudFormationStack/Compute/Type)

(Required if Compute is included)

The type of compute engine. You can use one of the following values:

EC2 (visual editor) or EC2 (YAML editor)

Optimized for flexibility during action runs.
Lambda (visual editor) or Lambda (YAML editor)

Optimized action start-up speeds.

For more information about compute types, see About compute types.

Corresponding UI: Configuration tab/Advanced - optional/Compute type

Fleet

(DeployCloudFormationStack/Compute/Fleet)

(Optional)

Specify the machine or fleet that will run your workflow or workflow actions. With on-demand fleets, when an action starts, the workflow provisions the resources it needs, and the machines are destroyed when the action finishes. Examples of on-demand fleets: Linux.x86-64.Large, Linux.x86-64.XLarge. For more information about on-demand fleets, see On-demand fleet properties.

With provisioned fleets, you configure a set of dedicated machines to run your workflow actions. These machines remain idle, ready to process actions immediately. For more information about provisioned fleets, see Provisioned fleet properties.

If Fleet is omitted, the default is Linux.x86-64.Large.

Corresponding UI: Configuration tab/Advanced - optional/Compute fleet

Timeout

(DeployCloudFormationStack/Timeout)

(Optional)

Specify the amount of time in minutes (YAML editor), or hours and minutes (visual editor), that the action can run before CodeCatalyst ends the action. The minimum is 5 minutes and the maximum is described in Quotas for workflows in CodeCatalyst. The default timeout is the same as the maximum timeout.

Corresponding UI: Configuration tab/Timeout in minutes - optional

Environment

(DeployCloudFormationStack/Environment)

(Required)

Specify the CodeCatalyst environment to use with the action.

For more information about environments, see Working with environments and Creating an environment.

Corresponding UI: Configuration tab/'Environment/account/role'/Environment

Name

(DeployCloudFormationStack/Environment/Name)

(Required if Environment is included)

Specify the name of an existing environment that you want to associate with the action.

Corresponding UI: Configuration tab/'Environment/account/role'/Environment

Connections

(DeployCloudFormationStack/Environment/Connections)

(Required if Environment is included)

Specify the account connection to associate with the action. You can specify a maximum of one account connection under Environment.

For more information about account connections, see Administering AWS accounts for a space. For information about how to associate an account connection with your environment, see Creating an environment.

Corresponding UI: Configuration tab/'Environment/account/role'/AWS account connection

Name

(DeployCloudFormationStack/Environment/Connections/Name)

(Required)

Specify the name of the account connection.

Corresponding UI: Configuration tab/'Environment/account/role'/AWS account connection

Role

(DeployCloudFormationStack/Environment/Connections/Role)

(Required)

Specify the name of the IAM role that the Deploy AWS CloudFormation stack action uses to access AWS and the AWS CloudFormation service.

Make sure this role includes the following policies:

The following permissions policy:

Warning

Limit the permissions to those shown in the following policy. Using a role with broader permissions might pose a security risk.


{
    "Version": "2012-10-17",
    "Statement": [{
    "Action": [
        "cloudformation:CreateStack",
        "cloudformation:DeleteStack",
        "cloudformation:Describe*",
        "cloudformation:UpdateStack",
        "cloudformation:CreateChangeSet",
        "cloudformation:DeleteChangeSet",
        "cloudformation:ExecuteChangeSet",
        "cloudformation:SetStackPolicy",
        "cloudformation:ValidateTemplate",
        "cloudformation:List*",
        "iam:PassRole"
    ],
    "Resource": "*",
    "Effect": "Allow"
}]
}

Note

The first time the role is used, use the following wildcard in the resource policy statement and then scope down the policy with the resource name after it is available.


"Resource": "*"

The following custom trust policy:


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "",
            "Effect": "Allow",
            "Principal": {
                "Service":  [
                   "codecatalyst-runner.amazonaws.com",
                   "codecatalyst.amazonaws.com"
                 ]
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

Make sure that this role is added to the account connection in your space. To learn more about adding an IAM role to an account connection, see Adding IAM roles to account connections.

Note

You can specify the name of the CodeCatalystWorkflowDevelopmentRole-spaceName role here, if you'd like. For more information about this role, see Creating the CodeCatalystWorkflowDevelopmentRole-spaceName role for your account and space. Understand that the CodeCatalystWorkflowDevelopmentRole-spaceName role has very broad permissions which may pose a security risk. We recommend that you only use this role in tutorials and scenarios where security is less of a concern.

Corresponding UI: Configuration tab/'Environment/account/role'/Role

Inputs

(DeployCloudFormationStack/Inputs)

(Optional)

The Inputs section defines the data that the DeployCloudFormationStack needs during a workflow run.

Note

A maximum of four inputs (one source and three artifacts) are allowed per Deploy AWS CloudFormation stack action.

If you need to refer to files residing in different inputs (say a source and an artifact), the source input is the primary input, and the artifact is the secondary input. References to files in secondary inputs take a special prefix to distiguish them from the primary. For details, see Example: Referencing files in multiple artifacts.

Corresponding UI: Inputs tab

Sources

(DeployCloudFormationStack/Inputs/Sources)

(Required if your CloudFormation or AWS SAM template is stored in a source repository)

If your CloudFormation or AWS SAM template is stored in a source repository, specify the label of that source repository. Currently, the only supported label is WorkflowSource.

If your CloudFormation or AWS SAM template is not contained within a source repository, it must reside in an artifact generated by another action, or in an Amazon S3 bucket.

For more information about sources, see Working with sources.

Corresponding UI: Inputs tab/Sources - optional

Artifacts - input

(DeployCloudFormationStack/Inputs/Artifacts)

(Required if your CloudFormation or AWS SAM template is stored in an output artifact from a previous action)

If the CloudFormation or AWS SAM template that you want to deploy is contained in an artifact generated by a previous action, specify that artifact here. If your CloudFormation template is not contained within an artifact, it must reside in your source repository or in an Amazon S3 bucket.

For more information about artifacts, including examples, see Working with artifacts.

Corresponding UI: Configuration tab/Artifacts - optional

Configuration

(DeployCloudFormationStack/Configuration)

(Required)

A section where you can define the configuration properties of the action.

Corresponding UI: Configuration tab

name

(DeployCloudFormationStack/Configuration/name)

(Required)

Specify a name for the CloudFormation stack that the Deploy AWS CloudFormation stack action creates or updates.

Corresponding UI: Configuration tab/Stack name

region

(DeployCloudFormationStack/Configuration/region)

(Required)

Specify the AWS Region into which the stack will be deployed. For a list of Region codes, see Regional endpoints.

Corresponding UI: Configuration tab/Stack region

template

(DeployCloudFormationStack/Configuration/template)

(Required)

Specify the name and path to your CloudFormation or AWS SAM template file. The template can be in JSON or YAML format, and can reside in a source repository, an artifact from a previous action, or an Amazon S3 bucket. If the template file is in a source repository or artifact, the path is relative to the source or artifact root. If the template is in an Amazon S3 bucket, the path is the template's Object URL value.

Examples:

./MyFolder/MyTemplate.json

MyFolder/MyTemplate.yml

https://MyBucket.s3.us-west-2.amazonaws.com/MyTemplate.yml

Note

You may need to add a prefix to the template's file path to indicate which artifact or source to find it in. For more information, see Referencing files in a source repository and Referencing files in an artifact.

Corresponding UI: Configuration tab/Template

role-arn

(DeployCloudFormationStack/Configuration/role-arn)

(Required)

Specify the Amazon Resource Name (ARN) of the stack role. CloudFormation uses this role to access and modify resources in your stack. For example: arn:aws:iam::123456789012:role/StackRole.

Make sure the stack role includes:

One or more permissions policies. The policies depend on the resources you have in your stack. For example, if your stack includes an AWS Lambda function, you need to add permissions that grant access to Lambda. If you followed the tutorial described in Tutorial: Deploy a serverless application using AWS CloudFormation, it includes a procedure titled, To create a stack role that lists the permissions that the stack role needs if you're deploying a typical serverless application stack.

Warning
Limit the permissions to those required by the CloudFormation service to access resources in your stack. Using a role with broader permissions might pose a security risk.

The following trust policy:


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "",
            "Effect": "Allow",
            "Principal": {
                "Service": "cloudformation.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

Optionally, associate this role with your account connection. To learn more about associating an IAM role with an account connection, see Adding IAM roles to account connections. If you do not associate the stack role with the account connection, then the stack role will not appear in the Stack role drop-down list in the visual editor; however, the role ARN can still be specified in the role-arn field using the YAML editor.

Note

Corresponding UI: Configuration tab/Stack role - optional

capabilities

(DeployCloudFormationStack/Configuration/capabilities)

(Required)

Specify a list of IAM capabilities that are required to allow AWS CloudFormation to create certain stacks. In most cases, you can leave capabilities with the default value of CAPABILITY_IAM,CAPABILITY_NAMED_IAM,CAPABILITY_AUTO_EXPAND.

If you see ##[error] requires capabilities: [capability-name] in your Deploy AWS CloudFormation stack action's logs, see How do I fix IAM capabilities errors? for information about how to fix the problem.

For more information about IAM capabilities, see Acknowledging IAM resources in AWS CloudFormation templates in the IAM User Guide.

Corresponding UI: Configuration tab/Advanced/Capabilities

parameter-overrides

(DeployCloudFormationStack/Configuration/parameter-overrides)

(Optional)

Specify parameters in your AWS CloudFormation or AWS SAM template that don't have default values, or for which you want to specify non-default values. For more information about parameters, see Parameters in the AWS CloudFormation User Guide.

The parameter-overrides property accepts:

A JSON file containing the parameters and values.
A comma-separate list of parameters and values.

To specify a JSON file

Make sure the JSON file uses one of the following syntaxes:
```
{
  "Parameters": {
    "Param1": "Value1",
    "Param2": "Value2",
    ...
  }
}
```
Or...
```
[
  {
     "ParameterKey": "Param1",
     "ParameterValue": "Value1"
  },
  ...
]
```
(There are other syntaxes, but they are not supported by CodeCatalyst at the time of writing.) For more information about specifying CloudFormation parameters in a JSON file, see Supported JSON syntax in the AWS CLI Command Reference.

Specify the path to the JSON file using one of the following formats:

If your JSON file resides in an output artifact from a previous action, use:

file:///artifacts/current-action-name/output-artifact-name/path-to-json-file

See Example 1 for details.

If your JSON file resides in your source repository, use:

file:///sources/WorkflowSource/path-to-json-file

See Example 2 for details.

Example 1 – The JSON file resides in an output artifact


##My workflow YAML
...
Actions:
  MyBuildAction:
    Identifier: aws/build@v1
    Outputs:
      Artifacts:
        - Name: ParamArtifact
          Files:
            - params.json
    Configuration:
    ...
  MyDeployCFNStackAction:
    Identifier: aws/cfn-deploy@v1
    Configuration:
      parameter-overrides: file:///artifacts/MyDeployCFNStackAction/ParamArtifact/params.json

Example 2 – The JSON file resides in your source repository, in a folder called my/folder


##My workflow YAML
...
Actions:
  MyDeployCloudFormationStack:
    Identifier: aws/cfn-deploy@v1
    Inputs:
      Sources:
        - WorkflowSource
    Configuration:
      parameter-overrides: file:///sources/WorkflowSource/my/folder/params.json

To use a comma-separate list of parameters

Add parameter name-value pairs in the parameter-overrides property using the following format:

param-1=value-1,param-2=value-2

For example, assuming the following AWS CloudFormation template:
```
##My CloudFormation template

Description: My AWS CloudFormation template

Parameters:
  InstanceType:
    Description: Defines the Amazon EC2 compute for the production server.
    Type: String
    Default: t2.micro
    AllowedValues:
      - t2.micro
      - t2.small
      - t3.medium
    
Resources:
...
```
...you might set the parameter-overrides property as follows:
```
##My workflow YAML
...
Actions:
...
  DeployCloudFormationStack:
    Identifier: aws/cfn-deploy@v1
    Configuration:
      parameter-overrides: InstanceType=t3.medium,UseVPC=true   
```
Note
You can specify a parameter name without a corresponding value using undefined as the value. For example:
parameter-overrides: MyParameter=undefined
The effect is that during a stack update, CloudFormation uses the existing parameter value for the given parameter name.

Corresponding UI:

Configuration tab/Advanced/Parameter overrides
Configuration tab/Advanced/Parameter overrides/Specify overrides using a file
Configuration tab/Advanced/Parameter overrides/Specify overrides using a value set

no-execute-changeset

(DeployCloudFormationStack/Configuration/no-execute-changeset)

(Optional)

Specify whether you want CodeCatalyst to create the CloudFormation change set and then stop before running it. This gives you the opportunity to review the change set in the CloudFormation console. If you determine that the change set looks good, disable this option and then re-run the workflow so that CodeCatalyst can create and run the change set without stopping. The default is to create and run the change set without stopping. For more information, see the AWS CloudFormation deploy parameter in the AWS CLI Command Reference. For more information about viewing change sets, see Viewing a change set in the AWS CloudFormation User Guide.

Corresponding UI: Configuration tab/Advanced/No execute change set

fail-on-empty-changeset

(DeployCloudFormationStack/Configuration/fail-on-empty-changeset)

(Optional)

Specify whether you want CodeCatalyst to fail the Deploy AWS CloudFormation stack action if the CloudFormation change set is empty. (If a change set is empty, it means there were no changes made to the stack during the latest deployment.) The default is to allow the action to proceed if the change set is empty, and to return an UPDATE_COMPLETE message even though the stack was not updated.

For more information about this setting, see the AWS CloudFormation deploy parameter in the AWS CLI Command Reference. For more information about change sets, see Updating stacks using change sets in the AWS CloudFormation User Guide.

Corresponding UI: Configuration tab/Advanced/Fail on empty changeset

disable-rollback

(DeployCloudFormationStack/Configuration/disable-rollback)

(Optional)

Specify whether you want CodeCatalyst to roll back the stack deployment if it fails. The rollback returns the stack to the last known stable state. The default is to enable rollbacks. For more information about this setting, see the AWS CloudFormation deploy parameter in the AWS CLI Command Reference.

For more information about how the Deploy AWS CloudFormation stack action handles rollbacks, see Configuring rollbacks.

For more information about rolling back a stack, see Stack failure options in the AWS CloudFormation User Guide.

Corresponding UI: Configuration tab/Advanced/Disable rollback

termination-protection

(DeployCloudFormationStack/Configuration/termination-protection)

(Optional)

Specify whether you want the Deploy AWS CloudFormation stack to add termination protection to the stack that it is deploying. If a user attempts to delete a stack with termination protection enabled, the deletion fails and the stack, including its status, remains unchanged. The default is to disable termination protection. For more information, see Protecting a stack from being deleted in the AWS CloudFormation User Guide.

Corresponding UI: Configuration tab/Advanced/Termination protection

timeout-in-minutes

(DeployCloudFormationStack/Configuration/timeout-in-minutes)

(Optional)

Specify the amount of time, in minutes, that CloudFormation should allot before timing out stack creation operations and setting the stack status to CREATE_FAILED. If CloudFormation can't create the entire stack in the time allotted, it fails the stack creation due to timeout and rolls back the stack.

By default, there is no timeout for stack creation. However, individual resources may have their own timeouts based on the nature of the service they implement. For example, if an individual resource in your stack times out, stack creation also times out even if the timeout you specified for stack creation hasn't yet been reached.

Corresponding UI: Configuration tab/Advanced/CloudFormation timeout

notification-arns

(DeployCloudFormationStack/Configuration/notification-arns)

(Optional)

Specify the ARN of an Amazon SNS topic that you want CodeCatalyst to send notification messages to. For example, arn:aws:sns:us-east-1:111222333:MyTopic. When the Deploy AWS CloudFormation stack action runs, CodeCatalyst coordinates with CloudFormation to send one notification per AWS CloudFormation event that occurs during the stack creation or update process. (The events are visible in the AWS CloudFormation console's Events tab for the stack.) You can specify up to five topics. For more information, see What is Amazon SNS?.

Corresponding UI: Configuration tab/Advanced/Notification ARNs

monitor-alarm-arns

(DeployCloudFormationStack/Configuration/monitor-alarm-arns)

(Optional)

Specify the Amazon Resource Name (ARN) of an Amazon CloudWatch alarm to use as a rollback trigger. For example, arn:aws:cloudwatch::123456789012:alarm/MyAlarm. You can have a maximum of five rollback triggers.

Note

If you specify a CloudWatch alarm ARN, you'll also need to configure additional permissions to enable the action to access CloudWatch. For more information, see Configuring rollbacks.

Corresponding UI: Configuration tab/Advanced/Monitor alarm ARNs

monitor-timeout-in-minutes

(DeployCloudFormationStack/Configuration/monitor-timeout-in-minutes)

(Optional)

Specify an amount of time, from 0 to 180 minutes, during which CloudFormation monitors the specified alarms. Monitoring begins after all the stack resources have been deployed. If the alarm occurs within the specified monitoring time, then the deployment fails, and CloudFormation rolls back the entire stack operation.

Default: 0. CloudFormation only monitors alarms while the stack resources are being deployed, not after.

Corresponding UI: Configuration tab/Advanced/Monitoring time