# Tutorial: Deploy an application into Amazon ECS
In this tutorial, you learn how to deploy an application into Amazon ECS using CodeDeploy. You start with an application you already created and deployed into Amazon ECS. The first step is to update your application by modifying its task definition file with a new tag. Next, you use CodeDeploy to deploy the update. During deployment, CodeDeploy installs your update into a new, replacement task set. Then, it shifts production traffic from the original version of your Amazon ECS application, which is in its original task set, to the updated version in the replacement task set.
During an Amazon ECS deployment, CodeDeploy uses a load balancer that is configured with two target groups and one production traffic listener. The following diagram shows how the load balancer, production listener, target groups, and your Amazon ECS application are related before the deployment starts. This tutorial uses an Application Load Balancer. You can also use a Network Load Balancer.
![\[The Application Load Balancer or Network Load Balancer, one production listener, two target groups, one task set, and one Amazon ECS service.\]](http://docs.aws.amazon.com/codedeploy/latest/userguide/images/codedeploy-ecs-deployment-with-no-test-listener-step-1.png)
After a successful deployment, the production traffic listener serves traffic to your new replacement task set and the original task set is terminated. The following diagram shows how your resources are related after a successful deployment. For more information, see [What happens during an Amazon ECS deployment](deployment-steps-ecs.md#deployment-steps-what-happens).
![\[The Application Load Balancer or Network Load Balancer, one production listener, two target groups, and one replacement task set.\]](http://docs.aws.amazon.com/codedeploy/latest/userguide/images/codedeploy-ecs-deployment-with-no-test-listener-step-5.png)
For information about how to use the AWS CLI to deploy an application into Amazon ECS, see [ Tutorial: Creating a service using a blue/green deployment](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/create-blue-green.html). For information about how to use CodePipeline to detect and automatically deploy changes to an Amazon ECS service with CodeDeploy, see [Tutorial: Create a pipeline with an Amazon ECR source and ECS-to-CodeDeploy deployment](https://docs.aws.amazon.com/codepipeline/latest/userguide/tutorials-ecs-ecr-codedeploy.html).
After you complete this tutorial, you can use the CodeDeploy application and deployment group you created to add a deployment validation test in [Tutorial: Deploy an Amazon ECS service with a validation test](tutorial-ecs-deployment-with-hooks.md).
**Topics**
+ [Prerequisites](tutorial-ecs-prereqs.md)
+ [Step 1: Update your Amazon ECS application](tutorial-ecs-update-the-ecs-application.md)
+ [Step 2: Create the AppSpec file](tutorial-ecs-create-appspec-file.md)
+ [Step 3: Use the CodeDeploy console to deploy your application](tutorial-ecs-deployment-deploy.md)
+ [Step 4: Clean up](tutorial-ecs-clean-up.md)
# Prerequisites
To complete this tutorial, you must first:
+ Complete steps 2 and 3 in [Getting started with CodeDeploy](getting-started-codedeploy.md).
+ Create an Application Load Balancer configured with two target groups and one listener. For information about creating a load balancer using the console, see [Set up a load balancer, target groups, and listeners for CodeDeploy Amazon ECS deployments](deployment-groups-create-load-balancer-for-ecs.md). For information about creating a load balancer using the AWS CLI, see [Step 1: Create an Application Load Balancer](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/create-blue-green.html#create-blue-green-loadbalancer) in the *Amazon Elastic Container Service User Guide*. When you create your load balancer, make a note of the following for this tutorial:
+ The name of your load balancer.
+ The names of your target groups.
+ The port used by your load balancer's listener.
+ Create an Amazon ECS cluster and service. For more information, see steps 2, 3, and 4 in [ Tutorial: Creating a service using a blue/green deployment](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/create-blue-green.html) in the *Amazon Elastic Container Service User Guide*. Make a note of the following for this tutorial:
+ The name of your Amazon ECS cluster.
+ The ARN of the the task definition used by your Amazon ECS service.
+ The name of the the container used by your Amazon ECS service.
+ Create an Amazon S3 bucket for your AppSpec file.
# Step 1: Update your Amazon ECS application
In this section, you update your Amazon ECS application with a new revision of its task definition. The updated revision adds a new key and tag pair. In [Step 3: Use the CodeDeploy console to deploy your application](tutorial-ecs-deployment-deploy.md), you deploy the updated version of your Amazon ECS application.
**To update your task definition**
1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2).
1. In the navigation pane, choose **Task Definitions**.
1. Choose the task definition used by your Amazon ECS service.
1. Select the task definition revision, and then choose **Create new revision**, **Create new revision**.
1. For this tutorial, make a small update to the task definition by adding a tag. At the bottom of the page, under **Tags**, create a new tag by entering a new key and value pair.
1. Choose **Create**.
Your task definition's revision number is incremented by one.
1. Choose the **JSON** tab. Make a note of the following because you need this information in the next step.
+ The value for `taskDefinitionArn`. Its format is `arn:aws:ecs:aws-region:account-id:task-definition/task-definition-family:task-definition-revision`. This is the ARN of your updated task definition.
+ In the `containerDefinitions` element, the value for `name`. This is the name of your container.
+ In the `portMappings` element, the value for `containerPort`. This is the port for your container.
# Step 2: Create the AppSpec file
In this section, you create your AppSpec file and upload it to the Amazon S3 bucket you created in the [Prerequisites](tutorial-ecs-prereqs.md) section. The AppSpec file for an Amazon ECS deployment specifies your task definition, container name, and container port. For more information, see [AppSpec File example for an Amazon ECS deployment](reference-appspec-file-example.md#appspec-file-example-ecs) and [AppSpec 'resources' section for Amazon ECS deployments](reference-appspec-file-structure-resources.md#reference-appspec-file-structure-resources-ecs).
**To create your AppSpec file**
1. If you want to create your AppSpec file using YAML, create a file named `appspec.yml`. If you want to create your AppSpec file using JSON, create a file named `appspec.json`.
1. Choose the appropriate tab, depending on if you use YAML or JSON for your AppSpec file, and copy its content into the AppSpec file you just created. For the `TaskDefinition` property, use the task definition ARN you noted in [Step 1: Update your Amazon ECS application](tutorial-ecs-update-the-ecs-application.md) section.
------
#### [ JSON AppSpec ]
```
{
"version": 0.0,
"Resources": [
{
"TargetService": {
"Type": "AWS::ECS::Service",
"Properties": {
"TaskDefinition": "arn:aws:ecs:aws-region-id:aws-account-id:task-definition/ecs-demo-task-definition:revision-number",
"LoadBalancerInfo": {
"ContainerName": "your-container-name",
"ContainerPort": your-container-port
}
}
}
}
]
}
```
------
#### [ YAML AppSpec ]
```
version: 0.0
Resources:
- TargetService:
Type: AWS::ECS::Service
Properties:
TaskDefinition: "arn:aws:ecs:aws-region-id:aws-account-id:task-definition/ecs-demo-task-definition:revision-number"
LoadBalancerInfo:
ContainerName: "your-container-name"
ContainerPort: your-container-port
```
------
**Note**
Your replacement task set inherits the subnet, security group, platform version, and assigned public IP values from your original task set. You can override these values for your replacement task set by setting their optional properties in your 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) and [AppSpec File example for an Amazon ECS deployment](reference-appspec-file-example.md#appspec-file-example-ecs).
1. Upload your AppSpec file to the S3 bucket you created as a prerequisite for this tutorial.
# Step 3: Use the CodeDeploy console to deploy your application
In this section, you create a CodeDeploy application and deployment group to deploy your updated application into Amazon ECS. During deployment, CodeDeploy shifts the production traffic for your application to its new version in a new, replacement task set. To complete this step, you need the following items:
+ Your Amazon ECS cluster name.
+ Your Amazon ECS service name.
+ Your Application Load Balancer name.
+ Your production listener port.
+ Your target group names.
+ The name of the S3 bucket you created.
**To create a CodeDeploy application**
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/).
1. Choose **Create application**.
1. In **Application name**, enter **ecs-demo-codedeploy-app**.
1. In **Compute platform**, choose **Amazon ECS**.
1. Choose **Create application**.
**To create a CodeDeploy deployment group**
1. On the **Deployment groups** tab of your application page, choose **Create deployment group**.
1. In **Deployment group name**, enter **ecs-demo-dg**.
1. In **Service role**, choose a service role that grants CodeDeploy access to Amazon ECS. For more information, see [Identity and access management for AWS CodeDeploy](security-iam.md).
1. In **Environment configuration**, choose your Amazon ECS cluster name and service name.
1. From **Load balancers**, choose the name of the load balancer that serves traffic to your Amazon ECS service.
1. From **Production listener port**, choose the port and protocol for the listener that serves production traffic to your Amazon ECS service (for example, **HTTP: 80**). This tutorial does not include an optional test listener, so do not choose a port from **Test listener port**.
1. From **Target group 1 name** and **Target group 2 name**, choose two different target groups to route traffic during your deployment. Make sure that these are the target groups you created for your load balancer. It does not matter which is used for target group 1 and which is used for target group 2.
1. Choose **Reroute traffic immediately**.
1. For **Original revision termination**, choose 0 days, 0 hours, and 5 minutes. This lets you see your deployment complete faster than if you use the default (1 hour).
![\[The environment configuration section of the CodeDeploy console.\]](http://docs.aws.amazon.com/codedeploy/latest/userguide/images/ecs-demo-create-acd-dg.png)
1. Choose **Create deployment group**.
**To deploy your Amazon ECS application**
1. From your deployment group console page, choose **Create deployment**.
1. For **Deployment group**, choose **ecs-demo-dg**.
1. For **Revision type**, choose **My application is stored in Amazon S3**. In **Revision location**, enter the name of your S3 bucket.
1. For **Revision file type**, choose **.json** or **.yaml**, as appropriate.
1. (Optional) In **Deployment description**, enter a description for your deployment.
1. Choose **Create deployment**.
1. In **Deployment status**, you can monitor your deployment. After 100% of production traffic is routed to the replacement task set and before the five-minute wait time expires, you can choose **Terminate original task set** to immediately terminate the original task set. If you do not choose **Terminate original task set**, the original task set terminates after the five-minute wait time you specified expires.
![\[The deployment status section of the CodeDeploy console.\]](http://docs.aws.amazon.com/codedeploy/latest/userguide/images/ecs-tutorial-deployment-status-without-test-listener.png)
# Step 4: Clean up
The next tutorial, [Tutorial: Deploy an Amazon ECS service with a validation test](tutorial-ecs-deployment-with-hooks.md), builds on this tutorial and uses the CodeDeploy application and deployment group you created. If you want to follow the steps in that tutorial, skip this step and do not delete the resources you created.
**Note**
Your AWS account does not incur charges for the CodeDeploy resources you created.
The resource names in these steps are the names suggested in this tutorial (for example, **ecs-demo-codedeploy-app** for the name of your CodeDeploy application). If you used different names, then be sure to use those during your cleanup.
1. Use the [delete-deployment-group](https://docs.aws.amazon.com/cli/latest/reference/deploy/delete-deployment-group.html) command to delete the CodeDeploy deployment group.
```
aws deploy delete-deployment-group --application-name ecs-demo-codedeploy-app --deployment-group-name ecs-demo-dg --region aws-region-id
```
1. Use the [delete-application](https://docs.aws.amazon.com/cli/latest/reference/deploy/delete-application.html) command to delete the CodeDeploy application.
```
aws deploy delete-application --application-name ecs-demo-codedeploy-app --region aws-region-id
```