Deploy from AWS CodeBuild to ECS, EKS, and Lambda

Simple explanation

Think of CodeBuild as a temporary computer that AWS spins up, runs your commands, and then shuts down. Normally those commands compile code or run tests. There is nothing stopping you from also saying “and then update the live application” at the end.

CodeBuild organizes commands into four phases: install, pre_build, build, and post_build. The first three handle setup and building. The post_build phase is where deployment steps go. After a successful build, post_build can run aws ecs update-service, kubectl set image, or aws lambda update-function-code, and the target platform picks up the change.

The mental model is: build artifact or image → success check → deployment command → wait for rollout → done. CodeBuild is just running AWS CLI commands with an IAM role that has permission to update the target service. If you can run those commands from your laptop with the right credentials, you can run them from CodeBuild.

How deploying from CodeBuild works

CodeBuild executes phases in order. Each phase runs to completion before the next starts. If a phase fails, subsequent phases are skipped — except post_build, which always runs. This is why a deployment guard is required in every post_build that contains deployment steps.

After all phases complete, CodeBuild marks the build as succeeded or failed based on exit codes. If the post_build deployment step exits non-zero — for example, because kubectl rollout status reports a failed rollout — the overall build is marked failed. This means the build result in CodeBuild accurately reflects whether the deployment succeeded or not.

When to use this

Direct deployment from CodeBuild is a good fit when:

• You are doing a simple rolling update to a single ECS service with no traffic shifting or automatic rollback needed.
• You are running a straightforward kubectl rollout on an EKS cluster where a direct image update is all that is needed.
• You are updating a Lambda function where all-at-once deployment is acceptable and you are not using aliases for traffic splitting.
• You are deploying to dev or staging where a full CodePipeline setup is not yet justified.
• Your team is new to CI/CD and wants to keep the setup simple before adding CodePipeline and CodeDeploy complexity.

When not to use this

Do not deploy directly from CodeBuild when:

• You need canary or blue/green traffic shifting. CodeBuild cannot shift 10% of traffic to a new ECS task set, wait, and then shift the rest. That is what CodeDeploy is for. See Canary Deployments and Blue/Green Deployments for those patterns.
• You need automatic rollback on a CloudWatch alarm. CodeBuild cannot watch for a spike in 5xx errors post-deployment and roll back automatically. CodeDeploy with a deployment group and alarm configuration can.
• You need a manual approval gate before production. A human approval step before the production deployment requires CodePipeline. CodeBuild is a single job that runs start to finish without pausing for a reviewer.
• You are promoting code through multiple environments. If deployment should move through dev, staging, and production with different approval rules per stage, use CodePipeline with environment stages.

CodeBuild vs CodeDeploy vs CodePipeline

These three tools serve different purposes and work best together. Beginners often confuse them because all three appear in deployment discussions.

The most common production pattern is: CodeBuild builds the Docker image and produces an artifact file, CodePipeline passes that artifact through stages, and CodeDeploy manages the actual rollout with traffic shifting. This page covers the simpler path where CodeBuild handles the deployment itself, and when that is enough.

Before you start

Before adding deployment steps to your buildspec, make sure these are in place:

• buildspec.yml knowledge. Understand the four phases and how environment variables work. See AWS CodeBuild Overview if this is new to you.
• Target platform already exists. The ECS service, EKS cluster, or Lambda function must already be running. CodeBuild updates them; it does not create them.
• IAM role permissions configured. The CodeBuild service role must have the correct permissions for the deployment target. See the IAM section below.
• Image registry ready for ECS and EKS. Container deployments require an ECR repository and a working Docker build step. See Building Docker Images with CodeBuild.
• Environment separation in place. Use separate CodeBuild projects or branch conditions for dev and production. A single project deploying everywhere on every push is a misconfiguration. See Dev vs Staging vs Production.
• Secrets handled correctly. Deployment credentials must not appear in the buildspec file. Use SSM Parameter Store or Secrets Manager references. See Secrets in CI/CD Pipelines.

Guarding deployment on build success

CODEBUILD_BUILD_SUCCEEDING is set to 1 when all previous phases succeeded, and 0 when any phase has failed. Add this check as the first command in post_build:

post_build:
  commands:
    - |
      if [ "$CODEBUILD_BUILD_SUCCEEDING" -ne 1 ]; then
        echo "Build failed. Skipping deployment."
        exit 0
      fi
    - echo "Build succeeded. Proceeding with deployment..."
    # deployment commands follow

This pattern appears at the start of every deployment example on this page. It is the single most important line in any deployment buildspec.

Deploying to Amazon ECS

An ECS deployment from CodeBuild updates a service to run a new Docker image. The process has three steps: register a new task definition revision pointing to the updated image, call update-service to apply it, and wait until the service stabilizes. For a full end-to-end pipeline with CodePipeline stages and the imagedefinitions.json artifact, see CI/CD Pipelines for Amazon ECS.

