Ecs Devops

ECS DevOps — Deployment Strategies and CI/CD

Advisory guidance for shipping software to Amazon ECS safely: choosing a deployment strategy (rolling, native blue/green, linear, canary), configuring failure detection and rollback (circuit breaker, CloudWatch alarms, one-click rollback), and wiring CI/CD pipelines (CodePipeline, GitHub Actions, ECR scanning). Every capability is scoped by launch type — EC2, Fargate, ECS Managed Instances, and ECS Anywhere (EXTERNAL) — because the strategy menu is not the same on each.

The accuracy bar (non-negotiable for this skill). ECS deployment capabilities changed rapidly between mid-2025 and mid-2026 (native blue/green Jul 2025, linear/canary Oct 2025, NLB for linear/canary Feb 2026, pause/continue May 2026, configurable circuit breaker Jul 2026). Never state a strategy/load-balancer/launch-type support combination you cannot cite to an AWS-published source — stale claims in this domain are usually plausible but wrong. When in doubt, defer to the live ECS service deployment options page.

When to Use This Skill

Activate when the user wants to:

• Pick a deployment strategy for an ECS service (rolling vs blue/green vs canary vs linear)
• Configure or debug native ECS blue/green, linear, or canary deployments (lifecycle hooks, bake time, test traffic, weighted target groups)
• Set up the deployment circuit breaker, CloudWatch alarm rollback, or deployment pause/continue
• Roll back a bad ECS deployment, or understand why a deployment is stuck or failed
• Build a CI/CD pipeline that deploys to ECS (CodePipeline, GitHub Actions, ECR push + scan + deploy)
• Migrate from the CodeDeploy blue/green controller to ECS-native strategies
• Understand the external deployment controller / task sets
• Know which strategies work on Fargate vs EC2 vs Managed Instances vs ECS Anywhere

Don't use this skill for:

• EKS or Kubernetes deployments of any kind → use the eks-* skills (eks-best-practices for strategy, eks-build for artifacts)
• ECS monitoring, logging, metrics, tracing, or alerting stack selection → ecs-observability (this skill covers alarms only as deployment-failure triggers)
• GPU / ML / GenAI workloads on ECS → ecs-genai
• ECS security posture, IAM hardening, or compliance → ecs-security
• Auditing the operational health of a live ECS cluster → ecs-operation-review
• Greenfield ECS architecture / launch-type selection with no deployment or pipeline angle → ecs-architect

If a routed sibling skill is not installed yet, don't dead-end the user: answer from general knowledge (staying within this skill's cited facts where they apply) and note that a dedicated skill is pending.

Sibling Skill Disambiguation

Deployment Controller and Strategy Model

Facts verified 2026-07-09 against https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_service-options.html GA dates in this skill follow AWS What's New post dates; the ECS doc-history page can log the same launch a few days earlier (e.g., blue/green Jul 15 vs Jul 17, 2025) — both are AWS sources, this skill standardizes on What's New except where it explicitly cites doc history.

• deploymentController.type has three values — ECS, CODE_DEPLOY, EXTERNAL.
• Under the ECS controller, deploymentConfiguration.strategy selects one of four built-in strategies — ROLLING (default), BLUE_GREEN (GA Jul 17, 2025), LINEAR and CANARY (GA Oct 30, 2025).
• The CODE_DEPLOY controller is the older blue/green path. For new adoptions, AWS's stated recommendation is the native ECS blue/green deployment (deployment-type-bluegreen). It remains fully supported with no announced end-of-life — staying on CodeDeploy indefinitely is a valid steady state for existing estates; migrate when you want something native adds (Service Connect, richer hooks, simpler pipelines), not by default.
• The EXTERNAL controller hands the whole deployment process to your own tooling via task-set APIs — see references/controllers-and-migration.md.
• Since July 15, 2025 the deployment controller is updatable in place on an existing service — you can migrate a service between controller types without recreating it (doc history).

Strategy Selector

Blue/green, linear, and canary all run blue and green revisions simultaneously — plan for up to 2× capacity (EC2 cluster headroom or Fargate/Managed Instances spend) during deployments (deployment-type-blue-green).

Load Balancer Support Matrix (current state)

Facts verified 2026-07-09 against https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_service-options.html and https://aws.amazon.com/about-aws/whats-new/2026/02/amazon-ecs-nlb-linear-canary-deployments/

