ECS Plugin

Note: The ECS plugin is currently in alpha status.

The ECS plugin enables PipeCD to deploy applications to Amazon ECS. It manages deployments via ECS task sets using the EXTERNAL deployment controller, which allows PipeCD to control traffic routing and progressive delivery directly.

There are two main deployment modes:

• Service: An application that runs continuously, optionally placed behind a load balancer. Requires a TaskDefinition file and a Service definition file.
• Standalone task: A one-time or periodic batch job. Requires only a TaskDefinition file.

Prerequisites

piped configuration

Add the ECS plugin to your piped configuration:

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  plugins:
    - name: ecs
      port: 7003
      url: file:///path/to/.piped/plugins/ecs
      deployTargets:
        - name: my-ecs-target
          config:
            region: us-east-1

See ECSDeployTargetConfig for all available options including cross-account role assumption and OIDC-based authentication.

IAM permissions

ECS deployments involve three distinct IAM roles. Confusing them is a common source of permission errors.

Deployment role: the role assumed by piped when calling AWS APIs to deploy your application. Configured via roleARN in the deploy target config, or resolved from the default credential chain. This role needs:

{
  "Effect": "Allow",
  "Action": [
    "ecs:CreateService",
    "ecs:UpdateService",
    "ecs:DescribeServices",
    "ecs:RegisterTaskDefinition",
    "ecs:DescribeTaskDefinition",
    "ecs:CreateTaskSet",
    "ecs:UpdateServicePrimaryTaskSet",
    "ecs:DeleteTaskSet",
    "ecs:DescribeTaskSets",
    "ecs:ListTasks",
    "ecs:DescribeTasks",
    "ecs:RunTasks",
    "ecs:ListTagsForResource",
    "ecs:TagResource",
    "ecs:UntagResource",
    "elasticloadbalancing:DescribeListeners",
    "elasticloadbalancing:DescribeRules",
    "elasticloadbalancing:ModifyRule",
    "iam:PassRole"
  ],
  "Resource": "*"
}

iam:PassRole is required because AWS enforces it whenever a caller passes a role ARN to ECS APIs. Specifically, it is triggered by RegisterTaskDefinition (which receives executionRoleArn and taskRoleArn from the task definition file) and CreateService (which receives the service role ARN). In practice, scope this permission to the specific role ARNs used in your task and service definitions rather than "Resource": "*".

Task execution role: assumed by the ECS agent on your behalf to prepare the task environment before the container starts. It is not used by piped or your application. Typical uses:

• Pull container images from Amazon ECR
• Publish container logs to CloudWatch Logs
• Retrieve secrets from Secrets Manager or SSM Parameter Store

This role is specified as executionRoleArn in your task definition file.

Task role: assumed by the application running inside the container. It is not used by piped or the ECS agent. Grant only the permissions your application needs at runtime, for example reading from S3 or writing to DynamoDB.

This role is specified as taskRoleArn in your task definition file.

Definition files

The ECS plugin reads two YAML or JSON files from your application directory to determine what to deploy.

Task definition file

Specifies the container(s) to run: image, CPU, memory, ports, environment variables, and IAM roles. The file is parsed into the AWS SDK types.TaskDefinition struct (the response type), then the plugin forwards a subset of those fields to RegisterTaskDefinition. Field names must match the Go struct field names (case-insensitive), which correspond to the AWS API JSON field names in camelCase. Fields present in RegisterTaskDefinitionInput but absent from types.TaskDefinition cannot be set through this file.

# taskdef.yaml
family: my-service
executionRoleArn: arn:aws:iam::XXXX:role/ECSTaskExecutionRole
taskRoleArn: arn:aws:iam::XXXX:role/ECSTaskRole # optional: grants your app AWS permissions
requiresCompatibilities:
  - FARGATE
networkMode: awsvpc
cpu: "256"
memory: "512"
containerDefinitions:
  - name: web
    image: public.ecr.aws/nginx/nginx:1.27
    portMappings:
      - containerPort: 80
    cpu: 100
    memory: 100

The default filename is taskdef.json. Override it with taskDefinitionFile in the application config.

Note: The tags field in the task definition file is not currently forwarded to RegisterTaskDefinition. Support is planned for a future version.

Service definition file

Specifies how the ECS service runs: cluster, desired task count, network configuration, and load balancer settings. The file is parsed into the AWS SDK types.Service struct (the response type), then the plugin forwards a subset of those fields to CreateService or UpdateService. Field names must match the Go struct field names (case-insensitive), which correspond to the AWS API JSON field names in camelCase. Fields present in CreateServiceInput/UpdateServiceInput but absent from types.Service cannot be set through this file.

