Creating an Amazon ECS blue/green deployment - Amazon Elastic Container Service
PrerequisitesProcedureNext steps

Creating an Amazon ECS blue/green deployment

By using Amazon ECS blue/green deployments, you can make and test service changes before implementing them in a production environment.

Prerequisites

Perform the following operations before you start a blue/green deployment.

  1. Configure the appropriate permissions.

  2. Amazon ECS blue/green deployments require that your service to use one of the following features: Configure the appropriate resources.

  3. Create a rule to route traffic to your green service revision. For more information, see Listener rules in the Network Load Balancer User Guide.

  4. Create a target group for your green service revision. When you use the awsvpc network mode for your tasks, the target type must be ip. For information about target groups, see Target groups in the Network Load Balancer User Guide.

  5. Decide if you want to run Lambda functions for the lifecycle events.

    • 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 event. For more information, see Create a Lambda function with the console in the AWS Lambda Developer Guide.

Procedure

You can use the console or the AWS CLI to create an Amazon ECS blue/green service.

Console

  1. Open the console at https://console.aws.amazon.com/ecs/v2.

  2. Determine the resource from where you launch the service.

    To start a service from Steps

    Clusters

    1. On the Clusters page, select the cluster to create the service in.

      The cluster details page displays.

    2. On the Services tab, choose Create.
    Task definition

    1. On the Task definitions page, select the task definition.

    2. From the Deploy menu, choose Create service.

    The Create service page displays.

  3. Under Service details, do the following:

    1. For Task definition family, choose the task definition to use. Then, for Task definition revision, enter the revision to use.

    2. For Service name, enter a name for your service.

  4. To run the service in an existing cluster, for Existing cluster, choose the cluster. To run the service in a new cluster, choose Create cluster

  5. Choose how your tasks are distributed across your cluster infrastructure. Under Compute configuration, choose your option.

    Compute option Steps

    Capacity provider strategy

    1. Under Compute options, choose Capacity provider strategy.

    2. Choose a strategy:

      • To use the cluster's default capacity provider strategy, choose Use cluster default.

      • If your cluster doesn't have a default capacity provider strategy, or to use a custom strategy, choose Use custom, Add capacity provider strategy, and then define your custom capacity provider strategy by specifying a Base, Capacity provider, and Weight.

    Note

    To use a capacity provider in a strategy, the capacity provider must be associated with the cluster.

    Launch type

    1. In the Compute options section, select Launch type.

    2. For Launch type, choose a launch type.

    3. (Optional) When the Fargate launch type is specified, for Platform version, specify the platform version to use. If a platform version isn't specified, the LATEST platform version is used.

  6. Under Deployment configuration, do the following:

    1. For Service type, choose Replica.

    2. For Desired tasks, enter the number of tasks to launch and maintain in the service.

    3. To have Amazon ECS monitor the distribution of tasks across Availability Zones, and redistribute them when there is an imbalance, under Availability Zone service rebalancing, select Availability Zone service rebalancing.

    4. For Health check grace period, enter the amount of time (in seconds) that the service scheduler ignores unhealthy Elastic Load Balancing, VPC Lattice, and container health checks after a task has first started. If you do not specify a health check grace period value, the default value of 0 is used.

    1. For Bake time, enter the number of minutes that both the blue and green service revisions will run simultaneously before the blue revision is terminated. This allows time for verification and testing.

    2. (Optional) Run Lambda functions to run at specific stages of the deployment. Under Deployment lifecycle hooks, select the stages to run the lifecycle hooks.

      To add a lifecycle hook:

      1. Choose Add.

      2. For Lambda function, enter the function name or ARN.

      3. For Role, select the IAM role that has permission to invoke the Lambda function.

      4. For Lifecycle stages, select the stages when the Lambda function should run.

  8. To configure how Amazon ECS detects and handles deployment failures, expand Deployment failure detection, and then choose your options.

    1. To stop a deployment when the tasks cannot start, select Use the Amazon ECS deployment circuit breaker.

      To have the software automatically roll back the deployment to the last completed deployment state when the deployment circuit breaker sets the deployment to a failed state, select Rollback on failures.

    2. To stop a deployment based on application metrics, select Use CloudWatch alarm(s). Then, from CloudWatch alarm name, choose the alarms. To create a new alarm, go to the CloudWatch console.

      To have the software automatically roll back the deployment to the last completed deployment state when a CloudWatch alarm sets the deployment to a failed state, select Rollback on failures.

  9. (Optional) To interconnect your service using Service Connect, expand Service Connect, and then specify the following:

    1. Select Turn on Service Connect.

    2. Under Service Connect configuration, specify the client mode.

      • If your service runs a network client application that only needs to connect to other services in the namespace, choose Client side only.

      • If your service runs a network or web service application and needs to provide endpoints for this service, and connects to other services in the namespace, choose Client and server.

    3. To use a namespace that is not the default cluster namespace, for Namespace, choose the service namespace.

    4. (Optional) Configure test traffic header rules for blue/green deployments. Under Test traffic routing, specify the following:

      1. Select Enable test traffic header rules to route specific requests to the green service revision during testing.

      2. For Header matching rules, configure the criteria for routing test traffic:

        • Header name: Enter the name of the HTTP header to match (for example, X-Test-Version or User-Agent).

        • Match type: Choose the matching criteria:

          • Exact match: Route requests where the header value exactly matches the specified value

          • Header present: Route requests that contain the specified header, regardless of value

          • Pattern match: Route requests where the header value matches a specified pattern

        • Header value (if using exact match or pattern match): Enter the value or pattern to match against.

        You can add multiple header matching rules to create complex routing logic. Requests matching any of the configured rules will be routed to the green service revision for testing.

      3. Choose Add header rule to configure additional header matching conditions.

      Note

      Test traffic header rules enable you to validate new functionality with controlled traffic before completing the full deployment. This allows you to test the green service revision with specific requests (such as those from internal testing tools or beta users) while maintaining normal traffic flow to the blue service revision.

    5. (Optional) Specify a log configuration. Select Use log collection. The default option sends container logs to CloudWatch Logs. The other log driver options are configured using AWS FireLens. For more information, see Send Amazon ECS logs to an AWS service or AWS Partner.

      The following describes each container log destination in more detail.

      • Amazon CloudWatch – Configure the task to send container logs to CloudWatch Logs. The default log driver options are provided, which create a CloudWatch log group on your behalf. To specify a different log group name, change the driver option values.

      • Amazon Data Firehose – Configure the task to send container logs to Firehose. The default log driver options are provided, which send logs to a Firehose delivery stream. To specify a different delivery stream name, change the driver option values.

      • Amazon Kinesis Data Streams – Configure the task to send container logs to Kinesis Data Streams. The default log driver options are provided, which send logs to an Kinesis Data Streams stream. To specify a different stream name, change the driver option values.

      • Amazon OpenSearch Service – Configure the task to send container logs to an OpenSearch Service domain. The log driver options must be provided.

      • Amazon S3 – Configure the task to send container logs to an Amazon S3 bucket. The default log driver options are provided, but you must specify a valid Amazon S3 bucket name.

  10. (Optional) Configure Load balancing for blue/green deployment.

    Elastic Load Balancing type Steps

    Application Load Balancer

    1. For Load balancer type, choose Application Load Balancer.

    2. Choose Create a new load balancer to create a new Application Load Balancer or Use an existing load balancer to select an existing Application Load Balancer.

    3. For Container, choose the container that hosts the service.

    4. For Load balancer name, enter a unique name.

    5. For Listener, enter a port and protocol for the Application Load Balancer to listen for connection requests on. By default, the load balancer will be configured to use port 80 and HTTP.

      • For Production rule, enter the Evaluation order and Path pattern for the rule.

        This rule is for your production (blue) service revision traffic.

      • For Test rule, enter the Evaluation order and Path pattern for the rule.

        This rule is for your test (green) service revision traffic.

    6. For Target group, configure the following:

      • For Target group name, enter a name and a protocol for the target group that the Application Load Balancer routes requests to.

      • For Protocol, choose the protocol for the target group that the Application Load Balancer routes requests to. By default, the target group routes requests to the first container defined in your task definition.

      • For Degregistration delay, enter the number of seconds for the load balancer to change the target state to UNUSED. The default is 300 seconds.

      • For Health check path, enter an existing path within your container where the Application Load Balancer periodically sends requests to verify the connection health between the Application Load Balancer and the container. The default is the root directory (/).

      • For Alternate group name, enter the group name for the target group for your test (green) service revision.
    Network Load Balancer

    1. For Load balancer type, select Network Load Balancer.

    2. For Load Balancer, choose an existing Network Load Balancer.

    3. For Choose container to load balance, choose the container that hosts the service.

    4. For Production listener, choose the Production listener port, and the Production listener protocol.

      This is the listener for your production (blue) service revision traffic.

    5. For Test listener, choose the Test listener port, and the Test listener protocol.

      This is the listener for your test (green) service revision traffic.

    6. For Target group, configure the following:

      • For Target group name, enter a name and a protocol for the target group that the Network Load Balancer routes requests to.

      • For Protocol, choose the protocol for the target group that the Network Load Balancer routes requests to. By default, the target group routes requests to the first container defined in your task definition.

      • For Degregistration delay, enter the number of seconds for the load balancer to change the target state to UNUSED. The default is 300 seconds.

      • For Health check path, enter an existing path within your container where the Application Load Balancer periodically sends requests to verify the connection health between the Application Load Balancer and the container. The default is the root directory (/).

      • For Alternate group name, enter the group name for the target group for your test (green) service revision.

  11. (Optional) To help identify your service and tasks, expand the Tags section, and then configure your tags.

    To have Amazon ECS automatically tag all newly launched tasks with the cluster name and the task definition tags, select Turn on Amazon ECS managed tags, and then for Propagate tags from, choose Task definitions.

    To have Amazon ECS automatically tag all newly launched tasks with the cluster name and the service tags, select Turn on Amazon ECS managed tags, and then for Propagate tags from, choose Service.

    Add or remove a tag.

    • [Add a tag] Choose Add tag, and then do the following:

      • For Key, enter the key name.

      • For Value, enter the key value.

    • [Remove a tag] Next to the tag, choose Remove tag.

  12. Choose Create.

