AWS CodePipeline
User Guide (API Version 2015-07-09)

The procedures in this guide support the new console design. If you choose to use the older version of the console, you will find many of the concepts and basic procedures in this guide still apply. To access help in the new console, choose the information icon.

Tutorial: Create a Pipeline That Deploys to AWS Service Catalog

AWS Service Catalog enables you to create and provision products based on AWS CloudFormation templates. This tutorial shows you how to create and configure a pipeline to deploy your product template to AWS Service Catalog and deliver changes you have made in your source repository (already created in GitHub, AWS CodeCommit, or Amazon S3).

First, you create a product in AWS Service Catalog, and then you create a pipeline in AWS CodePipeline. This tutorial provides two options for setting up the deployment configuration:

Option 1: Deploy to AWS Service Catalog Without a Configuration File

In this example, you upload the sample AWS CloudFormation template file for an Amazon S3 bucket, and then create your product in AWS Service Catalog. Next, you create your pipeline and specify deployment configuration in the AWS CodePipeline console.

Step 1: Upload Sample Template File to Source Repository

  1. Open a text editor. Create a sample template by pasting the following into the file. Save the file as S3_template.json.

    { "AWSTemplateFormatVersion": "2010-09-09", "Description": "AWS CloudFormation Sample Template S3_Bucket: Sample template showing how to create a privately accessible S3 bucket. **WARNING** This template creates an S3 bucket. You will be billed for the AWS resources used if you create a stack from this template.", "Resources": { "S3Bucket": { "Type": "AWS::S3::Bucket", "Properties": {} } }, "Outputs": { "BucketName": { "Value": { "Ref": "S3Bucket" }, "Description": "Name of Amazon S3 bucket to hold website content" } } }

    This template allows AWS CloudFormation to create an Amazon S3 bucket that can be used by AWS Service Catalog.

  2. Upload the S3_template.json file to your AWS CodeCommit repository.

Step 2: Create a Product in AWS Service Catalog

  1. As an IT administrator, sign in to the AWS Service Catalog console, go to the Products page, and then choose Upload new product.

  2. On the Upload new product page, complete the following:

    1. In Product name, enter the name you want to use for your new product.

    2. In Description, enter the product catalog description. This description is shown in the product listing to help the user choose the correct product.

    3. In Provided by, enter the name of your IT department or administrator.

    4. Choose Next.

  3. (Optional) In Enter support details, enter contact information for product support, and choose Next.

  4. In Version details, complete the following:

    1. Choose Upload a template file. Browse for your S3_template.json file and upload it.

    2. In Version title, enter the name of the product version (for example, "devops S3 v2").

    3. In Description, enter details that distinguish this version from other versions.

    4. Choose Next.

  5. On the Review page, verify that the information is correct, and then choose Confirm and upload.

  6. On the Products page, in the browser, copy the URL of your new product. This contains the product ID. Copy and retain this product ID. You use it when you create your pipeline in AWS CodePipeline.

    Here is the URL for a product named my-product. To extract the product ID, copy the value between the equals sign (=) and the ampersand (&). In this example, the product ID is prod-example123456.

    https://<region-URL>/servicecatalog/home?region=<region>#/admin-products?productCreated=prod-example123456&createdProductTitle=my-product

    Note

    Copy the URL for your product before you navigate away from the page. Otherwise, you must use the CLI to obtain your product ID.

    After a few seconds, your product appears on the Products page. You might need to refresh your browser to see the product in the list.

