[ECS-Plugin] Document for user by armistcxy · Pull Request #6712 · pipe-cd/pipecd

armistcxy · 2026-04-23T15:43:08Z

What this PR does: Adds user documentation for the ECS plugin (docs-v1.0.x) covering:

Prerequisites: piped configuration and IAM permissions (deployment role, task execution role, task role)
Definition files: task definition file and service definition file format, supported fields, and known limitations
Deployment modes: service (with ELB, service discovery) and standalone task
Deployment strategy selection: how the plugin automatically chooses between quick sync and pipeline sync based on container image changes
Pipeline sync stages: ECS_PRIMARY_ROLLOUT, ECS_CANARY_ROLLOUT, ECS_TRAFFIC_ROUTING, ECS_CANARY_CLEAN, ECS_ROLLBACK
Application live state: sync status, resource tree, resource metadata, and health status
Plan preview: how diff is computed for ECS applications
Migration guide from v0: key behavioral changes including the shift to EXTERNAL deployment controller, drift detection via commit hash tag, and rollback behavior changes

Why we need it:

Which issue(s) this PR fixes:

Fixes #6443

Does this PR introduce a user-facing change?:

How are users affected by this change:
Is this breaking change:
How to migrate (if breaking change):

Signed-off-by: Hoang Ngo <adlehoang118@gmail.com>

…on file" Signed-off-by: Hoang Ngo <adlehoang118@gmail.com>

Signed-off-by: Hoang Ngo <adlehoang118@gmail.com>

codecov · 2026-04-24T03:43:15Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 37.92%. Comparing base (fdec720) to head (c93da0a).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #6712      +/-   ##
==========================================
+ Coverage   29.48%   37.92%   +8.44%     
==========================================
  Files         593       61     -532     
  Lines       63440     5331   -58109     
==========================================
- Hits        18706     2022   -16684     
+ Misses      43289     3193   -40096     
+ Partials     1445      116    -1329

Flag	Coverage Δ
.	`?`
.-pkg-app-pipedv1-plugin-analysis	`32.43% <ø> (ø)`
.-pkg-app-pipedv1-plugin-ecs	`?`
.-pkg-app-pipedv1-plugin-kubernetes	`?`
.-pkg-app-pipedv1-plugin-kubernetes_multicluster	`?`
.-pkg-app-pipedv1-plugin-scriptrun	`54.83% <ø> (ø)`
.-pkg-app-pipedv1-plugin-terraform	`?`
.-pkg-app-pipedv1-plugin-wait	`33.04% <ø> (ø)`
.-pkg-app-pipedv1-plugin-waitapproval	`52.71% <ø> (ø)`
.-pkg-plugin-sdk	`50.34% <ø> (ø)`
.-tool-actions-gh-release	`19.23% <ø> (ø)`
.-tool-actions-plan-preview	`?`
.-tool-codegen-protoc-gen-auth	`0.00% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

eeshaanSA

Hello @armistcxy, is there no way to split this into multiple PRs? This would ease the reviewers, and eventually result in a faster merge.

armistcxy · 2026-04-27T15:17:40Z

Hi @eeshaanSA, really sorry for this big PR. I think I can't split this into multiple PRs.

You can review only the section you think important, I have noted the outline above

Also use make run/site for better readability when reviewing

eeshaanSA · 2026-04-30T08:07:32Z

Also use make run/site for better readability when reviewing

For this, I will have to checkout your PR or serve it on GitHub Codespaces (We have access to CoPilot Enterprise as Maintainers).

Please give me sometime, I will try reviewing it.

github-actions · 2026-05-31T00:56:12Z

This PR is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 7 days.

rahulshendre

apart from the nits, overall looks good to me @armistcxy
also SDK struct names on lines 94/121 need user-facing rewrites, also ECSTargetGroups and ECSTargetGroup tables have 3 columns (Field, Type, Description) while every other reference table has 4 (Field, Type, Default, Description). we should add a default column to both same for ECSDeployTargetConfig which is also missing Default.

rahulshendre · 2026-05-31T13:47:06Z

+- 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.
+
+> Standalone tasks always use quick sync. Pipeline sync is not supported for standalone tasks.


this is repeated on the line 200 as well. We should keep just the line 200

rahulshendre · 2026-05-31T13:49:33Z

+- You need manual approval gates before full rollout.
+- You want automated analysis (metrics, logs) to validate the new version before promoting it.
+
+## Quick sync


this should be ### as they're subsections of - choosing a deployment strategy

Actually, the content of "Choosing a deployment strategy" focuses on deciding between quick sync and pipeline sync, it explains which option is more appropriate for specific use cases. And the detailed configuration and setup instructions for each strategy are covered in separate ## sections below

makes sense, please ignore this one

rahulshendre · 2026-05-31T13:54:04Z

+
+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:


lowercase "piped"

also in back ticks please. All other occurrences as well. piped

rahulshendre · 2026-05-31T13:54:32Z

+
+## 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.


lowercase "piped"

actually there're many places in the document also put "Piped", maybe if we need consistency we should change to pipedv1, do you think it's ok ?

just piped in backticks, consistent with what @eeshaanSA said above

rahulshendre · 2026-05-31T13:56:35Z

+
+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.
+
+> 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.


this should have Note: prefix, for consistency

rahulshendre · 2026-05-31T13:57:16Z

+
+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.
+
+> Standalone tasks always use quick sync. Pipeline sync is not supported for standalone tasks.


this too the note prefix

Nice catch, I will fix it

rahulshendre · 2026-05-31T14:01:32Z

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


Add ```text to the resource tree code block, without it, renderers may mangle the └── characters.

