Skip to content
Tutorials Center
My learning

Topics

Lesson 65 of 70 ยท Real-world projects

Project: Containerized App with CI/CD

Build a containerized web app on AWS: ECR, ECS Fargate behind an ALB, and a GitHub Actions pipeline that deploys with OIDC and no stored keys. Includes simulators.

In this project you ship a small web service as a container. Every push to the main branch builds an image, stores it in a private registry, and rolls it out to a service that runs behind a load balancer, with no servers to manage and no long-lived AWS keys stored anywhere. It is the most common modern way to run a stateless app on AWS, and it ties together many earlier lessons: containers on ECS and Fargate, load balancers, IAM roles and CloudWatch.

AWS cannot run on this site, so every command, JSON document and workflow file below is read-only. The runnable examples are Python stand-ins: a rolling-deployment simulator, a canary-with-rollback simulator and a checker for the OIDC trust condition. They model the ideas, not the real services, and each one says what it simplifies.

What we are building

flowchart LR
    Dev["Developer<br/>git push main"] --> GH["GitHub Actions"]
    GH -- "OIDC token" --> STS["AWS STS<br/>temporary credentials"]
    GH -- "docker push" --> ECR["ECR repository<br/>app:commit-sha"]
    GH -- "register task definition<br/>update service" --> ECS["ECS service<br/>Fargate tasks"]
    ECR -- "image pull" --> ECS
    User["Users"] --> ALB["Application Load Balancer"]
    ALB --> ECS
    ECS --> CW["CloudWatch Logs"]

The pipeline pushes an image to ECR and tells ECS to run it; users reach the tasks through the ALB.

The pieces:

  • ECR (Elastic Container Registry) stores the images. Each image is tagged with the Git commit SHA, so you always know which code is running.
  • An ECS task definition describes the container: image, CPU, memory, ports, environment, log destination.
  • An ECS service keeps the desired number of tasks running on Fargate and replaces any that fail.
  • An ALB spreads traffic across the tasks and checks their health.
  • GitHub Actions is the CI/CD system here. (CodePipeline with CodeBuild and CodeDeploy is the all-AWS alternative; the ideas are the same.)
  • OIDC federation lets the workflow prove who it is to AWS and receive short-lived credentials, instead of you pasting an access key into GitHub secrets.

Step 1: the registry

Create a private repository with immutable tags (a tag can never be overwritten) and scan on push:

Terminal
aws ecr create-repository \
  --repository-name shop-api \
  --image-tag-mutability IMMUTABLE \
  --image-scanning-configuration scanOnPush=true

Immutable tags matter for rollbacks. If shop-api:v12 could be overwritten, "roll back to v12" would mean nothing. Commit SHAs are naturally unique, which is why pipelines use them.

You will also want an ECR lifecycle policy that expires old images, otherwise storage costs creep up. The image-layer storage is billed per GB-month.

Step 2: the task definition

A Fargate task definition must use the awsvpc network mode and declare CPU and memory at the task level. This is the file the pipeline renders and registers on every deploy (the image value is replaced with the new tag):

JSON
{
  "family": "shop-api",
  "requiresCompatibilities": ["FARGATE"],
  "networkMode": "awsvpc",
  "cpu": "256",
  "memory": "512",
  "executionRoleArn": "arn:aws:iam::123456789012:role/shop-api-execution",
  "taskRoleArn": "arn:aws:iam::123456789012:role/shop-api-task",
  "containerDefinitions": [
    {
      "name": "web",
      "image": "123456789012.dkr.ecr.eu-west-1.amazonaws.com/shop-api:placeholder",
      "essential": true,
      "portMappings": [{ "containerPort": 8080 }],
      "environment": [{ "name": "APP_ENV", "value": "production" }],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/shop-api",
          "awslogs-region": "eu-west-1",
          "awslogs-stream-prefix": "web"
        }
      }
    }
  ]
}

Notice the two roles, because they are easy to mix up:

  • The execution role is used by ECS itself to pull the image from ECR and write logs to CloudWatch.
  • The task role is what your application code uses when it calls AWS (for example reading a DynamoDB table). Give it only what the app needs, as taught in IAM best practices.

Step 3: the service, the ALB and the health check

The service ties tasks to a target group of the load balancer. Tasks run in private subnets; only the ALB lives in public subnets (the layout from the three-tier project):

