AWS CodeDeploy
User Guide (API Version 2014-10-06)

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.

AWS CodeDeploy Deployments

This topic provides information about the components and workflow of deployments in AWS CodeDeploy. The deployment process varies, depending on the compute platform (EC2/On-Premises or Lambda) you use for your deployments.

Note

Deployments on an Amazon ECS or an AWS Lambda compute platform are not supported in the following regions: Asia Pacific (Osaka-Local), AWS GovCloud (US-East), AWS GovCloud (US-West), China (Beijing), and China (Ningxia).

Deployments on an AWS Lambda Compute Platform

This topic provides information about the components and workflow of AWS CodeDeploy deployments that use the AWS Lambda compute platform.

Deployment Components on an AWS Lambda Compute Platform

The following diagram shows the components in an AWS CodeDeploy deployment on an AWS Lambda compute platform.

Deployment Workflow on an AWS Lambda Compute Platform

The following diagram shows the major steps in the deployment of new and updated AWS Lambda functions.

These steps include:

  1. Creating an application by specifying a name that uniquely represents the application revisions you want to deploy. To deploy Lambda functions, you specify the AWS Lambda compute platform when you create your application. AWS CodeDeploy uses this name during a deployment to make sure it is referencing the correct deployment components, such as the deployment group, deployment configuration, and application revision. For more information, see Create an Application with AWS CodeDeploy.

  2. Setting up a deployment group by specifying your deployment group's name.

  3. Choosing a deployment configuration to specify how traffic is shifted from your original AWS Lambda function version to your new Lambda function version. For more information, see View Deployment Configuration Details.

  4. Specifying an application specification file (AppSpec file). You can upload the file to Amazon S3, enter it into the console in YAML or JSON format, or specify it with the AWS CLI or SDK. The AppSpec file specifies an Amazon ECS task definition for the deployment, a container name and port mapping used to route traffic, and Lambda functions run after deployment lifecycle hooks. If you don't want to create an AppSpec file, you can enter this information directly in the console in YAML or JSON format. For more information, see Working with Application Revisions for AWS CodeDeploy.

  5. Deploying your application revision to the deployment group. AWS CodeDeploy deploys the Lambda function revision you specified. The traffic is shifted to your Lambda function revision using the deployment AppSpec file you chose when you created your application. For more information, see Create a Deployment with AWS CodeDeploy.

  6. Checking the deployment results. For more information, see Monitoring Deployments in AWS CodeDeploy.

Uploading Your Application Revision

Place an AppSpec file in Amazon S3 or enter it directly into the console or AWS CLI. For more information, see Application Specification Files.

Creating Your Application and Deployment Groups

An AWS CodeDeploy deployment group on an AWS Lambda compute platform identifies a collection of one or more AppSpec files. Each AppSpec file can deploy one Lambda function version. A deployment group also defines a set of configuration options for future deployments, such as alarms and rollback configurations.

Deploying Your Application Revision

Now you're ready to deploy the function revision specified in the AppSpec file to the deployment group. You can use the AWS CodeDeploy console or the create-deployment command. There are parameters you can specify to control your deployment, including the revision, deployment group, and deployment configuration.

Updating Your Application

You can make updates to your application and then use the AWS CodeDeploy console or call the create-deployment command to push a revision.

Stopped and Failed Deployments

You can use the AWS CodeDeploy console or the stop-deployment command to stop a deployment. When you attempt to stop the deployment, one of three things happens:

  • The deployment stops, and the operation returns a status of succeeded. In this case, no more deployment lifecycle events are run on the deployment group for the stopped deployment.

  • The deployment does not immediately stop, and the operation returns a status of pending. In this case, some deployment lifecycle events might still be running on the deployment group. After the pending operation is complete, subsequent calls to stop the deployment return a status of succeeded.

  • The deployment cannot stop, and the operation returns an error. For more information, see ErrorInformation and Common Errors in the AWS CodeDeploy API Reference.

Like stopped deployments, failed deployments might result in some deployment lifecycle events having already been run. To find out why a deployment failed, you can use the AWS CodeDeploy console or analyze the log file data from the failed deployment. For more information, see Application Revision and Log File Cleanup and View Log Data for AWS CodeDeploy EC2/On-Premises Deployments.

Redeployments and Deployment Rollbacks

AWS CodeDeploy implements rollbacks by redeploying, as a new deployment, a previously deployed revision.

