Tutorial: Create a pipeline that uses variables from AWS CloudFormation deployment actions - AWS CodePipeline

Tutorial: Create a pipeline that uses variables from AWS CloudFormation deployment actions

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.

Prerequisites: Create an AWS CloudFormation service role and a CodeCommit repository

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

  • 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

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

  1. Navigate to the sample template page for your Region. For example, the page for us-west-2 is at https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/sample-templates-services-us-west-2.html. Under Amazon DocumentDB, download the template for an Amazon DocumentDB Cluster. The file name is documentdb_full_stack.yaml.

  2. 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.
    2. For this example, add the following StackName output to your Outputs: section in the template.

      StackName: Value: !Ref AWS::StackName
  3. 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.

    2. Choose Add file, and then choose Upload file.

    3. 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.yml

Step 2: Create your pipeline

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

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.

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

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

  4. In Service role, do one of the following:

    • Choose New service role to allow CodePipeline to create a service role in IAM. In Role name, the role and policy name both default to this format: AWSCodePipelineServiceRole-region-pipeline_name.

      For example, the service role created for this tutorial is AWSCodePipelineServiceRole-us-west-2-MyS3DeployPipeline.

    • Choose Existing service role. In Role name, choose your service role from the list.

  5. 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.

    2. 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 and CodePipeline pipeline structure reference.

    Choose Next.

  6. In Step 2: Add source stage:

    1. In Source provider, choose AWS CodeCommit.

    2. In Repository name, choose the name of the CodeCommit repository that you created in Step 1: Create a CodeCommit repository.

    3. 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.

  7. In Step 3: Add build stage, choose Skip build stage, and then accept the warning message by choosing Skip again.

    Choose Next.

  8. In Step 4: Add deploy stage:

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

    2. In Action mode, choose Create or update a stack.

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

    4. 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.

    5. 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.

      
                Console screenshot showing the fields under step 4: Add deploy
                  stage.
    6. Choose Next.

    7. Choose Create pipeline. Allow your pipeline to run. Your two-stage pipeline is complete and ready for the additional stages to be added.

Step 3: Add an AWS CloudFormation deployment action to create the change set

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

  1. Open the CodePipeline console at https://console.aws.amazon.com/codepipeline/.

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

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

  3. Add a deployment action that will create a change set for the stack that was created in the previous action:

    1. In Action name, enter Change_Set. In Action provider, choose AWS CloudFormation.

    2. In Input artifact, choose SourceArtifact.

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

    4. 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}
    5. In Change set name, enter the name of the change set.

      my-changeset
    6. 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"}
    7. Choose Done to save the action.

Step 4: Add a manual approval action

Create a manual approval action in your pipeline.

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

  2. 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 AWS CloudFormation before the pipeline executes the change set.

Step 5: Add a CloudFormation deployment action to execute the change set

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

  1. Open the CodePipeline console at https://console.aws.amazon.com/codepipeline/.

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

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

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

    1. In Action name, enter Execute_Change_Set. In Action provider, choose AWS CloudFormation.

    2. In Input artifact, choose SourceArtifact.

    3. In Action mode, choose Execute a change set.

    4. 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}
    5. In Change set name, enter the name of the change set you created in the previous action.

      my-changeset
    6. Choose Done to save the action.

    7. Continue the pipeline run.

Step 6: Add a CloudFormation deployment action to delete the stack

Create a final action in your pipeline that allows AWS 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/.

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

  2. Choose to edit the pipeline.

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

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

    2. In Action mode, choose Delete a stack.

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

      
                Console screenshot showing how to add a deployment action to delete the
                  stack.
    4. Choose Done to save the action.

    5. Choose Save to save the pipeline.

      
                Diagram of the pipeline stages, including source, deploy, approval, and
                  delete stack.

    The pipeline runs when it is saved.