# What is CodeDeploy? CodeDeploy is a deployment service that automates application deployments to Amazon EC2 instances, on-premises instances, serverless Lambda functions, or Amazon ECS services. You can deploy a nearly unlimited variety of application content, including: + Code + Serverless AWS Lambda functions + Web and configuration files + Executables + Packages + Scripts + Multimedia files CodeDeploy can deploy application content that runs on a server and is stored in Amazon S3 buckets, GitHub repositories, or Bitbucket repositories. CodeDeploy can also deploy a serverless Lambda function. You do not need to make changes to your existing code before you can use CodeDeploy. CodeDeploy makes it easier for you to: + Rapidly release new features. + Update AWS Lambda function versions. + Avoid downtime during application deployment. + Handle 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. CodeDeploy works with various systems for configuration management, source control, [continuous integration](https://aws.amazon.com/devops/continuous-integration/), [continuous delivery](https://aws.amazon.com/devops/continuous-delivery/), and continuous deployment. For more information, see [Product integrations](https://aws.amazon.com/codedeploy/product-integrations/). The CodeDeploy console also provides a way to quickly search for your resources, such as repositories, build projects, deployment applications, and pipelines. Choose **Go to resource** or press the `/` key, and then type the name of the resource. Any matches appear in the list. Searches are case insensitive. You only see resources that you have permissions to view. For more information, see [Identity and access management for AWS CodeDeploy](security-iam.md). **Topics** + [ ## Benefits of AWS CodeDeploy ](#benefits) + [ ## Overview of CodeDeploy compute platforms ](#compute-platform) + [ ## Overview of CodeDeploy deployment types ](#welcome-deployment-overview) + [ ## We want to hear from you ](#welcome-contact-us) + [Primary Components](primary-components.md) + [Deployments](deployment-steps.md) + [Application Specification Files](application-specification-files.md) ## Benefits of AWS CodeDeploy CodeDeploy offers these benefits: + **Server, serverless, and container applications**. CodeDeploy lets you deploy both traditional applications on servers and applications that deploy a serverless AWS Lambda function version or an Amazon ECS application. + **Automated deployments**. CodeDeploy fully automates your application deployments across your development, test, and production environments. CodeDeploy scales with your infrastructure so that you can deploy to one instance or thousands. + **Minimize downtime**. If your application uses the EC2/On-Premises compute platform, CodeDeploy helps maximize your application availability. During an in-place deployment, 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. 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, 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 CodeDeploy console or the AWS CLI. You receive a report that lists when each application revision was deployed and to which Amazon EC2 instances. + **Easy to adopt**. CodeDeploy is platform-agnostic and works with any application. You can easily reuse your setup code. CodeDeploy can also integrate with your software release process or continuous delivery toolchain. + **Concurrent deployments**. If you have more than one application that uses the EC2/On-Premises compute platform, CodeDeploy can deploy them concurrently to the same set of instances. ## Overview of CodeDeploy compute platforms CodeDeploy is able to deploy applications to three compute platforms: + **EC2/On-Premises**: Describes instances of physical servers that can be Amazon EC2 cloud instances, on-premises servers, or both. Applications created using the EC2/On-Premises compute platform can be composed of executable files, configuration files, images, and more. Deployments that use the EC2/On-Premises compute platform manage the way in which traffic is directed to instances by using an in-place or blue/green deployment type. For more information, see [Overview of CodeDeploy deployment types](#welcome-deployment-overview). + **AWS Lambda**: Used to deploy applications that consist of an updated version of a Lambda function. AWS Lambda manages the Lambda function in a serverless compute environment made up of a high-availability compute structure. All administration of the compute resources is performed by AWS Lambda. For more information, see [Serverless Computing and Applications](https://aws.amazon.com/serverless/). For more information about AWS Lambda and Lambda functions, see [AWS Lambda](https://aws.amazon.com/lambda/). You can manage the way in which traffic is shifted to the updated Lambda function versions during a deployment by choosing a canary, linear, or all-at-once configuration. + **Amazon ECS**: Used to deploy an Amazon ECS containerized application as a task set. CodeDeploy performs a blue/green deployment by installing an updated version of the application as a new replacement task set. CodeDeploy reroutes production traffic from the original application task set to the replacement task set. The original task set is terminated after a successful deployment. For more information about Amazon ECS, see [Amazon Elastic Container Service](https://aws.amazon.com/ecs/). You can manage the way in which traffic is shifted to the updated task set during a deployment by choosing a canary, linear, or all-at-once configuration. **Note** Amazon ECS blue/green deployments are supported using both CodeDeploy and CloudFormation. Details for these deployments are described in subsequent sections. The following table describes how CodeDeploy components are used with each compute platform. For more information, see: + [Working with deployment groups in CodeDeploy](deployment-groups.md) + [Working with deployments in CodeDeploy](deployments.md) + [Working with deployment configurations in CodeDeploy](deployment-configurations.md) + [Working with application revisions for CodeDeploy](application-revisions.md) + [Working with applications in CodeDeploy](applications.md) | CodeDeploy component | EC2/On-Premises | AWS Lambda | Amazon ECS | | --- | --- | --- | --- | | Deployment group | Deploys a revision to a set of instances. | Deploys a new version of a serverless Lambda function on a high-availability compute infrastructure. | Specifies the Amazon ECS service with the containerized application to deploy as a task set, a production and optional test listener used to serve traffic to the deployed application, when to reroute traffic and terminate the deployed application's original task set, and optional trigger, alarm, and rollback settings. | | Deployment | Deploys a new revision that consists of an application and AppSpec file. The AppSpec specifies how to deploy the application to the instances in a deployment group. | Shifts production traffic from one version of a Lambda function to a new version of the same function. The AppSpec file specifies which Lambda function version to deploy. | Deploys an updated version of an Amazon ECS containerized application as a new, replacement task set. CodeDeploy reroutes production traffic from the task set with the original version to the new replacement task set with the updated version. When the deployment completes, the original task set is terminated. | | Deployment configuration | Settings that determine the deployment speed and the minimum number of instances that must be healthy at any point during a deployment. | Settings that determine how traffic is shifted to the updated Lambda function versions. | Settings that determine how traffic is shifted to the updated Amazon ECS task set. | | Revision | A combination of an AppSpec file and application files, such as executables, configuration files, and so on. | An AppSpec file that specifies which Lambda function to deploy and Lambda functions that can run validation tests during deployment lifecycle event hooks. | An AppSpec file that specifies: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codedeploy/latest/userguide/welcome.html) | | Application | A collection of deployment groups and revisions. An EC2/On-Premises application uses the EC2/On-Premises compute platform. | A collection of deployment groups and revisions. An application used for an AWS Lambda deployment uses the serverless AWS Lambda compute platform. | A collection of deployment groups and revisions. An application used for an Amazon ECS deployment uses the Amazon ECS compute platform. | ## Overview of CodeDeploy deployment types 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 use a load balancer so that each instance is deregistered during its deployment and then restored to service after the deployment is complete. Only deployments that use the EC2/On-Premises compute platform can use in-place deployments. For more information about in-place deployments, see [Overview of an in-place deployment](#welcome-deployment-overview-in-place). **Note** AWS Lambda and Amazon ECS deployments cannot use an in-place deployment type. + **Blue/green deployment**: The behavior of your deployment depends on which compute platform you use: + **Blue/green on an EC2/On-Premises compute platform**: 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 one or more Elastic Load Balancing load balancers, causing traffic to be rerouted to them. Instances in the original environment are deregistered and can be terminated or kept running for other uses. **Note** If you use an EC2/On-Premises compute platform, be aware that blue/green deployments work with Amazon EC2 instances only. + **Blue/green on an AWS Lambda or Amazon ECS compute platform**: Traffic is shifted in increments according to a **canary**, **linear**, or **all-at-once** deployment configuration. + **Blue/green deployments through CloudFormation**: Traffic is shifted from your current resources to your updated resources as part of an CloudFormation stack update. Currently, only ECS blue/green deployments are supported. For more information about blue/green deployments, see [Overview of a blue/green deployment](#welcome-deployment-overview-blue-green). **Note** Using the CodeDeploy agent, you can perform a deployment on an instance you are signed in to without the need for an application, deployment group, or even an AWS account. For information, see [Use the CodeDeploy agent to validate a deployment package on a local machine](deployments-local.md). **Topics** + [ ### Overview of an in-place deployment ](#welcome-deployment-overview-in-place) + [ ### Overview of a blue/green deployment ](#welcome-deployment-overview-blue-green) ### Overview of an in-place deployment **Note** AWS Lambda and Amazon ECS deployments cannot use an in-place deployment type. Here's how an in-place deployment 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 CodeDeploy. It defines the deployment actions you want 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*). 1. Next, you provide CodeDeploy with information about your deployment, such as which Amazon S3 bucket or GitHub repository to pull the revision from and to which set of Amazon EC2 instances to deploy its contents. CodeDeploy calls a set of Amazon EC2 instances a *deployment group*. A deployment group contains individually tagged Amazon EC2 instances, Amazon EC2 instances in Amazon EC2 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 is pulled for automatic deployments. 1. Next, the CodeDeploy agent on each instance polls CodeDeploy to determine what and when to pull from the specified Amazon S3 bucket or GitHub repository. 1. Finally, the CodeDeploy agent on each instance pulls the target revision from the Amazon S3 bucket or GitHub repository and, using the instructions in the AppSpec file, deploys the contents to the instance. CodeDeploy keeps a record of your deployments so that you can get deployment status, deployment configuration parameters, instance health, and so on. ### Overview of a blue/green deployment A blue/green deployment is used to update your applications while minimizing interruptions caused by the changes of a new application version. CodeDeploy provisions your new application version alongside the old version before rerouting your production traffic. + **AWS Lambda**: Traffic is shifted from one version of a Lambda function to a new version of the same Lambda function. + **Amazon ECS**: Traffic is shifted from a task set in your Amazon ECS service to an updated, replacement task set in the same Amazon ECS service. + **EC2/On-Premises**: Traffic is shifted from one set of instances in the original environment to a replacement set of instances. All AWS Lambda and Amazon ECS deployments are blue/green. An EC2/On-Premises deployment can be in-place or blue/green. A blue/green deployment offers a number of advantages over an in-place deployment: + You can install and test an application in the new replacement environment and deploy it to production simply by rerouting traffic. + If you're using the EC2/On-Premises compute platform, switching back to the most recent version of an application is faster and more reliable. That's 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. + If you're using the EC2/On-Premises compute platform, new instances are provisioned for a blue/green deployment and reflect the most up-to-date server configurations. This helps you avoid the types of problems that sometimes occur on long-running instances. + If you're using the AWS Lambda compute platform, you control how traffic is shifted from your original AWS Lambda function version to your new AWS Lambda function version. + If you're using the Amazon ECS compute platform, you control how traffic is shifted from your original task set to your new task set. A blue/green deployment with CloudFormation can use one of the following methods: + **CloudFormation templates for deployments**: When you configure deployments with CloudFormation templates, your deployments are triggered by CloudFormation updates. When you change a resource and upload a template change, a stack update in CloudFormation initiates the new deployment. For a list of resources you can use in CloudFormation templates, see [CloudFormation templates for CodeDeploy reference](reference-cloudformation-templates.md). + **Blue/green deployments through CloudFormation**: You can use CloudFormation to manage your blue/green deployments through stack updates. You define both your blue and green resources, in addition to specifying the traffic routing and stabilization settings, within the stack template. Then, if you update selected resources during a stack update, CloudFormation generates all the necessary green resources, shifts the traffic based on the specified traffic routing parameters, and deletes the blue resources. For more information, see [Automate Amazon ECS blue/green deployments through CodeDeploy using CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/blue-green.html) in the *AWS CloudFormation User Guide*. **Note** Supported for Amazon ECS blue/green deployments only. How you configure a blue/green deployment depends on which compute platform your deployment is using. #### Blue/Green deployment on an AWS Lambda or Amazon ECS compute platform If you're using the AWS Lambda or Amazon ECS compute platform, you must indicate how traffic is shifted from the original AWS Lambda function or Amazon ECS task set to the new function or task set. To indicate how traffic is shifted, you must specify one of the following deployment configurations: + **canary** + **linear** + **all-at-once** For information on how traffic is shifted in a canary, linear, or all-at-once deployment configurations, see [Deployment configuration](primary-components.md#primary-components-deployment-configuration). For details on the Lambda deployment configuration, see [Deployment configurations on an AWS Lambda compute platform](deployment-configurations.md#deployment-configuration-lambda). For details on the Amazon ECS deployment configuration, see [Deployment configurations on an Amazon ECS compute platform](deployment-configurations.md#deployment-configuration-ecs). #### Blue/Green deployment on an EC2/on-premises compute platform **Note** You must use Amazon EC2 instances for blue/green deployments on the EC2/On-Premises compute platform. On-premises instances are not supported for the blue/green deployment type. If you're using the EC2/On-Premises compute platform, the following applies: You must have one or more Amazon EC2 instances with identifying Amazon EC2 tags or an Amazon EC2 Auto Scaling group. The instances must meet these additional requirements: + Each Amazon EC2 instance must have the correct IAM instance profile attached. + The CodeDeploy agent must be installed and running on each instance. **Note** You 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 is used in blue/green deployments, you can choose how your replacement environment is specified: **Copy an existing Amazon EC2 Auto Scaling group**: During the blue/green deployment, CodeDeploy creates the instances for your replacement environment during the deployment. With this option, CodeDeploy uses the Amazon EC2 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, Amazon EC2 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 Amazon EC2 Auto Scaling group that serves as your original environment. The first time you run a blue/green deployment, you typically use instances that were already used in an in-place deployment. 1. In an existing 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 or load balancers that 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. 1. You create a deployment for this deployment group during which the following occur: 1. If you chose to copy an Amazon EC2 Auto Scaling group, instances are provisioned for your replacement environment. 1. The application revision you specify for the deployment is installed on the replacement instances. 1. If you specified a wait time in the deployment group settings, the deployment is 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 is stopped. 1. Instances in the replacement environment are registered with an Elastic Load Balancing load balancer and traffic starts being routed to them. 1. Instances in the original environment are deregistered and handled according to your specification in the deployment group, either terminated or kept running. #### Blue/Green deployment through CloudFormation You can manage CodeDeploy blue/green deployments by modeling your resources with an CloudFormation template. When you model your blue/green resources using an CloudFormation template, you create a stack update in CloudFormation that updates your task set. Production traffic shifts from your service's original task set to a replacement task set either all at once, with linear deployments and bake times, or with canary deployments. The stack update initiates a deployment in CodeDeploy. You can view the deployment status and history in CodeDeploy, but you do not otherwise create or manage CodeDeploy resources outside of the CloudFormation template. **Note** For blue/green deployments through CloudFormation, you don't create a CodeDeploy application or deployment group. This method supports Amazon ECS blue/green deployments only. For more information about blue/green deployments through CloudFormation, see [Create an Amazon ECS blue/green deployment through CloudFormation](deployments-create-ecs-cfn.md). ## We want to hear from you We welcome your feedback. To contact us, visit [the CodeDeploy forum](https://forums.aws.amazon.com/forum.jspa?forumID=179). **Topics** + [Primary Components](primary-components.md) + [Deployments](deployment-steps.md) + [Application Specification Files](application-specification-files.md) # CodeDeploy primary components Before you start working with the service, you should familiarize yourself with the major components of the CodeDeploy deployment process. **Topics** + [ ## Application ](#primary-components-application) + [ ## Compute platform ](#primary-components-compute-platform) + [ ## Deployment configuration ](#primary-components-deployment-configuration) + [ ## Deployment group ](#primary-components-deployment-group) + [ ## Deployment type ](#primary-components-deployment-type) + [ ## IAM instance profile ](#primary-components-iam-instance-profile) + [ ## Revision ](#primary-components-revision) + [ ## Service role ](#primary-components-service-role) + [ ## Target revision ](#primary-components-target-revision) + [ ## Other components ](#primary-components-other-components) ## Application An *application* is a name that uniquely identifies the application you want to deploy. CodeDeploy uses this name, which functions as a container, to ensure the correct combination of revision, deployment configuration, and deployment group are referenced during a deployment. ## Compute platform A *compute platform* is a platform on which CodeDeploy deploys an application. There are three compute platforms: + **EC2/On-Premises**: Describes instances of physical servers that can be Amazon EC2 cloud instances, on-premises servers, or both. Applications created using the EC2/On-Premises compute platform can be composed of executable files, configuration files, images, and more. Deployments that use the EC2/On-Premises compute platform manage the way in which traffic is directed to instances by using an in-place or blue/green deployment type. For more information, see [Overview of CodeDeploy deployment types](welcome.md#welcome-deployment-overview). + **AWS Lambda**: Used to deploy applications that consist of an updated version of a Lambda function. AWS Lambda manages the Lambda function in a serverless compute environment made up of a high-availability compute structure. All administration of the compute resources is performed by AWS Lambda. For more information, see [Serverless Computing and Applications](https://aws.amazon.com/serverless/). For more information about AWS Lambda and Lambda functions, see [AWS Lambda](https://aws.amazon.com/lambda/). You can manage the way in which traffic is shifted to the updated Lambda function versions during a deployment by choosing a canary, linear, or all-at-once configuration. + **Amazon ECS**: Used to deploy an Amazon ECS containerized application as a task set. CodeDeploy performs a blue/green deployment by installing an updated version of the application as a new replacement task set. CodeDeploy reroutes production traffic from the original application task set to the replacement task set. The original task set is terminated after a successful deployment. For more information about Amazon ECS, see [Amazon Elastic Container Service](https://aws.amazon.com/ecs/). You can manage the way in which traffic is shifted to the updated task set during a deployment by choosing a canary, linear, or all-at-once configuration. **Note** Amazon ECS blue/green deployments are supported through both CodeDeploy and CloudFormation. Details for these deployments are described in subsequent sections. ## Deployment configuration A *deployment configuration* is a set of deployment rules and deployment success and failure conditions used by CodeDeploy during a deployment. If your deployment uses the EC2/On-Premises compute platform, you can specify the minimum number of healthy instances for the deployment. If your deployment uses the AWS Lambda or the Amazon ECS compute platform, you can specify how traffic is routed to your updated Lambda function or ECS task set. For more information about specifying the minimum number of healthy hosts for a deployment that uses the EC2/On-Premises compute platform, see [About the minimum number of healthy instances](instances-health.md#minimum-healthy-hosts). The following deployment configurations specify how traffic is routed during a deployment that uses the Lambda or the ECS compute platform: + **Canary**: Traffic is shifted in two increments. You can choose from predefined canary options that specify the percentage of traffic shifted to your updated Lambda function or ECS task set in the first increment and the interval, in minutes, before the remaining traffic is shifted in the second increment. + **Linear**: Traffic is shifted in equal increments with an equal number of minutes between each increment. You can choose from predefined linear options that specify the percentage of traffic shifted in each increment and the number of minutes between each increment. + **All-at-once**: All traffic is shifted from the original Lambda function or ECS task set to the updated function or task set all at once. ## Deployment group A *deployment group* is a set of individual instances. A deployment group contains individually tagged instances, Amazon EC2 instances in Amazon EC2 Auto Scaling groups, or both. For information about Amazon EC2 instance tags, see [Working with Tags Using the Console](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#Using_Tags_Console). For information about on-premises instances, see [Working with on-premises instances for CodeDeploy](instances-on-premises.md). For information about Amazon EC2 Auto Scaling, see [Integrating CodeDeploy with Amazon EC2 Auto Scaling](integrations-aws-auto-scaling.md). ## Deployment type A *deployment type* is a method used to make the latest application revision available on instances in a deployment group. There are two deployment types: + **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 use a load balancer so that each instance is deregistered during its deployment and then restored to service after the deployment is complete. Only deployments that use the EC2/On-Premises compute platform can use in-place deployments. For more information about in-place deployments, see [Overview of an in-place deployment](welcome.md#welcome-deployment-overview-in-place). + **Blue/green deployment**: The behavior of your deployment depends on which compute platform you use: + **Blue/green on an EC2/On-Premises compute platform**: 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 one or more Elastic Load Balancing load balancers, causing traffic to be rerouted to them. Instances in the original environment are deregistered and can be terminated or kept running for other uses. **Note** If you use an EC2/On-Premises compute platform, be aware that blue/green deployments work with Amazon EC2 instances only. + **Blue/green on an AWS Lambda or Amazon ECS compute platform**: Traffic is shifted in increments according to a **canary**, **linear**, or **all-at-once** deployment configuration. + **Blue/green deployments through CloudFormation**: Traffic is shifted from your current resources to your updated resources as part of an CloudFormation stack update. Currently, only ECS blue/green deployments are supported. For more information about blue/green deployments, see [Overview of a blue/green deployment](welcome.md#welcome-deployment-overview-blue-green). **Note** Amazon ECS blue/green deployments are supported using both CodeDeploy and CloudFormation. Details for these deployments are described in subsequent sections. ## IAM instance profile An *IAM instance profile* is an IAM role that you attach to your Amazon EC2 instances. This profile includes the permissions required to access the Amazon S3 buckets or GitHub repositories where the applications are stored. For more information, see [Step 4: Create an IAM instance profile for your Amazon EC2 instances](getting-started-create-iam-instance-profile.md). ## Revision A *revision* is a version of your application. An AWS Lambda deployment revision is a YAML- or JSON-formatted file that specifies information about the Lambda function to deploy. An EC2/On-Premises deployment revision is an archive file that contains source content (source code, webpages, executable files, and deployment scripts) and an application specification file (AppSpec file). AWS Lambda revisions can be stored in Amazon S3 buckets. EC2/On-Premises revisions are stored in Amazon S3 buckets or GitHub repositories. For Amazon S3, a revision is uniquely identified by its Amazon S3 object key and its ETag, version, or both. For GitHub, a revision is uniquely identified by its commit ID. ## Service role A *service role* is an IAM role that grants permissions to an AWS service so it can access AWS resources. The policies you attach to the service role determine which AWS resources the service can access and the actions it can perform with those resources. For CodeDeploy, a service role is used for the following: + To read either the tags applied to the instances or the Amazon EC2 Auto Scaling group names associated with the instances. This enables CodeDeploy to identify instances to which it can deploy applications. + To perform operations on instances, Amazon EC2 Auto Scaling groups, and Elastic Load Balancing load balancers. + To publish information to Amazon SNS topics so that notifications can be sent when specified deployment or instance events occur. + To retrieve information about CloudWatch alarms to set up alarm monitoring for deployments. For more information, see [Step 2: Create a service role for CodeDeploy](getting-started-create-service-role.md). ## Target revision A *target revision* is the most recent version of the application revision that you have uploaded to your repository and want to deploy to the instances in a deployment group. In other words, the application revision currently targeted for deployment. This is also the revision that is pulled for automatic deployments. ## Other components For information about other components in the CodeDeploy workflow, see the following topics: + [Choose a CodeDeploy repository type](application-revisions-repository-type.md) + [CodeDeploy deployments](deployment-steps.md) + [CodeDeploy application specification (AppSpec) files](application-specification-files.md) + [CodeDeploy instance health](instances-health.md) + [Working with the CodeDeploy agent](codedeploy-agent.md) + [Working with on-premises instances for CodeDeploy](instances-on-premises.md) # CodeDeploy deployments This topic provides information about the components and workflow of deployments in CodeDeploy. The deployment process varies, depending on the compute platform or deployment method (Lambda, Amazon ECS, EC2/On-Premises, or through AWS CloudFormation) that you use for your deployments. **Topics** + [ # Deployments on an AWS Lambda Compute Platform ](deployment-steps-lambda.md) + [ # Deployments on an Amazon ECS Compute Platform ](deployment-steps-ecs.md) + [ # Deployments on an EC2/On-Premises Compute Platform ](deployment-steps-server.md) # Deployments on an AWS Lambda Compute Platform This topic provides information about the components and workflow of CodeDeploy deployments that use the AWS Lambda compute platform. **Topics** + [ ## Deployment workflow on an AWS Lambda compute platform ](#deployment-process-workflow-lambda) + [ ## Uploading your application revision ](#deployment-steps-uploading-your-app-lambda) + [ ## Creating your application and deployment groups ](#deployment-steps-registering-app-deployment-groups-lambda) + [ ## Deploying your application revision ](#deployment-steps-deploy-lambda) + [ ## Updating your application ](#deployment-steps-updating-your-app-lambda) + [ ## Stopped and failed deployments ](#deployment-stop-fail-lambda) + [ ## Redeployments and deployment rollbacks ](#deployment-rollback-lambda) ## Deployment workflow on an AWS Lambda compute platform The following diagram shows the primary steps in the deployment of new and updated AWS Lambda functions. ![\[How CodeDeploy deploys a new or updated AWS Lambda function.\]](http://docs.aws.amazon.com/codedeploy/latest/userguide/images/deployment-process-lambda.png) These steps include: 1. Create an application and give it a name that uniquely identifies the application revisions you want to deploy. To deploy Lambda functions, choose AWS Lambda compute platform when you create your application. 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 CodeDeploy](applications-create.md). 1. Set up a deployment group by specifying your deployment group's name. 1. Choose 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 with CodeDeploy](deployment-configurations-view-details.md). 1. Uploading an *application specification file* (AppSpec file) to Amazon S3. The AppSpec file specifies a Lambda function version and Lambda functions used to validate your deployment. If you don't want to create an AppSpec file, you can specify a Lambda function version and Lambda deployment validation functions directly in the console using YAML or JSON. For more information, see [Working with application revisions for CodeDeploy](application-revisions.md). 1. Deploy 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 CodeDeploy](deployments-create.md). 1. Check the deployment results. For more information, see [Monitoring deployments in CodeDeploy](monitoring.md). ## 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 [CodeDeploy application specification (AppSpec) files](application-specification-files.md). ## Creating your application and deployment groups A 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 CodeDeploy console or the [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/deploy/create-deployment.html) 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 CodeDeploy console or call the [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/deploy/create-deployment.html) command to push a revision. ## Stopped and failed deployments You can use the CodeDeploy console or the [stop-deployment](https://docs.aws.amazon.com/cli/latest/reference/deploy/stop-deployment.html) 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](https://docs.aws.amazon.com/codedeploy/latest/APIReference/API_ErrorInformation.html) and [Common errors](https://docs.aws.amazon.com/codedeploy/latest/APIReference/CommonErrors.html) 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 CodeDeploy console or analyze the log file data from the failed deployment. For more information, see [Application revision and log file cleanup](codedeploy-agent.md#codedeploy-agent-revisions-logs-cleanup) and [View log data for CodeDeploy EC2/On-Premises deployments](deployments-view-logs.md). ## Redeployments and deployment rollbacks 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 CodeDeploy console shows which ones are the result of an automatic deployment. For more information, see [Redeploy and roll back a deployment with CodeDeploy](deployments-rollback-and-redeploy.md). # Deployments on an Amazon ECS Compute Platform This topic provides information about the components and workflow of CodeDeploy deployments that use the Amazon ECS compute platform. **Topics** + [ ## Before you begin an Amazon ECS deployment ](#deployment-steps-prerequisites-ecs) + [ ## Deployment workflow (high level) on an Amazon ECS compute platform ](#deployment-process-workflow-ecs) + [ ## What happens during an Amazon ECS deployment ](#deployment-steps-what-happens) + [ ## Uploading your application revision ](#deployment-steps-uploading-your-app-ecs) + [ ## Creating your application and deployment groups ](#deployment-steps-registering-app-deployment-groups-ecs) + [ ## Deploying your application revision ](#deployment-steps-deploy-ecs) + [ ## Updating your application ](#deployment-steps-updating-your-app-ecs) + [ ## Stopped and failed deployments ](#deployment-stop-fail-ecs) + [ ## Redeployments and deployment rollbacks ](#deployment-rollback-ecs) + [ ## Amazon ECS blue/green deployments through AWS CloudFormation ](#deployment-steps-ecs-cf) ## 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 CodeDeploy application's deployment group. For more information, see [Amazon ECS clusters](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ECS_clusters.html) 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 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](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_services.html) 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 a 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 load balancer when you create your CodeDeploy application's deployment group. For more information, see [Set up a load balancer, target groups, and listeners for CodeDeploy Amazon ECS deployments](deployment-groups-create-load-balancer-for-ecs.md) and [Creating a load balancer](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/create-load-balancer.html) in the *Amazon Elastic Container Service User Guide*. **One or two listeners** 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](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-listener.html) in the *Elastic Load Balancing User Guide* and [Creating a service](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/create-service.html) 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, 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 CodeDeploy application's deployment group. During a deployment, 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](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-target-groups.html) 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 CodeDeploy application's AppSpec file. For more information, see [Amazon ECS task definitions](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html) in the *Amazon Elastic Container Service User Guide* and [AppSpec 'resources' section for Amazon ECS deployments](reference-appspec-file-structure-resources.md#reference-appspec-file-structure-resources-ecs). **A container for your Amazon ECS application** A Docker *container* is a unit of software that packages up code and its dependencies so your application can run. A container isolates your application so it runs in different computing environments. 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 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?](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html) in the *Amazon Elastic Container Service User Guide* and [AppSpec 'resources' section for Amazon ECS deployments](reference-appspec-file-structure-resources.md#reference-appspec-file-structure-resources-ecs). **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 CodeDeploy application's AppSpec file. You specify the port in your CodeDeploy application's AppSpec file. For more information, see [AppSpec 'resources' section for Amazon ECS deployments](reference-appspec-file-structure-resources.md#reference-appspec-file-structure-resources-ecs). ## Deployment workflow (high level) on an Amazon ECS compute platform The following diagram shows the primary steps in the deployment of updated Amazon ECS services. ![\[How CodeDeploy deploys an application as a task set into Amazon ECS.\]](http://docs.aws.amazon.com/codedeploy/latest/userguide/images/deployment-process-ecs.png) These steps include: 1. Create 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, choose the Amazon ECS compute platform. 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 CodeDeploy](applications-create.md). 1. Set up a deployment group by specifying: + The deployment group name. + Your Amazon ECS cluster and service name. The Amazon ECS service's deployment controller must be set to 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. 1. 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 container name must be a container in your Amazon ECS task definition. For more information, see [Working with application revisions for CodeDeploy](application-revisions.md). 1. Deploy 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 CodeDeploy](deployments-create.md). 1. Check the deployment results. For more information, see [Monitoring deployments in CodeDeploy](monitoring.md). ## What happens during an Amazon ECS deployment Before an Amazon ECS deployment with a test listener starts, you must configure its components. For more information, see [Before you begin an Amazon ECS deployment](#deployment-steps-prerequisites-ecs). The following diagram shows the relationship between these components when an Amazon ECS deployment is ready to start. ![\[The relationship between the load balancer, listeners, target groups, and task set when an Amazon ECS deployment is ready to start.\]](http://docs.aws.amazon.com/codedeploy/latest/userguide/images/codedeploy-ecs-deployment-step-1.png) When the deployment starts, the deployment lifecycle events start to execute one at a time. Some lifecycle events are hooks that only execute Lambda functions specified in the AppSpec file. The deployment lifecycle events in the following table are listed in the order they execute. For more information, see [AppSpec 'hooks' section for an Amazon ECS deployment](reference-appspec-file-structure-hooks.md#appspec-hooks-ecs). | Lifecycle event | Lifecycle event action | | --- | --- | | BeforeInstall (a hook for Lambda functions) | Run Lambda functions. | | Install | Set up the replacement task set. | | AfterInstall (a hook for Lambda functions) | Run Lambda functions. | | AllowTestTraffic | Route traffic from the test listener to target group 2. | | AfterAllowTestTraffic (a hook for Lambda functions) | Run Lambda functions. | | BeforeAllowTraffic (a hook for Lambda functions) | Run Lambda functions. | | AllowTraffic | Route traffic from the production listener to target group 2. | | AfterAllowTraffic | Run Lambda functions. | **Note** Lambda functions in a hook are optional. 1. **** Execute any Lambda functions specified in the `BeforeInstall` hook in the AppSpec file. 1. **** During the `Install` lifecycle event: 1. A replacement task set is created in your Amazon ECS service. 1. The updated containerized application is installed into the replacement task set. 1. The second target group is associated with the replacement task set. This diagram shows deployment components with the new replacement task set. The containerized application is inside this task set. The task set is composed of three tasks. (An application can have any number of tasks.) The second target group is now associated with the replacement task set. ![\[The deployment components with the new replacement task set. The containerized application is inside this task set. The task set is composed of three tasks. The second target group is now associated with the replacement task set.\]](http://docs.aws.amazon.com/codedeploy/latest/userguide/images/codedeploy-ecs-deployment-step-2.png) 1. **** Execute any Lambda functions specified in the `AfterInstall` hook in the AppSpec file. 1. **** The `AllowTestTraffic` event is invoked. During this lifecycle event, the test listener routes traffic to the updated containerized application. ![\[The test listener routes traffic to the updated containerized application.\]](http://docs.aws.amazon.com/codedeploy/latest/userguide/images/codedeploy-ecs-deployment-step-3.png) 1. **** Execute any Lambda functions specified in the `AfterAllowTestTraffic` hook in the AppSpec file. Lambda functions can validate the deployment using the test traffic. For example, a Lambda function can serve traffic to the test listener and track metrics from the replacement task set. If rollbacks are configured, you can configure a CloudWatch alarm that triggers a rollback when the validation test in your Lambda function fails. After the validation tests are complete, one of the following occurs: + If validation fails and rollbacks are configured, the deployment status is marked `Failed` and components return to their state when the deployment started. + If validation fails and rollbacks are not configured, the deployment status is marked `Failed` and components remain in their current state. + If validation succeeds, the deployment continues to the `BeforeAllowTraffic` hook. For more information, see [Monitoring deployments with CloudWatch alarms in CodeDeploy](monitoring-create-alarms.md), [Automatic rollbacks](deployments-rollback-and-redeploy.md#deployments-rollback-and-redeploy-automatic-rollbacks), and [Configure advanced options for a deployment group](deployment-groups-configure-advanced-options.md). 1. **** Execute any Lambda functions specified in the `BeforeAllowTraffic` hook in the AppSpec file. 1. **** The `AllowTraffic` event is invoked. Production traffic is rerouted from the original task set to the replacement task set. The following diagram shows the replacement task set receiving production traffic. ![\[The replacement task set receives production traffic.\]](http://docs.aws.amazon.com/codedeploy/latest/userguide/images/codedeploy-ecs-deployment-step-4.png) 1. **** Execute any Lambda functions specified in the `AfterAllowTraffic` hook in the AppSpec file. 1. **** After all events succeed, the deployment status is set to `Succeeded` and the original task set is removed. ![\[All events succeeding.\]](http://docs.aws.amazon.com/codedeploy/latest/userguide/images/codedeploy-ecs-deployment-step-6.png) ## 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 [CodeDeploy application specification (AppSpec) files](application-specification-files.md). ## Creating your application and deployment groups A 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 CodeDeploy console or the [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/deploy/create-deployment.html) 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 CodeDeploy console or call the [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/deploy/create-deployment.html) command to push a revision. ## Stopped and failed deployments You can use the CodeDeploy console or the [stop-deployment](https://docs.aws.amazon.com/cli/latest/reference/deploy/stop-deployment.html) 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](https://docs.aws.amazon.com/codedeploy/latest/APIReference/API_ErrorInformation.html) and [Common errors](https://docs.aws.amazon.com/codedeploy/latest/APIReference/CommonErrors.html) in the AWS CodeDeploy API Reference. ## Redeployments and deployment rollbacks 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 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 CodeDeploy](deployments-rollback-and-redeploy.md). ## Amazon ECS blue/green deployments through AWS CloudFormation You can use AWS CloudFormation to manage Amazon ECS blue/green deployments through CodeDeploy. For more information, see [Create an Amazon ECS blue/green deployment through CloudFormation](deployments-create-ecs-cfn.md). **Note** Managing Amazon ECS blue/green deployments with CloudFormation is not available in the Asia Pacific (Osaka) region. # Deployments on an EC2/On-Premises Compute Platform This topic provides information about the components and workflow of CodeDeploy deployments that use the EC2/On-Premises compute platform. For information about blue/green deployments, see [Overview of a blue/green deployment](welcome.md#welcome-deployment-overview-blue-green). **Topics** + [ ## Deployment components on an EC2/on-premises compute platform ](#deployment-steps-components-server) + [ ## Deployment workflow on an EC2/on-premises compute platform ](#deployment-steps-workflow) + [ ## Setting up instances ](#deployment-steps-setting-up-instances) + [ ## Uploading your application revision ](#deployment-steps-uploading-your-app) + [ ## Creating your application and deployment groups ](#deployment-steps-registering-app-deployment-groups) + [ ## Deploying your application revision ](#deployment-steps-deploy) + [ ## Updating your application ](#deployment-steps-updating-your-app) + [ ## Stopped and failed deployments ](#deployment-stop-fail) + [ ## Redeployments and deployment rollbacks ](#deployment-rollback) ## Deployment components on an EC2/on-premises compute platform The following diagram shows the components in a CodeDeploy deployment on an EC2/On-Premises compute platform. ![\[The components in a CodeDeploy deployment on an EC2/On-Premises compute platform.\]](http://docs.aws.amazon.com/codedeploy/latest/userguide/images/deployment-components-workflow.png) ## Deployment workflow on an EC2/on-premises compute platform The following diagram shows the major steps in the deployment of application revisions: ![\[The major steps in the deployment of application revisions.\]](http://docs.aws.amazon.com/codedeploy/latest/userguide/images/deployment-process.png) These steps include: 1. Create an application and give it a name that uniquely identifies the application revisions you want to deploy and the compute platform for your application. 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 CodeDeploy](applications-create.md). 1. Set 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, CodeDeploy deploys to instances that have at least one of the specified tags applied. If you specify two or more tag groups, CodeDeploy deploys only to the instances that meet the criteria for each of the tag groups. For more information, see [Tagging instances for deployment groups in CodeDeploy](instances-tagging.md). 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 CodeDeploy agent installed and running. We provide you with an 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 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 CodeDeploy](deployment-groups-create.md). You can also specify the following options: + **Amazon SNS notifications**. Create triggers that 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](monitoring-sns-event-notifications.md). + **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. 1. Specify a deployment configuration to indicate to how many instances your application revisions should be simultaneously deployed and to describe the success and failure conditions for the deployment. For more information, see [View deployment configuration details with CodeDeploy](deployment-configurations-view-details.md). 1. Upload 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 CodeDeploy](application-revisions.md). 1. Deploy your application revision to the deployment group. The CodeDeploy agent on each instance in the deployment group copies your application revision from Amazon S3 or GitHub to the instance. The 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 CodeDeploy](deployments-create.md). 1. Check the deployment results. For more information, see [Monitoring deployments in CodeDeploy](monitoring.md). 1. Redeploy 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, 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. Then execute a new deployment to the same deployment group with the new revision. For more information, see [Create a deployment with CodeDeploy](deployments-create.md). ## Setting up instances You must 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 launch or use five instances. To manually provision instances: 1. Install the CodeDeploy agent on the instances. The CodeDeploy agent can be installed on Amazon Linux, Ubuntu Server, RHEL, and Windows Server instances. 1. Enable tagging, if you are using tags to identify instances in a deployment group. CodeDeploy relies on tags to identify and group instances into 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. 1. 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 for the CodeDeploy agent to verify the identity of the instance. 1. Create a service role. Provide service access so that CodeDeploy can expand the tags in your AWS account. For an initial deployment, the 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 CodeDeploy agent already installed. For more information, see [Working with instances for CodeDeploy](instances.md). **Note** For a blue/green deployment, you can choose between using instances that you already have for the replacement environment or letting 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 [CodeDeploy application specification (AppSpec) files](application-specification-files.md). 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 A 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 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 deployment groups in CodeDeploy](instances-tagging.md). ## 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 CodeDeploy console or the [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/deploy/create-deployment.html) 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 CodeDeploy console or call the [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/deploy/create-deployment.html) command to push a revision. ## Stopped and failed deployments You can use the CodeDeploy console or the [stop-deployment](https://docs.aws.amazon.com/cli/latest/reference/deploy/stop-deployment.html) 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. 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](https://docs.aws.amazon.com/codedeploy/latest/APIReference/API_ErrorInformation.html) and [Common errors](https://docs.aws.amazon.com/codedeploy/latest/APIReference/CommonErrors.html) 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 CodeDeploy console, call the [get-deployment-instance](https://docs.aws.amazon.com/cli/latest/reference/deploy/get-deployment-instance.html) command, or analyze the log file data from the failed deployment. For more information, see [Application revision and log file cleanup](codedeploy-agent.md#codedeploy-agent-revisions-logs-cleanup) and [View log data for CodeDeploy EC2/On-Premises deployments](deployments-view-logs.md). ## Redeployments and deployment rollbacks 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 CodeDeploy console shows which ones are the result of an automatic deployment. For more information, see [Redeploy and roll back a deployment with CodeDeploy](deployments-rollback-and-redeploy.md). # CodeDeploy application specification (AppSpec) files An application specification file (AppSpec file), which is unique to CodeDeploy, is a [YAML](http://www.yaml.org)-formatted or [JSON](http://www.json.org)-formatted file. The AppSpec file is used to manage each deployment as a series of lifecycle event hooks, which are defined in the file. For information about how to create a well-formed AppSpec file, see [CodeDeploy AppSpec file reference](reference-appspec-file.md). **Topics** + [ ## AppSpec files on an Amazon ECS Compute Platform ](#appspec-files-on-ecs-compute-platform) + [ ## AppSpec files on an AWS Lambda compute platform ](#appspec-files-on-lambda-compute-platform) + [ ## AppSpec files on an EC2/on-premises compute platform ](#appspec-files-on-server-compute-platform) + [ ## How the CodeDeploy agent uses the AppSpec file ](#application-specification-files-agent-usage) ## AppSpec files on an Amazon ECS Compute Platform If your application uses the Amazon ECS compute platform, the AppSpec file can be formatted with either YAML or JSON. It can also be typed directly into an editor in the console. The AppSpec file is used to specify: + The name of the Amazon ECS service and the container name and port used to direct traffic to the new task set. + The functions to be used as validation tests. You can run validation Lambda functions after deployment lifecycle events. For more information, see [AppSpec 'hooks' section for an Amazon ECS deployment](reference-appspec-file-structure-hooks.md#appspec-hooks-ecs), [AppSpec file structure for Amazon ECS deployments](reference-appspec-file-structure.md#ecs-appspec-structure), and [AppSpec File example for an Amazon ECS deployment](reference-appspec-file-example.md#appspec-file-example-ecs). ## AppSpec files on an AWS Lambda compute platform If your application uses the AWS Lambda compute platform, the AppSpec file can be formatted with either YAML or JSON. It can also be typed directly into an editor in the console. The AppSpec file is used to specify: + The AWS Lambda function version to deploy. + The functions to be used as validation tests. You can run validation Lambda functions after deployment lifecycle events. For more information, see [AppSpec 'hooks' section for an AWS Lambda deployment](reference-appspec-file-structure-hooks.md#appspec-hooks-lambda). ## AppSpec files on an EC2/on-premises compute platform If your application uses the EC2/On-Premises compute platform, the AppSpec file is always YAML-formatted. The AppSpec file is used to: + Map the source files in your application revision to their destinations on the instance. + Specify custom permissions for deployed files. + Specify scripts to be run on each instance at various stages of the deployment process. You can run scripts on an instance after many of the individual deployment lifecycle events. CodeDeploy runs only those scripts specified in the file, but those scripts can call other scripts on the instance. You can run any type of script as long as it is supported by the operating system running on the instances. For more information, see [AppSpec 'hooks' section for an EC2/On-Premises deployment](reference-appspec-file-structure-hooks.md#appspec-hooks-server). ## How the CodeDeploy agent uses the AppSpec file During deployment, the CodeDeploy agent looks up the name of the current event in the **hooks** section of the AppSpec file. If the event is not found, the CodeDeploy agent moves on to the next step. If the event is found, the CodeDeploy agent retrieves the list of scripts to execute. The scripts are run sequentially, in the order in which they appear in the file. The status of each script is logged in the CodeDeploy agent log file on the instance. If a script runs successfully, it returns an exit code of 0 (zero). **Note** The CodeDeploy agent is not used in an AWS Lambda or an Amazon ECS deployment. During the **Install** event, the CodeDeploy agent uses the mappings defined in the **files** section of the AppSpec file to determine which folders or files to copy from the revision to the instance. If the CodeDeploy agent installed on the operating system doesn't match what's listed in the AppSpec file, the deployment fails. For information about CodeDeploy agent log files, see [Working with the CodeDeploy agent](codedeploy-agent.md).