You can configure a deployment group to automatically roll back deployments when certain conditions are met, including when a deployment fails or an alarm monitoring threshold is met. You can also override the rollback settings specified for a deployment group in an individual deployment.

You can also choose to roll back a failed deployment by manually redeploying a previously deployed revision.

In all cases, the new or rolled-back deployment is assigned its own deployment ID. The list of deployments you can view in the AWS CodeDeploy console shows which ones are the result of an automatic deployment.

For more information, see Redeploy and Roll Back a Deployment with AWS CodeDeploy.

Deployments on an Amazon ECS Compute Platform

This topic provides information about the components and workflow of AWS CodeDeploy deployments that use the Amazon ECS compute platform.

Before You Begin an Amazon ECS Deployment

Before you begin an Amazon ECS application deployment, you must have the following ready. Some requirements are specified when you create your deployment group, and some are specified in the AppSpec file.

Requirement Where specified
Amazon ECS cluster Deployment group
Amazon ECS service Deployment group
Application Load Balancer or Network Load Balancer Deployment group
Production listener Deployment group
Test listener (optional) Deployment group
Two target groups Deployment group
Amazon ECS task definition AppSpec file
Container name AppSpec file
Container port AppSpec file
Amazon ECS cluster

An Amazon ECS cluster is a logical grouping of tasks or services. You specify the Amazon ECS cluster that contains your Amazon ECS service when you create your AWS CodeDeploy application's deployment group. For more information, see Amazon ECS Clusters in the Amazon Elastic Container Service User Guide.

Amazon ECS service

An Amazon ECS service maintains and runs specified instances of a task definition in an Amazon ECS cluster. Your Amazon ECS service must be enabled for AWS CodeDeploy. By default, an Amazon ECS service is enabled for Amazon ECS deployments. When you create your deployment group, you choose to deploy an Amazon ECS service that is in your Amazon ECS cluster. For more information, see Amazon ECS Services in the Amazon Elastic Container Service User Guide.

Application Load Balancer or Network Load Balancer

You must use Elastic Load Balancing with the Amazon ECS service you want to update with an Amazon ECS deployment. You can use an Application Load Balancer or an Network Load Balancer. We recommend an Application Load Balancer so you can take advantage of features such as dynamic port mapping and path-based routing and priority rules. You specify the a load balancer when you create your AWS CodeDeploy application's deployment group. For more information, see Creating a Load Balancer in the Amazon Elastic Container Service User Guide.

One or two listenters

A listener is used by your load balancer to direct traffic to your target groups. One production listener is required. You can specify an optional second test listener that directs traffic to your replacement task set while you run validation tests. You specify one or both listeners when you create your deployment group. If you use the Amazon ECS console to create your Amazon ECS service, your listeners are created for you. For more information, see Listeners for Your Application Load Balancers in the Elastic Load Balancing User Guide and Creating a Service in the Amazon Elastic Container Service User Guide.

Two Amazon ECS target groups

A target group is used to route traffic to a registered target. An Amazon ECS deployment requires two target groups: one for your Amazon ECS application's original task set and one for its replacement task set. During deployment, AWS CodeDeploy creates a replacement task set and reroutes traffic from the original task set to the new one. You specify the target groups when you create your AWS CodeDeploy application's deployment group.

During a deployment, AWS CodeDeploy determines which target group is associated with the task set in your Amazon ECS service that has the status PRIMARY (this is the original task set) and associates one target group with it, and then associates the other target group with the replacement task set. If you do another deployment, the target group associated with the current deployment's original task set is associated with the next deployment's replacement task set. For more information, see Target Groups for Your Application Load Balancers in the Elastic Load Balancing User Guide.

An Amazon ECS task definition

A task definition is required to run the Docker container that contains your Amazon ECS application. You specify the ARN of your task definition in your AWS CodeDeploy application's AppSpec file. For more information, see Amazon ECS Task Definitions in the Amazon Elastic Container Service User Guide and AppSpec 'resources' Section for Amazon ECS Deployments .

A container for your Amazon ECS application

A Docker container contains everything that your software application needs to run. Your load balancer directs traffic to a container in your Amazon ECS application's task set. You specify the name of your container in your AWS CodeDeploy application's AppSpec file. The container specified in your AppSpec file must be one of the containers specified in your Amazon ECS task definition. For more information, see What Is Amazon Elastic Container Service? in the Amazon Elastic Container Service User Guide and AppSpec 'resources' Section for Amazon ECS Deployments .

A port for your replacement task set

During your Amazon ECS deployment, your load balancer directs traffic to this port on the container specified in your AWS CodeDeploy application's AppSpec file. You specify the port in your AWS CodeDeploy application's AppSpec file. For more information, see AppSpec 'resources' Section for Amazon ECS Deployments .

Deployment Components on an Amazon ECS Compute Platform

The following diagram shows the components in an AWS CodeDeploy deployment on an Amazon ECS compute platform.

Deployment Workflow on an Amazon ECS Compute Platform

The following diagram shows the major steps in the deployment of updated Amazon ECS services.

These steps include:

  1. Creating an AWS CodeDeploy application by specifying a name that uniquely represents what you want to deploy. To deploy an Amazon ECS application, in your AWS CodeDeploy application, you specify the Amazon ECS compute platform. AWS CodeDeploy uses an application during a deployment to reference the correct deployment components, such as the deployment group, target groups, listeners, and traffic rerouting behavior, and application revision. For more information, see Create an Application with AWS CodeDeploy.

  2. Setting up a deployment group by specifying:

    • Deployment group name.

    • Your Amazon ECS cluster and service name. The Amazon ECS service's deployment controller must be set to AWS CodeDeploy.

    • The production listener, an optional test listener, and target groups used during a deployment.

    • Deployment settings, such as when to reroute production traffic to the replacement Amazon ECS task set in your Amazon ECS service and when to terminate the original Amazon ECS task set in your Amazon ECS service.

    • Optional settings, such as triggers, alarms, and rollback behavior.

  3. Specify an application specification file (AppSpec file). You can upload it to Amazon S3, enter it into the console in YAML or JSON format, or specify it with the AWS CLI or SDK. The AppSpec file specifies an Amazon ECS task definition for the deployment, a container name and port mapping used to route traffic, and Lambda functions run after deployment lifecycle hooks. The specified container name must be a container in your specified Amazon ECS task definition. For more information, see Working with Application Revisions for AWS CodeDeploy.

  4. Deploying your application revision. AWS CodeDeploy reroutes traffic from the original version of a task set in your Amazon ECS service to a new, replacement task set. Target groups specified in the deployment group are used to serve traffic to the original and replacement task sets. After the deployment is complete, the original task set is terminated. You can specify an optional test listener to serve test traffic to your replacement version before traffic is rerouted to it. For more information, see Create a Deployment with AWS CodeDeploy.

  5. Checking the deployment results. For more information, see Monitoring Deployments in AWS CodeDeploy.

Uploading Your Application Revision

Place an AppSpec file in Amazon S3 or enter it directly into the console or AWS CLI. For more information, see Application Specification Files.

Creating Your Application and Deployment Groups

An AWS CodeDeploy deployment group on an Amazon ECS compute platform identifies listeners to serve traffic to your updated Amazon ECS application and two target groups used during your deployment. A deployment group also defines a set of configuration options, such as alarms and rollback configurations.

Deploying Your Application Revision

Now you're ready to deploy the updated Amazon ECS service specified in your deployment group. You can use the AWS CodeDeploy console or the create-deployment command. There are parameters you can specify to control your deployment, including the revision and deployment group.

Updating Your Application

You can make updates to your application and then use the AWS CodeDeploy console or call the create-deployment command to push a revision.

Stopped and Failed Deployments

You can use the AWS CodeDeploy console or the stop-deployment command to stop a deployment. When you attempt to stop the deployment, one of three things happens:

  • The deployment stops, and the operation returns a status of succeeded. In this case, no more deployment lifecycle events are run on the deployment group for the stopped deployment.

  • The deployment does not immediately stop, and the operation returns a status of pending. In this case, some deployment lifecycle events might still be running on the deployment group. After the pending operation is complete, subsequent calls to stop the deployment return a status of succeeded.

  • The deployment cannot stop, and the operation returns an error. For more information, see Error Information and Common Errors in the AWS CodeDeploy API Reference.

Redeployments and Deployment Rollbacks

AWS CodeDeploy implements rollbacks by rerouting traffic from the replacement task set to the original task set.

You can configure a deployment group to automatically roll back deployments when certain conditions are met, including when a deployment fails or an alarm monitoring threshold is met. You can also override the rollback settings specified for a deployment group in an individual deployment.

You can also choose to roll back a failed deployment by manually redeploying a previously deployed revision.

In all cases, the new or rolled-back deployment is assigned its own deployment ID. The AWS CodeDeploy console displays a list of deployments that are the result of an automatic deployment.

If you redeploy, the target group associated with the current deployment's original task set is associated with the redeployment's replacement task set.

For more information, see Redeploy and Roll Back a Deployment with AWS CodeDeploy.

Deployments on an EC2/On-Premises Compute Platform

This topic provides information about the components and workflow of AWS CodeDeploy deployments that use the EC2/On-Premises compute platform. For information about blue/green deployments, see Overview of a Blue/Green Deployment

Deployment Components on an EC2/On-Premises Compute Platform

The following diagram shows the components in an AWS CodeDeploy deployment on an EC2/On-Premises compute platform.

Deployment Workflow on an EC2/On-Premises Compute Platform

The following diagram shows the major steps in the deployment of application revisions:

These steps include:

  1. Creating an application by specifying a name that uniquely represents the application revisions you want to deploy and the compute platform for your application. AWS CodeDeploy uses this name during a deployment to make sure it is referencing the correct deployment components, such as the deployment group, deployment configuration, and application revision. For more information, see Create an Application with AWS CodeDeploy.

  2. Setting up a deployment group by specifying a deployment type and the instances to which you want to deploy your application revisions. An in-place deployment updates instances with the latest application revision. A blue/green deployment registers a replacement set of instances for the deployment group with a load balancer and deregisters the original instances.

    You can specify the tags applied to the instances, the Amazon EC2 Auto Scaling group names, or both.

    If you specify one group of tags in a deployment group, AWS CodeDeploy deploys to instances that have at least one of the specified tags applied. If you specify two or more tag groups, AWS CodeDeploy deploys only to the instances that meet the criteria for each of the tag groups. For more information, see Tagging Instances for AWS CodeDeploy Deployments.

    In all cases, the instances must be configured to be used in a deployment (that is, they must be tagged or belong to an Amazon EC2 Auto Scaling group) and have the AWS CodeDeploy agent installed and running.

    We provide you with an AWS CloudFormation template that you can use to quickly set up an Amazon EC2 instance based on Amazon Linux or Windows Server. We also provide you with the standalone AWS CodeDeploy agent so that you can install it on Amazon Linux, Ubuntu Server, Red Hat Enterprise Linux (RHEL), or Windows Server instances. For more information, see Create a Deployment Group with AWS CodeDeploy.

    You can also specify the following options:

    • Amazon SNS notifications — Create triggers that will send notifications to subscribers of an Amazon SNS topic when specified events, such as success or failure events, occur in deployments and instances. For more information, see Monitoring Deployments with Amazon SNS Event Notifications.

    • Alarm-based deployment management — Implement Amazon CloudWatch alarm monitoring to stop deployments when your metrics exceed or fall below the thresholds set in CloudWatch.

    • Automatic deployment rollbacks — Configure a deployment to roll back automatically to the previously known good revision when a deployment fails or an alarm threshold is met.

  3. Specifying a deployment configuration to indicate to how many instances to simultaneously deploy your application revisions and describing the success and failure conditions for the deployment. For more information, see View Deployment Configuration Details.

  4. Uploading an application revision to Amazon S3 or GitHub. In addition to the files you want to deploy and any scripts you want to run during the deployment, you must include an application specification file (AppSpec file). This file contains deployment instructions, such as where to copy the files onto each instance and when to run deployment scripts. For more information, see Working with Application Revisions for AWS CodeDeploy.

  5. Deploying your application revision to the deployment group. The AWS CodeDeploy agent on each instance in the deployment group copies your application revision from Amazon S3 or GitHub to the instance. The AWS CodeDeploy agent then unbundles the revision, and using the AppSpec file, copies the files into the specified locations and executes any deployment scripts. For more information, see Create a Deployment with AWS CodeDeploy.

  6. Checking the deployment results. For more information, see Monitoring Deployments in AWS CodeDeploy.

  7. Redeploying a revision. You might want to do this if you need to fix a bug in the source content, or run the deployment scripts in a different order, or address a failed deployment. To do this, you rebundle your revised source content, any deployment scripts, and the AppSpec file into a new revision, and then upload the revision to the Amazon S3 bucket or GitHub repository. You then execute a new deployment to the same deployment group with the new revision. For more information, see Create a Deployment with AWS CodeDeploy.

Setting Up Instances

You need to set up instances before you can deploy application revisions for the first time. If an application revision requires three production servers and two backup servers, you will launch or use five instances.

