This article will show you how to add your private ECR to Coder. If you're using a public ECR registry, you do not need to follow the steps below.

Amazon requires users to request temporary login credentials to access a private Elastic Container Registry (ECR) registry. When interacting with ECR, Coder will request temporary credentials from the registry using the AWS credentials linked to the registry.

Step 1: Setting up authentication for Coder

To access a private ECR registry, Coder needs to authenticate with AWS. Coder supports two methods of authentication with AWS ECR:

  • Static credentials
  • Alpha: IAM roles for service accounts

Option A: Provision static credentials for Coder

You can use an Access Key ID and Secret Access Key tied to either your own AWS account or credentials tied to a dedicated IAM user (we recommend the latter option).

You are not limited to providing a single set of AWS credentials. For example, you can use a set of credentials with access to all of your ECR repositories, or you can use individual sets of credentials, each with access to a single repository.

To provision static credentials for Coder:

  1. Optional: Create an IAM user for Coder to access ECR. You can either attach the AWS-managed policy AmazonEC2ContainerRegistryReadOnly to the user, or you can create your own.

  2. Create an access key for the IAM user to be used with Coder (if one does not already exist).

Note: This is currently an alpha feature.

Coder can use an IAM role linked to Coder's Kubernetes service account, though this is only supported when Coder is running in AWS EKS. This is because the EKS Pod Identity Webhook is required to provision and inject the required token into the coderd pod.

For more information on IAM Roles for Service Accounts (IRSA), please consult the AWS Documentation.

To link an IAM role to Coder's Kubernetes service account:

  1. Enable the feature under Manage > Admin > Infrastructure > ECR IAM Role Authentication.

  2. Create an IAM OIDC Provider for your EKS cluster (if it does not already exist).

  3. Create the IAM role to be used by Coder, if it does not already exist.

    Note: Ensure that you also create and attach a trust policy that permits the Coder service account the action sts:AssumeRoleWithWebIdentity. The trust policy will look similar to the following:

      "Version": "2012-10-17",
      "Statement": [
          "Effect": "Allow",
          "Principal": {
            "Federated": "arn:aws:iam::${ACCT_ID}:oidc-provider/${OIDC_PROVIDER}"
          "Action": "sts:AssumeRoleWithWebIdentity",
          "Condition": {
            "StringEquals": {
              "${OIDC_PROVIDER}:sub": "system:serviceaccount:${NAMESPACE}:${SERVICE_ACCOUNT}"
  4. Annotate the Coder service account with the role ARN:

    a) Add the following to your values.yaml for your Coder helm deployment:

         eks.amazonaws.com/role-arn: my-role-arn

    b) Update the Helm deployment:

    helm upgrade coder coder/coder --values values.yaml

    c) Verify that the Coder service account now has the correct annotation:

    kubectl get serviceaccount coder -o yaml | grep eks.amazonaws.com/role-arn
      eks.amazonaws.com/role-arn: my-role-arn
  5. Validate that pods created with the coder service account have permission to assume the role:

kubectl run -it --rm awscli --image=amazon/aws-cli \
  --overrides='{"spec":{"serviceAccount":"coder"}}' \
  --command aws ecr describe-repositories

Step 2: Add your private ECR registry to Coder

You can add your private ECR registry at the same time that you add your images. To import an image:

  1. In Coder, go to Images and click on Import Image in the upper-right.

  2. In the dialog that opens, you'll be prompted to pick a registry. However, to add a registry, click Add a new registry located immediately below the registry selector.

  3. Provide a registry name and the registry.

  4. Set the registry kind to ECR and provide your Access Key ID and Secret Access Key, if required. If you want to use IRSA instead of static credentials, to authenticate with ECR, leave Access Key ID and Secret Access Key blank.

  5. Continue with the process of adding your image.

  6. When done, click Import.

See an opportunity to improve our docs? Make an edit.