# servicedef.yaml
serviceName: my-service
clusterArn: arn:aws:ecs:ap-northeast-1:XXXX:cluster/my-cluster
desiredCount: 2
deploymentController:
  type: EXTERNAL # required by the ECS plugin
launchType: FARGATE
networkConfiguration:
  awsvpcConfiguration:
    assignPublicIp: ENABLED
    subnets:
      - subnet-YYYY
    securityGroups:
      - sg-YYYY
schedulingStrategy: REPLICA

Note: Due to current parsing limitations, not all fields are forwarded to CreateService and UpdateService. The fields listed below are not yet supported:

• CreateService: capacityProviderStrategy, serviceConnectConfiguration
• UpdateService: deploymentConfiguration, healthCheckGracePeriodSeconds, placementConstraints, platformVersion, capacityProviderStrategy, serviceConnectConfiguration, serviceRegistries, volumeConfigurations

Full field support is planned alongside support for the ECS deployment controller in a future version.

Fields you should not include:

• loadBalancers: PipeCD injects the target group configuration from targetGroups in the app config at deploy time.
• desiredCount: omit this when using Auto Scaling, otherwise PipeCD will reconcile it back to the value in the file on every deployment.
• Tags managed by PipeCD (pipecd/managed-by, pipecd/commit-hash, etc.): these are stamped automatically and will be overwritten.

The service definition file is not needed for standalone tasks.

Service definition requirements

The ECS plugin manages deployments via task sets. Your service definition file must specify the EXTERNAL deployment controller:

deploymentController:
  type: EXTERNAL

Without this, the plugin cannot create or manage task sets for your service.

Note: Support for the ECS deployment controller (type: ECS) is planned for a future version.

Choosing a deployment strategy

When a pipeline is configured, the ECS plugin compares the container images in the target task definition against those in the currently running deployment to decide whether to execute the pipeline or skip it with a quick sync:

The comparison checks each container by name. If the image name differs, the full change is reported; if only the tag or digest differs, the version change is reported. All detected changes appear in the deployment summary in the UI.

Note: Non-image changes (environment variables, CPU/memory, etc.) do not affect strategy selection. If you update only those fields, the plugin will choose quick sync even when a pipeline is configured.

Use quick sync when:

• You want a simple, immediate rollout with no traffic splitting.
• The environment is non-critical (e.g. dev, staging) where gradual rollout adds no value.

Use pipeline sync when:

• You want to gradually shift traffic using canary or blue-green strategies.
• You need manual approval gates before full rollout.
• You want automated analysis (metrics, logs) to validate the new version before promoting it.

Quick sync

By default, when no pipeline is specified in the application configuration, PipeCD triggers a quick sync for any merged pull request. Quick sync registers the new task definition, creates/updates the ECS service, promotes a new primary task set, waits for stability, and removes old task sets. All traffic is switched to the new version immediately.

Note: Standalone tasks always use quick sync. Pipeline sync is not supported for standalone tasks.

Service with load balancer

apiVersion: pipecd.dev/v1beta1
kind: Application
spec:
  name: my-service
  plugin: ecs
  deployTarget: my-ecs-target
  plugins:
    ecs:
      input:
        serviceDefinitionFile: servicedef.yaml
        taskDefinitionFile: taskdef.yaml
        targetGroups:
          primary:
            targetGroupArn: arn:aws:elasticloadbalancing:ap-northeast-1:XXXX:targetgroup/ecs-lb/YYYY
            containerName: web
            containerPort: 80

Standalone task (batch job)

apiVersion: pipecd.dev/v1beta1
kind: Application
spec:
  name: my-batch-job
  plugin: ecs
  deployTarget: my-ecs-target
  plugins:
    ecs:
      input:
        taskDefinitionFile: taskdef.yaml
        runStandaloneTask: true
        clusterArn: arn:aws:ecs:ap-northeast-1:XXXX:cluster/my-cluster
        launchType: FARGATE
        awsvpcConfiguration:
          assignPublicIp: ENABLED
          subnets:
            - subnet-YYYY
          securityGroups:
            - sg-YYYY

Service discovery (no load balancer)

apiVersion: pipecd.dev/v1beta1
kind: Application
spec:
  name: my-internal-service
  plugin: ecs
  deployTarget: my-ecs-target
  plugins:
    ecs:
      input:
        serviceDefinitionFile: servicedef.yaml
        taskDefinitionFile: taskdef.yaml
        accessType: SERVICE_DISCOVERY