Terminal
aws ecs create-service \
  --cluster shop \
  --service-name shop-api \
  --task-definition shop-api \
  --desired-count 3 \
  --launch-type FARGATE \
  --network-configuration "awsvpcConfiguration={subnets=[subnet-aaa,subnet-bbb,subnet-ccc],securityGroups=[sg-app],assignPublicIp=DISABLED}" \
  --load-balancers "targetGroupArn=arn:aws:elasticloadbalancing:eu-west-1:123456789012:targetgroup/shop-api/abc123,containerName=web,containerPort=8080" \
  --deployment-configuration "minimumHealthyPercent=100,maximumPercent=200,deploymentCircuitBreaker={enable=true,rollback=true}"

Three settings deserve attention:

  • The security group sg-app should allow inbound traffic on port 8080 only from the ALB's security group, never from the internet.
  • The ALB health check path (for example /health) decides when a new task may receive traffic and when an old one is considered broken. Make it cheap and honest: return 200 only when the app can really serve.
  • The deployment configuration controls how a rolling update behaves. Let's simulate it.

Rolling updates: minimum healthy and maximum percent

When you register a new task definition revision and update the service, ECS replaces tasks gradually. minimumHealthyPercent is the lowest share of the desired count that must stay healthy. maximumPercent is the upper limit on how many tasks (old plus new) may exist at once. Together they decide how fast the rollout goes and whether capacity dips.

This stand-in models one step as: new tasks that were starting become healthy, old tasks are stopped as far as the minimum allows, then new tasks are started as far as the maximum allows. Real ECS also waits for health checks and drains connections, so it is slower and subtler.

Python Rolling deployment simulator

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Read the three runs as three trade-offs. The default 100/200 never drops below full capacity but briefly runs up to twice as many tasks, so it needs headroom (and costs a little more during the deploy). The 50/100 setting never exceeds the desired count, so it costs nothing extra, but half the capacity disappears while it rolls. The 100/100 setting is a trap: ECS may neither start an extra task nor stop a healthy one, so nothing can move. Real ECS also refuses or stalls on such a combination, which is why the defaults are what they are.

Failing safely: the deployment circuit breaker

What if the new image crashes on startup? Without protection, ECS keeps trying to start tasks that die. With the deployment circuit breaker enabled, ECS counts failed task launches. When the failures reach a threshold, it marks the deployment failed and, with rollback=true, returns the service to the last version that worked. Your users keep being served by the old tasks the whole time, because minimumHealthyPercent=100 stopped ECS from removing them before replacements were healthy.

If you need finer control than rolling updates, ECS also supports blue/green deployments through CodeDeploy, and in newer setups built-in blue/green and canary strategies: a second set of tasks is started and traffic is shifted gradually, with alarms that can trigger a rollback. The next stand-in models traffic shifting with a health gate.

Python Canary traffic shifting with automatic rollback

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Release 1.4.0 stays under the limit at every step and is promoted. Release 1.5.0 looks fine at 10% but breaks at 100% in the third step; a larger share of traffic exposes problems that a small canary hides, which is why the early steps are small and the final step is gated too. Release 1.5.1 passes at 50% with 1.9% errors, then trips at 100%. The point of the gate is that a machine decides quickly, using a CloudWatch alarm in the real system, rather than a person noticing the dashboard later.

Step 4: keyless deploys with GitHub OIDC

Here is the part that removes the biggest risk of CI: stored AWS keys. GitHub can issue each workflow run a signed identity token (an OpenID Connect token). AWS trusts GitHub as an identity provider, so the workflow trades that token for temporary credentials with sts:AssumeRoleWithWebIdentity. No secret is stored in GitHub, and the credentials expire on their own.

One-time setup: create an IAM OIDC identity provider for https://token.actions.githubusercontent.com with the audience sts.amazonaws.com, then create a role whose trust policy names exactly which repositories and branches may assume it:

JSON
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "token.actions.githubusercontent.com:sub": "repo:acme/shop-api:ref:refs/heads/main"
        }
      }
    }
  ]
}

The sub (subject) condition is the lock. Without it, any GitHub repository in the world could ask to assume your role. Test the logic of that lock with a stand-in; it uses the same wildcard rules as StringLike:

