DEV-3798 Document the new ECS Strategy #856

goruha · 2026-01-26T13:26:12Z

what

Document the new ECS Strategy

why

Allow developers to follow the best practices

…o ecs-atmos-deployment * 'ecs-atmos-deployment' of github.com:cloudposse/docs: Fix release versioning by storing library docs in draft releases (#854) docs: Add RunsOn regional availability guidance to primary region decision (#851) Add redirects for all Spacelift tutorials (#853) Add redirect for Spacelift tutorial (#850)

milldr

please fix build (broken links)

…o ecs-atmos-deployment * 'ecs-atmos-deployment' of github.com:cloudposse/docs: docs: Add setup guidance for SuperAdmin auth, account IDs, and placeholders (#852) Add RunsOn license acquisition step to setup guide (#855)

docs/layers/software-delivery/software-delivery.mdx

milldr · 2026-01-26T21:12:54Z

docs/jumpstart/action-items.mdx

+      ### <StepNumber/> PATs for ECS with `ecspresso` (Deprecated)
+
+      :::note
+      This step can likely be skipped. The ecspresso-based ECS deployment approach is deprecated in favor of [ECS with Atmos](/layers/software-delivery/ecs-atmos/), which does not require these PATs.
+      :::
+


Let's just remove this whole section from this page and move all requirements for ecspresso to that ecspresso page, docs/layers/software-delivery/ecs-ecspresso/ecs-ecspresso.mdx

docs/jumpstart/action-items.mdx

milldr · 2026-01-26T21:18:20Z

docs/layers/software-delivery/ecs-atmos/setup.mdx

+    ### <StepNumber/> Deploy Platform Infrastructure
+
+    Deploy the foundational infrastructure components in your `infra` repository.
+
+    Ensure the following components are deployed in your target AWS accounts:
+
+    ```bash
+    # Deploy VPC
+    atmos terraform deploy vpc -s plat-use1-dev
+    atmos terraform deploy vpc -s plat-use1-staging
+    atmos terraform deploy vpc -s plat-use1-prod
+
+    # Deploy ECS Cluster
+    atmos terraform deploy ecs/cluster -s plat-use1-dev
+    atmos terraform deploy ecs/cluster -s plat-use1-staging
+    atmos terraform deploy ecs/cluster -s plat-use1-prod
+
+    # Deploy Github OIDC Provider
+    atmos terraform deploy github-oidc-provider -s plat-gbl-dev
+    atmos terraform deploy github-oidc-provider -s plat-gbl-staging
+    atmos terraform deploy github-oidc-provider -s plat-gbl-prod
+    ```


Instead of asking the user to redeploy these specific three components, we should have a task list that lists what is required for the ECS app. (see the "TaskList" component).

Phrasing like we have in now implies that the user has to redeploy a VPC, EKS cluster, and GitHub OIDC, but in reality, those are already all deployed by this point.

docs/layers/software-delivery/ecs-atmos/setup.mdx

milldr · 2026-01-26T21:21:04Z

docs/layers/software-delivery/ecs-atmos/setup.mdx

+    The template includes:
+    - Sample Go application with Dockerfile
+    - GitHub Actions workflows for CI/CD
+    - Terraform/OpenTofu components for ECS task definitions
+    - Atmos stack configurations for each environment


Fix formatting. Use one of the existing components. For example, TaskList, or Steps.

same for other lists:

docs/layers/software-delivery/ecs-atmos/setup.mdx

milldr · 2026-01-26T21:24:00Z

docs/layers/software-delivery/ecs-atmos/setup.mdx

+        tfstate-backend-apps:
+          vars:
+            privileged_principal_arns:
+              - !terraform.state example-app/iam-role .role.arn


fix format
https://atmos.tools/stacks/sharing-state/terraform-state

this is the valid format

docs/layers/software-delivery/ecs-atmos/setup.mdx

milldr

Please see comments.

milldr

Please see comments.

milldr · 2026-01-28T17:19:51Z

docs/layers/software-delivery/software-delivery.mdx

+### ECS with Atmos (Recommended)
+
+The [app-on-ecs-v2](https://github.com/cloudposse-examples/app-on-ecs-v2) example demonstrates a self-contained approach where workflows are defined directly in the application repository. This approach uses Atmos for configuration orchestration and OpenTofu for infrastructure management.
+
+With this approach, you need only a few workflows in your application repository:
+
+  1. `feature-branch.yml` - Build and deploy to preview environments
+  2. `preview-cleanup.yml` - Clean up preview environments when PRs close
+  3. `main-branch.yaml` - Build, deploy to dev, and create draft release
+  4. `release.yaml` - Promote and deploy to staging/production
+  5. (optional) `validate.yml` - Run validation checks
+  6. (optional) `labeler.yaml` - Auto-label PRs
+
+```console
+app-on-ecs-v2/
+├── .github/
+│   └── workflows/
+│       ├── feature-branch.yml
+│       ├── preview-cleanup.yml
+│       ├── main-branch.yaml
+│       ├── release.yaml
+│       ├── validate.yml
+│       └── labeler.yaml
+├── app/
+│   ├── main.go
+│   └── Dockerfile
+├── terraform/
+│   ├── components/
+│   │   └── ecs-task/
+│   └── stacks/
+│       ├── dev.yaml
+│       ├── staging.yaml
+│       ├── prod.yaml
+│       └── preview.yaml
+└── .opentofu-version
+```
+
+### ECS with Ecspresso (Deprecated)
+
+:::warning
+The ecspresso-based approach is deprecated. For new projects, use [ECS with Atmos](/layers/software-delivery/ecs-atmos/) instead.
+:::
+
+<details>
+<summary>View deprecated ecspresso workflow structure</summary>


these should be on the given page for the implementation. For instance move ECS with Atmos (Recommended) to the ecs-atmos.mdx and ECS with Ecspresso to ecs-ecspresso.mdx

Or if it's a high-level description, it should be included in the tab content.

milldr · 2026-01-28T17:20:39Z

examples/snippets/stacks/catalog/iam-role/example-app.yaml

fix indentation

milldr · 2026-01-28T17:21:01Z

examples/snippets/stacks/catalog/iam-role/example-app.yaml

did you add this to refarch-scaffold?

docs/layers/software-delivery/ecs-atmos/setup.mdx

milldr · 2026-01-28T17:26:29Z

docs/layers/software-delivery/ecs-atmos/setup.mdx

+    ```yaml title="terraform/stacks/deps/vpc.yaml"
+    components:
+      terraform:
+        vpc:
+          metadata:
+            component: vpc
+            type: abstract
+            terraform_workspace: "{{ .vars.tenant }}-{{ .vars.environment }}-{{ .vars.deps_stage }}"
+          backend_type: s3
+          backend:
+            s3:
+              bucket: "acme-core-gbl-root-tfstate"
+              region: "us-east-1"
+              encrypt: true
+              key: terraform.tfstate
+              acl: bucket-owner-full-control
+              assume_role:
+                role_arn: "arn:aws:iam::111111111111:role/acme-core-gbl-root-tfstate-ro"
+    ```
+
+    ```yaml title="terraform/stacks/deps/ecs-cluster.yaml"
+    components:
+      terraform:
+        vpc:
+          metadata:
+            component: vpc
+            type: abstract
+            terraform_workspace: "{{ .vars.tenant }}-{{ .vars.environment }}-{{ .vars.deps_stage }}"
+          backend_type: s3
+          backend:
+            s3:
+              bucket: "acme-core-gbl-root-tfstate"
+              region: "us-east-1"
+              encrypt: true


The second YAML example appears to have a copy-paste error—it defines vpc: instead of ecs-cluster::

components:
terraform:
ecs-cluster: # <-- Should be ecs-cluster, not vpc
metadata:
component: ecs-cluster # <-- And here
...

milldr · 2026-01-28T17:38:44Z

docs/layers/software-delivery/ecs-atmos/setup.mdx

+- [ ] Container definitions configured in `terraform/stacks/default/app.yaml`
+- [ ] `atmos terraform plan app -s preview` runs successfully
+</TaskList>
+


Add call to action for trigger workflows. See the CTA component

milldr · 2026-01-28T17:40:42Z

docs/layers/software-delivery/ecs-atmos/triggering-workflows.mdx

+    ### <StepNumber/> Create a Pull Request
+
+    Create a PR and add the `deploy` label to deploy a preview environment:
+
+    ```bash
+    git checkout -b feature/test-preview
+    # Make changes
+    git push origin feature/test-preview
+    ```
+
+    Then add the `deploy` label to the PR in GitHub.
+  </Step>


Where can the user see this preview environment? (github ui has deployment link)

What are the different CI or CD steps that are being run for a preview environment? (add simple explanation)

What cluster is this deployed to by default? (dev)

milldr · 2026-01-28T17:40:54Z

docs/layers/software-delivery/ecs-atmos/triggering-workflows.mdx

+
+    Then add the `deploy` label to the PR in GitHub.
+  </Step>
+


PR clean up steps?

milldr · 2026-01-28T17:41:23Z

docs/layers/software-delivery/ecs-atmos/triggering-workflows.mdx

+    ### <StepNumber/> Merge PR into Main Branch
+
+    Push any change to the `main` branch to trigger the main branch workflow:
+
+    ```bash
+    git add .
+    git commit -m "Initial setup"
+    git push origin main
+    ```
+
+    This will:
+    - Build and push a Docker image to ECR
+    - Deploy to the `dev` environment
+    - Create a draft release


What CI or CD steps are being run now?

Where can the engineer see the deployment?

What ECS cluster is this deployed to? How is that determined?

milldr · 2026-01-28T17:41:58Z

docs/layers/software-delivery/ecs-atmos/triggering-workflows.mdx

+  <Step>
+    ### <StepNumber/> Publish a Release
+
+    Edit the draft release created by the main branch workflow and click "Publish release". This will:
+    - Promote the Docker image tag
+    - Deploy to `staging`
+    - Wait for approval (if configured)
+    - Deploy to `prod`
+  </Step>
+</Steps>


Again, now what CI / CD steps are being run?

Where can the engineer see the deployment?

How do we configure approval?

Co-authored-by: Dan Miller <miller0daniel@gmail.com>

goruha added 3 commits January 12, 2026 18:21

Added base docs for ECS atmos deployment

c6d4422

Added ecs deprication notes

18ebf95

Added ecs atmos deployment

b9f25df

goruha had a problem deploying to preview January 26, 2026 13:26 — with GitHub Actions Failure

Merge branch 'master' into ecs-atmos-deployment

9b5cf7a

goruha temporarily deployed to preview January 26, 2026 13:28 — with GitHub Actions Inactive

goruha added 2 commits January 26, 2026 21:03

Documented ECS deployment with atmos

804d8fd

goruha had a problem deploying to preview January 26, 2026 20:04 — with GitHub Actions Error

goruha requested a review from milldr January 26, 2026 20:04

Merge branch 'master' into ecs-atmos-deployment

1609813

goruha had a problem deploying to preview January 26, 2026 20:04 — with GitHub Actions Failure

milldr requested changes Jan 26, 2026

View reviewed changes

goruha added 2 commits January 26, 2026 21:32

Documented ECS deployment with atmos

e1a0628

goruha temporarily deployed to preview January 26, 2026 20:33 — with GitHub Actions Inactive

milldr reviewed Jan 26, 2026

View reviewed changes

docs/layers/software-delivery/software-delivery.mdx Show resolved Hide resolved

milldr reviewed Jan 26, 2026

View reviewed changes

docs/jumpstart/action-items.mdx Show resolved Hide resolved

milldr reviewed Jan 26, 2026

View reviewed changes

docs/layers/software-delivery/ecs-atmos/setup.mdx Show resolved Hide resolved

milldr reviewed Jan 26, 2026

View reviewed changes

docs/layers/software-delivery/ecs-atmos/setup.mdx Outdated Show resolved Hide resolved

milldr reviewed Jan 26, 2026

View reviewed changes

docs/layers/software-delivery/ecs-atmos/setup.mdx Outdated Show resolved Hide resolved

milldr reviewed Jan 26, 2026

View reviewed changes

docs/layers/software-delivery/ecs-atmos/setup.mdx Outdated Show resolved Hide resolved

milldr reviewed Jan 26, 2026

View reviewed changes

docs/layers/software-delivery/ecs-atmos/setup.mdx Outdated Show resolved Hide resolved

milldr requested changes Jan 26, 2026

View reviewed changes

goruha added 2 commits January 27, 2026 14:23

Added software delivery

f093f12

Address PR comments

2051351

goruha temporarily deployed to preview January 27, 2026 15:53 — with GitHub Actions Inactive

milldr requested changes Jan 28, 2026

View reviewed changes

Merge branch 'master' into ecs-atmos-deployment

46b490f

milldr temporarily deployed to preview January 28, 2026 17:43 — with GitHub Actions Inactive

Update docs/layers/software-delivery/ecs-atmos/setup.mdx

98e4321

Co-authored-by: Dan Miller <miller0daniel@gmail.com>

goruha had a problem deploying to preview January 29, 2026 19:15 — with GitHub Actions Error

Merge branch 'master' into ecs-atmos-deployment

f62390b

goruha deployed to preview January 29, 2026 19:15 — with GitHub Actions View deployment

Uh oh!

DEV-3798 Document the new ECS Strategy #856

Are you sure you want to change the base?

DEV-3798 Document the new ECS Strategy #856

Uh oh!

Conversation

goruha commented Jan 26, 2026

what

why

Uh oh!

milldr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

milldr left a comment

Choose a reason for hiding this comment

Uh oh!

milldr 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!

Choose a reason for hiding this comment

Uh oh!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants