Cloud►Infrastructure

How ECS Uses External Docker Image Registry

Amazon ECS (Elastic Container Service) supports pulling images from external Docker registries such as Docker Hub, GitHub Container Registry (GHCR), Google Container Registry (GCR), and even private self-hosted registries. This flexibility is useful for teams who manage images outside of Amazon ECR or rely on open-source or enterprise images stored in third-party registries. The steps below explain how to configure ECS to securely pull images from an external registry, including support for authentication, permissions, and networking requirements.

  1. Define your container image in the ECS task definition using the full image path.
    In your ECS task definition, the image field should include the full URL of the external image. For example, for a public image from Docker Hub, you can use "nginx:latest" or "docker.io/library/nginx:latest". If you’re using GitHub Container Registry, an image might look like "ghcr.io/myorg/myapp:latest". ECS will attempt to pull this image when the task is launched.

  2. Store private registry credentials in AWS Secrets Manager.
    If the image is hosted on a private registry that requires authentication (e.g., a private Docker Hub repo or GHCR package), you’ll need to store credentials in AWS Secrets Manager. Create a secret with a JSON structure like this:
    {"username": "your-username", "password": "your-password-or-token"}.
    This secret will be referenced later in the ECS task definition so ECS can authenticate before pulling the image.

  3. Reference the secret using the repositoryCredentials field in your task definition.
    In the same container definition where you specify the image, add a repositoryCredentials section that points to the full ARN of your Secrets Manager secret. For example:
    "repositoryCredentials": { "credentialsParameter": "arn:aws:secretsmanager:us-east-1:123456789012:secret:MyDockerHubSecret-Abc123" }.
    ECS will retrieve the secret at runtime and use it to authenticate against the registry.

  4. Attach the correct permissions to the ECS task execution role.
    The IAM role associated with the ECS task execution (not the task role) must have permission to access the secret from Secrets Manager. Add the following permission to your task execution role:
    "Effect": "Allow", "Action": "secretsmanager:GetSecretValue", "Resource": "<your-secret-arn>".
    Without this permission, the task will fail to pull the image from the registry.

  5. Ensure ECS tasks have internet access to reach external registries.
    ECS must connect to the external registry over the internet to pull the image. For EC2 launch type, make sure the instance has a public IP or outbound access via NAT Gateway. For Fargate, place the task in a public subnet or ensure the private subnet routes to a NAT Gateway. Without internet access, ECS won’t be able to download the container image and the task will fail.

  6. Use GitHub Container Registry as an example for private registry authentication.
    If you’re using GitHub Container Registry (ghcr.io), generate a personal access token with read:packages scope from GitHub. Then, create a secret in AWS Secrets Manager with this structure:
    {"username": "your-github-username", "password": "ghp_xxxxxxxx"}.
    Reference this secret in your ECS task definition as described above, and ECS will use it to authenticate when pulling the image from GHCR.

  7. Pin your images by digest instead of using tags for immutability.
    Tags like latest can change over time, which can lead to unpredictable behavior in production. To avoid this, use the image’s digest instead of a tag. For example:
    "ghcr.io/myorg/myapp@sha256:abcdef123456...".
    This ensures that the same image is pulled every time the task runs, regardless of future changes to the tag.

  8. Deploy your ECS service or task and monitor for pull success.
    Once your task definition is updated and permissions are in place, deploy your ECS task or service. ECS will retrieve the credentials from Secrets Manager and attempt to pull the image from the external registry. If the task fails, check the ECS console and CloudWatch Logs for error messages related to image pulling or authentication. Common issues include missing permissions, incorrect secret formats, or network connectivity failures.

By following these steps, you can run container workloads in ECS using images stored outside of Amazon ECR. This makes it easy to reuse existing CI/CD pipelines, leverage third-party registry services, and adopt open-source containers without needing to migrate everything into ECR. Whether you’re working with public images or private packages that require authentication, ECS can securely connect to external registries and keep your containers running reliably.