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

AWS CodeDeploy Deployments

This page provides information about the components and workflow of deployments in AWS CodeDeploy.

Deployment Components

The following diagram shows how the components in an AWS CodeDeploy deployment relate to one another.

AWS CodeDeploy deployment components

Deployment Workflow

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

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

     

  2. Setting up a deployment group by specifying the instances to which you want to deploy your application revisions. You can specify the tags applied to the instances, the Auto Scaling group names, or a combination of both. If you specify tags, AWS CodeDeploy deploys to instances that have at least one of the specified tags applied. These instances must be configured to be used in a deployment (that is, they must be tagged or belong to an 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.

     

    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 by determining 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 at what point in time to run deployment scripts. For more information, see Working with Application Revisions.

     

  5. Deploying your application revision to the deployment group. The AWS CodeDeploy agent on each participating 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 Deploy a Revision.

     

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

     

  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 Deploy a Revision.

Setting Up Instances

You need to set up instances before you can deploy application revisions. 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.

The AWS CloudFormation template does all of this for you automatically. 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.

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, Auto Scaling group names, or both. Multiple application revisions can be deployed to the same instance, and 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, giving you the ability to choose which set of servers (or both) should participate in a deployment.

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 will stop, and the operation will return a status of succeeded. In this case, no more deployment lifecycle events will be run on the deployment group for the stopped deployment. Some files may have already been copied to, and some scripts may have already been run on, one or more of the instances in the deployment group.

  • The deployment will not immediately stop, and the operation will return a status of pending. In this case, some deployment lifecycle events may still be running on the deployment group. Some files may have already been copied to, and some scripts may 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 will return a status of succeeded.

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

Like stopped deployments, failed deployments may 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 files on the failed instance. For more information about AWS CodeDeploy log files, see Application Revision and Log File Cleanup.

Note

The causes of many deployment failures can be identified by reviewing the log files created during the deployment process. For simplicity, we recommend using Amazon CloudWatch Logs to centrally monitor log files instead of viewing them instance by instance. For information, see View AWS CodeDeploy Logs in CloudWatch Logs Console.

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, and the list of deployments you can view in AWS CodeDeploy indicates which ones are the result of an automatic deployment.

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