Skip to main content

atmos auth ecr-login

Login to AWS Elastic Container Registry (ECR) using a named integration, an identity's linked integrations, or explicit registry URLs. This command writes Docker credentials to the standard Docker config location.

atmos auth ecr-login --help

Usage​

atmos auth ecr-login [integration] [flags]

Examples​

# Login using a named integration
atmos auth ecr-login dev/ecr/primary

# Login using an identity's linked integrations
atmos auth ecr-login --identity dev-admin

# Login with explicit registry URL (uses current AWS credentials)
atmos auth ecr-login --registry 123456789012.dkr.ecr.us-east-1.amazonaws.com

# Login to multiple explicit registries
atmos auth ecr-login \
  --registry 123456789012.dkr.ecr.us-east-1.amazonaws.com \
  --registry 987654321098.dkr.ecr.us-west-2.amazonaws.com

Arguments​

integration

Name of the integration to use for ECR login. The integration must be configured in auth.integrations with kind: aws/ecr. When provided, Atmos authenticates the integration's linked identity and logs into the configured registry.

Flags​

--identity (alias -i)

Identity name whose linked integrations should be executed. All aws/ecr integrations that reference this identity will be triggered. This authenticates the identity first, then executes all its linked integrations.

--registry (alias -r)

Explicit ECR registry URL(s) for ad-hoc login. This mode uses the current AWS credentials from the environment (not Atmos identities). Can be specified multiple times for multiple registries.

Format: {account_id}.dkr.ecr.{region}.amazonaws.com

Configuration​

ECR integrations are configured in atmos.yaml under auth.integrations:

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 derive credentials from identities
  integrations:
    dev/ecr/primary:
      kind: aws/ecr
      via:
        identity: dev-admin           # Which identity provides AWS credentials
      spec:
        auto_provision: true          # Auto-trigger on identity login (default: true)
        registry:
          account_id: "123456789012"
          region: us-east-2

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

Integration Configuration Options​

FieldRequiredDefaultDescription
kindYes-Must be aws/ecr for ECR integrations
via.identityYes-Name of identity providing AWS credentials
spec.auto_provisionNotrueAuto-trigger on identity login
spec.registry.account_idYes-AWS account ID for the ECR registry
spec.registry.regionYes-AWS region for the ECR registry

How It Works​

Named Integration Mode​

When you specify an integration name:

  1. Atmos looks up the integration config from auth.integrations
  2. Authenticates the linked identity (via via.identity)
  3. Calls ecr:GetAuthorizationToken using the identity's credentials
  4. Writes credentials to Docker config (~/.docker/config.json)

Identity Mode​

When you use --identity:

  1. Atmos finds all integrations that reference the specified identity
  2. Authenticates the identity
  3. Executes each linked integration
  4. Each integration writes its credentials to Docker config

Explicit Registry Mode​

When you use --registry:

  1. Atmos uses the current AWS credentials from the environment
  2. Parses the registry URL to extract account ID and region
  3. Calls ecr:GetAuthorizationToken
  4. Writes credentials to Docker config (~/.docker/config.json)

Credential Storage​

ECR credentials are written to ~/.docker/config.json by default, the standard Docker config location. This means:

  • Docker commands work immediately after login without additional configuration
  • Credentials are merged with existing entries in your Docker config
  • Respects DOCKER_CONFIG environment variable if set

If you need isolated credentials, set DOCKER_CONFIG before running the command:

export DOCKER_CONFIG=~/.config/atmos/docker
atmos auth ecr-login dev/ecr

Auto-Provisioning​

When auto_provision is true (the default), ECR integrations are automatically triggered when you authenticate with their linked identity:

$ atmos auth login dev-admin
Authenticating with identity: dev-admin
Opening browser for SSO authentication...
Successfully authenticated as dev-admin
✓ ECR login: 123456789012.dkr.ecr.us-east-2.amazonaws.com (expires in 11h59m)
✓ ECR login: 123456789012.dkr.ecr.us-west-2.amazonaws.com (expires in 11h59m)

To disable auto-provisioning for an integration, set auto_provision: false:

integrations:
  dev/ecr/optional:
    kind: aws/ecr
    via:
      identity: dev-admin
    spec:
      auto_provision: false  # Only triggered via explicit ecr-login command
      registry:
        account_id: "123456789012"
        region: eu-west-1

Error Handling​

  • Named integration failures: Return error to user (fatal)
  • Auto-provisioned integration failures: Log warning and continue (non-fatal)
  • Invalid registry URL: Return error with supported format

ECR integration failures during atmos auth login are logged but don't block authentication. Your identity credentials succeed even if ECR login fails.

Notes​

  • ECR tokens expire after approximately 12 hours (AWS-enforced)
  • The actual expiration time is displayed when login succeeds
  • Only private ECR registries are supported (not ECR Public or China/GovCloud regions)
  • Required IAM permission: ecr:GetAuthorizationToken

See Also​