as far as I remember when I rendered there's nothing wrong with it. Let me check when I complete all the fixes above

Seems good with nothing wrong

rahulshendre · 2026-05-31T14:06:05Z

+|---|---|
+| Task definition diff | Unified diff between the running `taskdef` file and the target `taskdef` file |
+| Service definition diff | Unified diff between the running `servicedef` file and the target `servicedef` file (only shown when `serviceDefinitionFile` is set) |
+| Summary | A one-line summary: `task definition changed`, `service definition changed`, or `No changes were detected` |


No changes were detected has a trailing period while every other entry doesn't, we should remove it

Hmm, I don't see a trailing period in "No changes were detected". Could you point me to where you're seeing it? The only inconsistency I notice is the capitalization though ^^

my bad, you can proceed with the capitalization fixes :D

Will later fix with chore PR

armistcxy · 2026-05-31T14:32:00Z

Thanks @rahulshendre for your review, I will take a look

eeshaanSA

Apart from the nits, everything largely looks good.

eeshaanSA · 2026-05-31T14:34:51Z

+
+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:


also in back ticks please. All other occurrences as well. piped

eeshaanSA · 2026-05-31T14:38:15Z

+
+### Blue/Green deployment
+
+Deploys the new version (green) at full scale alongside the old version (blue), then cuts over all traffic atomically after approval. Requires **two ALB target groups** (primary and canary) both attached to the same listener.


automatically*

eeshaanSA · 2026-05-31T14:39:55Z

+
+The application config format changes in two ways: the `kind` field and the location of ECS-specific fields.
+
+**v0 app config:**


better to say: "v0 application.config.yaml file"

or

"application configuration file"

eeshaanSA · 2026-05-31T14:40:07Z