Pipeline sync (progressive delivery)

Add a pipeline field to the application configuration to define a custom deployment strategy using the following ECS stages:

Common stages also available:

ECS_ROLLBACK is automatically added when autoRollback: true is set (the default).

Note: ECS_SYNC is the stage used internally by quick sync. It is not intended for use in a custom pipeline.

Canary deployment

Gradually shifts a small fraction of traffic to the new version first, observes it, then promotes to primary. Requires two ALB target groups (primary and canary) both attached to the same listener.

apiVersion: pipecd.dev/v1beta1
kind: Application
spec:
  name: my-service
  plugin: ecs
  deployTarget: my-ecs-target
  plugins:
    ecs:
      input:
        serviceDefinitionFile: servicedef.yaml
        taskDefinitionFile: taskdef.yaml
        targetGroups:
          primary:
            targetGroupArn: arn:aws:elasticloadbalancing:ap-northeast-1:XXXX:targetgroup/ecs-primary/YYYY
            containerName: web
            containerPort: 80
          canary:
            targetGroupArn: arn:aws:elasticloadbalancing:ap-northeast-1:XXXX:targetgroup/ecs-canary/ZZZZ
            containerName: web
            containerPort: 80
  pipeline:
    stages:
      # 1. Deploy the canary task set at 30% of the primary workload capacity.
      #    At this point canary is running but receives no traffic yet.
      - name: ECS_CANARY_ROLLOUT
        with:
          scale: 30

      # 2. Route 10% of traffic to canary, 90% stays on primary.
      - name: ECS_TRAFFIC_ROUTING
        with:
          canary: 10

      # 3. (Optional) Run automated analysis while canary is receiving 10% traffic.
      #    Piped queries the analysis provider every 5 minutes for 10 minutes total.
      #    If the HTTP error rate exceeds 1%, the stage fails and ECS_ROLLBACK triggers.
      #    Remove this stage if you do not have an analysis provider configured.
      - name: ANALYSIS
        with:
          duration: 10m
          metrics:
            - strategy: THRESHOLD
              provider: my-prometheus # name of the analysis provider in piped config
              interval: 5m
              expected:
                max: 0.01 # fail if error rate exceeds 1%
              query: |
                sum(rate(http_requests_total{job="my-service",status=~"5.*"}[5m]))
                /
                sum(rate(http_requests_total{job="my-service"}[5m]))

      # 4. Increase canary traffic to 50%.
      - name: ECS_TRAFFIC_ROUTING
        with:
          canary: 50

      # 5. Wait for manual approval before completing the rollout.
      - name: WAIT_APPROVAL
        with:
          timeout: 1h

      # 6. Promote: update the PRIMARY task set to the new version.
      #    Primary still receives 50% traffic during rollout.
      - name: ECS_PRIMARY_ROLLOUT

      # 7. Route 100% of traffic back to primary (new version).
      - name: ECS_TRAFFIC_ROUTING
        with:
          primary: 100

      # 8. Remove the canary task set.
      - name: ECS_CANARY_CLEAN

Blue/Green deployment

Deploys the new version (green) at full scale alongside the old version (blue), then cuts over all traffic automatically after approval. Requires two ALB target groups (primary and canary) both attached to the same listener.

apiVersion: pipecd.dev/v1beta1
kind: Application
spec:
  name: my-service
  plugin: ecs
  deployTarget: my-ecs-target
  plugins:
    ecs:
      input:
        serviceDefinitionFile: servicedef.yaml
        taskDefinitionFile: taskdef.yaml
        targetGroups:
          primary:
            targetGroupArn: arn:aws:elasticloadbalancing:ap-northeast-1:XXXX:targetgroup/ecs-blue/YYYY
            containerName: web
            containerPort: 80
          canary:
            targetGroupArn: arn:aws:elasticloadbalancing:ap-northeast-1:XXXX:targetgroup/ecs-green/ZZZZ
            containerName: web
            containerPort: 80
  pipeline:
    stages:
      # 1. Deploy the green task set at 100% capacity alongside the existing blue.
      #    Green receives no traffic yet.
      - name: ECS_CANARY_ROLLOUT
        with:
          scale: 100

      # 2. Wait for approval before cutting over traffic.
      - name: WAIT_APPROVAL
        with:
          timeout: 1h

      # 3. Cut over: send 100% of traffic to green (canary target group).
      #    Blue tasks are still running as a fallback.
      - name: ECS_TRAFFIC_ROUTING
        with:
          canary: 100

      # 4. Update the PRIMARY task set to the new version.
      - name: ECS_PRIMARY_ROLLOUT

      # 5. Switch traffic back to the primary target group (now running the new version).
      - name: ECS_TRAFFIC_ROUTING
        with:
          primary: 100

      # 6. Remove the green (canary) task set.
      - name: ECS_CANARY_CLEAN

