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

What Is AWS CodeDeploy?

AWS CodeDeploy is a deployment service that automates application deployments to Amazon EC2 instances or on-premises instances in your own facility.

You can deploy a nearly unlimited variety of application content, such as code, web and configuration files, executables, packages, scripts, multimedia files, and so on. AWS CodeDeploy can deploy application content stored in Amazon S3 buckets, GitHub repositories, or Bitbucket repositories. You do not need to make changes to your existing code before you can use AWS CodeDeploy.

AWS CodeDeploy makes it easier for you to rapidly release new features, helps you avoid downtime during application deployment, and handles the complexity of updating your applications, without many of the risks associated with error-prone manual deployments.

The service scales with your infrastructure so you can easily deploy to one instance or thousands.

AWS CodeDeploy works with various systems for configuration management, source control, continuous integration, continuous delivery, and continuous deployment. For more information, see Product Integrations.

Video Introduction to AWS CodeDeploy

This short video (2:10) describes how AWS CodeDeploy automates code deployments to Amazon EC2 instances, making it easier for you to rapidly release new features, eliminate downtime during deployment, and avoid the need for error-prone, manual operations.

Benefits of AWS CodeDeploy

AWS CodeDeploy offers these benefits:

  • Automated deployments. AWS CodeDeploy fully automates your application deployments across your development, test, and production environments. AWS CodeDeploy scales with your infrastructure so that you can deploy to one instance or thousands.

  • Minimize downtime. AWS CodeDeploy helps maximize your application availability. During an in-place deployment, AWS CodeDeploy performs a rolling update across Amazon EC2 instances. You can specify the number of instances to be taken offline at a time for updates. During a blue/green deployment, the latest application revision is installed on replacement instances, and traffic is rerouted to these instances when you choose, either immediately or as soon as you are done testing the new environment. For both deployment types, AWS CodeDeploy tracks application health according to rules you configure.

  • Stop and roll back. You can automatically or manually stop and roll back deployments if there are errors.

  • Centralized control. You can launch and track the status of your deployments through the AWS CodeDeploy console or the AWS CLI. You will receive a report that lists when each application revision was deployed and to which Amazon EC2 instances.

  • Easy to adopt. AWS CodeDeploy is platform-agnostic and works with any application. You can easily reuse your setup code. AWS CodeDeploy can also integrate with your software release process or continuous delivery toolchain.

Overview of AWS CodeDeploy Deployment Types

AWS CodeDeploy provides two deployment type options:

  • In-place deployment: The application on each instance in the deployment group is stopped, the latest application revision is installed, and the new version of the application is started and validated. You can choose to use a load balancer so each instance is deregistered during its deployment and then restored to service after the deployment is complete.

    For more information about in-place deployments, see Overview of an In-Place Deployment.

  • Blue/green deployment: The instances in a deployment group (the original environment) are replaced by a different set of instances (the replacement environment) using these steps:

    • Instances are provisioned for the replacement environment.

    • The latest application revision is installed on the replacement instances.

    • An optional wait time occurs for activities such as application testing and system verification.

    • Instances in the replacement environment are registered with an Elastic Load Balancing load balancer, causing traffic to be rerouted to them. Instances in the original environment are deregistered and can be terminated or kept running for other uses.

    For more information about blue/green deployments, see Overview of a Blue/Green Deployment.

Overview of an In-Place Deployment

The following diagram illustrates the flow of a typical AWS CodeDeploy in-place deployment:

Here's how it works:

  1. First, you create deployable content on your local development machine or similar environment, and then you add an application specification file (AppSpec file). The AppSpec file is unique to AWS CodeDeploy; it defines the deployment actions you want AWS CodeDeploy to execute. You bundle your deployable content and the AppSpec file into an archive file, and then upload it to an Amazon S3 bucket or a GitHub repository. This archive file is called an application revision (or simply a revision).

  2. Next, you provide AWS CodeDeploy with information about your deployment, such as which Amazon S3 bucket or GitHub repository to pull the revision from and which set of Amazon EC2 instances to deploy its contents to. AWS CodeDeploy calls a set of Amazon EC2 instances a deployment group. A deployment group contains individually tagged Amazon EC2 instances, Amazon EC2 instances in Auto Scaling groups, or both.

    Each time you successfully upload a new application revision that you want to deploy to the deployment group, that bundle is set as the target revision for the deployment group. In other words, the application revision that is currently targeted for deployment is the target revision. This is also the revision that will be pulled for automatic deployments.

  3. Next, the AWS CodeDeploy agent on each instance polls AWS CodeDeploy to determine what and when to pull from the specified Amazon S3 bucket or GitHub repository.

  4. Finally, the AWS CodeDeploy agent on each instance pulls the target revision from the specified Amazon S3 bucket or GitHub repository and, using the instructions in the AppSpec file, deploys the contents to the instance.

AWS CodeDeploy keeps a record of your deployments so that you can get information such as deployment status, deployment configuration parameters, instance health, and so on.

Overview of a Blue/Green Deployment

A blue/green deployment, in which traffic is rerouted from one set of instances (the original environment) to a different set (the replacement environment), offers a number of advantages over an in-place deployment:

  • An application can be installed and tested on the new instances ahead of time and deployed to production simply by switching traffic to the new servers.

  • Switching back to the most recent version of an application is faster and more reliable because traffic can be routed back to the original instances as long as they have not been terminated. With an in-place deployment, versions must be rolled back by redeploying the previous version of the application.

  • Because the instances provisioned for a blue/green deployment are new, they reflect the most up-to-date server configurations, which helps you avoid the types of problems that sometimes occur on long-running instances.

For a blue/green deployment to take place, you must have one or more Amazon EC2 instances with identifying Amazon EC2 tags or an Auto Scaling group. The instances must meet these additional requirements:

  • Each Amazon EC2 instance must have the correct IAM instance profile attached.

  • The AWS CodeDeploy agent must be installed and running on each instance.


You will typically also have an application revision running on the instances in your original environment, but this is not a requirement for a blue/green deployment.

When you create a deployment group that will be used in blue/green deployments, you can choose how your replacement environment is specified:

Copy an existing Auto Scaling group: During the blue/green deployment, AWS CodeDeploy will create the instances for your replacement environment automatically during the deployment. With this option, AWS CodeDeploy will use the Auto Scaling group you specify as a template for the replacement environment, including the same number of running instances and many other configuration options.

Choose instances manually: You can specify the instances to be counted as your replacement using Amazon EC2 instance tags, Auto Scaling group names, or both. If you choose this option, you do not need to specify the instances for the replacement environment until you create a deployment.

Here's how it works:

  1. You already have instances or an Auto Scaling group that will serve as your original environment. The first time you run a blue/green deployment, you'll typically use instances that were already used in an in-place deployment.

  2. In an existing AWS CodeDeploy application, you create a blue/green deployment group where, in addition to the options required for an in-place deployment, you specify the following:

    • The load balancer that will route traffic from your original environment to your replacement environment during the blue/green deployment process.

    • Whether to reroute traffic to the replacement environment immediately or wait for you to reroute it manually.

    • The rate at which traffic is routed to the replacement instances.

    • Whether the instances that are replaced are terminated or kept running.

  3. You create a deployment for this deployment group during which the following occur:

    1. If you chose to copy an Auto Scaling group, instances are provisioned for your replacement environment.

    2. The application revision you specify for the deployment is installed on the replacement instances.

    3. If you specified a wait time in the deployment group settings, the deployment will be paused. This is the time when you can run tests and verifications in your replacement environment. If you don't manually reroute the traffic before the end of the wait period, the deployment will be stopped.

    4. Instances in the replacement environment are registered with an Elastic Load Balancing load balancer and traffic begins to be routed to them.

    5. Instances in the original environment are deregistered and handled according to your specification in the deployment group, either terminated or kept running.

We Want to Hear from You

We welcome your feedback. To contact us, visit the AWS CodeDeploy forum.