Python Does this GitHub run match the trust policy?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Only the run on main passes the strict rule. The second half shows why repo:acme/shop-api:* is too loose: every branch and every pull request could then deploy to production. A pull request from a fork could even run workflow code you did not write, so keep pull requests away from deploy roles. A common refinement is a GitHub environment named production with required reviewers; its subject looks like repo:acme/shop-api:environment:production.

Step 5: the workflow

Put this in .github/workflows/deploy.yml. The role that the workflow assumes needs permission to push to the one ECR repository, register task definitions, update the one service, and iam:PassRole for the two task roles, and nothing else.

YAML
name: deploy
on:
  push:
    branches: [main]

permissions:
  id-token: write   # allows requesting the OIDC token
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-deploy-shop-api
          aws-region: eu-west-1

      - id: ecr
        uses: aws-actions/amazon-ecr-login@v2

      - name: Build and push
        env:
          IMAGE: ${{ steps.ecr.outputs.registry }}/shop-api:${{ github.sha }}
        run: |
          docker build -t "$IMAGE" .
          docker push "$IMAGE"
          echo "image=$IMAGE" >> "$GITHUB_OUTPUT"
        id: build

      - id: render
        uses: aws-actions/amazon-ecs-render-task-definition@v1
        with:
          task-definition: ecs/task-definition.json
          container-name: web
          image: ${{ steps.build.outputs.image }}

      - uses: aws-actions/amazon-ecs-deploy-task-definition@v2
        with:
          task-definition: ${{ steps.render.outputs.task-definition }}
          service: shop-api
          cluster: shop
          wait-for-service-stability: true

A good pipeline also runs your tests before the image is pushed, scans the image, and treats wait-for-service-stability as the last gate: the job turns red when the deployment fails or rolls back, so nobody believes a broken release shipped. Pin third-party actions to a full commit SHA if your security rules demand it.

Operating it

  • Logs. The awslogs driver sends stdout and stderr to the log group; use Logs Insights to search them (CloudWatch lesson).
  • Scaling. Add an Application Auto Scaling target-tracking policy on average CPU or on requests per target (Auto Scaling lesson).
  • Secrets. Reference Secrets Manager or Parameter Store values in the task definition's secrets list; never bake them into the image (Secrets lesson).
  • Cost. A Fargate task is billed per second for the CPU and memory it reserves, plus the ALB's hourly and usage charges. A NAT gateway for image pulls and outbound calls can become the biggest line; VPC endpoints for ECR and S3 can avoid it (NAT and endpoints).
  • Rollback by hand. Update the service to the previous task definition revision; because image tags are immutable, it points at exactly the old build.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the main benefit of GitHub OIDC federation over storing an access key in GitHub secrets?

    The workflow exchanges a signed token for temporary credentials through STS. There is no stored key to rotate or steal, and the role's trust policy limits which repositories and branches can use it.
  2. 2. Which ECS role does the application code use when it calls other AWS services, such as DynamoDB?

    The execution role is for ECS itself (pulling images, writing logs). The task role is assumed by your container code, so it should carry the application's own permissions.
  3. 3. A service uses minimumHealthyPercent=100 and maximumPercent=100. What happens during a deployment?

    With no room above the desired count and no allowed dip below it, ECS has no legal move. Leave headroom with a maximum above 100, or allow a lower minimum.
  4. 4. Why does the trust policy of the deploy role include a condition on the sub claim?

    Without a subject condition, any GitHub workflow could request the role. A pattern like repo:acme/shop-api:ref:refs/heads/main limits it to one repository and branch.
  5. 5. What does the deployment circuit breaker with rollback enabled do?

    ECS counts failed launches for the new revision. At the threshold it fails the deployment and, with rollback on, restores the previous task definition so users stay on working tasks.

Summary

  • The flow is: push to main, build an image tagged with the commit SHA, push to ECR, render a new task definition, update the ECS service, wait for it to become stable.
  • Fargate tasks run in private subnets behind an ALB; the app's security group accepts traffic only from the ALB.
  • Use two roles correctly: the execution role pulls images and writes logs, the task role is the app's own identity.
  • minimumHealthyPercent and maximumPercent shape a rolling update; 100/200 keeps capacity but needs headroom. The circuit breaker rolls a broken release back.
  • GitHub OIDC replaces stored keys with temporary credentials, and a strict sub condition is what keeps the role safe.
  • Immutable image tags make rollbacks exact.

Next: Practice Exercises with Solutions