⚠️ Stale-claim trap: "linear/canary support only ALB and Service Connect" was true only from Oct 2025 to Feb 2026. NLB support for linear and canary launched Feb 4, 2026. If you have seen the older claim (including in earlier internal material), it is obsolete — state the matrix below with its verification date.

Sources: blue/green implementation · NLB nuance · CodeDeploy controller · external controller · Service Connect deployment support

Launch-Type Scoping (applies to everything in this skill)

Facts verified 2026-07-09 against https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateService.html and https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-anywhere.html

• The launchType enum has four values: EC2 | FARGATE | EXTERNAL | MANAGED_INSTANCES. FARGATE_SPOT is not a launch type — it is a capacity provider ("a capacity provider strategy must be used" for Fargate Spot). To use ECS Managed Instances you specify a capacityProviderStrategy and omit launchType — launchType and capacityProviderStrategy are mutually exclusive on CreateService, so a request that sets both is rejected. The MANAGED_INSTANCES enum value exists because launch type appears in API responses and task metadata; it is not how you select Managed Instances (API_CreateService).
• EC2 launch type: all four strategies and both failure-detection methods. Service Connect needs ECS agent ≥ 1.67.2 on a current ECS-optimized AMI; image-digest resolution needs agent ≥ 1.31.0 for ECR-hosted images and ≥ 1.70.0 for all other registries (Service Connect deploy, rolling deployment).
• Fargate: all four strategies; no DAEMON scheduling; Service Connect needs Linux platform version ≥ 1.4.0. Circuit breaker GA covered both EC2 and Fargate (GA announcement).
• ECS Managed Instances (GA Sep 30, 2025): fully managed EC2-based compute consumed via capacity providers only (Managed Instances). Strategy support: all four native strategies (ROLLING, BLUE_GREEN, LINEAR, CANARY) via the ECS controller — the native strategy pages scope by load balancer/Service Connect, not away from Managed Instances (blue/green implementation). Failure-detection support (circuit breaker, alarms) on Managed Instances is inferred from the docs scoping those features only by deployment controller — not explicitly documented for Managed Instances as of 2026-07-10; verify before relying on it (same evidence posture as the ECS Anywhere caveat below). CODE_DEPLOY and EXTERNAL controllers on Managed Instances are not clearly documented: both are task-set-based, and the developer guide documents task-set launchType as EC2 | FARGATE | EXTERNAL (external controller) while the CreateTaskSet API reference lists MANAGED_INSTANCES in the enum — the two pages disagree, so do not claim controller support beyond ECS for Managed Instances; say the docs are inconsistent and verify.
• ECS Anywhere (EXTERNAL launch type): no service load balancing, no service discovery, no awsvpc network mode, no capacity providers, and Service Connect is explicitly unsupported on external container instances. Net effect — no managed traffic shifting is possible, so rolling update (min/max percent) is the practical deployment strategy on ECS Anywhere. Blue/green-family support without traffic management is not documented for Anywhere — do not claim it. Circuit-breaker support on the EXTERNAL launch type is not explicitly documented — the docs scope the circuit breaker only by deployment controller, and the GA announcement names EC2 and Fargate — verify before relying on it. (ECS Anywhere, Service Connect deploy)

Rolling Update Quick Reference

Facts verified 2026-07-10 against https://docs.aws.amazon.com/AmazonECS/latest/developerguide/deployment-type-ecs.html and https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DeploymentConfiguration.html

• minimumHealthyPercent — lower bound on running-and-healthy tasks during deployment, as % of desired count, rounded up. Default 100% for replica services. Example: min 50% + desired 4 → the scheduler may stop 2 tasks before starting replacements; min 75% + desired 2 → it cannot stop any first.
• maximumPercent — upper bound on running tasks, as % of desired count, rounded down. Example: max 200% + desired 4 → 4 new tasks can start before any old stop; max 125% + desired 3 → no task can start first. Daemon services: maximumPercent must be 100; default min-healthy is 0% via CLI/SDK/API but 50% via the console (API_DeploymentConfiguration).
• Zero-downtime recipe: minimumHealthyPercent=100, maximumPercent=200 — requires headroom for 2× tasks during the rollout (applies on EC2 only if the cluster has spare capacity; on Fargate/Managed Instances it is a spend question).
• Misconfigured min/max that prevents both stopping and starting stalls the deployment and emits a service event — check service events first when a rolling deployment hangs.
• Version consistency: ECS resolves image tags to digests at deployment time (first started task pins the digests); 3+ digest-resolution failures with circuit breaker enabled fail and roll back the deployment. Configurable per container via versionConsistency.
• Always pair rolling with failure detection (on EC2/Fargate/Managed Instances; see the ECS Anywhere caveat above) — circuit breaker for "tasks can't start / can't get healthy", CloudWatch alarms for "metrics regressed". Circuit breaker is rolling-only; alarms work with any strategy under the ECS controller; usable together; whichever trips first fails the deployment (alarm-based detection).