To manually provision instances:

  1. Install the AWS CodeDeploy agent on the instances. The AWS CodeDeploy agent can be installed on Amazon Linux, Ubuntu Server, RHEL, and Windows Server instances.

  2. Enable tagging, if you are using tags to identify instances in a deployment group. AWS CodeDeploy relies on tags to identify and group instances into AWS CodeDeploy deployment groups. Although the Getting Started tutorials used both, you can simply use a key or a value to define a tag for a deployment group.

  3. Launch Amazon EC2 instances with an IAM instance profile attached. The IAM instance profile must be attached to an Amazon EC2 instance as it is launched in order for the AWS CodeDeploy agent to verify the identity of the instance.

  4. Create a service role. Provide service access so that AWS CodeDeploy can expand the tags in your AWS account.

For an initial deployment, the AWS CloudFormation template does all of this for you. It creates and configures new, single Amazon EC2 instances based on Amazon Linux or Windows Server with the AWS CodeDeploy agent already installed. For more information, see Working with Instances for AWS CodeDeploy.

Note

For a blue/green deployment, you can choose between using instances you already have for the replacement environment or letting AWS CodeDeploy provision new instances for you as part of the deployment process.

Uploading Your Application Revision

Place an AppSpec file under the root folder in your application's source content folder structure. For more information, see Application Specification Files.

Bundle the application's source content folder structure into an archive file format such as zip, tar, or compressed tar. Upload the archive file (the revision) to an Amazon S3 bucket or GitHub repository.

Note

The tar and compressed tar archive file formats (.tar and .tar.gz) are not supported for Windows Server instances.

Creating Your Application and Deployment Groups

An AWS CodeDeploy deployment group identifies a collection of instances based on their tags, Amazon EC2 Auto Scaling group names, or both. Multiple application revisions can be deployed to the same instance. An application revision can be deployed to multiple instances.

For example, you could add a tag of "Prod" to the three production servers and "Backup" to the two backup servers. These two tags can be used to create two different deployment groups in the AWS CodeDeploy application, allowing you to choose which set of servers (or both) should participate in a deployment.

You can use multiple tag groups in a deployment group to restrict deployments to a smaller set of instances. For information, see Tagging Instances for AWS CodeDeploy Deployments.

Deploying Your Application Revision

Now you're ready to deploy your application revision from Amazon S3 or GitHub to the deployment group. You can use the AWS CodeDeploy console or the create-deployment command. There are parameters you can specify to control your deployment, including the revision, deployment group, and deployment configuration.

Updating Your Application

You can make updates to your application and then use the AWS CodeDeploy console or call the create-deployment command to push a revision.

Stopped and Failed Deployments

You can use the AWS CodeDeploy console or the stop-deployment command to stop a deployment. When you attempt to stop the deployment, one of three things will happen:

  • The deployment stops, and the operation returns a status of succeeded. In this case, no more deployment lifecycle events are run on the deployment group for the stopped deployment. Some files might have already been copied to, and some scripts might have already been run on, one or more of the instances in the deployment group.

  • The deployment does not immediately stop, and the operation returns a status of pending. In this case, some deployment lifecycle events might still be running on the deployment group. Some files might have already been copied to, and some scripts might have already been run on, one or more of the instances in the deployment group. After the pending operation is complete, subsequent calls to stop the deployment return a status of succeeded.

  • The deployment cannot stop, and the operation returns an error. For more information, see ErrorInformation and Common Errors in the AWS CodeDeploy API Reference.

Like stopped deployments, failed deployments might result in some deployment lifecycle events having already been run on one or more of the instances in the deployment group. To find out why a deployment failed, you can use the AWS CodeDeploy console, call the get-deployment-instance command, or analyze the log file data from the failed deployment. For more information, see Application Revision and Log File Cleanup and View Log Data for AWS CodeDeploy EC2/On-Premises Deployments.

Redeployments and Deployment Rollbacks

AWS CodeDeploy implements rollbacks by redeploying, as a new deployment, a previously deployed revision.

You can configure a deployment group to automatically roll back deployments when certain conditions are met, including when a deployment fails or an alarm monitoring threshold is met. You can also override the rollback settings specified for a deployment group in an individual deployment.

You can also choose to roll back a failed deployment by manually redeploying a previously deployed revision.

In all cases, the new or rolled-back deployment is assigned its own deployment ID. The list of deployments you can view in the AWS CodeDeploy console shows which ones are the result of an automatic deployment.

For more information, see Redeploy and Roll Back a Deployment with AWS CodeDeploy.