+      - name: ECS_CANARY_CLEAN
+```
+
+**v1 app config:**


same as above

eeshaanSA · 2026-05-31T14:41:12Z

+
+## 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.


How about putting everything related to v0 in one section? Like in one the sections above? You can make multiple subsections there? thoughts?

Hard to make decision here because I'm developing a feature supporting new controller type. So let just keep this document version flat and I will need your consulting later ^^

eeshaanSA · 2026-05-31T14:41:40Z

+
+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: only the old PRIMARY task set is removed


better to have a cleaner title, and say the rest in in the body of the section

eeshaanSA · 2026-05-31T14:44:32Z

Overall looks good. @armistcxy

But, some sections can be actually separated into different files, for example, the config reference, migration.

of course, it is just a readability thing, I know this is urgent, so we can have it merged, and then later create a section for each plugin, and multiple files under it.

Signed-off-by: Hoang Ngo <adlehoang118@gmail.com>

armistcxy · 2026-06-07T06:31:04Z

@eeshaanSA @rahulshendre I think it's all good now, some changes will be postponed to the next version of ECS plugin

github-actions Bot added the area/docs label Apr 23, 2026

armistcxy added 10 commits April 24, 2026 10:40

docs: user guide for using ecs plugin

64325ef

Signed-off-by: Hoang Ngo <adlehoang118@gmail.com>

docs: document livestate and planpreview feature for ecs plugin

bdd7543

Signed-off-by: Hoang Ngo <adlehoang118@gmail.com>

docs: add changes from v0 section

28b8364

Signed-off-by: Hoang Ngo <adlehoang118@gmail.com>

docs: add migrating from v0

62eaf6b

Signed-off-by: Hoang Ngo <adlehoang118@gmail.com>

docs: note about iam role

ea647b1

Signed-off-by: Hoang Ngo <adlehoang118@gmail.com>

docs: add section about task definition and service file

f35c98d

Signed-off-by: Hoang Ngo <adlehoang118@gmail.com>

docs: not need docs for ecs controller yet

af5aba9

Signed-off-by: Hoang Ngo <adlehoang118@gmail.com>

chore: move "Service definition requirements" below "Service definiti…

39f2dd4

…on file" Signed-off-by: Hoang Ngo <adlehoang118@gmail.com>

docs: note about support for ecs deployment controller

86227d2

Signed-off-by: Hoang Ngo <adlehoang118@gmail.com>

docs: note about determining strategy when syncing

c93da0a

Signed-off-by: Hoang Ngo <adlehoang118@gmail.com>

armistcxy force-pushed the ecs-plugin/user-docs branch from 7ca28b5 to c93da0a Compare April 24, 2026 03:40

armistcxy marked this pull request as ready for review April 24, 2026 03:42

armistcxy requested review from a team as code owners April 24, 2026 03:42

armistcxy requested review from Warashi, ffjlabo, khanhtc1202 and t-kikuc April 24, 2026 03:42

armistcxy mentioned this pull request Apr 27, 2026

[LFX Mentorship T-1 2026] Implement Amazon ECS Plugin for pipedv1 #6443

Open

eeshaanSA reviewed Apr 27, 2026

View reviewed changes

github-actions Bot added the Stale label May 31, 2026

armistcxy removed the Stale label May 31, 2026

rahulshendre reviewed May 31, 2026

View reviewed changes

eeshaanSA requested changes May 31, 2026

View reviewed changes

armistcxy added 6 commits June 7, 2026 11:19

fix: add prefix **Note:** for every quote

584671a

Signed-off-by: Hoang Ngo <adlehoang118@gmail.com>

chore: change Piped to piped

9fcfa32

Signed-off-by: Hoang Ngo <adlehoang118@gmail.com>

chore: lowercase v1

cd2577d

Signed-off-by: Hoang Ngo <adlehoang118@gmail.com>

chore: typo (atomatically -> automatically)

10a6ead

Signed-off-by: Hoang Ngo <adlehoang118@gmail.com>

chore: application config -> application configuration file

bcb5918

Signed-off-by: Hoang Ngo <adlehoang118@gmail.com>

fix: make the changing titles clean

4594ad0

Signed-off-by: Hoang Ngo <adlehoang118@gmail.com>

armistcxy force-pushed the ecs-plugin/user-docs branch from 557ce62 to 4594ad0 Compare June 7, 2026 04:49


		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:


		## 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.


		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.

		> 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.


		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.

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


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

		```


		### Blue/Green deployment

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


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

		v0 app config:


		## 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.


		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: only the old PRIMARY task set is removed

Conversation

armistcxy commented Apr 23, 2026

Uh oh!

codecov Bot commented Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

eeshaanSA left a comment

Choose a reason for hiding this comment

Uh oh!

armistcxy commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

eeshaanSA commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented May 31, 2026

Uh oh!

rahulshendre left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

armistcxy May 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

armistcxy commented May 31, 2026

Uh oh!

eeshaanSA left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov Bot commented Apr 24, 2026 •

edited

Loading

armistcxy commented Apr 27, 2026 •

edited

Loading

eeshaanSA commented Apr 30, 2026 •

edited

Loading

armistcxy May 31, 2026 •

edited

Loading