version: 0.2

env:
  variables:
    AWS_DEFAULT_REGION: "us-east-1"
    ECR_REPO_NAME: "my-app"
    ECS_CLUSTER_NAME: "my-cluster"
    ECS_SERVICE_NAME: "my-app-service"
    TASK_FAMILY: "my-app"

phases:
  pre_build:
    commands:
      - AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
      - ECR_REGISTRY="${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_DEFAULT_REGION}.amazonaws.com"
      - IMAGE_URI="${ECR_REGISTRY}/${ECR_REPO_NAME}"
      - COMMIT_HASH=$(echo $CODEBUILD_RESOLVED_SOURCE_VERSION | cut -c 1-8)
      - aws ecr get-login-password --region $AWS_DEFAULT_REGION | docker login --username AWS --password-stdin $ECR_REGISTRY

  build:
    commands:
      - docker build -t $IMAGE_URI:$COMMIT_HASH .
      - docker push $IMAGE_URI:$COMMIT_HASH

  post_build:
    commands:
      - |
        if [ "$CODEBUILD_BUILD_SUCCEEDING" -ne 1 ]; then
          echo "Build failed. Skipping deployment."
          exit 0
        fi

      # Register a new task definition revision with the updated image
      - TASK_DEF=$(aws ecs describe-task-definition --task-definition $TASK_FAMILY --query taskDefinition)
      - NEW_TASK_DEF=$(echo $TASK_DEF | python3 -c "
          import json, sys
          td = json.load(sys.stdin)
          td['containerDefinitions'][0]['image'] = '${IMAGE_URI}:${COMMIT_HASH}'
          for key in ['taskDefinitionArn','revision','status','requiresAttributes','compatibilities','registeredAt','registeredBy']:
              td.pop(key, None)
          print(json.dumps(td))
        ")
      - NEW_TASK_DEF_ARN=$(aws ecs register-task-definition --cli-input-json "$NEW_TASK_DEF" --query 'taskDefinition.taskDefinitionArn' --output text)

      # Update the service and wait for stability
      - aws ecs update-service --cluster $ECS_CLUSTER_NAME --service $ECS_SERVICE_NAME --task-definition $NEW_TASK_DEF_ARN --force-new-deployment
      - aws ecs wait services-stable --cluster $ECS_CLUSTER_NAME --services $ECS_SERVICE_NAME

      - echo "ECS deployment complete"

What aws ecs wait services-stable does: It polls the service until all running tasks use the new task definition and pass their health checks, or until a 10-minute timeout. Without this wait, CodeBuild exits immediately after calling update-service and reports success even if new tasks are crashing on startup.

Most common failure point: Missing iam:PassRole on the CodeBuild service role. Registering a new task definition requires the caller to pass the task execution role to ECS. Without this permission, register-task-definition fails with an access denied error that references the task role ARN rather than naming the missing action directly. See Fixing IAM AccessDenied Errors if you hit this.

Deploying to Amazon EKS

EKS deployments from CodeBuild use kubectl, which must be installed during the install phase. The CodeBuild service role also needs access to the cluster through IAM (to generate a kubeconfig) and through Kubernetes RBAC (to apply changes inside the cluster). For a comparison of ECS and EKS as deployment targets, see EKS vs ECS.

phases:
  install:
    commands:
      # Install kubectl
      - curl -LO "https://dl.k8s.io/release/$(curl -Ls https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
      - chmod +x kubectl && mv kubectl /usr/local/bin/

  pre_build:
    commands:
      # Generate kubeconfig for the EKS cluster
      - aws eks update-kubeconfig --name my-eks-cluster --region us-east-1
      - COMMIT_HASH=$(echo $CODEBUILD_RESOLVED_SOURCE_VERSION | cut -c 1-8)

  build:
    commands:
      - docker build -t $IMAGE_URI:$COMMIT_HASH .
      - docker push $IMAGE_URI:$COMMIT_HASH

  post_build:
    commands:
      - |
        if [ "$CODEBUILD_BUILD_SUCCEEDING" -ne 1 ]; then exit 0; fi

      # Update the deployment image and wait for rollout
      - kubectl set image deployment/my-app my-app=$IMAGE_URI:$COMMIT_HASH -n production
      - kubectl rollout status deployment/my-app -n production --timeout=5m

Granting the CodeBuild role in-cluster access

Running aws eks update-kubeconfig generates a kubeconfig but does not grant Kubernetes RBAC permissions inside the cluster. The CodeBuild role must be authorized separately. How you do that depends on how your cluster was set up.

Current recommendation: EKS access entries

Use aws eks create-access-entry to register the CodeBuild role, then attach a scoped access policy:

# Register the CodeBuild service role as a cluster principal
aws eks create-access-entry \
  --cluster-name my-eks-cluster \
  --principal-arn arn:aws:iam::123456789012:role/CodeBuildDeployRole

# Attach edit access scoped to the production namespace only
aws eks associate-access-policy \
  --cluster-name my-eks-cluster \
  --principal-arn arn:aws:iam::123456789012:role/CodeBuildDeployRole \
  --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSEditPolicy \
  --access-scope type=namespace,namespaces=production

AWS provides four managed access policies. AmazonEKSEditPolicy scoped to a specific namespace is appropriate for a deploy role. Avoid AmazonEKSClusterAdminPolicy on a build role unless the cluster is development-only.

Legacy approach: aws-auth ConfigMap

For clusters that have not migrated to access entries, add the CodeBuild role to the aws-auth ConfigMap in the kube-system namespace:

# Download the current ConfigMap
kubectl get configmap aws-auth -n kube-system -o yaml > aws-auth.yaml

# Add the CodeBuild role to mapRoles, then apply
# - rolearn: arn:aws:iam::123456789012:role/CodeBuildDeployRole
#   username: codebuild
#   groups:
#     - system:deployers  # a custom RBAC group, not system:masters

kubectl apply -f aws-auth.yaml

Most common failure point: kubectl returns Unauthorized. The kubeconfig was generated successfully (IAM permission worked) but the CodeBuild role has not been granted in-cluster access yet. See Troubleshooting Authentication Errors for step-by-step diagnosis.

Deploying to AWS Lambda

Lambda deployments are the simplest of the three: package the function code, upload it to S3, and call aws lambda update-function-code. Lambda updates are atomic. The new code is staged and then activated in a single step with no rolling update or task replacement involved.

version: 0.2

env:
  variables:
    LAMBDA_FUNCTION_NAME: "my-function"
    AWS_DEFAULT_REGION: "us-east-1"
    ARTIFACT_BUCKET: "my-artifacts-bucket"

phases:
  install:
    runtime-versions:
      python: 3.12

  build:
    commands:
      - pip install -r requirements.txt -t build/
      - cp -r src/ build/
      - cd build && zip -r ../function.zip . && cd ..

  post_build:
    commands:
      - |
        if [ "$CODEBUILD_BUILD_SUCCEEDING" -ne 1 ]; then exit 0; fi

      # Upload to S3 first (recommended for packages over 10 MB)
      - aws s3 cp function.zip s3://${ARTIFACT_BUCKET}/lambda/${CODEBUILD_RESOLVED_SOURCE_VERSION}/function.zip

      # Update the function code from S3
      - aws lambda update-function-code \
          --function-name $LAMBDA_FUNCTION_NAME \
          --s3-bucket $ARTIFACT_BUCKET \
          --s3-key lambda/$CODEBUILD_RESOLVED_SOURCE_VERSION/function.zip

      # Publish a version (required if you use Lambda aliases for traffic splitting)
      - aws lambda publish-version --function-name $LAMBDA_FUNCTION_NAME

      - echo "Lambda deployment complete"

What publish-version does: It creates an immutable snapshot of the function code at a specific version number. If you use Lambda aliases (for example, a production alias that points to a specific version) you must publish a version first and then update the alias to point to it. If you are not using aliases, this step is optional.

Most common failure point: Missing lambda:UpdateFunctionCode on the CodeBuild service role, or the S3 artifact bucket being in a different region than the Lambda function. The update-function-code call will fail with an access denied error or a region mismatch.

Using CodeBuild with CodeDeploy

When a simple rolling update is not enough — you need canary traffic shifting or automatic rollback on a CloudWatch alarm — use CodeBuild for the build step and CodeDeploy for the rollout, connected through CodePipeline. CodeBuild’s job in this pattern is to produce the artifact file that CodeDeploy expects.

# CodeBuild post_build: produce artifacts for CodeDeploy
post_build:
  commands:
    - |
      if [ "$CODEBUILD_BUILD_SUCCEEDING" -ne 1 ]; then exit 0; fi

    # imageDetail.json is used by ECS blue/green via CodeDeploy
    - printf '{"ImageURI":"%s"}' $IMAGE_URI:$COMMIT_HASH > imageDetail.json

    # imagedefinitions.json is used by the ECS rolling update deploy action
    - printf '[{"name":"my-app","imageUri":"%s"}]' $IMAGE_URI:$COMMIT_HASH > imagedefinitions.json

artifacts:
  files:
    - imagedefinitions.json
    - imageDetail.json
    - appspec.yml
    - taskdef.json

CodeDeploy picks up those artifacts and manages the traffic shift. CodeBuild does no deployment work itself in this pattern. For how CodeDeploy handles rollback when something goes wrong, see Rollbacks in CodeDeploy.

IAM permissions per deployment target

Each deployment target requires different IAM permissions on the CodeBuild service role. Scope permissions to specific resource ARNs rather than * to follow least privilege. For broader guidance on hardening the CodeBuild role, see Secure CI/CD Pipelines.