ecs

AWS ECS plugin

Overview

ECS plugin supports the Deployment for AWS ECS.

[!CAUTION] Currently, this is alpha status.

Quick sync

Quick sync rolls out the new version and switches all traffic to it immediately.

It will be planned in one of the following cases:

• no pipeline was specified in the application configuration file
• the application is a standalone task (pipeline sync is not supported for standalone tasks)

For example, the application configuration below is missing the pipeline field. This means any pull request that touches the application will trigger a quick sync deployment.

apiVersion: pipecd.dev/v1beta1
kind: Application
spec:
  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

Pipeline sync

You can configure the pipeline to enable a progressive deployment with a strategy like canary or blue-green.

ECS plugin defines two variants for each application: primary (aka stable) and canary.

• primary runs the current version of code and configuration.
• canary runs the proposed change of code or configuration.

Once the deployment is completed, only the primary variant should remain.

These are the provided stages for ECS plugin you can use to build your pipeline:

• ECS_SYNC: sync ECS service with given task definition (used for quick sync)
• ECS_PRIMARY_ROLLOUT: roll out the new task set as PRIMARY variant
• ECS_CANARY_ROLLOUT: roll out the new task set as CANARY variant (serves no traffic initially when using ELB)
• ECS_CANARY_CLEAN: clean up task sets of CANARY variant
• ECS_TRAFFIC_ROUTING: route traffic between PRIMARY and CANARY task sets
• ECS_ROLLBACK: rollback to the previous task set (automatically added when autoRollback is enabled)

Directory Structure

ecs/
├── main.go         # Plugin entrypoint
├── config/         # Configuration types for piped, deploy targets, application, and stages
├── deployment/     # Stage execution and pipeline planning
├── provider/       # AWS ECS API client and resource operations
├── livestate/      # Live state fetcher (reports current state of ECS resources)
└── planpreview/    # Plan preview (shows diff before deployment)

How to Build & Run

Build

Build the ECS plugin binary using the build/plugin Makefile target from the repository root:

# Build all plugins (including ecs)
make build/plugin

# Build only the ECS plugin
make build/plugin PLUGINS=ecs

The binary will be placed at ~/.piped/plugins/ecs by default.

Run

Configure your piped to load the ECS plugin by adding it to the piped config:

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  plugins:
  - name: ecs
    port: 7003 # any unused port
    url: file:///home/<user>/.piped/plugins/ecs
    deployTargets:
      - name: production
        config:
          region: us-east-1

Then start piped as usual. The plugin process will be launched automatically by piped on the specified port.

[!NOTE] If you build the plugin manually with go build and place the binary at a custom path, piped may use a previously cached binary instead. Pass --force-plugin-redownload when starting piped to ensure it picks up your locally built binary:

piped --force-plugin-redownload ...

How to Test

Unit tests

Unit tests use mocks for all AWS API calls and do not require real AWS credentials. Run them from the repository root:

go test ./pkg/app/pipedv1/plugin/ecs/...

Integration tests

To test against a real AWS environment, build and run piped with the plugin pointing to a real ECS cluster. The plugin resolves credentials in the following order:

1. credentialsFile + profile in deploy target config: explicit credentials file and profile
2. tokenFile + roleARN in deploy target config: OIDC web identity role assumption
3. AWS default credential chain: env vars, ~/.aws/credentials, instance metadata

The simplest approach for local development is to rely on the default credential chain by setting environment variables:

export AWS_ACCESS_KEY_ID=<your-access-key-id>
export AWS_SECRET_ACCESS_KEY=<your-secret-access-key>
export AWS_REGION=<your-region>

Plugin Configuration

Piped Config

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  plugins:
  - name: ecs
    port: 7003 # any unused port
    url: file:///path/to/.piped/plugins/ecs # or remoteUrl(TBD)
    deployTargets:
      - name: production
        config:
          region: us-east-1

DeployTargetConfig

Application Config

apiVersion: pipecd.dev/v1beta1
kind: Application
spec:
  plugins:
    ecs: # same name as the one defined in `spec.plugins[].name`
      input:
        ...
      quickSync:
        ...
  pipeline:
    stages:
      ...

ECSDeploymentInput

ECSVpcConfiguration

ECSTargetGroups

Stage Config

pipeline:
  stages:
    - name: ECS_CANARY_ROLLOUT
      with:
        ...
    - name: ECS_PRIMARY_ROLLOUT
    - name: ECS_TRAFFIC_ROUTING
      with:
        ...
    - name: ECS_CANARY_CLEAN

ECS_SYNC

ECS_PRIMARY_ROLLOUT

No configuration options.

ECS_CANARY_ROLLOUT

ECS_CANARY_CLEAN

No configuration options.

ECS_ROLLBACK

No configuration options. This stage is automatically appended to the pipeline when autoRollback is enabled in the application configuration. It restores the ECS service to the previous task set.

ECS_TRAFFIC_ROUTING