Migrating from v0

This section covers the steps specific to ECS applications. For the general migration process (updating pipectl, migrating the Control Plane database, installing pipedv1), follow the Migrate to PipeCD v1 guide first.

1. Update the piped configuration

In v0, ECS was configured as a platform provider with type: ECS. In v1, it is a plugin.

v0 piped config:

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  platformProviders:
    - name: ecs-dev
      type: ECS
      config:
        region: us-east-1
        credentialsFile: ~/.aws/credentials
        profile: default
        roleARN: arn:aws:iam::XXXX:role/deployment-role
        tokenFile: /var/run/secrets/token

v1 piped config:

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  plugins:
    - name: ecs
      port: 7003
      url: https://github.com/pipe-cd/pipecd/releases/download/<version>/ecs-plugin
      deployTargets:
        - name: ecs-dev
          config:
            region: us-east-1
            credentialsFile: ~/.aws/credentials
            profile: default
            roleARN: arn:aws:iam::XXXX:role/deployment-role
            tokenFile: /var/run/secrets/token

The credential fields (region, credentialsFile, profile, roleARN, tokenFile) are identical. They move from platformProviders[].config to plugins[].deployTargets[].config.

2. Update the application configuration

The application configuration file format changes in two ways: the kind field and the location of ECS-specific fields.

v0 application configuration file:

apiVersion: pipecd.dev/v1beta1
kind: ECSApp
spec:
  name: my-service
  labels:
    env: production
  input:
    serviceDefinitionFile: servicedef.yaml
    taskDefinitionFile: taskdef.yaml
    targetGroups:
      primary:
        targetGroupArn: arn:aws:elasticloadbalancing:ap-northeast-1:XXXX:targetgroup/ecs-primary/YYYY
        containerName: web
        containerPort: 80
      canary:
        targetGroupArn: arn:aws:elasticloadbalancing:ap-northeast-1:XXXX:targetgroup/ecs-canary/ZZZZ
        containerName: web
        containerPort: 80
  quickSync:
    recreate: false
  pipeline:
    stages:
      - name: ECS_CANARY_ROLLOUT
        with:
          scale: 30
      - name: ECS_TRAFFIC_ROUTING
        with:
          canary: 20
      - name: ECS_PRIMARY_ROLLOUT
      - name: ECS_TRAFFIC_ROUTING
        with:
          primary: 100
      - name: ECS_CANARY_CLEAN

v1 application configuration file:

apiVersion: pipecd.dev/v1beta1
kind: Application
spec:
  name: my-service
  labels:
    env: production
  plugin: ecs
  deployTarget: ecs-dev
  plugins:
    ecs:
      input:
        serviceDefinitionFile: servicedef.yaml
        taskDefinitionFile: taskdef.yaml
        targetGroups:
          primary:
            targetGroupArn: arn:aws:elasticloadbalancing:ap-northeast-1:XXXX:targetgroup/ecs-primary/YYYY
            containerName: web
            containerPort: 80
          canary:
            targetGroupArn: arn:aws:elasticloadbalancing:ap-northeast-1:XXXX:targetgroup/ecs-canary/ZZZZ
            containerName: web
            containerPort: 80
      quickSync:
        recreate: false
  pipeline:
    stages:
      - name: ECS_CANARY_ROLLOUT
        with:
          scale: 30
      - name: ECS_TRAFFIC_ROUTING
        with:
          canary: 20
      - name: ECS_PRIMARY_ROLLOUT
      - name: ECS_TRAFFIC_ROUTING
        with:
          primary: 100
      - name: ECS_CANARY_CLEAN

Summary of field changes:

3. Review behavioral changes

The v1 plugin includes several fixes to behaviors that could cause service disruptions in v0. Read the Changes from v0 section to understand what changed before running your first v1 deployment.

Changes from v0

This section describes behavioral differences between the legacy ECS provider in PipeCD v0 and the ECS plugin in PipeCD v1. If you are migrating from v0, review these changes before deploying.

