# Tutorial: Create a pipeline that uses variables from AWS CloudFormation deployment actions
<a name="tutorials-cloudformation-action"></a>

In this tutorial, you use the AWS CodePipeline console to create a pipeline with a deployment action. When the pipeline runs, the template creates a stack and also creates an `outputs` file. Outputs generated by the stack template are the variables generated by the AWS CloudFormation action in CodePipeline.

In the action where you create the stack from the template, you designate a variable namespace. The variables produced by the `outputs` file can then be consumed by subsequent actions. In this example, you create a change set based on the `StackName` variable produced by the AWS CloudFormation action. After a manual approval, you execute the change set and then create a delete stack action that deletes the stack based on the `StackName` variable.

**Important**  
As part of creating a pipeline, an S3 artifact bucket provided by the customer will be used by CodePipeline for artifacts. (This is different from the bucket used for an S3 source action.) If the S3 artifact bucket is in a different account from the account for your pipeline, make sure that the S3 artifact bucket is owned by AWS accounts that are safe and will be dependable.

**Topics**
+ [Prerequisites: Create an AWS CloudFormation service role and a CodeCommit repository](#tutorials-cloudformation-action-prereq)
+ [Step 1: Download, edit, and upload the sample AWS CloudFormation template](#tutorials-cloudformation-action-upload)
+ [Step 2: Create your pipeline](#tutorials-cloudformation-action-pipeline)
+ [Step 3: Add an CloudFormation deployment action to create the change set](#tutorials-cloudformation-action-changeset)
+ [Step 4: Add a manual approval action](#tutorials-cloudformation-action-approval)
+ [Step 5: Add a CloudFormation deployment action to execute the change set](#tutorials-cloudformation-action-deployment)
+ [Step 6: Add a CloudFormation deployment action to delete the stack](#tutorials-cloudformation-action-delete)

## Prerequisites: Create an AWS CloudFormation service role and a CodeCommit repository
<a name="tutorials-cloudformation-action-prereq"></a>

You must already have the following:
+ A CodeCommit repository. You can use the AWS CodeCommit repository you created in [Tutorial: Create a simple pipeline (CodeCommit repository)](tutorials-simple-codecommit.md).
+ This example creates an Amazon DocumentDB stack from a template. You must use AWS Identity and Access Management (IAM) to create an AWS CloudFormation service role with the following permissions for Amazon DocumentDB.

  ```
  "rds:DescribeDBClusters",
  "rds:CreateDBCluster",
  "rds:DeleteDBCluster",
  "rds:CreateDBInstance"
  ```

## Step 1: Download, edit, and upload the sample AWS CloudFormation template
<a name="tutorials-cloudformation-action-upload"></a>

Download the sample AWS CloudFormation template file and upload it to your CodeCommit repository.

1. Navigate to the sample template for your Region. For example, use the table at [https://docs.aws.amazon.com/documentdb/latest/developerguide/quick_start_cfn.html#quick_start_cfn-launch_stack](https://docs.aws.amazon.com/documentdb/latest/developerguide/quick_start_cfn.html#quick_start_cfn-launch_stack) to choose the Region and download the template. Download the template for an Amazon DocumentDB Cluster. The file name is `documentdb_full_stack.yaml`.

1. Unzip the `documentdb_full_stack.yaml` file, and open it in a text editor. Make the following changes.

   1. For this example, add the following `Purpose:` parameter to your `Parameters` section in the template.

      ```
        Purpose:
          Type: String
          Default: testing
          AllowedValues:
            - testing
            - production
          Description: The purpose of this instance.
      ```

   1. For this example, add the following `StackName` output to your `Outputs:` section in the template.

      ```
        StackName:
          Value: !Ref AWS::StackName
      ```

1. Upload the template file to your AWS CodeCommit repository. You must upload the unzipped and edited template file to the root directory of your repository. 

   To use the CodeCommit console to upload your files: 

   1. Open the CodeCommit console, and choose your repository from the **Repositories** list.

   1. Choose **Add file**, and then choose **Upload file**. 

   1. Select **Choose file**, and then browse for your file. Commit the change by entering your user name and email address. Choose **Commit changes**.

   Your file should look like this at the root level in your repository:

   ```
   documentdb_full_stack.yaml
   ```

## Step 2: Create your pipeline
<a name="tutorials-cloudformation-action-pipeline"></a>

In this section, you create a pipeline with the following actions:
+ A source stage with a CodeCommit action where the source artifact is your template file.
+ A deployment stage with an CloudFormation deployment action.

Each action in the source and deployment stages created by the wizard is assigned a variable namespace, `SourceVariables` and `DeployVariables`, respectively. Because the actions have a namespace assigned, the variables configured in this example are available to downstream actions. For more information, see [Variables reference](reference-variables.md).

**To create a pipeline with the wizard**

1. Sign in to the AWS Management Console and open the CodePipeline console at [http://console.aws.amazon.com/codesuite/codepipeline/home](http://console.aws.amazon.com/codesuite/codepipeline/home).

1. On the **Welcome** page, **Getting started** page, or the **Pipelines** page, choose **Create pipeline**.

1. On the **Step 1: Choose creation option** page, under **Creation options**, choose the **Build custom pipeline** option. Choose **Next**.

1. In **Step 2: Choose pipeline settings**, in **Pipeline name**, enter **MyCFNDeployPipeline**.

1. CodePipeline provides V1 and V2 type pipelines, which differ in characteristics and price. The V2 type is the only type you can choose in the console. For more information, see [pipeline types](https://docs.aws.amazon.com/codepipeline/latest/userguide/pipeline-types-planning.html?icmpid=docs_acp_help_panel). For information about pricing for CodePipeline, see [Pricing](https://aws.amazon.com/codepipeline/pricing/).

1. In **Service role**, do one of the following:
   + Choose **New service role** to allow CodePipeline to create a service role in IAM.
   + Choose **Existing service role**. In **Role name**, choose your service role from the list.

1. In **Artifact store**: 

   1. Choose **Default location** to use the default artifact store, such as the Amazon S3 artifact bucket designated as the default, for your pipeline in the Region you selected for your pipeline.

   1. Choose **Custom location** if you already have an artifact store, such as an Amazon S3 artifact bucket, in the same Region as your pipeline.
**Note**  
This is not the source bucket for your source code. This is the artifact store for your pipeline. A separate artifact store, such as an S3 bucket, is required for each pipeline. When you create or edit a pipeline, you must have an artifact bucket in the pipeline Region and one artifact bucket per AWS Region where you are running an action.  
For more information, see [Input and output artifacts](welcome-introducing-artifacts.md) and [CodePipeline pipeline structure reference](reference-pipeline-structure.md).

   Choose **Next**.

1. In **Step 3: Add source stage**: 

   1. In **Source provider**, choose **AWS CodeCommit**.

   1. In **Repository name**, choose the name of the CodeCommit repository that you created in [Step 1: Create a CodeCommit repository](tutorials-simple-codecommit.md#codecommit-create-repository).

   1. In **Branch name**, choose the name of the branch that contains your latest code update.

   After you select the repository name and branch, the Amazon CloudWatch Events rule to be created for this pipeline is displayed. 

   Choose **Next**.

1. In **Step 4: Add build stage**, choose **Skip build stage**, and then accept the warning message by choosing **Skip** again. 

   Choose **Next**.

1. In **Step 5: Add test stage**, choose **Skip test stage**, and then accept the warning message by choosing **Skip** again. 

   Choose **Next**.

1. In **Step 6: Add deploy stage**:

   1. In **Action name**, choose **Deploy**. In **Deploy provider**, choose **CloudFormation**.

   1. In **Action mode**, choose **Create or update a stack**.

   1. In **Stack name**, enter a name for the stack. This is the name of the stack that the template will create.

   1. In **Output file name**, enter a name for the outputs file, such as **outputs**. This is the name of the file that will be created by the action after the stack is created.

   1. Expand **Advanced**. Under **Parameter overrides**, enter your template overrides as key-value pairs. For example, this template requires the following overrides.

      ```
      {
      "DBClusterName": "MyDBCluster",
      "DBInstanceName": "MyDBInstance",
      "MasterUser": "UserName",
      "MasterPassword": "Password",
      "DBInstanceClass": "db.r4.large",
      "Purpose": "testing"}
      ```

      If you don't enter overrides, the template creates a stack with default values.

   1. Choose **Next**.

   1. On **Step 7: Review**, choose **Create pipeline**. You should see a diagram that shows the pipeline stages. Allow your pipeline to run. Your two-stage pipeline is complete and ready for the additional stages to be added.

## Step 3: Add an CloudFormation deployment action to create the change set
<a name="tutorials-cloudformation-action-changeset"></a>

Create a next action in your pipeline that will allow CloudFormation to create the change set before the manual approval action.



1. Open the CodePipeline console at [https://console.aws.amazon.com/codepipeline/](https://console.aws.amazon.com/codepipeline/).

   Under **Pipelines**, choose your pipeline and choose **View**. The diagram shows your pipeline source and deployment stages.

1. Choose to edit the pipeline, or continue to display the pipeline in **Edit** mode.

1. Choose to edit the **Deploy** stage.

1. Add a deployment action that will create a change set for the stack that was created in the previous action. You add this action after the existing action in the stage.

   1. In **Action name**, enter **Change\$1Set**. In **Action provider**, choose **AWS CloudFormation **.

   1. In **Input artifact**, choose **SourceArtifact**.

   1. In **Action mode**, choose **Create or replace a change set**.

   1. In **Stack name**, enter the variable syntax as shown. This is the name of the stack that the change set is created for, where the default namespace `DeployVariables` is assigned to the action.

      ```
      #{DeployVariables.StackName}
      ```

   1. In **Change set name**, enter the name of the change set.

      ```
      my-changeset
      ```

   1. In **Parameter Overrides**, change the `Purpose` parameter from `testing` to `production`.

      ```
      {
      "DBClusterName": "MyDBCluster",
      "DBInstanceName": "MyDBInstance",
      "MasterUser": "UserName",
      "MasterPassword": "Password",
      "DBInstanceClass": "db.r4.large",
      "Purpose": "production"}
      ```

   1. Choose **Done** to save the action.

## Step 4: Add a manual approval action
<a name="tutorials-cloudformation-action-approval"></a>

Create a manual approval action in your pipeline.



1. Choose to edit the pipeline, or continue to display the pipeline in **Edit** mode.

1. Choose to edit the **Deploy** stage.

1. Add a manual approval action after the deploy action that creates the change set. This action allows you to verify the created resource change set in CloudFormation before the pipeline executes the change set.

## Step 5: Add a CloudFormation deployment action to execute the change set
<a name="tutorials-cloudformation-action-deployment"></a>

Create a next action in your pipeline that allows CloudFormation to execute the change set after the manual approval action.



1. Open the CodePipeline console at [https://console.aws.amazon.com/codepipeline/](https://console.aws.amazon.com/codepipeline/).

   Under **Pipelines**, choose your pipeline and choose **View**. The diagram shows your pipeline source and deployment stages.

1. Choose to edit the pipeline, or continue to display the pipeline in **Edit** mode.

1. Choose to edit the **Deploy** stage.

1. Add a deployment action that will execute the change set that was approved in the previous manual action:

   1. In **Action name**, enter **Execute\$1Change\$1Set**. In **Action provider**, choose **AWS CloudFormation**.

   1. In **Input artifact**, choose **SourceArtifact**.

   1. In **Action mode**, choose **Execute a change set**.

   1. In **Stack name**, enter the variable syntax as shown. This is the name of the stack that the change set is created for.

      ```
      #{DeployVariables.StackName}
      ```

   1. In **Change set name**, enter the name of the change set you created in the previous action.

      ```
      my-changeset
      ```

   1. Choose **Done** to save the action.

   1. Continue the pipeline run.

## Step 6: Add a CloudFormation deployment action to delete the stack
<a name="tutorials-cloudformation-action-delete"></a>

Create a final action in your pipeline that allows CloudFormation to get the stack name from the variable in the outputs file and delete the stack.



1. Open the CodePipeline console at [https://console.aws.amazon.com/codepipeline/](https://console.aws.amazon.com/codepipeline/).

   Under **Pipelines**, choose your pipeline and choose **View**. The diagram shows your pipeline source and deployment stages.

1. Choose to edit the pipeline.

1. Choose to edit the **Deploy** stage.

1. Add a deployment action that will delete the stack:

   1. In **Action name**, choose **DeleteStack**. In **Deploy provider**, choose **CloudFormation**.

   1. In **Action mode**, choose **Delete a stack**.

   1. In **Stack name**, enter the variable syntax as shown. This is the name of the stack that the action will delete.

   1. Choose **Done** to save the action.

   1. Choose **Save** to save the pipeline.

   The pipeline runs when it is saved.