# Working with deployments in CodeDeploy
In CodeDeploy, a deployment is the process, and the components involved in the process, of installing content on one or more instances. This content can consist of code, web and configuration files, executables, packages, scripts, and so on. CodeDeploy deploys content that is stored in a source repository, according to the configuration rules you specify.
If you use the EC2/On-Premises compute platform, then two deployments to the same set of instances can run concurrently.
CodeDeploy provides two deployment type options, in-place deployments and blue/green deployments.
+ **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).
For information about automatically deploying from Amazon S3, see [Automatically deploy from Amazon S3 using CodeDeploy](https://aws.amazon.com/blogs/devops/automatically-deploy-from-amazon-s3-using-aws-codedeploy/).
**Topics**
+ [Create a deployment](deployments-create.md)
+ [View deployment details](deployments-view-details.md)
+ [View deployment log data](deployments-view-logs.md)
+ [Stop a deployment](deployments-stop.md)
+ [Redeploy and roll back a deployment](deployments-rollback-and-redeploy.md)
+ [Deploy an application in a different AWS account](deployments-cross-account.md)
+ [Validate a deployment package on a local machine](deployments-local.md)
# Create a deployment with CodeDeploy
You can use the CodeDeploy console, the AWS CLI, or the CodeDeploy APIs to create a deployment that installs application revisions you have already pushed to Amazon S3 or, if your deployment is to an EC2/On-Premises compute platform, GitHub, on the instances in a deployment group.
The process for creating a deployment depends on the compute platform used by your deployment.
**Topics**
+ [Deployment prerequisites](deployments-create-prerequisites.md)
+ [Create an Amazon ECS Compute Platform deployment (console)](deployments-create-console-ecs.md)
+ [Create an AWS Lambda Compute Platform deployment (console)](deployments-create-console-lambda.md)
+ [Create an EC2/On-Premises Compute Platform deployment (console)](deployments-create-console.md)
+ [Create an Amazon ECS Compute Platform deployment (CLI)](deployments-create-ecs-cli.md)
+ [Create an AWS Lambda Compute Platform deployment (CLI)](deployments-create-lambda-cli.md)
+ [Create an EC2/On-Premises Compute Platform deployment (CLI)](deployments-create-cli.md)
+ [Create an Amazon ECS blue/green deployment through CloudFormation](deployments-create-ecs-cfn.md)
# Deployment prerequisites
Make sure the following steps are complete before you start a deployment.
## Deployment prerequisites on an AWS Lambda compute platform
+ Create an application that includes at least one deployment group. For information, see [Create an application with CodeDeploy](applications-create.md) and [Create a deployment group with CodeDeploy](deployment-groups-create.md).
+ Prepare the application revision, also known as the AppSpec file, that specifies the Lambda function version you want to deploy. The AppSpec file can also specify Lambda functions to validate your deployment. For more information see [Working with application revisions for CodeDeploy](application-revisions.md).
+ If you want to use a custom deployment configuration for your deployment, create it before you start the deployment process. For information, see [Create a deployment configuration with CodeDeploy](deployment-configurations-create.md).
## Deployment prerequisites on an EC2/on-premises compute platform
+ For an in-place deployment, create or configure the instances you want to deploy to. For information, see [Working with instances for CodeDeploy](instances.md). For a blue/green deployment, you either have an existing Amazon EC2 Auto Scaling group to use as a template for your replacement environment, or you have one or more instances or Amazon EC2 Auto Scaling groups that you specify as your original environment. For more information, see [Tutorial: Use CodeDeploy to deploy an application to an Auto Scaling group](tutorials-auto-scaling-group.md) and [Integrating CodeDeploy with Amazon EC2 Auto Scaling](integrations-aws-auto-scaling.md).
+ Create an application that includes at least one deployment group. For information, see [Create an application with CodeDeploy](applications-create.md) and [Create a deployment group with CodeDeploy](deployment-groups-create.md).
+ Prepare the application revision that you want to deploy to the instances in your deployment group. For information, see [Working with application revisions for CodeDeploy](application-revisions.md).
+ If you want to use a custom deployment configuration for your deployment, create it before you start the deployment process. For information, see [Create a deployment configuration with CodeDeploy](deployment-configurations-create.md).
+ If you are deploying your application revision from an Amazon S3 bucket, the bucket is in the same AWS Region as the instances in your deployment group.
+ If you are deploying your application revision from an Amazon S3 bucket, an Amazon S3 bucket policy has been applied to the bucket. This policy grants your instances the permissions required to download the application revision.
For example, the following Amazon S3 bucket policy allows any Amazon EC2 instance with an attached IAM instance profile containing the ARN `arn:aws:iam::444455556666:role/CodeDeployDemo` to download from anywhere in the Amazon S3 bucket named `amzn-s3-demo-bucket`:
```
{
"Statement": [
{
"Action": [
"s3:Get*",
"s3:List*"
],
"Effect": "Allow",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*",
"Principal": {
"AWS": [
"arn:aws:iam::444455556666:role/CodeDeployDemo"
]
}
}
]
}
```
The following Amazon S3 bucket policy allows any on-premises instance with an associated IAM user containing the ARN `arn:aws:iam::444455556666:user/CodeDeployUser` to download from anywhere in the Amazon S3 bucket named `amzn-s3-demo-bucket`:
```
{
"Statement": [
{
"Action": [
"s3:Get*",
"s3:List*"
],
"Effect": "Allow",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*",
"Principal": {
"AWS": [
"arn:aws:iam::444455556666:user/CodeDeployUser"
]
}
}
]
}
```
For information about how to generate and attach an Amazon S3 bucket policy, see [Bucket policy examples](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-bucket-policies.html).
+ If you are creating a blue/green deployment, or you have specified an optional Classic Load Balancer, Application Load Balancer, or Network Load Balancer in the deployment group for an in-place deployment, you have created a VPC using Amazon VPC that contains at least two subnets. (CodeDeploy uses Elastic Load Balancing, which requires all instances in a load balancer group to be in a single VPC.)
If you have not created a VPC yet, see the [Amazon VPC Getting Started Guide](https://docs.aws.amazon.com/AmazonVPC/latest/GettingStartedGuide/ExerciseOverview.html).
+ If you are creating a blue/green deployment, you have configured at least one Classic Load Balancer, Application Load Balancer, or Network Load Balancer in Elastic Load Balancing and used it to register the instances that make up your original environment.
**Note**
The instances in your replacement environment will be registered with the load balancer later.
For more information about configuring a load balancer, see [Set up a load balancer in Elastic Load Balancing for CodeDeploy Amazon EC2 deployments](deployment-groups-create-load-balancer.md), and [Set up a load balancer, target groups, and listeners for CodeDeploy Amazon ECS deployments](deployment-groups-create-load-balancer-for-ecs.md).
## Deployment prerequisites for a blue/green deployment through CloudFormation
+ Your template does not need to model resources for a CodeDeploy application or deployment group.
+ Your template must include resources for a VPC using Amazon VPC that contains at least two subnets.
+ Your template must include resources for one or more Classic Load Balancers, Application Load Balancers, or Network Load Balancers in Elastic Load Balancing that are used to direct traffic to your target groups.
# Create an Amazon ECS Compute Platform deployment (console)
This topic shows you how to deploy an Amazon ECS service using the console. For more information, see [Tutorial: Deploy an application into Amazon ECS](tutorial-ecs-deployment.md) and [Tutorial: Deploy an Amazon ECS service with a validation test](tutorial-ecs-deployment-with-hooks.md).
1. Sign in to the AWS Management Console and open the CodeDeploy console at [https://console.aws.amazon.com/codedeploy](https://console.aws.amazon.com/codedeploy).
**Note**
Sign in with the same user that you set up in [Getting started with CodeDeploy](getting-started-codedeploy.md).
1. Do one of the following:
+ If you want to deploy an application, in the navigation pane, expand **Deploy**, and then choose **Applications**. Choose the name of the application you want to deploy. Make sure the **Compute platform** column for your application is **Amazon ECS**.
+ If you want to redeploy a deployment, in the navigation pane, expand **Deploy**, and then choose **Deployments**. Choose the deployment you want to redeploy, and in the **Application** column, choose the name of its application. Make sure the **Compute platform** column for your deployment is **Amazon ECS**.
1. On the **Deployments** tab, choose **Create deployment**.
**Note**
Your application must have a deployment group before it can be deployed. If your application does not have a deployment group, on the **Deployment groups** tab, choose **Create deployment group**. For more information, see [Create a deployment group with CodeDeploy](deployment-groups-create.md).
1. In **Deployment group**, choose a deployment group to use for this deployment.
1. Next to **Revision location**, choose where your revision is located:
+ **My application is stored in Amazon S3** — For information, see [Specify information about a revision stored in an Amazon S3 bucket](deployments-create-console-s3.md), and then return to step 6.
+ **Use AppSpec editor** — Select either JSON or YAML, and then enter your AppSpec file into the editor. You can save the AppSpec file by choosing **Save as text file**. When you choose **Deploy** at the end of these steps, you receive an error if your JSON or YAML is not valid. For more information about creating an AppSpec file, see [Add an application specification file to a revision for CodeDeploy](application-revisions-appspec-file.md).
1. (Optional) In **Deployment description**, enter a description for this deployment.
1. (Optional) In **Rollback configuration overrides**, you can specify different automatic rollback options for this deployment than were specified for the deployment group, if any.
For information about rollbacks in CodeDeploy, see [Redeployments and deployment rollbacks](deployment-steps-lambda.md#deployment-rollback-lambda) and [Redeploy and roll back a deployment with CodeDeploy](deployments-rollback-and-redeploy.md).
Choose from the following:
+ **Roll back when a deployment fails** — CodeDeploy redeploys the last known good revision as a new deployment.
+ **Roll back when alarm thresholds are met** — If alarms were added to the deployment group, CodeDeploy redeploys the last known good revision when one or more of the specified alarms is activated.
+ **Disable rollbacks** — Do not perform rollbacks for this deployment.
1. Choose **Create deployment**.
To track the status of your deployment, see [View CodeDeploy deployment details](deployments-view-details.md).
# Create an AWS Lambda Compute Platform deployment (console)
This topic shows you how to deploy a Lambda function using the console.
1. Sign in to the AWS Management Console and open the CodeDeploy console at [https://console.aws.amazon.com/codedeploy](https://console.aws.amazon.com/codedeploy).
**Note**
Sign in with the same user that you set up in [Getting started with CodeDeploy](getting-started-codedeploy.md).
1. Do one of the following:
+ If you want to deploy an application, in the navigation pane, expand **Deploy**, and then choose **Applications**. Choose the name of the application you want to deploy. Make sure the **Compute platform** column for your application is **AWS Lambda**.
+ If you want to redeploy a deployment, in the navigation pane, expand **Deploy**, and then choose **Deployments**. Choose the deployment you want to redeploy, and in the **Application** column, choose the name of its application. Make sure the **Compute platform** column for your deployment is **AWS Lambda**.
1. On the **Deployments** tab, choose **Create deployment**.
**Note**
Your application must have a deployment group before it can be deployed. If your application does not have a deployment group, on the **Deployment groups** tab, choose **Create deployment group**. For more information, see [Create a deployment group with CodeDeploy](deployment-groups-create.md).
1. In **Deployment group**, choose a deployment group to use for this deployment.
1. Next to **Revision location**, choose where your revision is located:
+ **My application is stored in Amazon S3** — For information, see [Specify information about a revision stored in an Amazon S3 bucket](deployments-create-console-s3.md), and then return to step 6.
+ **Use AppSpec editor** — Select either JSON or YAML, and then enter your AppSpec file into the editor. You can save the AppSpec file by choosing **Save as text file**. When you choose **Deploy** at the end of these steps, you receive an error if your JSON or YAML is not valid. For more information about creating an AppSpec file, see [Add an application specification file to a revision for CodeDeploy](application-revisions-appspec-file.md).
1. (Optional) In **Deployment description**, enter a description for this deployment.
1. (Optional) Expand **Deployment group overrides** to choose a deployment configuration to control how traffic is shifted to the Lambda function version that is different from the one specified in the deployment group.
For more information, see [Deployment configurations on an AWS Lambda compute platform](deployment-configurations.md#deployment-configuration-lambda).
1. (Optional) In **Rollback configuration overrides**, you can specify different automatic rollback options for this deployment than were specified for the deployment group, if any.
For information about rollbacks in CodeDeploy, see [Redeployments and deployment rollbacks](deployment-steps-lambda.md#deployment-rollback-lambda) and [Redeploy and roll back a deployment with CodeDeploy](deployments-rollback-and-redeploy.md).
Choose from the following:
+ **Roll back when a deployment fails** — CodeDeploy redeploys the last known good revision as a new deployment.
+ **Roll back when alarm thresholds are met** — If alarms were added to the deployment group, CodeDeploy redeploys the last known good revision when one or more of the specified alarms is activated.
+ **Disable rollbacks** — Do not perform rollbacks for this deployment.
1. Choose **Create deployment**.
To track the status of your deployment, see [View CodeDeploy deployment details](deployments-view-details.md).
# Create an EC2/On-Premises Compute Platform deployment (console)
This topic shows you how to deploy an application to an Amazon EC2 or on-premises server using the console.
1. Sign in to the AWS Management Console and open the CodeDeploy console at [https://console.aws.amazon.com/codedeploy](https://console.aws.amazon.com/codedeploy).
**Note**
Sign in with the same user that you set up in [Getting started with CodeDeploy](getting-started-codedeploy.md).
1. Do one of the following:
+ If you want to deploy an application, in the navigation pane, expand **Deploy**, and then choose **Applications**. Choose the name of the application you want to deploy. Make sure the **Compute platform** column for your application is **EC2/On-Premises**.
+ If you want to redeploy a deployment, in the navigation pane, expand **Deploy**, and then choose **Deployments**. Locate the deployment you want to redeploy, and then choose the name of its application in the **Application** column. Make sure the **Compute platform** column for your deployment is **EC2/On-Premises**.
1. On the **Deployments** tab, choose **Create deployment**.
**Note**
Your application must have a deployment group before it can be deployed. If your application does not have a deployment group, on the **Deployment groups** tab, choose **Create deployment group**. For more information, see [Create a deployment group with CodeDeploy](deployment-groups-create.md).
1. In **Deployment group**, choose a deployment group to use for this deployment.
1. Next to **Repository type**, choose the repository type your revision is stored in:
+ **My application is stored in Amazon S3** — For information, see [Specify information about a revision stored in an Amazon S3 bucket](deployments-create-console-s3.md), and then return to step 6.
+ **My application is stored in GitHub** — For information, see [Specify information about a revision stored in a GitHub repository](deployments-create-console-github.md), and then return to step 6.
1. (Optional) In **Deployment description**, enter a description for this deployment.
1. (Optional) Expand **Override deployment configuration** to choose a deployment configuration to control how traffic is shifted to the Amazon EC2 or on-premises server that is different from the one specified in the deployment group.
For more information, see [Working with deployment configurations in CodeDeploy](deployment-configurations.md).
1.
1. Select **Don't fail the deployment if the ApplicationStop lifecycle event fails** if you want a deployment to an instance to succeed if the `ApplicationStop` lifecycle event fails.
1. Expand **Additional deployment behavior settings** to specify how CodeDeploy handles files in a deployment target location that weren't part of the previous successful deployment.
Choose from the following:
+ **Fail the deployment** — An error is reported and the deployment status is changed to `Failed`.
+ **Overwrite the content** — If a file of the same name exists in the target location, the version from the application revision replaces it.
+ **Retain the content** — If a file of the same name exists in the target location, the file is kept and the version in the application revision is not copied to the instance.
For more information, see [Rollback behavior with existing content](deployments-rollback-and-redeploy.md#deployments-rollback-and-redeploy-content-options).
1. (Optional) In **Rollback configuration overrides**, you can specify different automatic rollback options for this deployment than were specified for the deployment group, if any.
For information about rollbacks in CodeDeploy, see [Redeployments and deployment rollbacks](deployment-steps-server.md#deployment-rollback) and [Redeploy and roll back a deployment with CodeDeploy](deployments-rollback-and-redeploy.md).
Choose from the following:
+ **Roll back when a deployment fails** — CodeDeploy redeploys the last known good revision as a new deployment.
+ **Roll back when alarm thresholds are met** — If alarms were added to the deployment group, CodeDeploy deploys the last known good revision when one or more of the specified alarms is activated.
+ **Disable rollbacks** — Do not perform rollbacks for this deployment.
1. Choose **Start deployment**.
To track the status of your deployment, see [View CodeDeploy deployment details](deployments-view-details.md).
**Topics**
+ [Specify information about a revision stored in an Amazon S3 bucket](deployments-create-console-s3.md)
+ [Specify information about a revision stored in a GitHub repository](deployments-create-console-github.md)
# Specify information about a revision stored in an Amazon S3 bucket
If you are following the steps in [Create an EC2/On-Premises Compute Platform deployment (console)](deployments-create-console.md), follow these steps to add details about an application revision stored in an Amazon S3 bucket.
1. Copy your revision's Amazon S3 link into **Revision location**. To find the link value:
1. In a separate browser tab:
Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/).
Browse to and choose your revision.
1. If the **Properties** pane is not visible, choose the **Properties** button.
1. In the **Properties** pane, copy the value of the **Link** field into the **Revision location** box in the CodeDeploy console.
To specify an ETag (a file checksum) as part of the revision location:
+ If the **Link** field value ends in **?versionId=*versionId***, add **&etag=** and the ETag to the end of the **Link** field value.
+ If the **Link** field value does not specify a version ID, add **?etag=** and the ETag to the end of the **Link** field value.
**Note**
Although it's not as easy as copying the value of the **Link** field, you can also type the revision location in one of the following formats:
**s3://*bucket-name*/*folders*/*objectName***
**s3://*bucket-name*/*folders*/*objectName*?versionId=*versionId***
**s3://*bucket-name*/*folders*/*objectName*?etag=*etag***
**s3://*bucket-name*/*folders*/*objectName*?versionId=*versionId*&etag=*etag***
***bucket-name*.s3.amazonaws.com/*folders*/*objectName***
1. If a message appears in the **File type** list that says the file type could not be detected, choose the revision's file type. Otherwise, accept the detected file type.
# Specify information about a revision stored in a GitHub repository
If you are following the steps in [Create an EC2/On-Premises Compute Platform deployment (console)](deployments-create-console.md), follow these steps to add details about an application revision stored in a GitHub repository.
1. In **Connect to GitHub**, do one of the following:
+ To create a connection for CodeDeploy applications to a GitHub account, in a different web browser tab, sign out of GitHub. In **GitHub account**, enter a name to identify this connection, and then choose **Connect to GitHub**. The webpage prompts you to authorize CodeDeploy to interact with GitHub for your application. Continue to step 2.
+ To use a connection you have already created, in **GitHub account**, select its name, and then choose **Connect to GitHub**. Continue to step 4.
+ To create a connection to a different GitHub account, in a different web browser tab, sign out of GitHub. Choose **Connect to a different GitHub account**, and then choose **Connect to GitHub**. Continue to step 2.
1. If you are prompted to sign in to GitHub, follow the instructions on the **Sign in** page. Sign in with your GitHub user name or email and password.
1. If an **Authorize application** page appears, choose **Authorize application**.
1. On the **Create deployment** page, in the **Repository name** box, enter the GitHub user or organization name that contains the revision, followed by a forward slash (`/`), followed by the name of the repository that contains the revision. If you are unsure of the value to type:
1. In a different web browser tab, go to your [GitHub dashboard](https://github.com/dashboard).
1. In **Your repositories**, hover your mouse pointer over the target repository name. A tooltip appears, displaying the GitHub user or organization name, followed by a forward slash (`/`), followed by the name of the repository. Enter this displayed value into the **Repository name** box.
**Note**
If the target repository name is not visible in **Your repositories**, use the **Search GitHub** box to find the target repository name and GitHub user or organization name.
1. In **Commit ID**, enter the ID of the commit that refers to the revision in the repository. If you are unsure of the value to type:
1. In a different web browser tab, go to your [GitHub dashboard](https://github.com/dashboard).
1. In **Your repositories**, choose the repository name that contains the target commit.
1. In the list of commits, find and copy the commit ID that refers to the revision in the repository. This ID is typically 40 characters in length and consists of both letters and numbers. (Do not use the shorter version of the commit ID, which is typically the first 10 characters of the longer version of the commit ID.)
1. Paste the commit ID into the **Commit ID** box.
# Create an Amazon ECS Compute Platform deployment (CLI)
After you have created the application and revision (in Amazon ECS deployments, this is the AppSpec file):
Call the [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/deploy/create-deployment.html) command, specifying:
+ An application name. To view a list of application names, call the [list-applications](https://docs.aws.amazon.com/cli/latest/reference/deploy/list-applications.html) command.
+ A deployment group name. To view a list of deployment group names, call the [list-deployment-groups](https://docs.aws.amazon.com/cli/latest/reference/deploy/list-deployment-groups.html) command.
+ Information about the revision to be deployed:
For revisions stored in Amazon S3:
+ The Amazon S3 bucket name that contains the revision.
+ The name of the uploaded revision.
+ (Optional) The Amazon S3 version identifier for the revision. (If the version identifier is not specified, CodeDeploy uses the most recent version.)
+ (Optional) The ETag for the revision. (If the ETag is not specified, CodeDeploy skips object validation.)
For revisions stored in a file that is not in Amazon S3, you need the file name and its path. Your revision file is written using JSON or YAML, so it most likely has a .json or .yaml extension.
+ (Optional) A description for the deployment.
The revision file can be specified as a file uploaded to an Amazon S3 bucket or as a string. The syntax for each when used as part of the **create-deployment** command is:
+ Amazon S3 bucket:
The `version` and `eTag` are optional.
```
--s3-location bucket=string,key=string,bundleType=JSON|YAML,version=string,eTag=string
```
+ String:
```
--revision '{"revisionType": "String", "string": {"content":"revision-as-string"}}'
```
**Note**
The **create-deployment** command can load a revision from a file. For more information, see [Loading parameters from a file](https://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html#cli-using-param-file).
For AWS Lambda deployment revision templates, see [Add an AppSpec file for an AWS Lambda deployment](application-revisions-appspec-file.md#add-appspec-file-lambda). For an example revision, see [AppSpec File example for an AWS Lambda deployment](reference-appspec-file-example.md#appspec-file-example-lambda).
To track the status of your deployment, see [View CodeDeploy deployment details](deployments-view-details.md).
# Create an AWS Lambda Compute Platform deployment (CLI)
After you have created the application and revision (in AWS Lambda deployments, this is the AppSpec file):
Call the [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/deploy/create-deployment.html) command, specifying:
+ An application name. To view a list of application names, call the [list-applications](https://docs.aws.amazon.com/cli/latest/reference/deploy/list-applications.html) command.
+ A deployment group name. To view a list of deployment group names, call the [list-deployment-groups](https://docs.aws.amazon.com/cli/latest/reference/deploy/list-deployment-groups.html) command.
+ Information about the revision to be deployed:
For revisions stored in Amazon S3:
+ The Amazon S3 bucket name that contains the revision.
+ The name of the uploaded revision.
+ (Optional) The Amazon S3 version identifier for the revision. (If the version identifier is not specified, CodeDeploy uses the most recent version.)
+ (Optional) The ETag for the revision. (If the ETag is not specified, CodeDeploy skips object validation.)
For revisions stored in a file that is not in Amazon S3, you need the file name and its path. Your revision file is written using JSON or YAML, so it most likely has a .json or .yaml extension.
+ (Optional) The name of a deployment configuration to use. To view a list of deployment configurations, call the [list-deployment-configs](https://docs.aws.amazon.com/cli/latest/reference/deploy/list-deployment-configs.html) command. (If not specified, CodeDeploy uses a specific default deployment configuration.)
+ (Optional) A description for the deployment.
The revision file can be specified as a file uploaded to an Amazon S3 bucket or as a string. The syntax for each when used as part of the **create-deployment** command is:
+ Amazon S3 bucket:
The `version` and `eTag` are optional.
```
--s3-location bucket=string,key=string,bundleType=JSON|YAML,version=string,eTag=string
```
+ String:
```
--revision '{"revisionType": "String", "string": {"content":"revision-as-string"}}'
```
**Note**
The **create-deployment** command can load a revision from a file. For more information, see [Loading parameters from a file](https://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html#cli-using-param-file).
For AWS Lambda deployment revision templates, see [Add an AppSpec file for an AWS Lambda deployment](application-revisions-appspec-file.md#add-appspec-file-lambda). For an example revision, see [AppSpec File example for an AWS Lambda deployment](reference-appspec-file-example.md#appspec-file-example-lambda).
To track the status of your deployment, see [View CodeDeploy deployment details](deployments-view-details.md).
# Create an EC2/On-Premises Compute Platform deployment (CLI)
To use the AWS CLI to deploy a revision to the EC2/On-Premises compute platform:
1. After you have prepared the instances, created the application, and pushed the revision, do one of the following:
+ If you want to deploy a revision from an Amazon S3 bucket, continue to step 2 now.
+ If you want to deploy a revision from a GitHub repository, first complete the steps in [Connect a CodeDeploy application to a GitHub repository](deployments-create-cli-github.md), and then continue to step 2.
1. Call the [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/deploy/create-deployment.html) command, specifying:
+ `--application-name`: An application name. To view a list of application names, call the [list-applications](https://docs.aws.amazon.com/cli/latest/reference/deploy/list-applications.html) command.
+ `--deployment-group-name`: An Amazon EC2 deployment group name. To view a list of deployment group names, call the [list-deployment-groups](https://docs.aws.amazon.com/cli/latest/reference/deploy/list-deployment-groups.html) command.
+ `--revision`: Information about the revision to be deployed:
For revisions stored in Amazon S3:
+ `s3Location`: The Amazon S3 bucket name that contains the revision.
+ `s3Location --> key`: The name of the uploaded revision.
+ `s3Location --> bundleType`: The file type of the uploaded revision.
**Note**
The tar and compressed tar archive file formats (.tar and .tar.gz) are not supported for Windows Server instances.
+ `s3Location --> version`: (Optional) The Amazon S3 version identifier for the revision. (If the version identifier is not specified, CodeDeploy uses the most recent version.)
+ `s3Location --> eTag`: (Optional) The ETag for the revision. (If the ETag is not specified, CodeDeploy skips object validation.)
For revisions stored in GitHub:
+ `gitHubLocation --> repository`: The GitHub user or group name assigned to the repository that contains the revision, followed by a forward slash (`/`), followed by the repository name.
+ `gitHubLocation --> commitId`: The commit ID for the revision.
+ `--deployment-config-name`: (Optional) The name of a deployment configuration to use. To view a list of deployment configurations, call the [list-deployment-configs](https://docs.aws.amazon.com/cli/latest/reference/deploy/list-deployment-configs.html) command. (If not specified, CodeDeploy uses a specific default deployment configuration.)
+ `--ignore-application-stop-failures | --no-ignore-application-stop-failures`: (Optional) Whether you want the deployment to an instance to continue to the `BeforeInstall` deployment lifecycle event if the `ApplicationStop` deployment lifecycle event fails.
+ `--description`: (Optional) A description for the deployment.
+ `--file-exists-behavior`: (Optional) As part of the deployment process, the CodeDeploy agent removes from each instance all the files installed by the most recent deployment. Choose what happens when files that weren’t part of a previous deployment appear in target deployment locations.
+ `--target-instances`: For blue/green deployments, information about the instances that belong to the replacement environment in a blue/green deployment, including the names of one or more Amazon EC2 Auto Scaling groups, or the tag filter key, type, and value used to identify Amazon EC2 instances.
**Note**
Use this syntax as part of the **create-deployment** call to specify information about a revision in Amazon S3 directly on the command line. (The `version` and `eTag` are optional.)
```
--s3-location bucket=string,key=string,bundleType=tar|tgz|zip,version=string,eTag=string
```
Use this syntax as part of the **create-deployment** call to specify information about a revision in GitHub directly on the command line:
```
--github-location repository=string,commitId=string
```
To get information about revisions that have been pushed already, call the [list-application-revisions](https://docs.aws.amazon.com/cli/latest/reference/deploy/list-application-revisions.html) command.
To track the status of your deployment, see [View CodeDeploy deployment details](deployments-view-details.md).
## create-deployment command reference
Below is the command structure and options for the `create-deployment` command. For more information, see the [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/deploy/create-deployment.html) reference in the *AWS CLI Command Reference*.
```
create-deployment
--application-name
[--deployment-group-name ]
[--revision ]
[--deployment-config-name ]
[--description ]
[--ignore-application-stop-failures | --no-ignore-application-stop-failures]
[--target-instances ]
[--auto-rollback-configuration ]
[--update-outdated-instances-only | --no-update-outdated-instances-only]
[--file-exists-behavior ]
[--s3-location ]
[--github-location ]
[--cli-input-json ]
[--generate-cli-skeleton ]
```
# Connect a CodeDeploy application to a GitHub repository
Before you can deploy an application from a GitHub repository for the first time using the AWS CLI, you must first give CodeDeploy permission to interact with GitHub on behalf of your GitHub account. This step must be completed once for each application using the CodeDeploy console.
1. Sign in to the AWS Management Console and open the CodeDeploy console at [https://console.aws.amazon.com/codedeploy](https://console.aws.amazon.com/codedeploy).
**Note**
Sign in with the same user that you set up in [Getting started with CodeDeploy](getting-started-codedeploy.md).
1. Choose **Applications**.
1. From **Applications**, choose the application you want to link to your GitHub user account and choose **Deploy application**.
**Note**
You are not creating a deployment. This is currently the only way to give CodeDeploy permission to interact with GitHub on behalf of your GitHub user account.
1. Next to **Repository type**, choose **My application revision is stored in GitHub**.
1. Choose **Connect to GitHub**.
**Note**
If you see a **Connect to a different GitHub account** link:
You might have already authorized CodeDeploy to interact with GitHub on behalf of a different GitHub account for the application.
You might have revoked authorization for CodeDeploy to interact with GitHub on behalf of the signed-in GitHub account for all applications linked to in CodeDeploy.
For more information, see [GitHub authentication with applications in CodeDeploy](integrations-partners-github.md#behaviors-authentication).
1. If you are not already signed in to GitHub, follow the instructions on the **Sign in** page.
1. On the **Authorize application** page, choose **Authorize application**.
1. Now that CodeDeploy has permission, choose **Cancel**, and continue with the steps in [Create an EC2/On-Premises Compute Platform deployment (CLI)](deployments-create-cli.md).
# Create an Amazon ECS blue/green deployment through CloudFormation
You can use AWS CloudFormation to manage Amazon ECS blue/green deployments through CodeDeploy. You generate your deployment by defining your green and blue resources and specifying the traffic routing and stabilization settings to use in CloudFormation. This topic covers the differences between Amazon ECS blue/green deployments that are managed by CodeDeploy and deployments that are managed by CloudFormation.
For step-by-step instructions on using CloudFormation to manage your Amazon ECS blue/green deployments, see [Automate ECS blue/green deployments through CodeDeploy using AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/blue-green.html) in the *AWS CloudFormation User Guide*.
**Note**
Managing Amazon ECS blue/green deployments with CloudFormation is not available in the Asia Pacific (Osaka) region.
## Differences between Amazon ECS blue/green deployments through CodeDeploy and CloudFormation
The CloudFormation stack template models Amazon ECS task-related resources and infrastructure, and also the configuration options for deployments. So there are differences between the standard Amazon ECS blue/green deployments and blue/green deployments that are created through CloudFormation.
Unlike standard Amazon ECS blue/green deployments, you don't model or manually create the following:
+ You don't create an AWS CodeDeploy application by specifying a name that uniquely represents what you want to deploy.
+ You don't create an AWS CodeDeploy deployment group.
+ You don't specify an *application specification file* (AppSpec file). The information normally managed with the AppSpec file, such as the weighted configuration options or lifecycle events, is managed by the `AWS::CodeDeploy::BlueGreen` hook.
This table summarizes the differences in the high-level workflow between deployment types.
****
| Function | Standard blue/green deployments | Blue/green deployments through CloudFormation |
| --- | --- | --- |
| Specify the Amazon ECS cluster, Amazon ECS service, Application Load Balancer or Network Load Balancer, Production listener, test listener, and two target groups. | Create a CodeDeploy deployment group that specifies these resources. | Create an CloudFormation template to model these resources. |
| Specify the change to be deployed. | Create a CodeDeploy application. | Create an CloudFormation template that specifies the container image. |
| Specify the Amazon ECS task definition, container name, and container port. | Create an AppSpec file that specifies these resources. | Create an CloudFormation template to model these resources. |
| Specify the deployment traffic shifting options and lifecycle event hooks. | Create an AppSpec file that specifies these options. | Create an CloudFormation template that uses the AWS::CodeDeploy::BlueGreen hook parameters to specify these options. |
| CloudWatch alarms. | Create a CloudWatch alarm that triggers a rollback. | Configure a CloudWatch alarm at the CloudFormation stack level that triggers a rollback. |
| Rollback/redeployment. | Specify rollback and redeployment options. | Cancel the stack update in CloudFormation. |
## Monitoring Amazon ECS blue/green deployments through CloudFormation
You can monitor blue/green deployments through CloudFormation and CodeDeploy. For information about monitoring through CloudFormation, see [Monitoring blue/green events in CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/blue-green.html#blue-green-events) in the *AWS CloudFormation User Guide*.
**To view deployment status of blue/green deployments in CodeDeploy**
1. Sign in to the AWS Management Console and open the CodeDeploy console at [https://console.aws.amazon.com/codedeploy](https://console.aws.amazon.com/codedeploy).
**Note**
Sign in with the same user that you set up in [Getting started with CodeDeploy](getting-started-codedeploy.md).
1. In **Deployments**, the deployment that was triggered by the CloudFormation stack update appears. Choose the deployment to view the **Deployment history**.
![\[Console screenshot showing the Deployments section and deployment history.\]](http://docs.aws.amazon.com/codedeploy/latest/userguide/images/cfn-cd-bg-deplhist.png)
1. Choose the deployment to view the traffic shifting status. Note that the application and deployment group are not created.
![\[Console screenshot showing the deployment details with deployment status completed.\]](http://docs.aws.amazon.com/codedeploy/latest/userguide/images/cfn-cd-bg-deplstatus.png)
1. The following apply for rolling back or stopping the deployment:
+ The successful deployment appears in CodeDeploy and shows that the deployment was initiated by CloudFormation.
+ If you want to stop and roll back the deployment, you must cancel the stack update in CloudFormation.
# View CodeDeploy deployment details
You can use the CodeDeploy console, the AWS CLI, or the CodeDeploy APIs to view details about deployments associated with your AWS account.
**Note**
You can view EC2/On-Premises deployment logs on your instances in the following locations:
Amazon Linux, RHEL, and Ubuntu Server: `/opt/codedeploy-agent/deployment-root/deployment-logs/codedeploy-agent-deployments.log`
Windows Server: C:\$1ProgramData\$1Amazon\$1CodeDeploy\$1logs\$1scripts.log
For more information, see [Analyzing log files to investigate deployment failures on instances](troubleshooting-ec2-instances.md#troubleshooting-deploy-failures).
**Topics**
+ [View deployment details (console)](#deployments-view-details-console)
+ [View deployment details (CLI)](#deployments-view-details-cli)
## View deployment details (console)
To use the CodeDeploy console to view deployment details:
1. Sign in to the AWS Management Console and open the CodeDeploy console at [https://console.aws.amazon.com/codedeploy](https://console.aws.amazon.com/codedeploy).
**Note**
Sign in with the same user that you set up in [Getting started with CodeDeploy](getting-started-codedeploy.md).
1. In the navigation pane, expand **Deploy**, and then choose **Deployments**.
**Note**
If no entries are displayed, make sure the correct region is selected. On the navigation bar, in the region selector, choose one of the regions listed in [Region and Endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#codedeploy_region) in the *AWS General Reference*. CodeDeploy is supported in these regions only.
1. To see more details for a single deployment, in **Deployment history**, choose the deployment ID or choose the button next to the deployment ID, and then choose **View**.
## View deployment details (CLI)
To use the AWS CLI to view deployment details, call the `get-deployment` command or the `batch-get-deployments` command. You can call the `list-deployments` command to get a list of unique deployment IDs to use as inputs to the `get-deployment` command and the `batch-get-deployments` command.
To view details about a single deployment, call the [get-deployment](https://docs.aws.amazon.com/cli/latest/reference/deploy/get-deployment.html) command, specifying the unique deployment identifier. To get the deployment ID, call the [list-deployments](https://docs.aws.amazon.com/cli/latest/reference/deploy/list-deployments.html) command.
To view details about multiple deployments, call the [batch-get-deployments](https://docs.aws.amazon.com/cli/latest/reference/deploy/batch-get-deployments.html) command, specifying multiple unique deployment identifiers. To get the deployment IDs, call the [list-deployments](https://docs.aws.amazon.com/cli/latest/reference/deploy/list-deployments.html) command.
To view a list of deployment IDs, call the [list-deployments](https://docs.aws.amazon.com/cli/latest/reference/deploy/list-deployments.html) command, specifying:
+ The name of the application associated with the deployment. To view a list of application names, call the [list-applications](https://docs.aws.amazon.com/cli/latest/reference/deploy/list-applications.html) command.
+ The name of the deployment group associated with the deployment. To view a list of deployment group names, call the [list-deployment-groups](https://docs.aws.amazon.com/cli/latest/reference/deploy/list-deployment-groups.html) command.
+ Optionally, whether to include details about deployments by their deployment status. (If not specified, all matching deployments will be listed, regardless of their deployment status.)
+ Optionally, whether to include details about deployments by their deployment creation start times or end times, or both. (If not specified, all matching deployments will be listed, regardless of their creation times.)
# View log data for CodeDeploy EC2/On-Premises deployments
You can view the log data created by a CodeDeploy deployment by setting up the Amazon CloudWatch agent to view aggregated data in the CloudWatch console or by logging into an individual instance to review the log file.
**Note**
Logs are not supported for AWS Lambda or Amazon ECS deployments. They can be created for EC2/On-Premises deployments only.
**Topics**
+ [View log file data in the Amazon CloudWatch console](#deployments-view-logs-cloudwatch)
+ [View log files on an instance](#deployments-view-logs-instance)
## View log file data in the Amazon CloudWatch console
When the Amazon CloudWatch agent is installed on an instance, deployment data for all deployments to that instance becomes available for viewing in the CloudWatch console. For simplicity, we recommend using CloudWatch to centrally monitor log files instead of viewing them instance by instance. For more information, see [Send CodeDeploy agent logs to CloudWatch](codedeploy-agent-operations-cloudwatch-agent.md).
## View log files on an instance
To view deployment log data for an individual instance, you can sign in to the instance and browse for information about errors or other deployment events.
**Topics**
+ [To view deployment log files on Amazon Linux, RHEL, and Ubuntu Server instances](#deployments-view-logs-instance-unix)
+ [To view deployment log files on Windows Server instances](#deployments-view-logs-instance-windows)
### To view deployment log files on Amazon Linux, RHEL, and Ubuntu Server instances
On Amazon Linux, RHEL, and Ubuntu Server instances, deployment logs are stored in the following location:
`/opt/codedeploy-agent/deployment-root/deployment-logs/codedeploy-agent-deployments.log`
To view or analyze deployment logs on Amazon Linux, RHEL, and Ubuntu Server instances, sign in to the instance, and then type the following command to open the CodeDeploy agent log file:
```
less /var/log/aws/codedeploy-agent/codedeploy-agent.log
```
Type the following commands to browse the log file for error messages:
| Command | Result |
| --- | --- |
| & ERROR | Show just the error messages in the log file. Use a single space before and after the word ERROR. |
| / ERROR | Search for the next error message.¹ |
| ? ERROR | Search for the previous error message.² Use a single space before and after the word ERROR. |
| G | Go to the end of the log file. |
| g | Go to the start of the log file. |
| q | Exit the log file. |
| h | Learn about additional commands. |
| ¹ After you type **/ ERROR **, type **n** for the next error message. Type **N** for the previous error message. ² After you type **? ERROR **, type **n** for the next error message, or type **N** for the previous error message. |
You can also type the following command to open a CodeDeploy scripts log file:
```
less /opt/codedeploy-agent/deployment-root/deployment-group-ID/deployment-ID/logs/scripts.log
```
Type the following commands to browse the log file for error messages:
| Command | Result |
| --- | --- |
| &stderr | Show just the error messages in the log file. |
| /stderr | Search for the next error message.¹ |
| ?stderr | Search for the previous error message.² |
| G | Go to the end of the log file. |
| g | Go to the start of the log file. |
| q | Exit the log file. |
| h | Learn about additional commands. |
| ¹After you type **/stderr**, type **n** for the next error message forward. Type **N** for the previous error message backward. ² After you type **?stderr**, type **n** for the next error message backward. Type **N** for the previous error message forward. |
### To view deployment log files on Windows Server instances
**CodeDeploy agent log file**: On Windows Server instances, the CodeDeploy agent log file is stored at the following location:
`C:\ProgramData\Amazon\CodeDeploy\log\codedeploy-agent-log.txt`
To view or analyze the CodeDeploy agent log file on a Windows Server instance, sign in to the instance, and then type the following command to open the file:
```
notepad C:\ProgramData\Amazon\CodeDeploy\log\codedeploy-agent-log.txt
```
To browse the log file for error messages, press CTRL\$1F, type **ERROR [**, and then press Enter to find the first error.
**CodeDeploy scripts log files**: On Windows Server instances, deployment logs are stored at the following location:
`C:\ProgramData\Amazon\CodeDeploy\deployment-group-id\deployment-id\logs\scripts.log`
Where:
+ *deployment-group-id* is a string such as `examplebf3a9c7a-7c19-4657-8684-b0c68d0cd3c4`
+ *deployment-id* is an identifier such as `d-12EXAMPLE`
Type the following command to open a CodeDeploy scripts log file:
```
notepad C:\ProgramData\Amazon\CodeDeploy\deployment-group-ID\deployment-ID\logs\scripts.log
```
To browse the log file for error messages, press CTRL\$1F, type **stderr**, and then press Enter to find the first error.
# Stop a deployment with CodeDeploy
You can use the CodeDeploy console, the AWS CLI, or the CodeDeploy APIs to stop deployments associated with your AWS account.
**Warning**
Stopping an EC2/On-Premises deployment can leave some or all of the instances in your deployment groups in an indeterminate deployment state. For more information, see [Stopped and failed deployments](deployment-steps-server.md#deployment-stop-fail).
**Topics**
+ [Stop a deployment (console)](#deployments-stop-console)
+ [Stop a deployment (CLI)](#deployments-stop-cli)
**Note**
If your deployment is a blue/green deployment through CloudFormation, you cannot perform this task in the CodeDeploy console. Go to the CloudFormation console to perform this task.
## Stop a deployment (console)
1. Sign in to the AWS Management Console and open the CodeDeploy console at [https://console.aws.amazon.com/codedeploy](https://console.aws.amazon.com/codedeploy).
**Note**
Sign in with the same user that you set up in [Getting started with CodeDeploy](getting-started-codedeploy.md).
1. In the navigation pane, expand **Deploy**, and then choose **Deployments**.
**Note**
If no entries are displayed, make sure the correct region is selected. On the navigation bar, in the region selector, choose one of the regions listed in [Region and Endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#codedeploy_region) in the *AWS General Reference*. CodeDeploy is supported in these regions only.
1. Choose the deployment you want to stop do one of the following:
1. Choose **Stop deployment** to stop the deployment without a rollback.
1. Choose **Stop and roll back deployment** to stop and roll back the deployment
For more information, see [Redeploy and roll back a deployment with CodeDeploy](deployments-rollback-and-redeploy.md).
**Note**
If **Stop deployment** and **Stop and roll back deployment** are unavailable, the deployment has progressed to a point where it cannot be stopped.
## Stop a deployment (CLI)
Call the [stop-deployment](https://docs.aws.amazon.com/cli/latest/reference/deploy/stop-deployment.html) command, specifying the deployment ID. To view a list of deployment IDs, call the [list-deployments](https://docs.aws.amazon.com/cli/latest/reference/deploy/list-deployments.html) command.
# Redeploy and roll back a deployment with CodeDeploy
CodeDeploy rolls back deployments by redeploying a previously deployed revision of an application as a new deployment. These rolled-back deployments are technically new deployments, with new deployment IDs, rather than restored versions of a previous deployment.
Deployments can be rolled back automatically or manually.
**Topics**
+ [Automatic rollbacks](#deployments-rollback-and-redeploy-automatic-rollbacks)
+ [Manual rollbacks](#deployments-rollback-and-redeploy-manual-rollbacks)
+ [Rollback and redeployment workflow](#deployments-rollback-and-redeploy-workflow)
+ [Rollback behavior with existing content](#deployments-rollback-and-redeploy-content-options)
## Automatic rollbacks
You can configure a deployment group or deployment to automatically roll back when a deployment fails or when a monitoring threshold you specify is met. In this case, the last known good version of an application revision is deployed. You configure automatic rollbacks when you create an application or create or update a deployment group.
When you create a new deployment, you can also choose to override the automatic rollback configuration that were specified for the deployment group.
**Note**
You can use Amazon Simple Notification Service to receive a notification whenever a deployment is rolled back automatically. For information, see [Monitoring deployments with Amazon SNS event notifications](monitoring-sns-event-notifications.md).
For more information about configuring automatic rollbacks, see [Configure advanced options for a deployment group](deployment-groups-configure-advanced-options.md).
## Manual rollbacks
If you have not set up automatic rollbacks, you can manually roll back a deployment by creating a new deployment that uses any previously deployed application revision and following the steps to redeploy a revision. You might do this if an application has gotten into an unknown state. Rather than spending a lot of time troubleshooting, you can redeploy the application to a known working state. For more information, see [Create a deployment with CodeDeploy](deployments-create.md).
**Note**
If you remove an instance from a deployment group, CodeDeploy does not uninstall anything that might have already been installed on that instance.
## Rollback and redeployment workflow
When automatic rollback is initiated, or when you manually initiate a redeployment or manual rollback, CodeDeploy first tries to remove from each participating instance all files that were last successfully installed. CodeDeploy does this by checking the cleanup file:
`/opt/codedeploy-agent/deployment-root/deployment-instructions/deployment-group-ID-cleanup` file (for Amazon Linux, Ubuntu Server, and RHEL instances)
`C:\ProgramData\Amazon\CodeDeploy\deployment-instructions\deployment-group-ID-cleanup` file (for Windows Server instances)
If it exists, CodeDeploy uses the cleanup file to remove from the instance all listed files before starting the new deployment.
For example, the first two text files and two script files were already deployed to an Amazon EC2 instance running Windows Server, and the scripts created two more text files during deployment lifecycle events:
```
c:\temp\a.txt (previously deployed by CodeDeploy)
c:\temp\b.txt (previously deployed by CodeDeploy)
c:\temp\c.bat (previously deployed by CodeDeploy)
c:\temp\d.bat (previously deployed by CodeDeploy)
c:\temp\e.txt (previously created by c.bat)
c:\temp\f.txt (previously created by d.bat)
```
The cleanup file will list only the first two text files and two script files:
```
c:\temp\a.txt
c:\temp\b.txt
c:\temp\c.bat
c:\temp\d.bat
```
Before the new deployment, CodeDeploy will remove only the first two text files and the two script files, leaving the last two text files untouched:
```
c:\temp\a.txt will be removed
c:\temp\b.txt will be removed
c:\temp\c.bat will be removed
c:\temp\d.bat will be removed
c:\temp\e.txt will remain
c:\temp\f.txt will remain
```
As part of this process, CodeDeploy will not try to revert or otherwise reconcile any actions taken by any scripts in previous deployments during subsequent redeployments, whether manual or automatic rollbacks. For example, if the `c.bat` and `d.bat` files contain logic to not re-create the `e.txt` and `f.txt` files if they already exist, then the old versions of `e.txt` and `f.txt` will remain untouched whenever CodeDeploy runs `c.bat` and `d.bat` in subsequent deployments. You can add logic to `c.bat` and `d.bat` to always check for and delete old versions of `e.txt` and `f.txt` before creating new ones.
## Rollback behavior with existing content
As part of the deployment process, the CodeDeploy agent removes from each instance all the files installed by the most recent deployment. If files that weren’t part of a previous deployment appear in target deployment locations, you can choose what CodeDeploy does with them during the next deployment:
+ **Fail the deployment** — An error is reported and the deployment status is changed to Failed.
+ **Overwrite the content** — The version of the file from the application revision replaces the version already on the instance.
+ **Retain the content** — The file in the target location is kept and the version in the application revision is not copied to the instance.
You can choose this behavior when you create a deployment. If creating a deployment in the console, see [Create an EC2/On-Premises Compute Platform deployment (console)](deployments-create-console.md). If creating a deployment with the AWS CLI, see [Create an EC2/On-Premises Compute Platform deployment (CLI)](deployments-create-cli.md).
You might choose to retain files that you want to be part of the next deployment without having to add them to the application revision package. For example, you might upload files directly to the instance that are required for the deployment but weren’t added to the application revision bundle. Or you might upload files to the instance if your applications are already in your production environment but you want to use CodeDeploy for the first time to deploy them.
In the case of rollbacks, where the most recent successfully deployed application revision is redeployed due to a deployment failure, the content-handling option for that last successful deployment is applied to the rollback deployment.
However, if the deployment that failed was configured to overwrite, instead of retain files, an unexpected result can occur during the rollback. Specifically, the files you expected to be retained might be removed by the failed deployment. The files are not on the instance when the rollback deployment runs.
In the following example, there are three deployments. Any file that is overwritten (deleted) during the failed second deployment is no longer available (cannot be retained) when application revision 1 is deployed again during deployment 3:
****
| Deployment | Application revision | Content overwrite option | Deployment status | Behavior and result |
| --- | --- | --- | --- | --- |
| deployment 1 | application revision 1 | RETAIN | Succeeded | CodeDeploy detects files in the target locations that were not deployed by the previous deployment. These files might be placed there intentionally to become part of the current deployment. They are kept and recorded as part of the current deployment package. |
| deployment 2 | application revision 2 | OVERWRITE | Failed | During the deployment process, CodeDeploy deletes all the files that are part of the previous successful deployment. This includes the files that were retained during deployment 1. However, the deployment fails for unrelated reasons. |
| deployment 3 | application revision 1 | RETAIN | | Because auto rollback is enabled for the deployment or deployment group, CodeDeploy deploys the last known good application revision, application revision 1.However, the files that you wanted to retain in deployment 1 were deleted before deployment 2 failed and cannot be retrieved by AWS CodeDeploy. You can add them to the instance yourself if they are required for application revision 1, or you can create a new application revision. |
# Deploy an application in a different AWS account
Organizations commonly have multiple AWS accounts that they use for different purposes (for example, one for system administration tasks and another for development, test, and production tasks or one associated with development and test environments and another associated with the production environment).
Although you might perform related work in different accounts, CodeDeploy deployment groups and the Amazon EC2 instances to which they deploy are strictly tied to the accounts under which they were created. You cannot, for example, add an instance that you launched in one account to a deployment group in another.
Assume you have two AWS accounts: your development account and your production account. You work primarily in the development account, but you want to be able kick off deployments in your production account without a full set of credentials there or without having to sign out of the development account and in to the production account.
After following the cross-account configuration steps, you can initiate deployments that belong to another of your organization’s accounts without needing a full set of credentials for that other account. You do this, in part, by using a capability provided by the AWS Security Token Service (AWS STS) that grants you temporary access to that account.
## Step 1: Create an S3 bucket in either account
In either the development account or the production account:
+ If you have not already done so, create an Amazon S3 bucket where the application revisions for the production account will be stored. For information, see [Create a Bucket in Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/CreatingABucket.html). You can even use the same bucket and application revisions for both accounts, deploying the same files to your production environment that you tested and verified in your development account.
## Step 2: Grant Amazon S3 bucket permissions to the production account's IAM instance profile
If the Amazon S3 bucket you created in step 1 is in your production account, this step is not required. The role you assume later will already have access to this bucket because it is also in the production account.
If you created the Amazon S3 bucket in the development account, do the following:
+ In the production account, create an IAM instance profile. For information, see [Step 4: Create an IAM instance profile for your Amazon EC2 instances](getting-started-create-iam-instance-profile.md).
**Note**
Make note of the ARN for this IAM instance profile. You will need to add it to the cross-bucket policy you create next.
+ In the development account, give access to the Amazon S3 bucket you created in the development account to the IAM instance profile you just created in your production account. For information, see [ Example 2: Bucket owner granting cross-account bucket permissions](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-walkthroughs-managing-access-example2.html).
Note the following as you complete the process of granting cross-account bucket permissions:
+ In the sample walkthrough, Account A represents your development account and Account B represents your production account.
+ When you [perform the Account A (development account) tasks](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-walkthroughs-managing-access-example2.html#access-policies-walkthrough-cross-account-permissions-acctA-tasks), modify the following bucket policy to grant cross-account permissions instead of using the sample policy provided in the walkthrough.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Cross-account permissions",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/role-name"
},
"Action": [
"s3:Get*",
"s3:List*"
],
"Resource": [
"arn:aws:s3:::bucket-name/*"
]
}
]
}
```
------
*account-id* represents the account number of the production account where you just created the IAM instance profile.
*role-name* represents the name of the IAM instance profile you just created.
*bucket-name* represents the name of the bucket you created in step 1. Be sure to include the `/*` after the name of your bucket to provide access to each of the files inside the bucket.
## Step 3: Create resources and a cross-account role in the production account
In your production account:
+ Create your CodeDeploy resources — application, deployment group, deployment configuration, Amazon EC2 instances, Amazon EC2 instance profile, service role, and so on — using the instructions in this guide.
+ Create an additional role, a cross-account IAM role, that a user in your development account can assume to perform CodeDeploy operations in this production account.
Use the [Walkthrough: Delegate access across AWS accounts using IAM roles ](https://docs.aws.amazon.com/IAM/latest/UserGuide/walkthru_cross-account-with-roles.html) as a guide to help you create the cross-account role. Instead of adding the sample permissions in the walkthrough to your policy document, you should attach, at minimum, the following two AWS supplied policies to the role:
+ `AmazonS3FullAccess`: Required only if the S3 bucket is in the development account. Provides the assumed production account role with full access to the Amazon S3 services and resources in the development account, where the revision is stored.
+ `AWSCodeDeployDeployerAccess`: Enables a user to register and deploy revisions.
If you want to create and manage deployment groups and not just initiate deployments, add the `AWSCodeDeployFullAccess` policy instead of the `AWSCodeDeployDeployerAccess` policy. For more information about using IAM managed policies to grant permissions for CodeDeploy tasks, see [AWS managed (predefined) policies for CodeDeploy](managed-policies.md).
You can attach additional policies if you want to perform tasks in other AWS services while using this cross-account role.
**Important**
As you create the cross-account IAM role, make a note of the details you will need to gain access to the production account.
To use the AWS Management Console to switch roles, you will need to supply either of the following:
A URL for accessing the production account with the assumed role's credentials. You will find the URL on the **Review** page, which is displayed at the end of the cross-account role creation process.
The name of the cross-account role and either the account ID number or alias.
To use the AWS CLI to switch roles, you will need to supply the following:
The ARN of the cross-account role you will assume.
## Step 4: Upload the application revision to Amazon S3 bucket
In the account in which you created the Amazon S3 bucket:
+ Upload your application revision to the Amazon S3 bucket. For information, see [Push a revision for CodeDeploy to Amazon S3 (EC2/On-Premises deployments only)](application-revisions-push.md).
## Step 5: Assume the cross-account role and deploy applications
In the development account, you can use the AWS CLI or the AWS Management Console to assume the cross-account role and initiate the deployment in the production account.
For instructions about how to use the AWS Management Console to switch roles and initiate deployments, see [Switching to a role (AWS Management Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-console.html) and [Create an EC2/On-Premises Compute Platform deployment (console)](deployments-create-console.md).
For instructions about how to use the AWS CLI to assume the cross-account role and initiate deployments, see [Switching to an IAM role (AWS Command Line Interface)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-cli.html) and [Create an EC2/On-Premises Compute Platform deployment (CLI)](deployments-create-cli.md).
For more information about assuming a role through AWS STS, see [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) in the [AWS Security Token Service User Guide](https://docs.aws.amazon.com/STS/latest/APIReference/Welcome.html) and [assume-role](https://docs.aws.amazon.com/cli/latest/reference/sts/assume-role.html) in the [AWS CLI Command Reference](https://docs.aws.amazon.com/cli/latest/reference/).
**Related topic:**
+ [CodeDeploy: Deploying from a development account to a production account](https://aws.amazon.com/blogs/devops/aws-codedeploy-deploying-from-a-development-account-to-a-production-account/)
# Use the CodeDeploy agent to validate a deployment package on a local machine
Using the CodeDeploy agent, you can deploy content on an instance you are logged in to. This allows you to test the integrity of an application specification file (AppSpec file) that you intend to use in a deployment and the content you intend to deploy.
You do not need to create an application and deployment group. If you want to deploy content stored on the local instance, you do not even need an AWS account. For the simplest testing, you can run the **codedeploy-local** command, without specifying any options, in a directory that contains the AppSpec file and the content to be deployed. There are options for other test cases in the tool.
By validating a deployment package on a local machine you can:
+ Test the integrity of an application revision.
+ Test the contents of an AppSpec file.
+ Try out CodeDeploy for the first time with your existing application code.
+ Deploy content rapidly when you are already logged in to an instance.
You can use deploy content that is stored on the local instance or in a supported remote repository type (Amazon S3 buckets or public GitHub repositories).
## Prerequisites
Before you start a local deployment, complete the following steps:
+ Create or use an instance type supported by the CodeDeploy agent. For information, see [Operating systems supported by the CodeDeploy agent](codedeploy-agent.md#codedeploy-agent-supported-operating-systems).
+ Install version 1.0.1.1352 or later of the CodeDeploy agent. For information, see [Install the CodeDeploy agent](codedeploy-agent-operations-install.md).
+ If you are deploying your content from an Amazon S3 bucket or GitHub repository, provision a user to use with CodeDeploy. For information, see [Step 1: Setting up](getting-started-setting-up.md).
+ If you are deploying your application revision from an Amazon S3 bucket, create an Amazon S3 bucket in the region you are working in and apply an Amazon S3 bucket policy to the bucket. This policy grants your instances the permissions required to download the application revision.
For example, the following Amazon S3 bucket policy allows any Amazon EC2 instance with an attached IAM instance profile containing the ARN `arn:aws:iam::444455556666:role/CodeDeployDemo` to download from anywhere in the Amazon S3 bucket named `amzn-s3-demo-bucket`:
```
{
"Statement": [
{
"Action": [
"s3:Get*",
"s3:List*"
],
"Effect": "Allow",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*",
"Principal": {
"AWS": [
"arn:aws:iam::444455556666:role/CodeDeployDemo"
]
}
}
]
}
```
The following Amazon S3 bucket policy allows any on-premises instance with an associated IAM user containing the ARN `arn:aws:iam::444455556666:user/CodeDeployUser` to download from anywhere in the Amazon S3 bucket named `amzn-s3-demo-bucket`:
```
{
"Statement": [
{
"Action": [
"s3:Get*",
"s3:List*"
],
"Effect": "Allow",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*",
"Principal": {
"AWS": [
"arn:aws:iam::444455556666:user/CodeDeployUser"
]
}
}
]
}
```
For information about how to generate and attach an Amazon S3 bucket policy, see [Bucket policy examples](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-bucket-policies.html).
+ If you are deploying your application revision from an Amazon S3 bucket or GitHub repository, set up an IAM instance profile and attach it to the instance. For information, see [Step 4: Create an IAM instance profile for your Amazon EC2 instances](getting-started-create-iam-instance-profile.md), [Create an Amazon EC2 instance for CodeDeploy (AWS CLI or Amazon EC2 console)](instances-ec2-create.md), and [Create an Amazon EC2 instance for CodeDeploy (CloudFormation template)](instances-ec2-create-cloudformation-template.md).
+ If you are deploying your content from GitHub, create a GitHub account and a public repository. To create a GitHub account, see [Join GitHub](https://github.com/join). To create a GitHub repository, see [Create a repo](https://help.github.com/articles/create-a-repo/).
**Note**
Private repositories are not currently supported. If your content is stored in a private GitHub repository, you can download it to the instance and use the `--bundle-location` option to specify its local path.
+ Prepare the content (including an AppSpec file) that you want to deploy to the instance and place it on the local instance, in your Amazon S3 bucket, or in your GitHub repository. For information, see [Working with application revisions for CodeDeploy](application-revisions.md).
+ If you want to use values other than the defaults for other configuration options, create the configuration file and place it on the instance (`/etc/codedeploy-agent/conf/codedeployagent.yml` for Amazon Linux, RHEL, or Ubuntu Server instances or `C:\ProgramData\Amazon\CodeDeploy\conf.yml` for Windows Server instances). For information, see [CodeDeploy agent configuration reference](reference-agent-configuration.md).
**Note**
If you use a configuration file on Amazon Linux, RHEL, or Ubuntu Server instances, you must either:
Use the `:root_dir:` and `:log_dir:` variables to specify locations other than the defaults for the deployment root and log directory folders.
Use `sudo` to run CodeDeploy agent commands.
## Create a local deployment
On the instance where you want to create the local deployment, open a terminal session (Amazon Linux, RHEL, or Ubuntu Server instances) or a command prompt (Windows Server) to run the tool commands.
**Note**
The **codedeploy-local** command is installed in the following locations:
On Amazon Linux, RHEL, or Ubuntu Server: `/opt/codedeploy-agent/bin`.
On Windows Server: `C:\ProgramData\Amazon\CodeDeploy\bin`.
** Basic Command Syntax **
```
codedeploy-local [options]
```
**Synopsis**
```
codedeploy-local
[--bundle-location ]
[--type ]
[--file-exists-behavior ]
[--deployment-group ]
[--events ]
[--agent-configuration-file ]
[--appspec-filename ]
```
** Options**
**-l**, **--bundle-location**
The location of the application revision bundle. If you do not specify a location, the tool uses the directory you are currently working in by default. If you specify a value for `--bundle-location`, you must also specify a value for `--type`.
Bundle location format examples:
+ Local Amazon Linux, RHEL, or Ubuntu Server instance: `/path/to/local/bundle.tgz`
+ Local Windows Server instance: `C:/path/to/local/bundle`
+ Amazon S3 bucket: `s3://amzn-s3-demo-bucket/bundle.tar`
+ GitHub repository: `https://github.com/account-name/repository-name/`
**-t**, **--type**
The format of the application revision bundle. Supported types include `tgz`, `tar`, `zip`, and `directory`. If you do not specify a type, the tool uses `directory` by default. If you specify a value for `--type`, you must also specify a value for `--bundle-location`.
**-b**, **--file-exists-behavior**
Indicates how files are handled that already exist in a deployment target location but weren't part of a previous successful deployment. Options include DISALLOW, OVERWRITE, RETAIN. For more information, see [fileExistsBehavior](https://docs.aws.amazon.com/codedeploy/latest/APIReference/API_CreateDeployment.html#CodeDeploy-CreateDeployment-request-fileExistsBehavior) in *[AWS CodeDeploy API Reference](https://docs.aws.amazon.com/codedeploy/latest/APIReference/)*.
**-g**, **--deployment-group**
The path to the folder that is the target location for the content to be deployed. If you do not specify a folder, the tool creates one named *default-local-deployment-group* inside your deployment root directory. For each local deployment you create, the tool creates a subdirectory inside this folder with names such as *d-98761234-local*.
**-e**, **--events**
A set of override lifecycle event hooks you want to run, in order, instead of the events you listed in the AppSpec file. Multiple hooks can be specified, separated by commas. You can use this option if:
+ You want to run a different set of events without having to update the AppSpec file.
+ You want to run a single event hook as an exception to what's in the AppSpec file, such as `ApplicationStop`.
If you don't specify **DownloadBundle** and **Install** events in the override list, they will run before all the event hooks you do specify. If you include **DownloadBundle** and **Install** in the list of `--events` options, they must be preceded only by events that normally run before them in CodeDeploy deployments. For information, see [AppSpec 'hooks' section](reference-appspec-file-structure-hooks.md).
**-c**, **--agent-configuration-file**
The location of a configuration file to use for the deployment, if you store it in a location other than the default. A configuration file specifies alternatives to other default values and behaviors for a deployment.
By default, configuration files are stored in `/etc/codedeploy-agent/conf/codedeployagent.yml` (Amazon Linux, RHEL, or Ubuntu Server instances) or `C:/ProgramData/Amazon/CodeDeploy/conf.yml` (Windows Server). For more information, see [CodeDeploy agent configuration reference](reference-agent-configuration.md).
**-A**, **--appspec-filename**
The name of the AppSpec file. For local deployments, accepted values are `appspec.yml` and `appspec.yaml`. By default, the AppSpec file is called `appspec.yml`.
**-h**, **--help**
Displays a summary of help content.
**-v**, **--version**
Displays the tool's version number.
## Examples
The following are examples of valid command formats.
```
codedeploy-local
```
```
codedeploy-local --bundle-location /path/to/local/bundle/directory
```
```
codedeploy-local --bundle-location C:/path/to/local/bundle.zip --type zip --deployment-group my-deployment-group
```
```
codedeploy-local --bundle-location /path/to/local/directory --type directory --deployment-group my-deployment-group
```
Deploy a bundle from Amazon S3:
```
codedeploy-local --bundle-location s3://amzn-s3-demo-bucket/bundle.tgz --type tgz
```
```
codedeploy-local --bundle-location s3://amzn-s3-demo-bucket/bundle.zip?versionId=1234&etag=47e8 --type zip --deployment-group my-deployment-group
```
Deploy a bundle from a public GitHub repository:
```
codedeploy-local --bundle-location https://github.com/awslabs/aws-codedeploy-sample-tomcat --type zip
```
```
codedeploy-local --bundle-location https://api.github.com/repos/awslabs/aws-codedeploy-sample-tomcat/zipball/master --type zip
```
```
codedeploy-local --bundle-location https://api.github.com/repos/awslabs/aws-codedeploy-sample-tomcat/zipball/HEAD --type zip
```
```
codedeploy-local --bundle-location https://api.github.com/repos/awslabs/aws-codedeploy-sample-tomcat/zipball/1a2b3c4d --type zip
```
Deploy a bundle specifying multiple lifecycle events:
```
codedeploy-local --bundle-location /path/to/local/bundle.tar --type tar --application-folder my-deployment --events DownloadBundle,Install,ApplicationStart,HealthCheck
```
Stop a previously deployed application using the ApplicationStop lifecycle event:
```
codedeploy-local --bundle-location /path/to/local/bundle.tgz --type tgz --deployment-group --events ApplicationStop
```
Deploy using a specific deployment group ID:
```
codedeploy-local --bundle-location C:/path/to/local/bundle/directory --deployment-group 1234abcd-5dd1-4774-89c6-30b107ac5dca
```
```
codedeploy-local --bundle-location C:/path/to/local/bundle.zip --type zip --deployment-group 1234abcd-5dd1-4774-89c6-30b107ac5dca
```