# CodeDeploy blue/green deployments for Amazon ECS
We recommend that you use the Amazon ECS blue/green deployment. For more information, see [Creating an Amazon ECS blue/green deployment](deploy-blue-green-service.md).
The *blue/green* deployment type uses the blue/green deployment model controlled by CodeDeploy. Use this deployment type to verify a new deployment of a service before sending production traffic to it. For more information, see [What Is CodeDeploy](https://docs.aws.amazon.com/codedeploy/latest/userguide/welcome.html) in the *AWS CodeDeploy User Guide*.Validate the state of an Amazon ECS service before deployment
There are three ways traffic can shift during a blue/green deployment:
+ **Canary** — Traffic is shifted in two increments. You can choose from predefined canary options that specify the percentage of traffic shifted to your updated task set in the first increment and the interval, in minutes, before the remaining traffic is shifted in the second increment.
+ **Linear** — Traffic is shifted in equal increments with an equal number of minutes between each increment. You can choose from predefined linear options that specify the percentage of traffic shifted in each increment and the number of minutes between each increment.
+ **All-at-once** — All traffic is shifted from the original task set to the updated task set all at once.
The following are components of CodeDeploy that Amazon ECS uses when a service uses the blue/green deployment type:
**CodeDeploy application**
A collection of CodeDeploy resources. This consists of one or more deployment groups.
**CodeDeploy deployment group**
The deployment settings. This consists of the following:
+ Amazon ECS cluster and service
+ Load balancer target group and listener information
+ Deployment roll back strategy
+ Traffic rerouting settings
+ Original revision termination settings
+ Deployment configuration
+ CloudWatch alarms configuration that can be set up to stop deployments
+ SNS or CloudWatch Events settings for notifications
For more information, see [Working with Deployment Groups](https://docs.aws.amazon.com/codedeploy/latest/userguide/deployment-groups.html) in the *AWS CodeDeploy User Guide*.
**CodeDeploy deployment configuration**
Specifies how CodeDeploy routes production traffic to your replacement task set during a deployment. The following pre-defined linear and canary deployment configuration are available. You can also create custom defined linear and canary deployments as well. For more information, see [Working with Deployment Configurations](https://docs.aws.amazon.com/codedeploy/latest/userguide/deployment-configurations.html) in the *AWS CodeDeploy User Guide*.
+ **CodeDeployDefault.ECSAllAtOnce**: Shifts all traffic to the updated Amazon ECS container at once
+ **CodeDeployDefault.ECSLinear10PercentEvery1Minutes**: Shifts 10 percent of traffic every minute until all traffic is shifted.
+ **CodeDeployDefault.ECSLinear10PercentEvery3Minutes**: Shifts 10 percent of traffic every 3 minutes until all traffic is shifted.
+ **CodeDeployDefault.ECSCanary10Percent5Minutes**: Shifts 10 percent of traffic in the first increment. The remaining 90 percent is deployed five minutes later.
+ **CodeDeployDefault.ECSCanary10Percent15Minutes**: Shifts 10 percent of traffic in the first increment. The remaining 90 percent is deployed 15 minutes later.
**Revision**
A revision is the CodeDeploy application specification file (AppSpec file). In the AppSpec file, you specify the full ARN of the task definition and the container and port of your replacement task set where traffic is to be routed when a new deployment is created. The container name must be one of the container names referenced in your task definition. If the network configuration or platform version has been updated in the service definition, you must also specify those details in the AppSpec file. You can also specify the Lambda functions to run during the deployment lifecycle events. The Lambda functions allow you to run tests and return metrics during the deployment. For more information, see [AppSpec File Reference](https://docs.aws.amazon.com/codedeploy/latest/userguide/reference-appspec-file.html) in the *AWS CodeDeploy User Guide*.
## Considerations
Consider the following when using the blue/green deployment type:
+ When an Amazon ECS service using the blue/green deployment type is initially created, an Amazon ECS task set is created.
+ You must configure the service to use either an Application Load Balancer or Network Load Balancer. The following are the load balancer requirements:
+ You must add a production listener to the load balancer, which is used to route production traffic.
+ An optional test listener can be added to the load balancer, which is used to route test traffic. If you specify a test listener, CodeDeploy routes your test traffic to the replacement task set during a deployment.
+ Both the production and test listeners must belong to the same load balancer.
+ You must define a target group for the load balancer. The target group routes traffic to the original task set in a service through the production listener.
+ When a Network Load Balancer is used, only the `CodeDeployDefault.ECSAllAtOnce` deployment configuration is supported.
+ For services configured to use service auto scaling and the blue/green deployment type, auto scaling is not blocked during a deployment but the deployment may fail under some circumstances. The following describes this behavior in more detail.
+ If a service is scaling and a deployment starts, the green task set is created and CodeDeploy will wait up to an hour for the green task set to reach steady state and won't shift any traffic until it does.
+ If a service is in the process of a blue/green deployment and a scaling event occurs, traffic will continue to shift for 5 minutes. If the service doesn't reach steady state within 5 minutes, CodeDeploy will stop the deployment and mark it as failed.
+ Tasks using Fargate or the `CODE_DEPLOY` deployment controller types don't support the `DAEMON` scheduling strategy.
+ When you initially create a CodeDeploy application and deployment group, you must specify the following:
+ You must define two target groups for the load balancer. One target group should be the initial target group defined for the load balancer when the Amazon ECS service was created. The second target group's only requirement is that it can't be associated with a different load balancer than the one the service uses.
+ When you create a CodeDeploy deployment for an Amazon ECS service, CodeDeploy creates a *replacement task set* (or *green task set*) in the deployment. If you added a test listener to the load balancer, CodeDeploy routes your test traffic to the replacement task set. This is when you can run any validation tests. Then CodeDeploy reroutes the production traffic from the original task set to the replacement task set according to the traffic rerouting settings for the deployment group.
## Required IAM permissions
Blue/green deployments are made possible by a combination of the Amazon ECS and CodeDeploy APIs. Users must have the appropriate permissions for these services before they can use Amazon ECS blue/green deployments in the AWS Management Console or with the AWS CLI or SDKs.
In addition to the standard IAM permissions for creating and updating services, Amazon ECS requires the following permissions. These permissions have been added to the `AmazonECS_FullAccess` IAM policy. For more information, see [AmazonECS\$1FullAccess](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonECS_FullAccess).
+ `codedeploy:CreateApplication`
+ `codedeploy:CreateDeployment`
+ `codedeploy:CreateDeploymentGroup`
+ `codedeploy:GetApplication`
+ `codedeploy:GetDeployment`
+ `codedeploy:GetDeploymentGroup`
+ `codedeploy:ListApplications`
+ `codedeploy:ListDeploymentGroups`
+ `codedeploy:ListDeployments`
+ `codedeploy:StopDeployment`
+ `codedeploy:GetDeploymentTarget`
+ `codedeploy:ListDeploymentTargets`
+ `codedeploy:GetDeploymentConfig`
+ `codedeploy:GetApplicationRevision`
+ `codedeploy:RegisterApplicationRevision`
+ `codedeploy:BatchGetApplicationRevisions`
+ `codedeploy:BatchGetDeploymentGroups`
+ `codedeploy:BatchGetDeployments`
+ `codedeploy:BatchGetApplications`
+ `codedeploy:ListApplicationRevisions`
+ `codedeploy:ListDeploymentConfigs`
+ `codedeploy:ContinueDeployment`
+ `sns:ListTopics`
+ `cloudwatch:DescribeAlarms`
+ `lambda:ListFunctions`
**Note**
In addition to the standard Amazon ECS permissions required to run tasks and services, users also require `iam:PassRole` permissions to use IAM roles for tasks.
CodeDeploy needs permissions to call Amazon ECS APIs, modify your Elastic Load Balancing, invoke Lambda functions, and describe CloudWatch alarms, as well as permissions to modify your service's desired count on your behalf. Before creating an Amazon ECS service that uses the blue/green deployment type, you must create an IAM role (`ecsCodeDeployRole`). For more information, see [Amazon ECS CodeDeploy IAM Role](codedeploy_IAM_role.md).
# Migrate CodeDeploy blue/green deployments to Amazon ECS blue/green deployments
CodeDeploy blue/green and Amazon ECS blue/green deployments provide similar functionality, but they differ in how you configure and manage them.
## CodeDeploy blue/green deployment overview
When creating an Amazon ECS service using CodeDeploy, you:
1. Create a load balancer with a production listener and (optionally) a test listener. Each listener is configured with a single (default) rule that routes all traffic to a single target group (the primary target group).
1. Create an Amazon ECS service, configured to use the listener and target group, with `deploymentController` type set to `CODE_DEPLOY`. Service creation results in the creation of a (blue) task set registered with the specified target group.
1. Create a CodeDeploy deployment group (as part of a CodeDeploy application), and configure it with details of the Amazon ECS cluster, service name, load balancer listeners, two target groups (the primary target group used in the production listener rule, and a secondary target group to be used for replacement tasks), a service role (to grant CodeDeploy permissions to manipulate Amazon ECS and Elastic Load Balancing resources) and various parameters that control the deployment behavior.
With CodeDeploy, new versions of a service are deployed using `CreateDeployment()`, specifying the CodeDeploy application name, deployment group name, and an AppSpec file which provides details of the new revision and optional lifecycle hooks. The CodeDeploy deployment creates a replacement (green) task set and registers its tasks with the secondary target group. When this becomes healthy, it is available for testing (optional) and for production. In both cases, re-routing is achieved by changing the respective listener rule to point at the secondary target group associated with the green task set. Rollback is achieved by changing the production listener rule back to the primary target group.
## Amazon ECS blue/green deployment overview
With Amazon ECS blue/green deployments, The deployment configuration is part of the Amazon ECS service itself:
1. You must pre-configure the load balancer production listener with a rule that includes two target groups with weights of 1 and 0.
1. You need to specify the following resources, or update the service resources:
+ The ARN of this listener rule
+ The two target groups
+ An IAM role to grant Amazon ECS permission to call the Elastic Load Balancing APIs
+ An optional IAM role to run Lambda functions
+ Set `deploymentController` type to `ECS` and `deploymentConfiguration.strategy` to `BLUE_GREEN`. This results in the creation of a (blue) service deployment whose tasks are registered with the primary target group.
With Amazon ECS blue/green, a new service revision is created by calling Amazon ECS `UpdateService()`, passing details of the new revision. The service deployment creates new (green) service revision tasks and registers them with the secondary target group. Amazon ECS handles re-routing and rollback operations by switching the weights on the listener rule.
## Key implementation differences
While both approaches result in the creation of an initial set of tasks, the underlying implementation differs:
+ CodeDeploy uses a task set, whereas Amazon ECS uses a service revision. Amazon ECS task sets are an older construct which have been superseded by Amazon ECS service revisions and deployments. The latter offer greater visibility into the deployment process, as well as the service deployment and service revision history.
+ With CodeDeploy, lifecycle hooks are specified as part of the AppSpec file that is supplied to `CreateDeployment()`. This means that the hooks can be changed from one deployment to the next. With Amazon ECS blue/green, the hooks are specified as part of the service configuration, and any updates would require an `UpdateService()` call.
+ Both CodeDeploy and Amazon ECS blue/green use Lambda for hook implementation, but the expected inputs and outputs differ.
With CodeDeploy, the function must call `PutLifecycleEventHookExecutionStatus()` to return the hook status, which can either be `SUCCEEDED` or `FAILED`. With Amazon ECS, the Lambda response is used to indicate the hook status.
+ CodeDeploy invokes each hook as a one-off call, and expects a final execution status to be returned within one hour. Amazon ECS hooks are more flexible in that they can return an `IN_PROGRESS` indicator, which signals that the hook must be re-invoked repeatedly until it results in `SUCCEEDED` or `FAILED`. For more information, see [Lifecycle hooks for Amazon ECS service deployments](deployment-lifecycle-hooks.md).
## Migration approaches
There are three main approaches to migrating from CodeDeploy blue/green to Amazon ECS blue/green deployments. Each approach has different characteristics in terms of complexity, risk, rollback capability, and potential downtime.
### Reuse the same Elastic Load Balancing resources used for CodeDeploy
You update the existing Amazon ECS service to use the Amazon ECS deployment controller with blue/green deployment strategy instead of CodeDeploy deployment controller. Consider the following when using this approach:
+ The migration procedure is simpler because you are updating the existing Amazon ECS service deployment controller and deployment strategy.
+ There is no downtime when correctly configured and migrated.
+ A rollback requires that you revert the service revision.
+ The risk is high because there is no parallel blue/green configuration.
You use the same load balancer listener and target groups that are used for CodeDeploy. If you are using CloudFormation, see [Migrating an CloudFormation CodeDeploy blue/green deployment template to an Amazon ECS blue/green CloudFormation template](migrate-codedeploy-to-ecs-bluegreen-cloudformation-template.md).
1. Modify the default rule of the production/test listeners to include the alternate target group and set the weight of the primary target group to 1 and the alternate target group to 0.
For CodeDeploy, the listeners of the load balancer attached to the service are configured with a single (default) rule that routes all traffic to a single target group. For Amazon ECS blue/green, the load balancer listeners must be pre-configured with a rule that includes the two target groups with weights. The primary target group must be weighted to 1 and the alternate target group must be weighted to 0.
1. Update the existing Amazon ECS service by calling the `UpdateService` API and setting the parameter `deploymentController` to `ECS`, and the parameter `deploymentStrategy` to `BLUE_GREEN`. Specify the ARNs of the target group, the alternative target group, the production listener, and an optional test listener.
1. Verify that the service works as expected.
1. Delete the CodeDeploy setup for this Amazon ECS service as you are now using Amazon ECS blue/green.
### New service with existing load balancer
This approach uses the blue/green strategy for the migration.
Consider the following when using this approach:
+ There is minimal disruption. It occurs only during the Elastic Load Balancing port swap.
+ A rollback requires that you revert the Elastic Load Balancing port swap.
+ The risk is low because there are parallel configurations. Therefore you can test before the traffic shift.
1. Leave the listeners, the target groups, and the Amazon ECS service for the CodeDeploy setup intact so you can easily rollback to this setup if needed.
1. Create new target groups and new listeners (with different ports from the original listeners) under the existing load balancer. Then, create a new Amazon ECS service that matches the existing Amazon ECS service except that you use `ECS` as deployment controller, `BLUE_GREEN` as a deployment strategy, and pass the ARNs for the new target groups and the new listeners rules.
1. Verify the new setup by manually sending HTTP traffic to the service. If everything goes well, swap the ports of the original listeners and the new listeners to route the traffic to the new setup.
1. Verify the new setup, and if everything continues to work as expected, delete the CodeDeploy setup.
### New service with a new load balancer
Like the previous approach, this approach uses the blue/green strategy for the migration. The key difference is that the switch from the CodeDeploy setup to the Amazon ECS blue/green setup happens at a reverse proxy layer above the load balancer. Sample implementations for the reverse proxy layer are Route 53 and CloudFront.
This approach is suitable for customers who already have this reverse proxy layer, and if all the communication with the service is happening through it (for example, no direct communication at the load balancer level).
Consider the following when using this approach:
+ This requires a reverse proxy layer.
+ The migration procedure is more complex because you need to update the existing Amazon ECS service deployment controller and deployment strategy.
+ There is minimal disruption. It occurs only during the Elastic Load Balancing port swap.
+ A rollback requires that you reverse the proxy configuration changes.
+ The risk is low because there are parallel configurations. Therefore you can test before the traffic shift.
1. Do not modify the existing CodeDeploy setup intact (load balancer, listeners, target groups, Amazon ECS service, and CodeDeploy deployment group).
1. Create a new load balancer, target groups, and listeners configured for Amazon ECS blue/green deployments.
Configure the appropriate resources.
+ Application Load Balancer - For more information, see [Application Load Balancer resources for blue/green, linear, and canary deployments](alb-resources-for-blue-green.md).
+ Network Load Balancer - For more information, see [Network Load Balancer resources for Amazon ECS blue/green, linear and canary deployments](nlb-resources-for-blue-green.md).
1. Create a new service with `ECS` as deployment controller and `BLUE_GREEN` as deployment strategy, pointing to the new load balancer resources.
1. Verify the new setup by testing it through the new load balancer.
1. Update the reverse proxy configuration to route traffic to the new load balancer.
1. Observe the new service revision, and if everything continues to work as expected, delete the CodeDeploy setup.
## Next steps
After migrating to Amazon ECS blue/green deployments:
+ Update your deployment scripts and CI/CD pipelines to use the Amazon ECS `UpdateService` API instead of the CodeDeploy `CreateDeployment` API.
+ Update your monitoring and alerting to track Amazon ECS service deployments instead of CodeDeploy deployments.
+ Consider implementing automated testing of your new deployment process to ensure it works as expected.
# Migrating from a CodeDeploy blue/green to an Amazon ECS blue/green service deployment
By using Amazon ECS blue/green deployments, you can make and test service changes before implementing them in a production environment.
You must create new lifecycle hooks for your Amazon ECS blue/green deployment.
## Prerequisites
Perform the following operations before you start a blue/green deployment.
1. Replace the Amazon ECS CodeDeploy IAM role with the following permissions.
+ For information about Elastic Load Balancing permissions, see [Amazon ECS infrastructure IAM role for load balancers](AmazonECSInfrastructureRolePolicyForLoadBalancers.md).
+ For information about Lambda permissions, see [Permissions required for Lambda functions in Amazon ECS blue/green deployments](blue-green-permissions.md).
1. Turn off CodeDeploy automation. For more information, see [Working with deployment groups in CodeDeploy](https://docs.aws.amazon.com/codedeploy/latest/userguide/deployment-groups.html) in the *CodeDeploy User Guide*.
1. Make sure that you have the following information from your CodeDeploy blue/green deployment. You can reuse this information for the Amazon ECS blue/green deployment:
+ The production target group
+ The production listener
+ The production rule
+ The test target group
This is the target group for the green service revision,
1. Ensure that your Application Load Balancer target groups are properly associated with listener rules:
+ If you are not using test listeners, both target groups (production and test) must be associated with production listener rules.
+ If you are using test listeners, one target group must be linked to production listener rules and the other target group must be linked to test listener rules.
If this requirement is not met, the service deployment will fail with the following error: `Service deployment rolled back because of invalid networking configuration. Both targetGroup and alternateTargetGroup must be associated with the productionListenerRule or testListenerRule.`
1. Verify that there are no ongoing service deployments for the service. For more information, see [View service history using Amazon ECS service deployments](service-deployment.md).
1. Amazon ECS blue/green deployments require your service to use one of the following features: Configure the appropriate resources.
+ Application Load Balancer - For more information, see [Application Load Balancer resources for blue/green, linear, and canary deployments](alb-resources-for-blue-green.md).
+ Network Load Balancer - For more information, see [Network Load Balancer resources for Amazon ECS blue/green, linear and canary deployments](nlb-resources-for-blue-green.md).
+ Service Connect - For more information, see [Service Connect resources for Amazon ECS blue/green, linear, and canary deployments](service-connect-blue-green.md).
1. Decide if you want to run Lambda functions for the lifecycle stages for the stages in the Amazon ECS blue/green deployment.
+ Pre scale up
+ After scale up
+ Test traffic shift
+ After test traffic shift
+ Production traffic shift
+ After production traffic shift
Create Lambda functions for each lifecycle stage. For more information, see [Create a Lambda function with the console](https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html#getting-started-create-function) in the *AWS Lambda Developer Guide*.
For more information about updating a service's deployment controller, see [Update Amazon ECS service parameters](update-service-parameters.md).
## Procedure
1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2).
1. On the **Clusters** page, choose the cluster.
The cluster details page displays.
1. From the **Services** tab, choose the service.
The service details page displays.
1. In the banner, choose **Update deployment controller type**.
The **Migrate deployment controller type** page displays.
1. Expand **New**, and then specify the following parameters.
1. For **Deployment controller type**, choose **ECS**.
1. For **Deployment strategy**, choose **Blue/green**.
1. For **Bake time**, enter the time that both the blue and green service revisions run.
1. To run Lambda functions for a lifecycle stage, under **Deployment lifecyce hooks** do the following for each unique Lambda function:
1. Choose **Add**.
Repeat for every unique function you want to run.
1. For **Lambda function**, enter the function name.
1. For **Role**, choose the role that you created in the prerequisites with the blue/green permissions.
For more information, see [Permissions required for Lambda functions in Amazon ECS blue/green deployments](blue-green-permissions.md).
1. For **Lifecycle stages**, select the stages the Lambda function runs.
1. (Optional) For **Hook details**, enter a key-value pair that provides information about the hook.
1. Expand **Load Balancing**, and the configure the following:
1. For **Role**, choose the role that you created in the prerequisites with the blue/green permissions.
For more information, see [Permissions required for Lambda functions in Amazon ECS blue/green deployments](blue-green-permissions.md).
1. For **Listener**, choose the production listener from your CodeDeploy blue/green deployment.
1. For **Production rule**, choose the production rule from your CodeDeploy blue/green deployment.
1. For **Test rule**, choose the test rule from your CodeDeploy blue/green deployment.
1. For **Target group**, choose the production target group from your CodeDeploy blue/green deployment.
1. For **Alternate target group**, choose the test target group from your CodeDeploy blue/green deployment.
1. Choose **Update**.
## Next steps
+ Update the service to start the deployment. For more information, see [Updating an Amazon ECS service](update-service-console-v2.md).
+ Monitor the deployment process to ensure it follows the blue/green pattern:
+ The green service revision is created and scaled up
+ Test traffic is routed to the green revision (if configured)
+ Production traffic is shifted to the green revision
+ After the bake time, the blue revision is terminated
# Migrating an CloudFormation CodeDeploy blue/green deployment template to an Amazon ECS blue/green CloudFormation template
Migrate a CloudFormation template that uses CodeDeploy blue/green deployments for Amazon ECS services to one that uses the native Amazon ECS blue/green deployment strategy. The migration follows the "Reuse the same Elastic Load Balancing resources used for CodeDeploy" approach. For more information, see [Migrate CodeDeploy blue/green deployments to Amazon ECS blue/green deployments](migrate-codedeploy-to-ecs-bluegreen.md).
## Source template
This template uses the `AWS::CodeDeployBlueGreen` transform and `AWS::CodeDeploy::BlueGreen` hook to implement blue/green deployments for an Amazon ECS service.
### Source
This is the complete CloudFormation template using CodeDeploy blue/green deployment. For more information, see [Blue/green deployment template example](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/blue-green-template-example.html#blue-green-template-example.json) in the* AWS CloudFormation User Guide*:
```
{
"AWSTemplateFormatVersion": "2010-09-09",
"Parameters": {
"Vpc": {
"Type": "AWS::EC2::VPC::Id"
},
"Subnet1": {
"Type": "AWS::EC2::Subnet::Id"
},
"Subnet2": {
"Type": "AWS::EC2::Subnet::Id"
}
},
"Transform": [
"AWS::CodeDeployBlueGreen"
],
"Hooks": {
"CodeDeployBlueGreenHook": {
"Type": "AWS::CodeDeploy::BlueGreen",
"Properties": {
"TrafficRoutingConfig": {
"Type": "TimeBasedCanary",
"TimeBasedCanary": {
"StepPercentage": 15,
"BakeTimeMins": 5
}
},
"Applications": [
{
"Target": {
"Type": "AWS::ECS::Service",
"LogicalID": "ECSDemoService"
},
"ECSAttributes": {
"TaskDefinitions": [
"BlueTaskDefinition",
"GreenTaskDefinition"
],
"TaskSets": [
"BlueTaskSet",
"GreenTaskSet"
],
"TrafficRouting": {
"ProdTrafficRoute": {
"Type": "AWS::ElasticLoadBalancingV2::Listener",
"LogicalID": "ALBListenerProdTraffic"
},
"TargetGroups": [
"ALBTargetGroupBlue",
"ALBTargetGroupGreen"
]
}
}
}
]
}
}
},
"Resources": {
"ExampleSecurityGroup": {
"Type": "AWS::EC2::SecurityGroup",
"Properties": {
"GroupDescription": "Security group for ec2 access",
"VpcId": {"Ref": "Vpc"},
"SecurityGroupIngress": [
{
"IpProtocol": "tcp",
"FromPort": 80,
"ToPort": 80,
"CidrIp": "0.0.0.0/0"
},
{
"IpProtocol": "tcp",
"FromPort": 8080,
"ToPort": 8080,
"CidrIp": "0.0.0.0/0"
},
{
"IpProtocol": "tcp",
"FromPort": 22,
"ToPort": 22,
"CidrIp": "0.0.0.0/0"
}
]
}
},
"ALBTargetGroupBlue": {
"Type": "AWS::ElasticLoadBalancingV2::TargetGroup",
"Properties": {
"HealthCheckIntervalSeconds": 5,
"HealthCheckPath": "/",
"HealthCheckPort": "80",
"HealthCheckProtocol": "HTTP",
"HealthCheckTimeoutSeconds": 2,
"HealthyThresholdCount": 2,
"Matcher": {
"HttpCode": "200"
},
"Port": 80,
"Protocol": "HTTP",
"Tags": [
{
"Key": "Group",
"Value": "Example"
}
],
"TargetType": "ip",
"UnhealthyThresholdCount": 4,
"VpcId": {"Ref": "Vpc"}
}
},
"ALBTargetGroupGreen": {
"Type": "AWS::ElasticLoadBalancingV2::TargetGroup",
"Properties": {
"HealthCheckIntervalSeconds": 5,
"HealthCheckPath": "/",
"HealthCheckPort": "80",
"HealthCheckProtocol": "HTTP",
"HealthCheckTimeoutSeconds": 2,
"HealthyThresholdCount": 2,
"Matcher": {
"HttpCode": "200"
},
"Port": 80,
"Protocol": "HTTP",
"Tags": [
{
"Key": "Group",
"Value": "Example"
}
],
"TargetType": "ip",
"UnhealthyThresholdCount": 4,
"VpcId": {"Ref": "Vpc"}
}
},
"ExampleALB": {
"Type": "AWS::ElasticLoadBalancingV2::LoadBalancer",
"Properties": {
"Scheme": "internet-facing",
"SecurityGroups": [
{"Ref": "ExampleSecurityGroup"}
],
"Subnets": [
{"Ref": "Subnet1"},
{"Ref": "Subnet2"}
],
"Tags": [
{
"Key": "Group",
"Value": "Example"
}
],
"Type": "application",
"IpAddressType": "ipv4"
}
},
"ALBListenerProdTraffic": {
"Type": "AWS::ElasticLoadBalancingV2::Listener",
"Properties": {
"DefaultActions": [
{
"Type": "forward",
"ForwardConfig": {
"TargetGroups": [
{
"TargetGroupArn": {"Ref": "ALBTargetGroupBlue"},
"Weight": 1
}
]
}
}
],
"LoadBalancerArn": {"Ref": "ExampleALB"},
"Port": 80,
"Protocol": "HTTP"
}
},
"ALBListenerProdRule": {
"Type": "AWS::ElasticLoadBalancingV2::ListenerRule",
"Properties": {
"Actions": [
{
"Type": "forward",
"ForwardConfig": {
"TargetGroups": [
{
"TargetGroupArn": {"Ref": "ALBTargetGroupBlue"},
"Weight": 1
}
]
}
}
],
"Conditions": [
{
"Field": "http-header",
"HttpHeaderConfig": {
"HttpHeaderName": "User-Agent",
"Values": [
"Mozilla"
]
}
}
],
"ListenerArn": {"Ref": "ALBListenerProdTraffic"},
"Priority": 1
}
},
"ECSTaskExecutionRole": {
"Type": "AWS::IAM::Role",
"Properties": {
"AssumeRolePolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "ecs-tasks.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
},
"ManagedPolicyArns": [
"arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy"
]
}
},
"BlueTaskDefinition": {
"Type": "AWS::ECS::TaskDefinition",
"Properties": {
"ExecutionRoleArn": {"Fn::GetAtt": ["ECSTaskExecutionRole", "Arn"]},
"ContainerDefinitions": [
{
"Name": "DemoApp",
"Image": "nginxdemos/hello:latest",
"Essential": true,
"PortMappings": [
{
"HostPort": 80,
"Protocol": "tcp",
"ContainerPort": 80
}
]
}
],
"RequiresCompatibilities": [
"FARGATE"
],
"NetworkMode": "awsvpc",
"Cpu": "256",
"Memory": "512",
"Family": "ecs-demo"
}
},
"ECSDemoCluster": {
"Type": "AWS::ECS::Cluster",
"Properties": {}
},
"ECSDemoService": {
"Type": "AWS::ECS::Service",
"Properties": {
"Cluster": {"Ref": "ECSDemoCluster"},
"DesiredCount": 1,
"DeploymentController": {
"Type": "EXTERNAL"
}
}
},
"BlueTaskSet": {
"Type": "AWS::ECS::TaskSet",
"Properties": {
"Cluster": {"Ref": "ECSDemoCluster"},
"LaunchType": "FARGATE",
"NetworkConfiguration": {
"AwsVpcConfiguration": {
"AssignPublicIp": "ENABLED",
"SecurityGroups": [
{"Ref": "ExampleSecurityGroup"}
],
"Subnets": [
{"Ref": "Subnet1"},
{"Ref": "Subnet2"}
]
}
},
"PlatformVersion": "1.4.0",
"Scale": {
"Unit": "PERCENT",
"Value": 100
},
"Service": {"Ref": "ECSDemoService"},
"TaskDefinition": {"Ref": "BlueTaskDefinition"},
"LoadBalancers": [
{
"ContainerName": "DemoApp",
"ContainerPort": 80,
"TargetGroupArn": {"Ref": "ALBTargetGroupBlue"}
}
]
}
},
"PrimaryTaskSet": {
"Type": "AWS::ECS::PrimaryTaskSet",
"Properties": {
"Cluster": {"Ref": "ECSDemoCluster"},
"Service": {"Ref": "ECSDemoService"},
"TaskSetId": {"Fn::GetAtt": ["BlueTaskSet", "Id"]}
}
}
}
}
```
## Migration steps
### Remove CodeDeploy-specific resources
You no longer need the following properties:
+ The `AWS::CodeDeployBlueGreen` transform
+ The `CodeDeployBlueGreenHook` hook
+ The `GreenTaskDefinition` and `GreenTaskSet` resources (these will be managed by Amazon ECS)
+ The `PrimaryTaskSet` resource (Amazon ECS will manage task sets internally)
### Reconfigure the load balancer listener
Modify the `ALBListenerProdTraffic` resource to use a forward action with two target groups:
```
{
"DefaultActions": [
{
"Type": "forward",
"ForwardConfig": {
"TargetGroups": [
{
"TargetGroupArn": {"Ref": "ALBTargetGroupBlue"},
"Weight": 1
},
{
"TargetGroupArn": {"Ref": "ALBTargetGroupGreen"},
"Weight": 0
}
]
}
}
]
}
```
### Update the deployment properties
Update and add the following:
+ Change the `DeploymentController` property from `EXTERNAL` to `ECS`.
+ Add the `Strategy` property and set it to BLUE\$1GREEN.
+ Add the `BakeTimeInMinutes` property.
```
{
"DeploymentConfiguration": {
"MaximumPercent": 200,
"MinimumHealthyPercent": 100,
"DeploymentCircuitBreaker": {
"Enable": true,
"Rollback": true
},
"BakeTimeInMinutes": 5,
"Strategy": "BLUE_GREEN"
}
}
```
+ Add the load balancer configuration to the service:
```
{
"LoadBalancers": [
{
"ContainerName": "DemoApp",
"ContainerPort": 80,
"TargetGroupArn": {"Ref": "ALBTargetGroupBlue"},
"AdvancedConfiguration": {
"AlternateTargetGroupArn": {"Ref": "ALBTargetGroupGreen"},
"ProductionListenerRule": {"Ref": "ALBListenerProdRule"},
"RoleArn": {"Fn::GetAtt": ["ECSInfrastructureRoleForLoadBalancers", "Arn"]}
}
}
]
}
```
+ Add the task definition reference to the service:
```
{
"TaskDefinition": {"Ref": "BlueTaskDefinition"}
}
```
### Create the AmazonECSInfrastructureRolePolicyForLoadBalancers role
Add a new IAM role that allows Amazon ECS to manage load balancer resources. For more information, see [Amazon ECS infrastructure IAM role for load balancers](AmazonECSInfrastructureRolePolicyForLoadBalancers.md)
## Testing recommendations
1. Deploy the migrated template to a non-production environment.
1. Verify that the service deploys correctly with the initial configuration.
1. Test a deployment by updating the task definition and observing the blue/green deployment process.
1. Verify that traffic shifts correctly between the blue and green deployments.
1. Test rollback functionality by forcing a deployment failure.
## Template after migration
### Final template
This is the complete CloudFormation template using an Amazon ECS blue/green deployment:
```
{
"AWSTemplateFormatVersion": "2010-09-09",
"Parameters": {
"Vpc": {
"Type": "AWS::EC2::VPC::Id"
},
"Subnet1": {
"Type": "AWS::EC2::Subnet::Id"
},
"Subnet2": {
"Type": "AWS::EC2::Subnet::Id"
}
},
"Resources": {
"ExampleSecurityGroup": {
"Type": "AWS::EC2::SecurityGroup",
"Properties": {
"GroupDescription": "Security group for ec2 access",
"VpcId": {"Ref": "Vpc"},
"SecurityGroupIngress": [
{
"IpProtocol": "tcp",
"FromPort": 80,
"ToPort": 80,
"CidrIp": "0.0.0.0/0"
},
{
"IpProtocol": "tcp",
"FromPort": 8080,
"ToPort": 8080,
"CidrIp": "0.0.0.0/0"
},
{
"IpProtocol": "tcp",
"FromPort": 22,
"ToPort": 22,
"CidrIp": "0.0.0.0/0"
}
]
}
},
"ALBTargetGroupBlue": {
"Type": "AWS::ElasticLoadBalancingV2::TargetGroup",
"Properties": {
"HealthCheckIntervalSeconds": 5,
"HealthCheckPath": "/",
"HealthCheckPort": "80",
"HealthCheckProtocol": "HTTP",
"HealthCheckTimeoutSeconds": 2,
"HealthyThresholdCount": 2,
"Matcher": {
"HttpCode": "200"
},
"Port": 80,
"Protocol": "HTTP",
"Tags": [
{
"Key": "Group",
"Value": "Example"
}
],
"TargetType": "ip",
"UnhealthyThresholdCount": 4,
"VpcId": {"Ref": "Vpc"}
}
},
"ALBTargetGroupGreen": {
"Type": "AWS::ElasticLoadBalancingV2::TargetGroup",
"Properties": {
"HealthCheckIntervalSeconds": 5,
"HealthCheckPath": "/",
"HealthCheckPort": "80",
"HealthCheckProtocol": "HTTP",
"HealthCheckTimeoutSeconds": 2,
"HealthyThresholdCount": 2,
"Matcher": {
"HttpCode": "200"
},
"Port": 80,
"Protocol": "HTTP",
"Tags": [
{
"Key": "Group",
"Value": "Example"
}
],
"TargetType": "ip",
"UnhealthyThresholdCount": 4,
"VpcId": {"Ref": "Vpc"}
}
},
"ExampleALB": {
"Type": "AWS::ElasticLoadBalancingV2::LoadBalancer",
"Properties": {
"Scheme": "internet-facing",
"SecurityGroups": [
{"Ref": "ExampleSecurityGroup"}
],
"Subnets": [
{"Ref": "Subnet1"},
{"Ref": "Subnet2"}
],
"Tags": [
{
"Key": "Group",
"Value": "Example"
}
],
"Type": "application",
"IpAddressType": "ipv4"
}
},
"ALBListenerProdTraffic": {
"Type": "AWS::ElasticLoadBalancingV2::Listener",
"Properties": {
"DefaultActions": [
{
"Type": "forward",
"ForwardConfig": {
"TargetGroups": [
{
"TargetGroupArn": {"Ref": "ALBTargetGroupBlue"},
"Weight": 1
},
{
"TargetGroupArn": {"Ref": "ALBTargetGroupGreen"},
"Weight": 0
}
]
}
}
],
"LoadBalancerArn": {"Ref": "ExampleALB"},
"Port": 80,
"Protocol": "HTTP"
}
},
"ALBListenerProdRule": {
"Type": "AWS::ElasticLoadBalancingV2::ListenerRule",
"Properties": {
"Actions": [
{
"Type": "forward",
"ForwardConfig": {
"TargetGroups": [
{
"TargetGroupArn": {"Ref": "ALBTargetGroupBlue"},
"Weight": 1
},
{
"TargetGroupArn": {"Ref": "ALBTargetGroupGreen"},
"Weight": 0
}
]
}
}
],
"Conditions": [
{
"Field": "http-header",
"HttpHeaderConfig": {
"HttpHeaderName": "User-Agent",
"Values": [
"Mozilla"
]
}
}
],
"ListenerArn": {"Ref": "ALBListenerProdTraffic"},
"Priority": 1
}
},
"ECSTaskExecutionRole": {
"Type": "AWS::IAM::Role",
"Properties": {
"AssumeRolePolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "ecs-tasks.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
},
"ManagedPolicyArns": [
"arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy"
]
}
},
"ECSInfrastructureRoleForLoadBalancers": {
"Type": "AWS::IAM::Role",
"Properties": {
"AssumeRolePolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowAccessToECSForInfrastructureManagement",
"Effect": "Allow",
"Principal": {
"Service": "ecs.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
},
"ManagedPolicyArns": [
"arn:aws:iam::aws:policy/AmazonECSInfrastructureRolePolicyForLoadBalancers"
]
}
},
"BlueTaskDefinition": {
"Type": "AWS::ECS::TaskDefinition",
"Properties": {
"ExecutionRoleArn": {"Fn::GetAtt": ["ECSTaskExecutionRole", "Arn"]},
"ContainerDefinitions": [
{
"Name": "DemoApp",
"Image": "nginxdemos/hello:latest",
"Essential": true,
"PortMappings": [
{
"HostPort": 80,
"Protocol": "tcp",
"ContainerPort": 80
}
]
}
],
"RequiresCompatibilities": [
"FARGATE"
],
"NetworkMode": "awsvpc",
"Cpu": "256",
"Memory": "512",
"Family": "ecs-demo"
}
},
"ECSDemoCluster": {
"Type": "AWS::ECS::Cluster",
"Properties": {}
},
"ECSDemoService": {
"Type": "AWS::ECS::Service",
"Properties": {
"Cluster": {"Ref": "ECSDemoCluster"},
"DesiredCount": 1,
"DeploymentController": {
"Type": "ECS"
},
"DeploymentConfiguration": {
"MaximumPercent": 200,
"MinimumHealthyPercent": 100,
"DeploymentCircuitBreaker": {
"Enable": true,
"Rollback": true
},
"BakeTimeInMinutes": 5,
"Strategy": "BLUE_GREEN"
},
"NetworkConfiguration": {
"AwsvpcConfiguration": {
"AssignPublicIp": "ENABLED",
"SecurityGroups": [
{"Ref": "ExampleSecurityGroup"}
],
"Subnets": [
{"Ref": "Subnet1"},
{"Ref": "Subnet2"}
]
}
},
"LaunchType": "FARGATE",
"PlatformVersion": "1.4.0",
"TaskDefinition": {"Ref": "BlueTaskDefinition"},
"LoadBalancers": [
{
"ContainerName": "DemoApp",
"ContainerPort": 80,
"TargetGroupArn": {"Ref": "ALBTargetGroupBlue"},
"AdvancedConfiguration": {
"AlternateTargetGroupArn": {"Ref": "ALBTargetGroupGreen"},
"ProductionListenerRule": {"Ref": "ALBListenerProdRule"},
"RoleArn": {"Fn::GetAtt": ["ECSInfrastructureRoleForLoadBalancers", "Arn"]}
}
}
]
}
}
}
}
```
# Migrating from a CodeDeploy blue/green to an Amazon ECS rolling update service deployment
You can migrate your service deployments from an CodeDeploy blue/green deployment to an Amazon ECS rolling update deployment. This moves you away from CodeDeploy dependency to using an integrated deployment.
The Amazon ECS service scheduler replaces the currently running tasks with new tasks. The number of tasks that Amazon ECS adds or removes from the service during a rolling update is controlled by the service deployment configuration.
## Prerequisites
Perform the following operations before you start a blue/green deployment.
1. You no longer need the Amazon ECS CodeDeploy IAM role.
1. Turn off CodeDeploy automation. For more information, see [Working with deployment groups in CodeDeploy](https://docs.aws.amazon.com/codedeploy/latest/userguide/deployment-groups.html) in the *CodeDeploy User Guide*.
1. Verify that there are no ongoing service deployments for the service. For more information, see [View service history using Amazon ECS service deployments](service-deployment.md).
For more information about updating a service's deployment controller, see [Update Amazon ECS service parameters](update-service-parameters.md).
## Procedure
1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2).
1. On the **Clusters** page, choose the cluster.
The cluster details page displays.
1. From the **Services** tab, choose the service.
The service details page displays.
1. In the banner, choose **Migrate**.
The **Update deployment configuration** page displays.
1. Expand **Deployment options**, and then specify the following parameters.
1. For **Deployment controller type**, choose **ECS**.
1. For **Deployment strategy**, choose **Rolling update**.
1. For **Min running tasks**, enter the lower limit on the number of tasks in the service that must remain in the `RUNNING` state during a deployment, as a percentage of the desired number of tasks (rounded up to the nearest integer). For more information, see [Deployment configuration](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/service_definition_parameters.html#sd-deploymentconfiguration).
1. For **Max running tasks**, enter the upper limit on the number of tasks in the service that are allowed in the `RUNNING` or `PENDING` state during a deployment, as a percentage of the desired number of tasks (rounded down to the nearest integer).
1. Expand **Load Balancing**, and then configure the following:
1. For **Role**, choose the role that you created in the prerequisites with the blue/green permissions.
For more information, see [Permissions required for Lambda functions in Amazon ECS blue/green deployments](blue-green-permissions.md).
1. For **Listener**, choose the production listener from your CodeDeploy blue/green deployment.
1. For **Target group**, choose the production target group from your CodeDeploy blue/green deployment.
1. Choose **Update**.
## Next steps
You must update the service for the change to take effect. For more information, see [Updating an Amazon ECS service](update-service-console-v2.md).