Prerequisites
For stack set operations, you use two different accounts: an administration account and a target account.
You create stack sets in the administrator account. You create individual stacks that belong to a stack set in the target account.
To create an administrator role with your administrator account
• Follow the instructions in Set up basic permissions for stack set operations. Your role must be named AWSCloudFormationStackSetAdministrationRole.
Step 1: Upload the sample AWS CloudFormation template and parameter file
To create a service role in the target account
• Create a service role in the target account that trusts the administrator account. Follow the instructions in Set up basic permissions for stack set operations. Your role must be named AWSCloudFormationStackSetExecutionRole.
Step 1: Upload the sample AWS CloudFormation template and parameter file
Create a source bucket for your stack set template and parameters files. Download the sample AWS CloudFormation template file, set up a parameters file, and then zip the files before upload to your S3 source bucket.
Note
Make sure to ZIP the source files before you upload to your S3 source bucket, even if the only source file is the template.To create an S3 source bucket
1. Sign in to the AWS Management Console and open the Amazon S3 console at https://
console.aws.amazon.com/s3/.
2. Choose Create bucket.
3. In Bucket name, enter a name for your bucket.
In Region, choose the Region where you want to create your pipeline. Choose Create bucket.
4. After the bucket is created, a success banner displays. Choose Go to bucket details.
5. On the Properties tab, choose Versioning. Choose Enable versioning, and then choose Save.
To create the AWS CloudFormation template file
1. Download the following sample template file for generating CloudTrail configuration for stack sets: https://s3.amazonaws.com/cloudformation-stackset-sample-templates-us-east-1/
EnableAWSCloudtrail.yml.
2. Save the file as template.yml.
To create the parameters.txt file
1. Create a file with the parameters for your deployment. Parameters are values that you want to update in your stack at runtime. The following sample file updates the template parameters for your stack set to enable logging validation and global events.
[
{ "ParameterKey": "EnableLogFileValidation", "ParameterValue": "true"
}, {
"ParameterKey": "IncludeGlobalEvents", "ParameterValue": "true"
} ]
2. Save the file as parameters.txt.
Step 2: Create your pipeline
To create the accounts.txt file
1. Create a file with the accounts where you want to create instances, as shown in the following sample file.
[ "111111222222,333333444444"
]
2. Save the file as accounts.txt.
To create and upload source files
1. Combine the files into a single ZIP file. Your files should look like this in your ZIP file.
template.yml parameters.txt accounts.txt
2. Upload the ZIP file to your S3 bucket. This file is the source artifact created by the Create Pipeline wizard for your deployment action in CodePipeline.
Step 2: Create your pipeline
In this section, you create a pipeline with the following actions:
• A source stage with an S3 source action where the source artifact is your template file and any supporting source files.
• A deployment stage with an AWS CloudFormation stack set deployment action that creates the stack set.
• A deployment stage with an AWS CloudFormation stack instances deployment action that creates the stacks and instances within the target accounts.
To create a pipeline with a CloudFormationStackSet action
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 MyStackSetsPipeline.
4. In Service role, choose New service role to allow CodePipeline to create a service role in IAM.
5. In Artifact store, leave the defaults.
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 (p. 14) and CodePipeline pipeline structure reference (p. 430).
Choose Next.
6. On the Step 2: Add source stage page, in Source provider, choose Amazon S3.
7. In Bucket, enter the S3 source bucket you created for this tutorial, such as BucketName. In S3 object key, enter the file path and file name for your ZIP file, such as MyFiles.zip.
Step 3: View initial deployment
8. Choose Next.
9. In Step 3: Add build stage, choose Skip build stage, and then accept the warning message by choosing Skip again.
Choose Next.
10. In Step 4: Add deploy stage:
a. In Deploy provider, choose AWS CloudFormation Stack Set.
b. In Stack set name, enter a name for the stack set. This is the name of the stack set that the template creates.
Note
Make a note of your stack set name. You will use it when you add the second StackSets deployment action to your pipeline.
c. In Template path, enter the artifact name and file path where you uploaded your template file.
For example, enter the following using the default source artifact name SourceArtifact.
SourceArtifact::template.yml
d. In Deployment targets, enter the artifact name and file path where you uploaded your accounts file. For example, enter the following using the default source artifact name SourceArtifact.
SourceArtifact::accounts.txt
e. In Deployment target AWS Regions, enter one Region for deployment of your initial stack instance, such as us-east-1.
f. Expand Deployment options. In Parameters, enter the artifact name and file path where you uploaded your parameters file. For example, enter the following using the default source artifact name SourceArtifact.
SourceArtifact::parameters.txt
To enter the parameters as a literal input rather than a file path, enter the following:
ParameterKey=EnableLogFileValidation,ParameterValue=true ParameterKey=IncludeGlobalEvents,ParameterValue=true
g. In Capabilities, choose CAPABILITY_IAM and CAPABILITY_NAMED_IAM.
h. In Permission model, choose SELF_MANAGED.
i. In Failure tolerance percentage, enter 20.
j. In Max concurrent percentage, enter 25.
k. Choose Next.
l. Choose Create pipeline. Your pipeline displays.
m. Allow your pipeline to run.
Step 3: View initial deployment
View the resources and status for your initial deployment. After verifying the deployment successfully created your stack set, you can add the second action to your Deploy stage.
To view the resources
Step 4: Add a CloudFormationStackInstances action
2. Under Pipelines, choose your pipeline and choose View. The diagram shows your pipeline source and deployment stages.
3. Choose the AWS CloudFormation action on the CloudFormationStackSet action in your pipeline.
The template, resources, and events for your stack set are shown in the AWS CloudFormation console.
4. In the left navigation panel, choose StackSets. In the list, choose the new stack set.
5. Choose the Stack instances tab. Verify that one stack instance for each account you provided was created in the us-east-1 Region. Verify that the status for each stack instance is CURRENT.
Step 4: Add a CloudFormationStackInstances action
Create a next action in your pipeline that will allow AWS CloudFormation StackSets to create the remainingstack instances.
To create a next action in your pipeline
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. The pipeline displays in Edit mode.
3. On the Deploy stage, choose Edit.
4. Under the AWS CloudFormation Stack Set deploy action, choose Add action group.
5. On the Edit action page, add the action details:
a. In Action name, enter a name for the action.
b. In Action provider, choose AWS CloudFormation Stack Instances.
c. Under Input artifacts, choose SourceArtifact.
d. In Stack set name, enter the name for the stack set. This is the name of the stack set that you provided in the first action.
e. In Deployment targets, enter the artifact name and file path where you uploaded your accounts file. For example, enter the following using the default source artifact name SourceArtifact.
SourceArtifact::accounts.txt
f. In Deployment target AWS Regions, enter the Regions for deployment of your remaining stack instances, such as us-east-2 and eu-central-1 as follows:
us-east2, eu-central-1
g. In Failure tolerance percentage, enter 20.
h. In Max concurrent percentage, enter 25.
i. Choose Save.
j. .Manually release a change. Your updated pipeline displays with two actions in the Deploy stage.
Step 5: View stack set resources for your deployment
You can view the resources and status for your stack set deployment.
To view the resources
1. Open the CodePipeline console at https://console.aws.amazon.com/codepipeline/.
Step 6: Make an update to your stack set
2. Under Pipelines, choose your pipeline and then choose View. The diagram shows your pipeline source and deployment stages.
3. Choose the AWS CloudFormation action on the AWS CloudFormation Stack Instances action in your pipeline. The template, resources, and events for your stack set are shown in the AWS CloudFormation console.
4. In the left navigation panel, choose StackSets. In the list, choose your stack set.
5. Choose the Stack instances tab. Verify that all remaining stack instances for each account you provided were created or updated in the expected Regions. Verify that the status for each stack instance is CURRENT.
Step 6: Make an update to your stack set
Make an update to your stack set and deploy the update to instances. In this example, you also make a change to the deployment targets you want to designate for update. The instances that are not part of the update move to an outdated status.
1. Open the CodePipeline console at https://console.aws.amazon.com/codepipeline/.
2. Under Pipelines, choose your pipeline and then choose Edit. On the Deploy stage, choose Edit.
3. Choose to edit the AWS CloudFormation Stack Set action in your pipeline. In Description, write over the existing description with a new description for the stack set.
4. Choose to edit the AWS CloudFormation Stack Instances action in your pipeline. In Deployment target AWS Regions, delete the us-east-2 value that was entered when the action was created.
5. Save the changes. Choose Release change to run your pipeline.
6. Open your action in AWS CloudFormation. Choose the StackSet info tab. In StackSet description, verify that the new description is shown.
7. Choose the Stack instances tab. Under Status, verify that the status for the stack instances in us-east-2 is OUTDATED.
Best practices
CodePipeline best practices and use cases
AWS CodePipeline is integrated with a number of products and services. The following sections describe best practices and use cases for CodePipeline and these related products and services.
A simple business use case for CodePipeline can help you understand ways you might implement the service and control user access. The use cases are described in general terms. They do not prescribe the APIs to use to achieve the results you want.
Topics
• Best practices (p. 144)
• Use cases for CodePipeline (p. 145)
Best practices
Use the best practices outlined in these sections when using CodePipeline.
Security best practices for CodePipeline resources
You use encryption and authentication for the source repositories that connect to your pipelines. For CodePipeline best practices for security, see Security best practices (p. 428).
Monitoring and logging best practices for CodePipeline resources
You can use logging features in AWS to determine the actions users have taken in your account and the resources that were used. The log files show:
• The time and date of actions.
• The source IP address for an action.
• Which actions failed due to inadequate permissions.
Logging features are available in the following AWS services:
• AWS CloudTrail can be used to log AWS API calls and related events made by or on behalf of an AWS account. For more information, see Logging CodePipeline API calls with AWS CloudTrail (p. 367).
• Amazon CloudWatch Events can be used to monitor your AWS Cloud resources and the applications you run on AWS. You can create alerts in Amazon CloudWatch Events based on metrics that you define. For more information, see Monitoring CodePipeline events (p. 350).
Best practices for the Jenkins plugin
Use the best practices provided in this section for pipelines with a Jenkins action provider.
Examples of how to use CodePipeline
Configure a separate Amazon EC2 instance and IAM role for your Jenkins build server
As a best practice, when you use a Jenkins build provider for your pipeline’s build or test action, install Jenkins on an Amazon EC2 instance and configure a separate EC2 instance profile. Make sure the
instance profile grants Jenkins only the AWS permissions required to perform tasks for your project, such as retrieving files from Amazon S3.
The instance profile provides applications running on an Amazon EC2 instance with the credentials to access other AWS services. As a result, you do not need to configure AWS credentials (AWS access key and secret key).
To learn how to create the role for your Jenkins instance profile, see the steps in Create an IAM role to use for Jenkins integration (p. 60).
Use cases for CodePipeline
You can create pipelines that integrate with other AWS services. These can be AWS services, such as Amazon S3, or third-party products, such as GitHub. This section provides examples for using CodePipeline to automate your code releases using different product integrations. For a full list of integrations with CodePipeline organized by action type, see CodePipeline pipeline structure reference (p. 430).
Topics
• Use CodePipeline with Amazon S3, AWS CodeCommit, and AWS CodeDeploy (p. 145)
• Use CodePipeline with third-party action providers (GitHub and Jenkins) (p. 146)
• Use CodePipeline with AWS CodeStar to build a pipeline in a code project (p. 146)
• Use CodePipeline to compile, build, and test code with CodeBuild (p. 146)
• Use CodePipeline with Amazon ECS for continuous delivery of container-based applications to the cloud (p. 147)
• Use CodePipeline with Elastic Beanstalk for continuous delivery of web applications to the cloud (p. 147)
• Use CodePipeline with AWS Lambda for continuous delivery of Lambda-based and serverless applications (p. 147)
• Use CodePipeline with AWS CloudFormation templates for continuous delivery to the cloud (p. 147)
Use CodePipeline with Amazon S3, AWS CodeCommit, and AWS CodeDeploy
When you create a pipeline, CodePipeline integrates with AWS products and services that act as action providers in each stage of your pipeline. When you choose stages in the wizard, you must choose a source stage and at least a build or deploy stage. The wizard creates the stages for you with default names that cannot be changed. These are the stage names created when you set up a full three-stage pipeline in the wizard:
• A source action stage with a default name of “Source.”
• A build action stage with a default name of “Build.”
Use CodePipeline with third-party action providers (GitHub and Jenkins)
• A deploy action stage with a default name of “Staging.”
You can use the tutorials in this guide to create pipelines and specify stages:
• The steps in Tutorial: Create a simple pipeline (S3 bucket) (p. 39) help you use the wizard to create a pipeline with two default stages: “Source” and “Staging”, where your Amazon S3 repository is the source provider. This tutorial creates a pipeline that uses AWS CodeDeploy to deploy a sample application from an Amazon S3 bucket to Amazon EC2 instances running Amazon Linux.
• The steps in Tutorial: Create a simple pipeline (CodeCommit repository) (p. 50) help you use the wizard to create a pipeline with a “Source” stage that uses your AWS CodeCommit repository as the source provider. This tutorial creates a pipeline that uses AWS CodeDeploy to deploy a sample application from an AWS CodeCommit repository to an Amazon EC2 instance running Amazon Linux.
Use CodePipeline with third-party action providers (GitHub and Jenkins)
You can create pipelines that integrate with third-party products such as GitHub and Jenkins. The steps in Tutorial: Create a four-stage pipeline (p. 58) show you how to create a pipeline that:
• Gets source code from a GitHub repository,
• Uses Jenkins to build and test the source code,
• Uses AWS CodeDeploy to deploy the built and tested source code to Amazon EC2 instances running Amazon Linux or Microsoft Windows Server.
Use CodePipeline with AWS CodeStar to build a pipeline in a code project
AWS CodeStar is a cloud-based service that provides a unified user interface for managing software development projects on AWS. AWS CodeStar works with CodePipeline to combine AWS resources into a project development toolchain. You can use your AWS CodeStar dashboard to automatically create the pipeline, repositories, source code, build spec files, deployment method, and hosting instances or serverless instances required for a complete code project.
To create your AWS CodeStar project, you choose your coding language and the type of application you want to deploy. You can create the following project types: a web application, a web service, or an Alexa skill.
At any time, you can integrate your preferred IDE into your AWS CodeStar dashboard. You can also add and remove team members and manage permissions for team members on your project. For a tutorial that shows you how to use AWS CodeStar to create a sample pipeline for a serverless application, see Tutorial: Creating and Managing a Serverless Project in AWS CodeStar.
Use CodePipeline to compile, build, and test code with CodeBuild
CodeBuild is a managed build service in the cloud that lets you build and test your code without a server or system. Use CodePipeline with CodeBuild to automate running revisions through the pipeline for continuous delivery of software builds whenever there is a change to the source code. For more information, see Use CodePipeline with CodeBuild to test code and run builds.
Use CodePipeline with Amazon ECS for continuous delivery of container-based applications to the cloud
Use CodePipeline with Amazon ECS for continuous delivery of container-based applications to the cloud
Amazon ECS is a container management service that lets you deploy container-based applications to Amazon ECS instances in the cloud. Use CodePipeline with Amazon ECS to automate running revisions through the pipeline for continuous deployment of container-based applications whenever there is a change to the source image repository. For more information, see Tutorial: Continuous Deployment with CodePipeline.
Use CodePipeline with Elastic Beanstalk for
continuous delivery of web applications to the cloud
Elastic Beanstalk is a compute service that lets you deploy web applications and services to web servers. Use CodePipeline with Elastic Beanstalk for continuous deployment of web applications to your application environment. You can also use AWS CodeStar to create a pipeline with an Elastic Beanstalk deploy action.
Use CodePipeline with AWS Lambda for continuous delivery of Lambda-based and serverless applications
You can use AWS Lambda with CodePipeline for invoking an AWS Lambda function, as described in Deploying Serverless Applications. You can also use AWS Lambda and AWS CodeStar to create a pipeline for deploying serverless applications.
Use CodePipeline with AWS CloudFormation templates for continuous delivery to the cloud
You can use AWS CloudFormation with CodePipeline for continuous delivery and automation. For more information, see Continuous Delivery with CodePipeline. AWS CloudFormation is also used to create the templates for pipelines created in AWS CodeStar.
Tagging resources
A tag is a custom attribute label that you or AWS assigns to an AWS resource. Each AWS tag has two parts:
• A tag key (for example, CostCenter, Environment, Project, or Secret). Tag keys are case sensitive.
• An optional field known as a tag value (for example, 111122223333, Production, or a team name).
Omitting the tag value is the same as using an empty string. Like tag keys, tag values are case sensitive.
Together these are known as key-value pairs.
Tags help you identify and organize your AWS resources. Many AWS services support tagging, so you can assign the same tag to resources from different services to indicate that the resources are related. For example, you can assign the same tag to a pipeline that you assign to an Amazon S3 source bucket.
For tips on using tags, see the AWS Tagging Strategies post on the AWS Answers blog.
You can tag the following resource types in CodePipeline:
• Tag a pipeline in CodePipeline (p. 278)
• Tag a custom action in CodePipeline (p. 302)
You can use the AWS CLI, CodePipeline APIs, or AWS SDKs to:
• Add tags to a pipeline, custom action, or webhook when you create it.
• Add, manage, and remove tags for a pipeline, custom action, or webhook.
You can also use the console to add, manage, and remove tags for a pipeline.
In addition to identifying, organizing, and tracking your resource with tags, you can use tags in IAM policies to help control who can view and interact with your resource. For examples of tag-based access policies, see Using tags to control access to CodePipeline resources (p. 397).