From c0439628862959dcd4fe60eeb38a174dfa7b1cda Mon Sep 17 00:00:00 2001 From: Cian Johnston Date: Wed, 10 Nov 2021 12:03:30 +0000 Subject: [PATCH 1/5] chore(docs): document IRSA requirements for ECR --- admin/registries/ecr.md | 122 +++++++++++++++++++++++++++++++++------- 1 file changed, 102 insertions(+), 20 deletions(-) diff --git a/admin/registries/ecr.md b/admin/registries/ecr.md index c59fccb9f..5292f2543 100644 --- a/admin/registries/ecr.md +++ b/admin/registries/ecr.md @@ -6,41 +6,121 @@ 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). +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. -## 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. +- Static Credentials +- 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 (recommended). + +**Note:** 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. -To provision AWS credentials for Coder: +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) +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/). +This is only supported when Coder is running in AWS EKS, as 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, 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 to be used by Coder, if it does not already exist.](https://docs.aws.amazon.com/eks/latest/userguide/create-service-account-iam-policy-and-role.html#create-service-account-iam-role). + 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: + + 1. Add the following to your Helm `values.yaml`, replacing the variables + `ACCT_ID` and `ROLE_NAME` where appropriate: + + ```yaml + coderd: + ... + builtinProviderServiceAccount: + ... + annotations: + eks.amazonaws.com/role-arn: my-role-arn + ``` + + 1. Update the Helm deployment: + + ```shell + helm upgrade coder coder/coder --values values.yaml + ``` + + 1. 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 +131,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). From b1a55a2660f85086916d9d4d1a1213d01188a261 Mon Sep 17 00:00:00 2001 From: Cian Johnston Date: Wed, 10 Nov 2021 20:51:22 +0000 Subject: [PATCH 2/5] fixup! chore(docs): document IRSA requirements for ECR --- admin/registries/ecr.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/admin/registries/ecr.md b/admin/registries/ecr.md index 5292f2543..b97541eec 100644 --- a/admin/registries/ecr.md +++ b/admin/registries/ecr.md @@ -56,10 +56,11 @@ 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 to be used by Coder, if it does not already exist.](https://docs.aws.amazon.com/eks/latest/userguide/create-service-account-iam-policy-and-role.html#create-service-account-iam-role). - 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: +1. [Create the IAM role to be used by Coder, if it does not already exist](https://docs.aws.amazon.com/eks/latest/userguide/create-service-account-iam-policy-and-role.html#create-service-account-iam-role). + + **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 { @@ -83,8 +84,7 @@ To link an IAM role to Coder's Kubernetes service account: 1. Annotate the Coder service account with the role ARN: - 1. Add the following to your Helm `values.yaml`, replacing the variables - `ACCT_ID` and `ROLE_NAME` where appropriate: + a) Add the following to your `values.yaml` for your Coder helm deployment: ```yaml coderd: @@ -95,13 +95,13 @@ To link an IAM role to Coder's Kubernetes service account: eks.amazonaws.com/role-arn: my-role-arn ``` - 1. Update the Helm deployment: + b) Update the Helm deployment: ```shell helm upgrade coder coder/coder --values values.yaml ``` - 1. Verify that the Coder service account now has the correct annotation: + 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 From cbdd7266660aceed0d362250e5a379f7102f04e3 Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Wed, 10 Nov 2021 16:07:07 -0600 Subject: [PATCH 3/5] edit text --- admin/registries/ecr.md | 43 ++++++++++++++++++++++------------------- 1 file changed, 23 insertions(+), 20 deletions(-) diff --git a/admin/registries/ecr.md b/admin/registries/ecr.md index 5292f2543..f5243d7d0 100644 --- a/admin/registries/ecr.md +++ b/admin/registries/ecr.md @@ -16,18 +16,19 @@ registry using the AWS credentials linked to the registry. To access a private ECR registry, Coder needs to authenticate with AWS. Coder supports two methods of authentication with AWS ECR: -- Static Credentials -- IAM Roles for Service Accounts +- Static credentials +- IAM roles for service accounts -### Option A: Provision Static Credentials for Coder +### 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 (recommended). +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). -**Note:** 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. +> 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: @@ -40,26 +41,28 @@ To provision static credentials for Coder: 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) +### 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/). -This is only supported when Coder is running in AWS EKS, as the +[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, please consult the -[AWS Documentation](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html). +> 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 an IAM OIDC Provider for your EKS cluster (if it does not already + exist). -1. [Create the IAM role to be used by Coder, if it does not already exist.](https://docs.aws.amazon.com/eks/latest/userguide/create-service-account-iam-policy-and-role.html#create-service-account-iam-role). - 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: +1. [Create the IAM role to be used by Coder (if it does not already exist).](https://docs.aws.amazon.com/eks/latest/userguide/create-service-account-iam-policy-and-role.html#create-service-account-iam-role). + Ensure that you also create and attach a trust policy that permits the action + `sts:AssumeRoleWithWebIdentity` for the Coder service account. The trust + policy will look similar to the following: ```json { From cf80e45ba403156b9c0c4aa9769d06fb07a49b82 Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Wed, 10 Nov 2021 16:09:13 -0600 Subject: [PATCH 4/5] edit text --- admin/registries/ecr.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/admin/registries/ecr.md b/admin/registries/ecr.md index b9adcf023..78fe84c3c 100644 --- a/admin/registries/ecr.md +++ b/admin/registries/ecr.md @@ -59,7 +59,8 @@ 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 to be used by Coder, if it does not already exist](https://docs.aws.amazon.com/eks/latest/userguide/create-service-account-iam-policy-and-role.html#create-service-account-iam-role). +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 From b2340fab324b28769cbdf555a4b3b5cc910821d2 Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Wed, 10 Nov 2021 16:09:59 -0600 Subject: [PATCH 5/5] lint --- admin/registries/ecr.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/admin/registries/ecr.md b/admin/registries/ecr.md index 78fe84c3c..8d6976548 100644 --- a/admin/registries/ecr.md +++ b/admin/registries/ecr.md @@ -7,9 +7,10 @@ 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. +[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 authentication for Coder