# Continuous delivery with CodePipeline Continuous delivery is a release practice in which code changes are automatically built, tested, and prepared for release to production. With CloudFormation and CodePipeline, you can use continuous delivery to automatically build and test changes to your CloudFormation templates before promoting them to production stacks. This release process lets you rapidly and reliably make changes to your AWS infrastructure. For example, you can create a workflow that automatically builds a test stack when you submit an updated template to a code repository. After CloudFormation builds the test stack, you can test it and then decide whether to push the changes to a production stack. For more information about the benefits of continuous delivery, see [What is continuous delivery?](https://aws.amazon.com/devops/continuous-delivery/). Use CodePipeline to build a continuous delivery workflow by building a pipeline for CloudFormation stacks. CodePipeline has built-in integration with CloudFormation, so you can specify CloudFormation-specific actions, such as creating, updating, or deleting a stack, within a pipeline. For more information about CodePipeline, see the [AWS CodePipeline User Guide](https://docs.aws.amazon.com/codepipeline/latest/userguide/). **Topics** + [ # Walkthrough: Building a pipeline for test and production stacks ](continuous-delivery-codepipeline-basic-walkthrough.md) + [ # CloudFormation configuration properties reference ](continuous-delivery-codepipeline-action-reference.md) + [ # CloudFormation artifacts ](continuous-delivery-codepipeline-cfn-artifacts.md) + [ # Using parameter override functions with CodePipeline pipelines ](continuous-delivery-codepipeline-parameter-override-functions.md) # Walkthrough: Building a pipeline for test and production stacks Imagine a release process where you submit an CloudFormation template, which CloudFormation then uses to automatically build a test stack. After you review the test stack, you can preview how your changes will modify your production stack, and then choose whether to implement them. To accomplish this workflow, you could use CloudFormation to build your test stack, delete the test stack, create a change set, and then execute the change set. However, with each action, you need to manually interact with CloudFormation. In this walkthrough, we'll build a CodePipeline pipeline that automates many of these actions, helping you achieve a continuous delivery workflow with your CloudFormation stacks. ## Prerequisites This walkthrough assumes that you have used CodePipeline and CloudFormation, and know how pipelines and AWS CloudFormation templates and stacks work. For more information about CodePipeline, see the [AWS CodePipeline User Guide](https://docs.aws.amazon.com/codepipeline/latest/userguide/). You also need to have an Amazon S3 bucket in the same AWS Region you create your pipeline in. **Important** The sample WordPress template creates an EC2 instance that requires a connection to the Internet. Check that you have a default VPC and subnet that allow traffic to the Internet. ## Walkthrough overview This walkthrough builds a pipeline for a sample WordPress site in a stack. The pipeline is separated into three stages. Each stage must contain at least one action, which is a task the pipeline performs on your artifacts (your input). A stage organizes actions in a pipeline. CodePipeline must complete all actions in a stage before the stage processes new artifacts, for example, if you submitted new input to rerun the pipeline. By the end of this walkthrough, you'll have a pipeline that performs the following workflow: 1. The first stage of the pipeline retrieves a source artifact (a CloudFormation template and its configuration files) from a repository. You'll prepare an artifact that includes a sample WordPress template and upload it to an S3 bucket. 1. In the second stage, the pipeline creates a test stack and then waits for your approval. After you review the test stack, you can choose to continue with the original pipeline or create and submit another artifact to make changes. If you approve, this stage deletes the test stack, and then the pipeline continues to the next stage. 1. In the third stage, the pipeline creates a change set against a production stack, and then waits for your approval. In your initial run, you won't have a production stack. The change set shows you all of the resources that CloudFormation will create. If you approve, this stage executes the change set and builds your production stack. **Note** CloudFormation is a free service. However, you are charged for the AWS resources, such as the EC2 instance, that you include in your stack at the current rate for each. For more information about AWS pricing, see the detail page for each product at [http://aws.amazon.com](http://aws.amazon.com). ## Step 1: Edit the artifact and upload it to an S3 Bucket Before you build your pipeline, you must set up your source repository and files. CodePipeline copies these source files into your pipeline's [artifacts store](https://docs.aws.amazon.com/codepipeline/latest/userguide/concepts.html#concepts-artifacts), and then uses them to perform actions in your pipeline, such as creating a CloudFormation stack. When you use Amazon Simple Storage Service (Amazon S3) as the source repository, CodePipeline requires you to zip your source files before uploading them to an S3 bucket. The zipped file is a CodePipeline artifact that can contain a CloudFormation template, a template configuration file, or both. We provide an artifact that contains a sample WordPress template and two template configuration files. The two configuration files specify parameter values for the WordPress template. CodePipeline uses them when it creates the WordPress stacks. One file contains parameter values for a test stack, and the other for a production stack. You'll need to edit the configuration files, for example, to specify an existing EC2 key-pair name that you own. For more information about artifacts, see [CloudFormation artifacts](continuous-delivery-codepipeline-cfn-artifacts.md). After you build your artifact, you'll upload it to an S3 bucket. **To edit and upload the artifact** 1. Download and open the sample artifact: [https://s3.amazonaws.com/cloudformation-examples/user-guide/continuous-deployment/wordpress-single-instance.zip](https://s3.amazonaws.com/cloudformation-examples/user-guide/continuous-deployment/wordpress-single-instance.zip). The artifact contains three files: + The sample WordPress template: `wordpress-single-instance.yaml` + The template configuration file for the test stack.: `test-stack-configuration.json` + The template configuration file for the production stack: `prod-stack-configuration.json` 1. Extract all of the files, and then use any text editor to modify the template configuration files. Open the configuration files to see that they contain key-value pairs that map to the WordPress template's parameters. The configuration files specify the parameter values that your pipeline uses when it creates the test and production stacks. Edit the `test-stack-configuration.json` file to specify parameter values for the test stack and the `prod-stack-configuration.json` file for the production stack. + Change the values of the `DBPassword` and `DBRootPassword` keys to passwords that you can use to log in to your WordPress database. As defined in the WordPress template, the parameter values must contain only alphanumeric characters. + Change the value of the `KeyName` key to an existing EC2 key-pair name in the region in which you will create your pipeline. 1. Add the modified configuration files to the original artifact (`.zip`) file, replacing duplicate files. You now have a customized artifact that you can upload to an S3 bucket. 1. [Upload the artifact to an S3 bucket that you own](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html). Note the file's location. You'll specify the location of this file when you build your pipeline. Notes about the artifact and S3 bucket: + Use a bucket that is in the same AWS Region in which you will create your pipeline. + CodePipeline requires that the bucket is [versioning enabled](https://docs.aws.amazon.com/AmazonS3/latest/userguide/versioning-workflows.html). + You can also use services that don't require you to zip your files before uploading them, like GitHub or CodeCommit, for your source repository. + Artifacts can contain sensitive information such as passwords. Limit access so that only permitted users can view the file. When you do, ensure that CodePipeline can still access the file. For example, if you upload your artifact to an S3 bucket, use [S3 bucket policies or user policies](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-management.html) to restrict access. You now have an artifact that CodePipeline can pull in to your pipeline. In the next step, you'll specify the artifact's location and build the WordPress pipeline. ## Step 2: Create the pipeline stack To create the WordPress pipeline, you'll use a sample CloudFormation template. In addition to building the pipeline, the template sets up AWS Identity and Access Management (IAM) service roles for CodePipeline and CloudFormation, an S3 bucket for the CodePipeline artifact store, and an Amazon Simple Notification Service (Amazon SNS) topic to which the pipeline sends notifications, such as notifications about reviews. The sample template makes it easy to provision and configure these resources in a single CloudFormation stack. For more details about the configuration of the pipeline, see [What the pipeline does](#codepipeline-basic-walkthrough-template-details). **Important** The sample WordPress template creates an EC2 instance that requires a connection to the Internet. Check that your default VPC and subnet allow traffic to the Internet. **To create the pipeline stack** 1. Download the sample template at [https://s3.amazonaws.com/cloudformation-examples/user-guide/continuous-deployment/basic-pipeline.yml](https://s3.amazonaws.com/cloudformation-examples/user-guide/continuous-deployment/basic-pipeline.yml). Save it on your computer. 1. Open the CloudFormation console at [https://console.aws.amazon.com/cloudformation/](https://console.aws.amazon.com/cloudformation/). 1. Choose an AWS Region that supports CodePipeline and CloudFormation. For more information, see [CodePipeline endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/codepipeline.html) and [CloudFormation endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/cfn.html) in the *AWS General Reference*. 1. Choose **Create stack**. 1. Under **Specify template**, choose **Upload a template file**, and then choose the template that you just downloaded, `basic-pipeline.yml`. 1. Choose **Next**. 1. For **Stack name**, type `sample-WordPress-pipeline`. 1. In the **Parameters** section, specify the following parameter values, and then choose **Next**. When setting stack parameters, if you kept the same names for the WordPress template and its configuration files, you can use the default values. If not, specify the filenames that you used. **PipelineName** The name of your pipeline, such as `WordPress-test-pipeline`. **S3Bucket** The name of the S3 bucket where you saved your artifact (`.zip` file). **SourceS3Key** The file name of your artifact. If you saved the artifact in a folder, include it as part of the file name, such as `folder/subfolder/wordpress-single-instance.zip`. **Email** The email address to which CodePipeline sends pipeline notification, such as `myemail@example.com`. 1. For this walkthrough, you don't need to add tags or specify advanced settings, so choose **Next**. 1. Ensure that the stack name and template URL are correct, and then choose **Create stack**. 1. To acknowledge that you're aware that CloudFormation might create IAM resources, choose the check box. It might take several minutes for AWS CloudFormation to create your stack. To monitor progress, view the stack events. For more information, see [Monitor stack progress](monitor-stack-progress.md). After your stack has been created, CodePipeline starts your new pipeline. To view its status, see the [CodePipeline console](https://console.aws.amazon.com/codepipeline/). From the list of pipelines, choose **WordPress-test-pipeline**. ### What the pipeline does This section explains the pipeline's three stages, using snippets from the sample WordPress pipeline template. #### Stage 1: Source The first stage of the pipeline is a source stage in which you specify the location of your source code. Every time you push a revision to this location, CodePipeline reruns your pipeline. The source code is located in an S3 bucket and is identified by its file name. You specified these values as input parameter values when you created the pipeline stack. To allow using the source artifact in subsequent stages, the snippet specifies the `OutputArtifacts` property, with the name `TemplateSource`. To use this artifact in later stages, you specify `TemplateSource` as an input artifact. ``` - Name: S3Source Actions: - Name: TemplateSource ActionTypeId: Category: Source Owner: AWS Provider: S3 Version: '1' Configuration: S3Bucket: !Ref 'S3Bucket' S3ObjectKey: !Ref 'SourceS3Key' OutputArtifacts: - Name: TemplateSource ``` #### Stage 2: TestStage In the `TestStage` stage, the pipeline creates the test stack, waits for approval, and then deletes the test stack. For the `CreateStack` action, the pipeline uses the test configuration file and WordPress template to create the test stack. Both files are contained in the `TemplateSource` input artifact, which is brought in from the source stage. The snippet uses the `REPLACE_ON_FAILURE` action mode. If stack creation fails, the pipeline replaces it so that you don't need to clean up or troubleshoot the stack before you can rerun the pipeline. The action mode is useful for quickly iterating on test stacks. For the `RoleArn` property, the value is an AWS CloudFormation service role that is declared elsewhere in the template. The `ApproveTestStack` action pauses the pipeline and sends a notification to the email address that you specified when you created the pipeline stack. While the pipeline is paused, you can check the WordPress test stack and its resources. Use CodePipeline to [approve or reject](https://docs.aws.amazon.com/codepipeline/latest/userguide/approvals-approve-or-reject.html) this action. The `CustomData` property includes a description of the action you're approving, which the pipeline adds to the notification email. After you approve this action, CodePipeline moves to the `DeleteTestStack` action and deletes the test WordPress stack and its resources. ``` - Name: TestStage Actions: - Name: CreateStack ActionTypeId: Category: Deploy Owner: AWS Provider: CloudFormation Version: '1' InputArtifacts: - Name: TemplateSource Configuration: ActionMode: REPLACE_ON_FAILURE RoleArn: !GetAtt [CFNRole, Arn] StackName: !Ref TestStackName TemplateConfiguration: !Sub "TemplateSource::${TestStackConfig}" TemplatePath: !Sub "TemplateSource::${TemplateFileName}" RunOrder: '1' - Name: ApproveTestStack ActionTypeId: Category: Approval Owner: AWS Provider: Manual Version: '1' Configuration: NotificationArn: !Ref CodePipelineSNSTopic CustomData: !Sub 'Do you want to create a change set against the production stack and delete the ${TestStackName} stack?' RunOrder: '2' - Name: DeleteTestStack ActionTypeId: Category: Deploy Owner: AWS Provider: CloudFormation Version: '1' Configuration: ActionMode: DELETE_ONLY RoleArn: !GetAtt [CFNRole, Arn] StackName: !Ref TestStackName RunOrder: '3' ``` #### Stage 3: ProdStage The `ProdStage` stage of the pipeline creates a change set against the existing production stack, waits for approval, and then executes the change set. A change set provides a preview of all modifications AWS CloudFormation will make to your production stack before implementing them. On your first pipeline run, you won't have a running production stack. The change set shows the actions that AWS CloudFormation performed when creating the test stack. To create the change set, the `CreateChangeSet` action uses the WordPress sample template and the production template configuration from the `TemplateSource` input artifact. Similar to the previous stage, the `ApproveChangeSet` action pauses the pipeline and sends an email notification. While the pipeline is paused, you can view the change set to check all of the proposed modifications to the production WordPress stack. Use CodePipeline to [approve or reject](https://docs.aws.amazon.com/codepipeline/latest/userguide/approvals-approve-or-reject.html) this action to continue or stop the pipeline, respectively. After you approve this action, the `ExecuteChangeSet` action executes the changes set, so that AWS CloudFormation performs all of the actions described in the change set. For the initial run, AWS CloudFormation creates the WordPress production stack. On subsequent runs, AWS CloudFormation updates the stack. ``` - Name: ProdStage Actions: - Name: CreateChangeSet ActionTypeId: Category: Deploy Owner: AWS Provider: CloudFormation Version: '1' InputArtifacts: - Name: TemplateSource Configuration: ActionMode: CHANGE_SET_REPLACE RoleArn: !GetAtt [CFNRole, Arn] StackName: !Ref ProdStackName ChangeSetName: !Ref ChangeSetName TemplateConfiguration: !Sub "TemplateSource::${ProdStackConfig}" TemplatePath: !Sub "TemplateSource::${TemplateFileName}" RunOrder: '1' - Name: ApproveChangeSet ActionTypeId: Category: Approval Owner: AWS Provider: Manual Version: '1' Configuration: NotificationArn: !Ref CodePipelineSNSTopic CustomData: !Sub 'A new change set was created for the ${ProdStackName} stack. Do you want to implement the changes?' RunOrder: '2' - Name: ExecuteChangeSet ActionTypeId: Category: Deploy Owner: AWS Provider: CloudFormation Version: '1' Configuration: ActionMode: CHANGE_SET_EXECUTE ChangeSetName: !Ref ChangeSetName RoleArn: !GetAtt [CFNRole, Arn] StackName: !Ref ProdStackName RunOrder: '3' ``` ## Step 3: View the WordPress stack As CodePipeline runs through the pipeline, it uses CloudFormation to create test and production stacks. To see the status of these stacks and their output, use the CloudFormation console. **To view a stack** 1. Open the CloudFormation console at [https://console.aws.amazon.com/cloudformation/](https://console.aws.amazon.com/cloudformation/). 1. Depending on whether your pipeline is in the test or production stage, choose the `Test-MyWordPressSite` or the `Prod-MyWordPressSite` stack. 1. To check the status of your stack, view the stack [events](cfn-console-view-stack-data-resources.md). If the stack is in a failed state, view the status reason to find the stack error. Fix the error, and then rerun the pipeline. If the stack is in the `CREATE_COMPLETE` state, view its outputs to get the URL of your WordPress site. You've successfully used CodePipeline to build a continuous delivery workflow for a sample WordPress site. If you submit changes to the S3 bucket, CodePipeline automatically detects a new version, and then reruns your pipeline. This workflow makes it easier to submit and test changes before making changes to your production site. ## Step 4: Clean up resources To make sure that you are not charged for unwanted services, delete your resources. **Important** Delete the test and production WordPress stacks before deleting the pipeline stack. The pipeline stack contains a service role that's required to delete the WordPress stacks. If you deleted the pipeline stack first, you can associate another service role Amazon Resource Name (ARN) with the WordPress stacks, and then delete them. **To delete objects in the artifact store** 1. Open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. Choose the S3 bucket that CodePipeline used as your pipeline's artifact store. The bucket's name follows the format: `stackname-artifactstorebucket-id`. If you followed this walkthrough, the bucket's name might look similar to the following example: `sample-WordPress-pipeline-artifactstorebucket-12345abcd12345`. 1. Delete all of the objects in the artifact store S3 bucket. When you delete the pipeline stack in the next step, this bucket must be empty. Otherwise, CloudFormation won't be able to delete the bucket. **To delete stacks** 1. From the CloudFormation console, choose the stack that you want to delete. If the WordPress stacks that were created by the pipeline are still running, choose them first. By default, the stack names are `Test-MyWordPressSite` and `Prod-MyWordPressSite`. If you already deleted the WordPress stacks, choose the `sample-WordPress-pipeline` stack. 1. Choose **Actions**, and then choose **Delete Stack**. 1. In the confirmation message, choose **Yes, Delete**. CloudFormation deletes the stack all of the stack's resources, such as the EC2 instance, notification topic, service role, and the pipeline. Now that you understand how to build a basic CloudFormation workflow with CodePipeline, you can use the sample template and artifacts as a starting point for building your own. ## See also The following related resources can help you as you work with these parameters. + For more information about the CloudFormation action parameters in CodePipeline, see the [CloudFormation deploy action configuration reference](https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference-CloudFormation.html) in the *AWS CodePipeline User Guide*. + For example template values by action provider, such as for the `Owner` field or the `configuration` fields, see the [Action structure reference](https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference.html) in the *AWS CodePipeline User Guide*. + To download example pipeline stack templates in YAML or JSON format, see [Tutorial: Create a pipeline with CloudFormation](https://docs.aws.amazon.com/codepipeline/latest/userguide/tutorials-cloudformation.html) in the *AWS CodePipeline User Guide*. # CloudFormation configuration properties reference When you build a CodePipeline pipeline, you add a `Deploy` action to the pipeline with CloudFormation as a provider. You then must specify which CloudFormation action the pipeline invokes and the action's settings. This topic describes the CloudFormation configuration properties. To specify properties, you can use the CodePipeline console, or you can create a JSON object to use for the AWS CLI, CodePipeline API, or CloudFormation templates. **Topics** + [ ## Configuration properties (console) ](#continuous-delivery-codepipeline-action-reference-console) + [ ## Configuration properties (JSON object) ](#continuous-delivery-codepipeline-action-reference-json) + [ ## See also ](#continuous-delivery-codepipeline-action-reference-see-also) ## Configuration properties (console) The CodePipeline [console](https://console.aws.amazon.com/codepipeline/) shows the configuration properties and indicates the properties that are required based on the action mode that you choose. **Note** When you create a pipeline, you can specify the **Create or update a stack** or **Create or replace a change set** action modes only. Properties in the **Advanced** section are available only when you edit a pipeline. **Action mode** The CloudFormation action that CodePipeline invokes when processing the associated stage. Choose one of the following action modes: + **Create or replace a change set** creates the change set if it doesn't exist based on the stack name and template that you submit. If the change set exists, CloudFormation deletes it, and then creates a new one. + **Create or update a stack** creates the stack if the specified stack doesn't exist. If the stack exists, CloudFormation updates the stack. Use this action to update existing stacks. CodePipeline won't replace the stack. + **Delete a stack** deletes a stack. If you specify a stack that doesn't exist, the action is completed successfully without deleting a stack. + **Execute a change set** executes a change set. + **Replace a failed stack** creates the stack if the specified stack doesn't exist. If the stack exists and is in a failed state (reported as `ROLLBACK_COMPLETE`, `ROLLBACK_FAILED`, `CREATE_FAILED`, `DELETE_FAILED`, or `UPDATE_ROLLBACK_FAILED`), CloudFormation deletes the stack and then creates a new one. If the stack isn't in a failed state, CloudFormation updates it. Use this action to replace failed stacks without recovering or troubleshooting them. You would typically choose this mode for testing. **Stack name** The name that is associated with an existing stack or a stack you want to create. The name must be unique in the AWS Region in which you are creating the stack. A stack name can contain only alphanumeric characters (case sensitive) and hyphens. It must start with an alphabetic character and cannot be longer than 128 characters. **Change set name** The name of an existing change set or a new change set that you want to create for the specified stack. **Template** The location of an CloudFormation template file, which follows the format `ArtifactName::TemplateFileName`. **Template configuration** The location of a template configuration file, which follows the format `ArtifactName::TemplateConfigurationFileName`. The template configuration file can contain template parameter values, a stack policy, and tags. If you include sensitive information, such as passwords, restrict access to this file. For more information, see [CloudFormation artifacts](continuous-delivery-codepipeline-cfn-artifacts.md). **Capabilities** For stacks that contain certain resources, explicit acknowledgment that CloudFormation might create or update those resources. For example, you must specify `CAPABILITY_IAM` if your stack template contains AWS Identity and Access Management (IAM) resources. For more information, see [https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html) API operation request parameters. If you have IAM resources in your stack template, you must specify this property. You can specify more than one capability. **Role name** The name of the IAM service role that CloudFormation assumes when it operates on resources in the specified stack. **Output file name** In the **Advanced** section, you can specify an output file name, such as `CreateStackOutput.json`, that CodePipeline adds to the [output artifact](https://docs.aws.amazon.com/codepipeline/latest/userguide/concepts.html#concepts-artifacts) after it performs the specified action. The output artifact contains a JSON file with the contents of the `Outputs` section of the CloudFormation template. If you don't specify a name, CodePipeline doesn't generate an output artifact. **Parameter overrides** Parameters are defined in your template and allow you to input custom values when you create or update a stack. You can specify a JSON object that overrides template parameter values in the template configuration file. All parameter names must be present in the stack template. For more information, see [CloudFormation template Parameters syntax](parameters-section-structure.md). There is a maximum size limit of 1 kilobyte for the JSON object that can be stored in the `ParameterOverrides` property. We recommend that you use the template configuration file to specify most of your parameter values. Use parameter overrides to specify dynamic parameter values only. Dynamic parameters are unknown until you run the pipeline. The following example defines a value for the `ParameterName` parameter by using a parameter override function. The function retrieves a value from a CodePipeline input artifact. For more information about parameter override functions, see [Using parameter override functions with CodePipeline pipelines](continuous-delivery-codepipeline-parameter-override-functions.md). ``` { "ParameterName" : { "Fn::GetParam" : ["ArtifactName", "config-file-name.json", "ParamName"]} } ``` ## Configuration properties (JSON object) When you specify `CloudFormation` as a provider for a stage action, define the following properties in the `Configuration` property. Use the JSON object for the AWS CLI, CodePipeline API, or CloudFormation templates. For examples, see [Walkthrough: Building a pipeline for test and production stacks](continuous-delivery-codepipeline-basic-walkthrough.md) and [CloudFormation configuration properties reference](#continuous-delivery-codepipeline-action-reference). `ActionMode` The CloudFormation action that CodePipeline invokes when it processes the associated stage. Specify only one of the following action modes: + `CHANGE_SET_EXECUTE` executes a change set. + `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, CloudFormation deletes it, and then creates a new one. + `CREATE_UPDATE` creates the stack if the specified stack doesn't exist. If the stack exists, CloudFormation updates the stack. Use this action to update existing stacks. CodePipeline won't 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 the specified stack doesn't exist. If the stack exists and is in a failed state (reported as `ROLLBACK_COMPLETE`, `ROLLBACK_FAILED`, `CREATE_FAILED`, `DELETE_FAILED`, or `UPDATE_ROLLBACK_FAILED`), CloudFormation deletes the stack and then creates a new stack. If the stack isn't in a failed state, CloudFormation updates it. Use this action to automatically replace failed stacks without recovering or troubleshooting them. You would typically choose this mode for testing. This property is required. `Capabilities` For stacks that contain certain resources, explicit acknowledgment that CloudFormation might create or update those resources. For example, you must specify `CAPABILITY_IAM` if your stack template contains AWS Identity and Access Management (IAM) resources. For more information, see [https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html) API operation request parameters. This property is conditional. If you have IAM resources in your stack template, you must specify this property. You can specify multiple capabilities. The following example adds the `CAPABILITY_IAM` and `CAPABILITY_AUTO_EXPAND` properties to the template: ``` configuration: ActionMode: CHANGE_SET_REPLACE Capabilities: CAPABILITY_IAM,CAPABILITY_AUTO_EXPAND ChangeSetName: pipeline-changeset RoleArn: CloudFormation_Role_ARN StackName: my-pipeline-stack TemplateConfiguration: 'my-pipeline-stack::template-configuration.json' TemplatePath: 'my-pipeline-stack::template-export.yml' ``` ``` "configuration": { "ActionMode": "CHANGE_SET_REPLACE", "Capabilities": "CAPABILITY_IAM,CAPABILITY_AUTO_EXPAND", "ChangeSetName": "pipeline-changeset", "RoleArn": "CloudFormation_Role_ARN", "StackName": "my-pipeline-stack", "TemplateConfiguration": "my-pipeline-stack::template-configuration.json", "TemplatePath": "my-pipeline-stack::template-export.yml" } ``` `ChangeSetName` 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. `OutputFileName` A name for the output file, such as `CreateStackOutput.json`. CodePipeline adds the file to the [output artifact](https://docs.aws.amazon.com/codepipeline/latest/userguide/concepts.html#concepts-artifacts) after it performs the specified action. The output artifact contains a JSON file with the contents of the `Outputs` section of the CloudFormation template. This property is optional. If you don't specify a name, CodePipeline doesn't generate an output artifact. `ParameterOverrides` Parameters are defined in your template and allow you to input custom values when you create or update a stack. You can specify a JSON object that overrides template parameter values in the template configuration file. All parameter names must be present in the stack template. For more information, see [CloudFormation template Parameters syntax](parameters-section-structure.md). The following example adds the `InstanceType` and `KeyName` parameter overrides to the template: ``` configuration: ActionMode: CHANGE_SET_REPLACE Capabilities: CAPABILITY_NAMED_IAM ChangeSetName: pipeline-changeset ParameterOverrides: '{"InstanceType": "t2.small","KeyName": "my-keypair"}' RoleArn: CloudFormation_Role_ARN StackName: my-pipeline-stack TemplateConfiguration: 'my-pipeline-stack::template-configuration.json' TemplatePath: 'my-pipeline-stack::template-export.yml' ``` ``` "configuration": { "ActionMode": "CHANGE_SET_REPLACE", "Capabilities": "CAPABILITY_NAMED_IAM", "ChangeSetName": "pipeline-changeset", "ParameterOverrides": "{\"InstanceType\": \"t2.small\",\"KeyName\": \"my-keypair\"}", "RoleArn": "CloudFormation_Role_ARN", "StackName": "my-pipeline-stack", "TemplateConfiguration": "my-pipeline-stack::template-configuration.json", "TemplatePath": "my-pipeline-stack::template-export.yml" } ``` The maximum size for the JSON object that can be stored in the `ParameterOverrides` property is 1 kilobyte. We recommend that you use the template configuration file to specify most of your parameter values. Use parameter overrides to specify dynamic parameter values only. Dynamic parameter values are unknown until you run the pipeline. The following example defines a value for the `ParameterName` parameter by using a parameter override function. The function retrieves a value from a CodePipeline input artifact. For more information about parameter override functions, see [Using parameter override functions with CodePipeline pipelines](continuous-delivery-codepipeline-parameter-override-functions.md). ``` { "ParameterName" : { "Fn::GetParam" : ["ArtifactName", "config-file-name.json", "ParamName"]} } ``` This property is optional. `RoleArn` The Amazon Resource Name (ARN) of the IAM service role that CloudFormation assumes when it operates on resources in a stack. This property is required for the following action modes: `CREATE_UPDATE`, `REPLACE_ON_FAILURE`, `DELETE_ONLY`, and `CHANGE_SET_REPLACE`. `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. `StackName` The name of an existing stack or a stack that you want to create. This property is required for all action modes. `TemplateConfiguration` `TemplateConfiguration` is the template configuration file. You include the file in an input artifact to this action. 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" ``` The template configuration file can contain template parameter values and a stack policy. If you include sensitive information, such as passwords, restrict access to this file. For an example template configuration file, see [CloudFormation artifacts](continuous-delivery-codepipeline-cfn-artifacts.md). This property is optional. `TemplatePath` `TemplatePath` represents the 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.yaml` file name creates a `TemplatePath` name, as shown in this example: ``` "TemplatePath": "SourceArtifact::template.yaml" ``` This property is required for the following action modes: `CREATE_UPDATE`, `REPLACE_ON_FAILURE`, and `CHANGE_SET_REPLACE`. For all other action modes, this property is ignored. ## See also The following related resources can help you as you work with these parameters. + For more information about the CloudFormation action parameters in CodePipeline, see the [CloudFormation deploy action configuration reference](https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference-CloudFormation.html) in the *AWS CodePipeline User Guide*. + For example template values by action provider, such as for the `Owner` field or the `configuration` fields, see the [Action structure reference](https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference.html) in the *AWS CodePipeline User Guide*. + To download example pipeline stack templates in YAML or JSON format, see [Tutorial: Create a pipeline with CloudFormation](https://docs.aws.amazon.com/codepipeline/latest/userguide/tutorials-cloudformation.html) in the *AWS CodePipeline User Guide*. # CloudFormation artifacts CodePipeline performs tasks on artifacts as CodePipeline runs a pipeline. For CloudFormation, artifacts can include a stack template file, a template configuration file, or both. CodePipeline uses these artifacts to work with CloudFormation stacks and change sets. If you use Amazon Simple Storage Service (Amazon S3) as a source repository, you must zip the template and template configuration files into a single file before you upload them to an S3 bucket. For other repositories, such as GitHub and AWS CodeCommit, upload artifacts without zipping them. For more information, see [Create a pipeline, stages, and actions](https://docs.aws.amazon.com/codepipeline/latest/userguide/pipelines-create.html) in the *AWS CodePipeline User Guide*. You can add as many files as you need to your repository. For example, you might want to include two different configurations for the same template: one for a test configuration and another for a production configuration. This topic describes each artifact type. **Topics** + [ ## Stack template file ](#w2aac21c15c13) + [ ## Template configuration file ](#w2aac21c15c15) + [ ## See also ](#w2aac21c15c17) ## Stack template file A stack template file defines the resources that CloudFormation provisions and configures. These files are the same template files that you use when you create or update stacks using CloudFormation. You can use YAML or JSON-formatted templates. For more information about templates, see [CloudFormation template sections](template-anatomy.md). ## Template configuration file A template configuration file is a JSON-formatted text file that can specify template parameter values, a [stack policy](protect-stack-resources.md), and tags. Use these configuration files to specify parameter values or a stack policy for a stack. All of the parameter values that you specify must be declared in the associated template. If you include sensitive information—such as passwords—in this file, restrict access to it. For example, if you upload your artifact to an S3 bucket, use [S3 bucket policies or user policies](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-management.html) to restrict access. To create a configuration file, use the following format : ``` { "Parameters" : { "NameOfTemplateParameter" : "ValueOfParameter", ... }, "Tags" : { "TagKey" : "TagValue", ... }, "StackPolicy" : { "Statement" : [ StackPolicyStatement ] } } ``` The following example specifies `TestEC2Key` for the `KeyName` parameter, adds a `Department` tag whose value is `Marketing`, and adds a stack policy that allows all update actions except for an update that deletes a resource. ``` { "Parameters" : { "KeyName" : "TestEC2Key" }, "Tags" : { "Department" : "Marketing" }, "StackPolicy" : { "Statement" : [ { "Effect" : "Allow", "NotAction" : "Update:Delete", "Principal": "*", "Resource" : "*" } ] } } ``` ## See also The following related resources can help you as you work with these parameters. + For more information about the CloudFormation action parameters in CodePipeline, see the [CloudFormation deploy action configuration reference](https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference-CloudFormation.html) in the *AWS CodePipeline User Guide*. + For example template values by action provider, such as for the `Owner` field or the `configuration` fields, see the [Action structure reference](https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference.html) in the *AWS CodePipeline User Guide*. + To download example pipeline stack templates in YAML or JSON format, see [Tutorial: Create a pipeline with CloudFormation](https://docs.aws.amazon.com/codepipeline/latest/userguide/tutorials-cloudformation.html) in the *AWS CodePipeline User Guide*. # Using parameter override functions with CodePipeline pipelines In a CodePipeline stage, you can specify [parameter overrides](continuous-delivery-codepipeline-action-reference.md) for CloudFormation actions. Parameter overrides let you specify template parameter values that override values in a template configuration file. CloudFormation provides functions to help you to specify dynamic values (values that are unknown until the pipeline runs). **Topics** + [ ## `Fn::GetArtifactAtt` ](#w2aac21c17b7) + [ ## `Fn::GetParam` ](#w2aac21c17b9) + [ ## See also ](#w2aac21c17c11) ## `Fn::GetArtifactAtt` The `Fn::GetArtifactAtt` function retrieves the value of an attribute from an input artifact, such as the S3 bucket name where the artifact is stored. Use this function to specify attributes of an artifact, such as its file name or Amazon S3 bucket name. When you run a pipeline, CodePipeline copies and writes files to the pipeline's artifact store (an S3 bucket). CodePipeline generates the file names in the artifact store. These file names are unknown before you run the pipeline. For example, in your pipeline, you might have a source stage where CodePipeline copies your AWS Lambda function source code to the artifact store. In the next stage, you have an CloudFormation template that creates the Lambda function, but CloudFormation requires the file name to create the function. You must use the `Fn::GetArtifactAtt` function to pass the exact S3 bucket and file names. ### Syntax Use the following syntax to retrieve an attribute value of an artifact. ``` { "Fn::GetArtifactAtt" : [ "artifactName", "attributeName" ] } ``` `artifactName` The name of the input artifact. You must declare this artifact as input for the associated action. `attributeName` The name of the artifact attribute whose value you want to retrieve. For details about each artifact attribute, see the following Attributes section. ### Example The following parameter overrides specify the `BucketName` and `ObjectKey` parameters by retrieving the S3 bucket name and file name of the `LambdaFunctionSource` artifact. This example assumes that CodePipeline copied Lambda function source code and saved it as an artifact, for example, as part of a source stage. ``` { "BucketName" : { "Fn::GetArtifactAtt" : ["LambdaFunctionSource", "BucketName"]}, "ObjectKey" : { "Fn::GetArtifactAtt" : ["LambdaFunctionSource", "ObjectKey"]} } ``` ### Attributes You can retrieve the following attributes for an artifact. `BucketName` The name of the S3 bucket where the artifact is stored. `ObjectKey` The name of the `.zip` file that contains the artifact that is generated by CodePipeline, such as `1ABCyZZ.zip`. `URL` The Amazon Simple Storage Service (Amazon S3) URL of the artifact, such as `https://s3.us-west-2.amazonaws.com/artifactstorebucket-yivczw8jma0c/test/TemplateSo/1ABCyZZ.zip`. ## `Fn::GetParam` The `Fn::GetParam` function returns a value from a key-value pair in a JSON-formatted file. The JSON file must be included in an artifact. Use this function to retrieve output values from an CloudFormation stack and use them as input for another action. For example, if you specify an output file name for an CloudFormation action, CodePipeline saves the output in a JSON file and then adds it to the output artifact's `.zip` file. Use the `Fn::GetParam` function to retrieve the output value, and use it as input for another action. ### Syntax Use the following syntax to retrieve a value from a key-value pair. ``` { "Fn::GetParam" : [ "artifactName", "JSONFileName", "keyName" ] } ``` `artifactName` The name of the artifact, which must be included as an input artifact for the associated action. `JSONFileName` The name of a JSON file that is contained in the artifact. `keyName` The name of the key whose value you want to retrieve. ### Examples The following examples demonstrate how to use the `Fn::GetParam` function in a parameter override. #### Syntax The following parameter override specifies the `WebSiteURL` parameter by retrieving the value of the `URL` key from the `stack-output.json` file that is in the `WebStackOutput` artifact. ``` { "WebSiteURL" : { "Fn::GetParam" : ["WebStackOutput", "stack-output.json", "URL"]} } ``` #### CloudFormation template snippets The following CloudFormation template snippets, from a CodePipeline pipeline, demonstrate how to pass stack outputs. These snippets show two stages of pipeline definition. The first stage creates a stack and saves its outputs in the `TestOutput.json` file in the `StackAOutput` artifact. These values are specified by the `OutputFileName` and `OutputArtifacts` properties. The name of the source input artifact for the stages is `TemplateSource`. The file name for the stack template is `teststackA.yaml`, and the file name for the configuration file is `test-configuration.json`. In both stages, these values are specified for the `TemplateConfiguration` and `TemplatePath` properties as shown: ``` TemplateConfiguration: TemplateSource::test-configuration.json TemplatePath: TemplateSource::teststackA.yaml ``` **Example Create stack A stage** ``` - Name: CreateTestStackA Actions: - Name: CloudFormationCreate ActionTypeId: Category: Deploy Owner: AWS Provider: CloudFormation Version: '1' Configuration: ActionMode: CREATE_UPDATE Capabilities: CAPABILITY_IAM OutputFileName: TestOutput.json RoleArn: !GetAtt [CFNRole, Arn] StackName: StackA TemplateConfiguration: TemplateSource::test-configuration.json TemplatePath: TemplateSource::teststackA.yaml InputArtifacts: - Name: TemplateSource OutputArtifacts: - Name: StackAOutput RunOrder: '1' ``` In a subsequent stage, stack B uses the outputs from stack A. In the `ParameterOverrides` property, the example uses the `Fn::GetParam` function to specify the `StackBInputParam` parameter. The resulting value is the value associated with the `StackAOutputName` key. **Example Create stack B stage** ``` - Name: CreateTestStackB Actions: - Name: CloudFormationCreate ActionTypeId: Category: Deploy Owner: AWS Provider: CloudFormation Version: '1' Configuration: ActionMode: CREATE_UPDATE Capabilities: CAPABILITY_IAM RoleArn: !GetAtt [CFNRole, Arn] StackName: StackB TemplateConfiguration: TemplateSource::test-configuration.json TemplatePath: TemplateSource::teststackB.yaml ParameterOverrides: | { "StackBInputParam" : { "Fn::GetParam" : ["StackAOutput", "TestOutput.json", "StackAOutputName"]} } InputArtifacts: - Name: TemplateSource - Name: StackAOutput RunOrder: '1' ``` ## See also The following related resources can help you as you work with these parameters. + For more information about the CloudFormation action parameters in CodePipeline, see the [CloudFormation deploy action configuration reference](https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference-CloudFormation.html) in the *AWS CodePipeline User Guide*. + For example template values by action provider, such as for the `Owner` field or the `configuration` fields, see the [Action structure reference](https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference.html) in the *AWS CodePipeline User Guide*. + To download example pipeline stack templates in YAML or JSON format, see [Tutorial: Create a pipeline with CloudFormation](https://docs.aws.amazon.com/codepipeline/latest/userguide/tutorials-cloudformation.html) in the *AWS CodePipeline User Guide*.