Step 3: Create Your Pipeline

  1. To name your pipeline and select parameters for your pipeline, do the following:

    1. Sign in to the AWS Management Console and open the AWS CodePipeline console at https://console.aws.amazon.com/codepipeline/.

    2. Choose Getting started. Choose Create pipeline, and then enter a name for your pipeline.

    3. In Service role name, choose New service role. This creates a service role for AWS CodePipeline to manage permissions to other AWS services.

      Note

      If you use an AWS CodePipeline service role that was created before October 16 2018, you need to add permissions for AWS Service Catalog. Open the IAM console, find the role, and then add the following permissions to the role's policy. For more information, see Add Permissions for Other AWS Services.

      "Statement": [ { "Effect": "Allow", "Action": [ "servicecatalog:ListProvisioningArtifacts", "servicecatalog:CreateProvisioningArtifact", "servicecatalog:DescribeProvisioningArtifact", "servicecatalog:DeleteProvisioningArtifact”, “servicecatalog:UpdateProduct” ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "cloudformation:ValidateTemplate" ], "Resource": "*" }
    4. In Artifact store, choose Default location. This uses the default Amazon S3 artifact bucket for this region.

    5. Choose Next.

  2. To add a source stage, do the following:

    1. In Source provider, choose AWS CodeCommit.

    2. In Repository name and Branch name, enter the repository and branch you want to use for your source action.

    3. Choose Next.

  3. In Add build stage, choose Skip, and then choose Skip on the confirmation message.

  4. In Add deploy stage, complete the following:

    1. In Deploy provider, choose AWS Service Catalog.

    2. For deployment consiguration, choose Provide deploy configuration in the console.

      
                  Add your pipeline's AWS Service Catalog deploy stage
    3. In Product ID, paste the product ID you copied from the AWS Service Catalog console.

    4. In Template file path, enter the relative path where the template file is stored.

    5. In Product type, choose AWS CloudFormation Template.

    6. In Product version name, enter the name of the product version you specified in AWS Service Catalog. If you want to have the template change deployed to a new product version, enter a product version name that has not been used for any previous product version in the same product.

    7. For Input artifact, choose the source input artifact.

    8. Choose Next.

  5. In Review, review your pipeline settings, and then choose Create.

  6. After your pipeline runs successfully, on the deployment stage, choose Details. This opens your product in AWS Service Catalog.

    
              View your pipeline's AWS Service Catalog deploy stage
  7. Under your product information, choose your version name to open the product template. View the template deployment.

    
              View your pipeline's AWS Service Catalog deployed template

Step 4: Push a Change and Verify Your Product in AWS Service Catalog

  1. View your pipeline in the AWS CodePipeline console, and on your source stage, choose Details. Your source AWS CodeCommit repository opens in the console. Choose Edit, and make a change in the file (for example, to the description).

    "Description": "Name of Amazon S3 bucket to hold and version website content"
  2. Commit and push your change. Your pipeline starts after you push the change. When the run of the pipeline is complete, on the deployment stage, choose Details to open your product in AWS Service Catalog.

  3. Under your product information, choose the new version name to open the product template. View the deployed template change.

    
              View your pipeline's AWS Service Catalog updated template

Option 2: Deploy to AWS Service Catalog Using a Configuration File

In this example, you upload the sample AWS CloudFormation template file for an Amazon S3 bucket, and then create your product in AWS Service Catalog. You also upload a separate configuration file that specifies your deployment configuration. Next, you create your pipeline and specify the location of your configuration file.

Step 1: Upload Sample Template File to Source Repository

  1. Open a text editor. Create a sample template by pasting the following into the file. Save the file as S3_template.json.

    { "AWSTemplateFormatVersion": "2010-09-09", "Description": "AWS CloudFormation Sample Template S3_Bucket: Sample template showing how to create a privately accessible S3 bucket. **WARNING** This template creates an S3 bucket. You will be billed for the AWS resources used if you create a stack from this template.", "Resources": { "S3Bucket": { "Type": "AWS::S3::Bucket", "Properties": {} } }, "Outputs": { "BucketName": { "Value": { "Ref": "S3Bucket" }, "Description": "Name of Amazon S3 bucket to hold website content" } } }

    This template allows AWS CloudFormation to create an Amazon S3 bucket that can be used by AWS Service Catalog.

  2. Upload the S3_template.json file to your AWS CodeCommit repository.

Step 2: Create Your Product Deployment Configuration File

  1. Open a text editor. Create the configuration file for your product. The configuration file is used to define your AWS Service Catalog deployment parameters/preferences. You use this file when you create your pipeline.

    This sample provides a ProductVersionName of "devops S3 v2" and a ProductVersionDescription of MyProductVersionDescription. If you want to have the template change deployed to a new product version, just enter a product version name that has not been used for any previous product version in the same product.

    Save the file as sample_config.json.

    { "SchemaVersion": "1.0", "ProductVersionName": "devops S3 v2", "ProductVersionDescription": "MyProductVersionDescription", "ProductType": "CLOUD_FORMATION_TEMPLATE", "Properties": { "TemplateFilePath": "/sample_template.json" } }

    This file creates the product version information for you each time your pipeline runs.

  2. Upload the sample_config.json file to your AWS CodeCommit repository. Make sure you upload this file to your source repository.

Step 3: Create a Product in AWS Service Catalog

  1. As an IT administrator, sign in to the AWS Service Catalog console, go to the Products page, and then choose Upload new product.

  2. On the Upload new product page, complete the following:

    1. In Product name, enter the name you want to use for your new product.

    2. In Decription, enter the product catalog description. This description appears in the product listing to help the user choose the correct product.

    3. In Provided by, enter the name of your IT department or administrator.

    4. Choose Next.

  3. (Optional) In Enter support details, enter product support contact information, and then choose Next.

  4. In Version details, complete the following:

    1. Choose Upload a template file. Browse for your S3_template.json file and upload it.

    2. In Version title, enter the name of the product version (for example, "devops S3 v2").

    3. In Description, enter details that distinguish this version from other versions.

    4. Choose Next.

  5. On the Review page, verify that the information is correct, and then choose Confirm and upload.

  6. On the Products page, in the browser, copy the URL of your new product. This contains the product ID. Copy and retain this product ID. You use when you create your pipeline in AWS CodePipeline.

    Here is the URLfor a product named my-product. To extract the product ID, copy the value between the equals sign (=) and the ampersand (&). In this example, the product ID is prod-example123456.

    https://<region-URL>/servicecatalog/home?region=<region>#/admin-products?productCreated=prod-example123456&createdProductTitle=my-product

    Note

    Copy the URL for your product before navigating away from the creation page. Otherwise, you will use the CLI to obtain your product ID rather than the console.

    After a few seconds, your product appears on the Products page. You might need to refresh your browser to see the product in the list.

Step 4: Create Your Pipeline

  1. To name your pipeline and select parameters for your pipeline, do the following:

    1. Sign in to the AWS Management Console and open the AWS CodePipeline console at https://console.aws.amazon.com/codepipeline/.

    2. Choose Getting started. Choose Create pipeline, and then enter a name for your pipeline.

    3. In Service role name, choose New service role. This creates a service role for AWS CodePipeline to manage permissions to other AWS services.

      Note

      If you use an AWS CodePipeline service role that was created before October 16 2018, you need to add permissions for AWS Service Catalog. Open the IAM console, find the role, and then add the following permissions to the role's policy. For more information, see Add Permissions for Other AWS Services.

      "Statement": [ { "Effect": "Allow", "Action": [ "servicecatalog:ListProvisioningArtifacts", "servicecatalog:CreateProvisioningArtifact", "servicecatalog:DescribeProvisioningArtifact", "servicecatalog:DeleteProvisioningArtifact”, “servicecatalog:UpdateProduct” ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "cloudformation:ValidateTemplate" ], "Resource": "*" }
    4. In Artifact store, choose Default location. This uses the default Amazon S3 artifact bucket for this region.

    5. Choose Next.

  2. To add a source stage, do the following:

    1. In Source provider, choose AWS CodeCommit.

    2. In Repository name and Branch name, enter the repository and branch you want to use for your source action.

    3. Choose Next.

  3. In Add build stage, choose Skip, and then choose Skip on the confirmation message.

  4. In Add deploy stage, complete the following:

    1. In Deploy provider, choose AWS Service Catalog.

    2. Choose Use configuration file.

      
                  Add your pipeline's AWS Service Catalog deploy stage and choose a separate configuration
                    file
    3. In Product ID, paste the product ID you copied from the AWS Service Catalog console.

    4. In Configuration file path, enter the file path of the configuration file in your repository.

    5. Choose Next.

  5. In Review, review your pipeline settings, and then choose Create.

  6. After your pipeline runs successfully, on your deployment stage, choose Details to open your product in AWS Service Catalog.

    
              View your pipeline's AWS Service Catalog deploy stage
  7. Under your product information, choose your version name to open the product template. View the template deployment.

    
              View your pipeline's AWS Service Catalog deployed template

Step 5: Push a Change and Verify Your Product in Service Catalog

  1. View your pipeline in the AWS CodePipeline console, and on the source stage, choose Details. Your source AWS CodeCommit repository opens in the console. Choose Edit, and then make a change in the file (for example, to the description).

    "Description": "Name of Amazon S3 bucket to hold and version website content"
  2. Commit and push your change. Your pipeline starts after you push the change. When the run of the pipeline is complete, on the deployment stage, choose Details to open your product in AWS Service Catalog.

  3. Under your product information, choose the new version name to open the product template. View the deployed template change.

    
              View your pipeline's AWS Service Catalog updated template