AWS CLI

  1. Create a file named service-definition.json with the following content.

    Replace the user-input with your values.

    {
  "serviceName": "myBlueGreenService",
  "cluster": "arn:aws:ecs:us-west-2:123456789012:cluster/sample-fargate-cluster",
  "taskDefinition": "sample-fargate:1",
  "desiredCount": 5,
  "launchType": "FARGATE",
  "networkConfiguration": {
    "awsvpcConfiguration": {
      "subnets": [
        "subnet-09ce6e74c116a2299",
        "subnet-00bb3bd7a73526788",
        "subnet-0048a611aaec65477"
      ],
      "securityGroups": [
        "sg-09d45005497daa123"
      ],
      "assignPublicIp": "ENABLED"
    }
  },
  "deploymentController": {
    "type": "ECS"
  },
  "deploymentConfiguration": {
    "strategy": "BLUE_GREEN",
    "maximumPercent": 200,
    "minimumHealthyPercent": 100,
    "bakeTimeInMinutes": 2,
    "alarms": {
      "alarmNames": [
        "myAlarm"
      ],
      "rollback": true,
      "enable": true
    },
    "lifecycleHooks": [
      {
        "hookTargetArn": "arn:aws:lambda:us-west-2:7123456789012:function:checkExample",
        "roleArn": "arn:aws:iam::123456789012:role/ECSLifecycleHookInvoke",
        "lifecycleStages": [
          "PRE_SCALE_UP"
        ]
      }
    ]
  },
  "loadBalancers": [
    {
      "targetGroupArn": "arn:aws:elasticloadbalancing:us-west-2:123456789012:targetgroup/blue-target-group/54402ff563af1197",
      "containerName": "fargate-app",
      "containerPort": 80,
      "advancedConfiguration": {
        "alternateTargetGroupArn": "arn:aws:elasticloadbalancing:us-west-2:123456789012:targetgroup/green-target-group/cad10a56f5843199",
        "productionListenerRule": "arn:aws:elasticloadbalancing:us-west-2:123456789012:listener-rule/app/my-blue-green-demo/32e0e4f946c3c05b/9cfa8c482e204f7d/831dbaf72edb911",
        "roleArn": "arn:aws:iam::123456789012:role/LoadBalancerManagementforECS"
      }
    }
  ]
}

  2. Run create-service.

    Replace the user-input with your values.

    aws ecs create-service --cli-input-json file://service-definition.json

    Alternatively, you can use the following example which creates a blue/green deployment service with a load balancer configuration:

    aws ecs create-service \
   --cluster "arn:aws:ecs:us-west-2:123456789012:cluster/MyCluster" \
   --service-name "blue-green-example-service" \
   --task-definition "nginxServer:1" \
   --launch-type "FARGATE" \
   --network-configuration "awsvpcConfiguration={subnets=[subnet-12345,subnet-67890,subnet-abcdef,subnet-fedcba],securityGroups=[sg-12345],assignPublicIp=ENABLED}" \
   --desired-count 3 \
   --deployment-controller "type=ECS" \
   --deployment-configuration "strategy=BLUE_GREEN,maximumPercent=200,minimumHealthyPercent=100,bakeTimeInMinutes=0" \
   --load-balancers "targetGroupArn=arn:aws:elasticloadbalancing:us-west-2:123456789012:targetgroup/MyBGtg1/abcdef1234567890,containerName=nginx,containerPort=80,advancedConfiguration={alternateTargetGroupArn=arn:aws:elasticloadbalancing:us-west-2:123456789012:targetgroup/MyBGtg2/0987654321fedcba,productionListenerRule=arn:aws:elasticloadbalancing:us-west-2:123456789012:listener-rule/app/MyLB/1234567890abcdef/1234567890abcdef,roleArn=arn:aws:iam::123456789012:role/ELBManagementRole}"

Next steps

  • Update the service to start the deployment. For more information, see Updating an Amazon ECS service.

  • 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