ECS_PRIMARY_ROLLOUT: eliminates 503 errors during canary promotion

v0 behavior: ECS_PRIMARY_ROLLOUT deleted all ACTIVE task sets (including the CANARY task set) before promoting the new PRIMARY. This created a window where no task set was serving traffic, causing HTTP 503 errors on the load balancer: issue #4710.

v1 behavior: ECS_PRIMARY_ROLLOUT records the current PRIMARY task set ARN before creating the new one, promotes the new task set to PRIMARY, then deletes only the old PRIMARY. Any CANARY task set created by an earlier ECS_CANARY_ROLLOUT stage remains intact and continues to serve its share of traffic throughout the rollout window. The CANARY is cleaned up separately by ECS_CANARY_CLEAN.

This change eliminates the 503 window that existed in v0 during canary deployments.

Rollback: eliminates 503 errors when reverting

v0 behavior: During rollback, task sets were recreated first. This left a window where the ALB listener was still sending a fraction of traffic to the canary target group even though its tasks were being deleted, resulting in 503 errors for requests hitting that target group.

v1 behavior: The ECS_ROLLBACK stage restores ALB listener weights to 100% primary / 0% canary before touching any task set. Listener ARNs and the canary target group ARN are persisted in deployment metadata by ECS_TRAFFIC_ROUTING, so rollback can look them up without an additional AWS API call. Only after the listener is safe does rollback create the new task set, promote it to PRIMARY, and delete the remaining task sets.

Drift detection: no false alerts from AWS-managed changes

v0 behavior: Drift detection compared the fields of the live ECS resources against what was declared in the Git definition files. This produced false OUT_OF_SYNC signals whenever AWS mutated a field outside of PipeCD’s control, for example when Auto Scaling adjusted desiredCount, or when AWS updated internal service metadata.

v1 behavior: The plugin stamps a pipecd/commit-hash tag onto each PRIMARY task set at the end of every deployment. Drift detection compares this tag value against the current Git commit hash:

• If they match: SYNCED
• If they differ: OUT_OF_SYNC, with the deployed and expected hashes shown as the reason

AWS-side mutations that do not change the deployed commit (such as Auto Scaling adjustments) no longer trigger drift alerts.

Application live state

The ECS plugin continuously monitors your application’s live state and displays it on the PipeCD UI. piped periodically polls AWS and compares the running state against the commit hash declared in Git.

Sync status

Resource tree

The UI displays the ECS resources as a hierarchy. The structure depends on the deployment controller type configured in the service definition.

EXTERNAL controller (required by this plugin for canary/blue-green):

ECS:Service
└── ECS:TaskSet  (one per variant: PRIMARY, CANARY, etc.)
    └── ECS:Task

Resource metadata

Each resource type exposes the following metadata fields in the UI:

ECS:Service

ECS:TaskSet (EXTERNAL controller only)

ECS:Task

Health status

Plan preview

Before a deployment is triggered, PipeCD can show a preview of what will change. The ECS plugin compares the running definition files (from the last deployed commit) against the target definition files (from the incoming commit) and displays a unified diff.

What is shown

Example output

When only the container image in the task definition is updated, the plan preview looks like:

--- taskdef (running)
+++ taskdef (target)
@@ -3,7 +3,7 @@
 containerDefinitions:
   - name: web
-    image: public.ecr.aws/nginx/nginx:1.25
+    image: public.ecr.aws/nginx/nginx:1.27
     cpu: 100
     memory: 100
     portMappings:

If no files changed between the two commits, the summary shows No changes were detected and no diff is displayed.

Notes

• When using an ALB, all listener rules that reference the configured target groups are controlled by PipeCD. Attach the target groups to your listener rules before deploying.
• Service Connect uses the ECS deployment controller, which is incompatible with the EXTERNAL controller required by this plugin. Canary and blue/green deployments are not available when using Service Connect.
• When using Service Auto Scaling, omit desiredCount from the service definition file to prevent PipeCD from reconciling it on every deployment.

Configuration reference

ECSDeployTargetConfig

Configured under plugins[].deployTargets[].config in the piped configuration.

ECSDeploymentInput

Configured under plugins.ecs.input in the application configuration.

ECSVpcConfiguration

ECSTargetGroups

ECSTargetGroup

ECSSyncStageOptions (quickSync)

Configured under plugins.ecs.quickSync.

ECS_CANARY_ROLLOUT options

ECS_TRAFFIC_ROUTING options

Specify either primary or canary. The other variant automatically receives the remainder.