aws ecs update-service --cluster prod --service web \
  --deployment-configuration \
  'minimumHealthyPercent=100,maximumPercent=200,deploymentCircuitBreaker={enable=true,rollback=true,resetOnHealthyTask=true,thresholdConfiguration={type=BOUNDED_PERCENT,value=50}},alarms={alarmNames=[web-5xx-alarm],enable=true,rollback=true}'

For circuit breaker thresholds, alarm gotchas, and the full rollback ladder, see: Failure Detection & Rollback

Native Blue/Green, Linear, and Canary Quick Reference

Facts verified 2026-07-09 against https://docs.aws.amazon.com/AmazonECS/latest/developerguide/deployment-type-blue-green.html and https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateService.html

All three are "blue/green-family": ECS stands up the green revision, optionally routes test traffic to it (Service Connect default test header: x-amzn-ecs-blue-green-test), shifts production traffic via weighted listener-rule target groups (all-at-once for BLUE_GREEN, stepped for LINEAR/CANARY), then holds both revisions through bake time before cleaning up blue. Rollback during bake time is a near-instant weight flip — no task relaunch.

Required plumbing (ALB/NLB path): a production listener rule pre-configured with two target groups weighted 1 and 0, plus per-load-balancer advancedConfiguration on the service (alternateTargetGroupArn, productionListenerRule, optional testListenerRule, and an infrastructure IAM role carrying AmazonECSInfrastructureRolePolicyForLoadBalancers) (CodeDeploy-to-native migration overview).

Minimal, correct deploymentConfiguration shapes (ECS controller — API_CreateService):

// Blue/green — all-at-once shift, 15-minute bake
"deploymentConfiguration": {
  "strategy": "BLUE_GREEN",
  "bakeTimeInMinutes": 15
}

// Canary — 10% first, bake 30 min on the canary slice, then 100%, then 15-min final bake
"deploymentConfiguration": {
  "strategy": "CANARY",
  "canaryConfiguration": { "canaryPercent": 10.0, "canaryBakeTimeInMinutes": 30 },
  "bakeTimeInMinutes": 15
}

// Linear — 20% steps (20/40/60/80/100), 10-min bake per step, 15-min final bake
"deploymentConfiguration": {
  "strategy": "LINEAR",
  "linearConfiguration": { "stepPercent": 20.0, "stepBakeTimeInMinutes": 10 },
  "bakeTimeInMinutes": 15
}

Valid ranges: stepPercent 3.0–100.0; stepBakeTimeInMinutes 0–1440 (linear deployment). Do not put deploymentCircuitBreaker in blue/green-family configs — the circuit breaker is rolling-only (see below).

