ECR Authentication

This guide shows you how to configure AWS Elastic Container Registry (ECR) authentication using Atmos integrations for automatic Docker login.

Overview

Atmos provides native ECR authentication through the integrations system. Integrations are client-only credential materializations that derive credentials from your AWS identity for service-specific access.

Key benefits:

• Automatic login: ECR credentials are provisioned when you authenticate with an identity
• Multi-registry support: Configure multiple ECR registries across accounts and regions
• Zero configuration: Credentials are written to ~/.docker/config.json and work immediately with Docker
• CI/CD ready: Works seamlessly in GitHub Actions, GitLab CI, and other pipelines

Quick Start

Basic ECR Integration

The simplest ECR setup links an integration to an existing AWS identity:

auth:
  providers:
    company-sso:
      kind: aws/iam-identity-center
      region: us-east-1
      start_url: https://company.awsapps.com/start/

  identities:
    dev-admin:
      kind: aws/permission-set
      via:
        provider: company-sso
      principal:
        name: AdministratorAccess
        account: dev

  integrations:
    dev/ecr:
      kind: aws/ecr
      via:
        identity: dev-admin
      spec:
        registry:
          account_id: "123456789012"
          region: us-east-2

Authenticate and use Docker:

# Login triggers ECR automatically (auto_provision defaults to true)
atmos auth login dev-admin

# Docker commands now work
docker pull 123456789012.dkr.ecr.us-east-2.amazonaws.com/my-app:latest
docker push 123456789012.dkr.ecr.us-east-2.amazonaws.com/my-app:v1.0.0

Understanding Integrations

Why Integrations vs Identities?

ECR login is fundamentally different from AWS identities:

Concept	IAM User/Role	Docker Login (ECR)
Stored identity object	Yes	No
Policy attachment	Yes	No
Server-side lifecycle	Yes	No
Client-only materialization	No	Yes

Integrations are things that use an identity to materialize client-side credentials. This separation keeps your configuration clean and explicit.

Integration Configuration

Each ECR integration requires:

integrations:
  my-ecr-integration:           # Unique name for this integration
    kind: aws/ecr               # Integration type
    via:
      identity: my-identity     # Which identity provides AWS credentials
    spec:
      auto_provision: true      # Auto-trigger on identity login (default)
      registry:
        account_id: "123456789012"
        region: us-east-2

Common Patterns

Multi-Environment Setup

Configure separate integrations for each environment:

auth:
  identities:
    dev-admin:
      kind: aws/permission-set
      via:
        provider: company-sso
      principal:
        name: AdministratorAccess
        account: dev

    prod-deployer:
      kind: aws/permission-set
      via:
        provider: company-sso
      principal:
        name: ContainerDeploy
        account: production

  integrations:
    # Dev environment ECR
    dev/ecr:
      kind: aws/ecr
      via:
        identity: dev-admin
      spec:
        registry:
          account_id: "111111111111"
          region: us-east-2

    # Production ECR
    prod/ecr:
      kind: aws/ecr
      via:
        identity: prod-deployer
      spec:
        registry:
          account_id: "222222222222"
          region: us-east-1

Usage:

# Development work
atmos auth login dev-admin
docker pull 111111111111.dkr.ecr.us-east-2.amazonaws.com/my-app:dev

# Production deployment
atmos auth login prod-deployer
docker push 222222222222.dkr.ecr.us-east-1.amazonaws.com/my-app:v1.0.0

Multi-Region Registries

One identity can link to multiple ECR registries across regions:

auth:
  identities:
    platform-admin:
      kind: aws/permission-set
      via:
        provider: company-sso
      principal:
        name: PlatformAdmin
        account: platform

  integrations:
    platform/ecr/us-east:
      kind: aws/ecr
      via:
        identity: platform-admin
      spec:
        registry:
          account_id: "333333333333"
          region: us-east-1

    platform/ecr/us-west:
      kind: aws/ecr
      via:
        identity: platform-admin
      spec:
        registry:
          account_id: "333333333333"
          region: us-west-2

    platform/ecr/eu-west:
      kind: aws/ecr
      via:
        identity: platform-admin
      spec:
        registry:
          account_id: "333333333333"
          region: eu-west-1

Login to all regions at once:

atmos auth login platform-admin
# ✓ ECR login: 333333333333.dkr.ecr.us-east-1.amazonaws.com (expires in 11h59m)
# ✓ ECR login: 333333333333.dkr.ecr.us-west-2.amazonaws.com (expires in 11h59m)
# ✓ ECR login: 333333333333.dkr.ecr.eu-west-1.amazonaws.com (expires in 11h59m)

Cross-Account Access

Access ECR registries in different AWS accounts:

auth:
  integrations:
    # Your account's ECR
    my-account/ecr:
      kind: aws/ecr
      via:
        identity: dev-admin
      spec:
        registry:
          account_id: "111111111111"
          region: us-east-2

    # Shared services account ECR (requires cross-account permissions)
    shared/ecr:
      kind: aws/ecr
      via:
        identity: dev-admin
      spec:
        registry:
          account_id: "999999999999"
          region: us-east-1

Optional Integrations

Disable auto-provisioning for integrations you only need occasionally:

auth:
  integrations:
    # Always provision on login
    dev/ecr/primary:
      kind: aws/ecr
      via:
        identity: dev-admin
      spec:
        registry:
          account_id: "123456789012"
          region: us-east-2

    # Only provision when explicitly requested
    dev/ecr/legacy:
      kind: aws/ecr
      via:
        identity: dev-admin
      spec:
        auto_provision: false    # Don't auto-trigger
        registry:
          account_id: "123456789012"
          region: eu-west-1

Usage:

# Normal login only provisions primary ECR
atmos auth login dev-admin

# Explicitly login to legacy ECR when needed
atmos auth ecr-login dev/ecr/legacy

Standalone ECR Login

You can trigger ECR login independently of identity authentication:

By Integration Name

atmos auth ecr-login dev/ecr

By Identity

Trigger all integrations linked to an identity:

atmos auth ecr-login --identity dev-admin

By Explicit Registry URL

Use current AWS credentials from the environment:

# Single registry
atmos auth ecr-login --registry 123456789012.dkr.ecr.us-east-2.amazonaws.com

# Multiple registries
atmos auth ecr-login \
  --registry 123456789012.dkr.ecr.us-east-2.amazonaws.com \
  --registry 987654321098.dkr.ecr.us-west-2.amazonaws.com

CI/CD Integration

GitHub Actions

# .github/workflows/build.yaml
name: Build and Push

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read

    steps:
      - uses: actions/checkout@v4

      - name: Install Atmos
        uses: cloudposse/github-action-setup-atmos@v2

      - name: Authenticate and Login to ECR
        run: |
          # Option A: Identity login (triggers auto-provisioned integrations)
          atmos auth login ci-deployer

          # Option B: Explicit integration
          # atmos auth ecr-login ci/ecr

      - name: Build and Push
        run: |
          docker build -t 123456789012.dkr.ecr.us-east-2.amazonaws.com/my-app:${{ github.sha }} .
          docker push 123456789012.dkr.ecr.us-east-2.amazonaws.com/my-app:${{ github.sha }}

GitLab CI

# .gitlab-ci.yml
build:
  image: docker:24
  services:
    - docker:24-dind
  before_script:
    - apk add --no-cache curl
    - curl -fsSL https://atmos.tools/install.sh | bash
    - atmos auth login ci-deployer
  script:
    - docker build -t 123456789012.dkr.ecr.us-east-2.amazonaws.com/my-app:$CI_COMMIT_SHA .
    - docker push 123456789012.dkr.ecr.us-east-2.amazonaws.com/my-app:$CI_COMMIT_SHA

IAM Permissions

The identity used for ECR login needs the ecr:GetAuthorizationToken permission:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "ecr:GetAuthorizationToken",
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ecr:BatchCheckLayerAvailability",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage",
        "ecr:PutImage",
        "ecr:InitiateLayerUpload",
        "ecr:UploadLayerPart",
        "ecr:CompleteLayerUpload"
      ],
      "Resource": "arn:aws:ecr:*:123456789012:repository/*"
    }
  ]
}

Credential Storage

Location

ECR credentials are stored in ~/.docker/config.json by default. This is the standard Docker config location, which means:

• No additional environment variables required
• Docker commands work immediately after login
• Credentials are merged with existing Docker config entries
• Has restricted permissions (0600)

If you need to use a custom location, set the DOCKER_CONFIG environment variable before running atmos auth ecr-login:

export DOCKER_CONFIG=/custom/path
atmos auth ecr-login dev/ecr

Troubleshooting

Token Expired

ECR tokens expire after approximately 12 hours. Re-authenticate to refresh:

atmos auth login dev-admin
# or
atmos auth ecr-login dev/ecr

Permission Denied

Ensure your identity has ecr:GetAuthorizationToken permission:

# Test with AWS CLI
aws ecr get-authorization-token --region us-east-2

Wrong Credentials Used

Check that ~/.docker/config.json contains the ECR registry:

cat ~/.docker/config.json | jq '.auths | keys'

If using a custom DOCKER_CONFIG, verify it's set correctly:

echo $DOCKER_CONFIG

Registry Not Found

Verify the registry URL format:

• Must be {account_id}.dkr.ecr.{region}.amazonaws.com
• ECR Public (public.ecr.aws) is not supported
• China/GovCloud regions are not supported

Next Steps

• Auth Login Command - Full login command reference
• ECR Login Command - ECR-specific command reference
• Auth Configuration - Complete configuration reference