diff --git a/admin/registries/ecr.md b/admin/registries/ecr.md index c59fccb9f..8d6976548 100644 --- a/admin/registries/ecr.md +++ b/admin/registries/ecr.md @@ -6,41 +6,126 @@ description: Add a private Amazon ECR to Coder. 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](https://docs.aws.amazon.com/AmazonECR/latest/userguide/registry_auth.html). -When interacting with ECR, Coder will request temporary credentials from the -registry using the AWS credentials linked to the registry. +Amazon requires users to +[request temporary login credentials](https://docs.aws.amazon.com/AmazonECR/latest/userguide/registry_auth.html) +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 your AWS credentials +## Step 1: Setting up authentication for Coder -To access a private ECR registry, Coder needs AWS credentials (specifically your -**access key ID** and **secret access key**) with authorization to access the -provided registry. You can either use AWS credentials tied to your own AWS -account *or* credentials tied to an IAM user specifically for Coder (we -recommend the latter option). +To access a private ECR registry, Coder needs to authenticate with AWS. Coder +supports two methods of authentication with AWS ECR: -Note that you are not limited to providing one 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. +- Static credentials +- IAM roles for service accounts -To provision AWS credentials for Coder: +### Option A: Provision static credentials for Coder -1. **Optional:** [Create an IAM user for - Coder](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html) +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](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html) to access ECR. You can either attach the AWS-managed policy - `AmazonEC2ContainerRegistryReadOnly` to the user, or you can [create your - own](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-policy-examples.html). + `AmazonEC2ContainerRegistryReadOnly` to the user, or you can + [create your own](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-policy-examples.html). -1. [Create an access - key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) +1. [Create an access key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) for the IAM user to be used with Coder (if one does not already exist). +### Option B: Link an AWS IAM role to the Coder Kubernetes service account (IRSA) + +Coder can use an +[IAM role linked to Coder's Kubernetes service account](https://aws.amazon.com/blogs/opensource/introducing-fine-grained-iam-roles-service-accounts/), +though this is only supported when Coder is running in AWS EKS. This is because +the +[EKS Pod Identity Webhook](https://github.com/aws/amazon-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](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html). + +To link an IAM role to Coder's Kubernetes service account: + +1. Create an IAM OIDC Provider for your EKS cluster (if it does not already + exist). + +1. [Create the IAM role](https://docs.aws.amazon.com/eks/latest/userguide/create-service-account-iam-policy-and-role.html#create-service-account-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: + + ```json + { + "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}" + } + } + } + ] + } + ``` + +1. Annotate the Coder service account with the role ARN: + + a) Add the following to your `values.yaml` for your Coder helm deployment: + + ```yaml + coderd: + ... + builtinProviderServiceAccount: + ... + annotations: + eks.amazonaws.com/role-arn: my-role-arn + ``` + + b) Update the Helm deployment: + + ```shell + helm upgrade coder coder/coder --values values.yaml + ``` + + c) Verify that the Coder service account now has the correct annotation: + + ```shell + kubectl get serviceaccount coder -o yaml | grep eks.amazonaws.com/role-arn + eks.amazonaws.com/role-arn: my-role-arn + ``` + +1. Validate that pods created with the `coder` service account have permission + to assume the role: + +```shell +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](../../images/index.md). To import an image: +You can add your private ECR registry at the same time that you +[add your images](../../images/index.md). To import an image: 1. In Coder, go to **Images** and click on **Import Image** in the upper-right. @@ -51,7 +136,9 @@ images](../../images/index.md). To import an image: 1. Provide a **registry name** and the **registry**. 1. Set the **registry kind** to **ECR** and provide your **Access Key ID** and - **Secret Access Key**. + **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. 1. Continue with the process of [adding your image](../../images/index.md).