• Lifecycle stages (shared by all three): RECONCILE_SERVICE → PRE_SCALE_UP → SCALE_UP → POST_SCALE_UP → TEST_TRAFFIC_SHIFT → POST_TEST_TRAFFIC_SHIFT → PRE_PRODUCTION_TRAFFIC_SHIFT → PRODUCTION_TRAFFIC_SHIFT → POST_PRODUCTION_TRAFFIC_SHIFT → BAKE_TIME → CLEAN_UP. Hooks attach to all stages except SCALE_UP, BAKE_TIME, CLEAN_UP; TEST_TRAFFIC_SHIFT and PRODUCTION_TRAFFIC_SHIFT (exactly those two — not the PRE_/POST_ variants) accept Lambda hooks only (how it works).
• For linear/canary, PRE_PRODUCTION_TRAFFIC_SHIFT / PRODUCTION_TRAFFIC_SHIFT hooks fire at every traffic step; each production shift step may last up to 24 h.
• Pause/continue (GA May 19, 2026): PAUSE-type lifecycle hooks on rolling and blue/green-family deployments (the rolling scope comes from the What's New; the doc page illustrates only blue/green-family stages; ECS Anywhere support is not documented as of 2026-07-10); resume or abort with aws ecs continue-service-deployment --hook-id <id> --action CONTINUE|ROLLBACK (pause hooks).
• Timeouts: each lifecycle stage max 24 h (timeout → fail + roll back); CloudFormation adds a 36 h whole-deployment cap; overall deployment limit 30 days.

For full lifecycle-hook config, test-traffic routing, pause/continue details, and deployment-speed tuning, see: Deployment Strategies Deep Dive

Failure Detection — Circuit Breaker vs CloudWatch Alarms

Facts verified 2026-07-10 against https://docs.aws.amazon.com/AmazonECS/latest/developerguide/deployment-circuit-breaker.html and https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DeploymentAlarms.html

⚠️ Scope wording trap: one sentence on the alarm-detection page reads "only supported for … the rolling update (ECS) deployment controller" — that "rolling update (ECS)" is the doc's name for the controller, not a strategy restriction. The API reference and the blue/green service definition (below) make the controller-vs-strategy distinction explicit.

Jul 1, 2026 knobs (What's New):

• thresholdConfiguration.type: BOUNDED_PERCENT (default; value default 50; threshold = ceil(value% × desired count) clamped to min 3 / max 200), UNBOUNDED_PERCENT (same formula, no clamps), or COUNT (fixed number).
• resetOnHealthyTask: true (default) counts consecutive failures (counter resets on a healthy task); false counts cumulative failures across the deployment.

Alarm-detection gotchas: ECS polls alarms via DescribeAlarms (CloudWatch API throttling can cause a missed rollback — mitigate by also enabling the circuit breaker and alerting on SERVICE_DEPLOYMENT_FAILED, both covered in this skill), and an alarm already in ALARM state at deployment start is ignored for that deployment — deliberately, so you can deploy a fix (alarm detection).

The Rollback Ladder (fastest first)

1. Bake-time weight flip (blue/green-family only) — while blue is still running, rollback is a listener-weight change; near-instant, no task relaunch.
2. One-click manual rollback (any strategy under the ECS deployment controller, while the deployment is in a stoppable state — PENDING, IN_PROGRESS, STOP_REQUESTED, ROLLBACK_REQUESTED, or ROLLBACK_IN_PROGRESS; GA May 2025): aws ecs stop-service-deployment --service-deployment-arn <arn> --stop-type ROLLBACK — rolls back to the previous service revision even if rollback was never configured on the service. Find the ARN with aws ecs list-service-deployments. For CodeDeploy-controller services or deployments that already reached COMPLETED, use rung 4 instead (stop-service-deployment).
3. Automatic rollback — circuit breaker trips (rolling only), an alarm trips (any ECS-controller strategy), or a lifecycle-hook/stage-timeout failure (blue/green-family); target is the most recent COMPLETED deployment. If no COMPLETED deployment exists, the circuit breaker does not launch new tasks and the failed deployment stalls — clean up manually.
4. Manual re-deploy — UpdateService back to the previous task-definition revision (universal fallback under the ECS and CodeDeploy controllers; under EXTERNAL, UpdateService cannot change the task definition — roll back by shifting your own task sets).

❌ --force-new-deployment is NOT a rollback. It starts a new deployment with no service-definition changes — a restart/re-pull (e.g., pick up a newer image behind the same mutable tag, refresh image digests, move to a newer Fargate platform version). It redeploys the same task definition; it does not return you to the previous revision. This is a common misconception — reach for stop-service-deployment --stop-type ROLLBACK or a previous task-def revision instead (UpdateService).

For rollback targets, EventBridge deployment events, and stoppable deployment states, see: Failure Detection & Rollback

CI/CD Quick Reference

Facts verified 2026-07-09 against https://docs.aws.amazon.com/codepipeline/latest/userguide/integrations-action-type.html and the aws-actions GitHub repos linked below

• There is no dedicated CodePipeline action for ECS-native blue/green/linear/canary (as of 2026-07-10). AWS's migration guidance is to switch pipelines from CodeDeploy CreateDeployment to the ECS UpdateService API (CodeDeploy-to-native migration overview).
• GitHub Actions building blocks (all official, aws-actions org): configure-aws-credentials (OIDC — no long-lived keys), amazon-ecr-login, amazon-ecs-render-task-definition (inject the new image URI), amazon-ecs-deploy-task-definition (register + deploy; wait-for-service-stability; CodeDeploy blue/green via codedeploy-appspec/codedeploy-application/codedeploy-deployment-group; actively maintained — v2.6.3, Jul 2026).
• ECR scanning in the pipeline: basic scanning (OS-package CVEs, on-push filters) or enhanced scanning via Amazon Inspector (OS + language packages, continuous rescans, ECS image-usage context, Inspector pricing applies). Gate deploys on scan findings via EventBridge (basic · enhanced).
• Launch-type caveat: pipeline mechanics (register task def → update service) are identical for EC2, Fargate, and Managed Instances — except ECS Anywhere, which is rolling-only: never attach CodeDeploy blue/green actions or native blue/green-family expectations to an Anywhere service (ECS Anywhere).

For full pipeline walkthroughs, a GitHub Actions workflow skeleton, and scan-gating patterns, see: CI/CD Pipelines

Top Guardrails (the high-cost mistakes)

1. Don't treat --force-new-deployment as a rollback — it re-deploys the same task definition (restart/re-pull). Use stop-service-deployment --stop-type ROLLBACK.
2. Don't repeat the pre-Feb-2026 LB matrix — linear/canary support NLB since Feb 4, 2026. Always state support matrices with a verification date.
3. Don't configure the circuit breaker on blue/green-family services — the circuit breaker is rolling-only. CloudWatch alarm detection is not — it works with any ECS-controller strategy. Blue/green-family safety = hooks + bake time + stage timeouts + (optionally) alarms.
4. Don't ship rolling deployments with no failure detection — a bad deployment can stay "in progress" indefinitely. Enable circuit breaker + alarms with rollback (on EC2/Fargate/Managed Instances; see the Anywhere caveat in Launch-Type Scoping), and alert on the SERVICE_DEPLOYMENT_FAILED EventBridge event.
5. Don't recommend blue/green-family strategies on ECS Anywhere — no ELB, no Service Connect, therefore no managed traffic shifting. Rolling only.
6. Don't call FARGATE_SPOT a launch type — it is a capacity provider; the launch-type enum is EC2 | FARGATE | EXTERNAL | MANAGED_INSTANCES, and Managed Instances itself is selected via capacityProviderStrategy, not launchType.
7. Don't start a blue/green-family rollout without 2× capacity headroom — blue and green run simultaneously until CLEAN_UP.
8. Don't build new CodeDeploy-controller integrations — AWS recommends native strategies for new adoptions; the controller is updatable in place since Jul 2025, so migration does not require service recreation. (But do not call CodeDeploy "deprecated" or push working existing CodeDeploy estates to migrate — it is a supported steady state with no announced EOL.)
9. Don't forget both target groups must be associated with the production/test listener rules — otherwise blue/green deployments fail with an invalid-networking-configuration rollback (migration steps page — a distinct page from the migration overview).

Detailed References

This skill uses progressive disclosure — essentials live in this file; load a reference when the task needs depth.

Sources

• Amazon ECS service deployment options · Rolling update · Blue/green deployment · How blue/green works · Linear deployment · Canary deployment
• Deployment circuit breaker · CloudWatch alarm failure detection · Pause lifecycle hooks · Stopping a service deployment
• CodeDeploy blue/green (legacy controller) · Migrate CodeDeploy to native blue/green · External deployment controller
• ECS CreateService API · ECS UpdateService API · ECS document history
• What's New: built-in blue/green (Jul 2025) · linear & canary (Oct 2025) · NLB for linear/canary (Feb 2026) · pause/continue (May 2026) · configurable circuit breaker (Jul 2026) · 1-click rollbacks (May 2025)
• CodePipeline integrations · CodePipeline image file reference · ECS blue/green action reference
• GitHub Actions: amazon-ecs-deploy-task-definition · amazon-ecs-render-task-definition · amazon-ecr-login · configure-aws-credentials
• ECR basic scanning · ECR enhanced scanning (Inspector)
• ECS Anywhere · ECS Managed Instances · Service Connect deployment considerations

This skill is provided as sample code for educational and demonstration purposes only. Verify point-in-time capability claims against the linked AWS documentation before acting on them. See the project's README and LICENSE for full terms.