diff --git a/docs/guides/gcp-to-aws.md b/docs/guides/gcp-to-aws.md new file mode 100644 index 0000000000000..5b9b54707c560 --- /dev/null +++ b/docs/guides/gcp-to-aws.md @@ -0,0 +1,184 @@ +# Federating a Google Cloud service account to AWS + +This guide will walkthrough how to use a Google Cloud service account to +authenticate the Coder control plane to AWS and create an EC2 workspace. The +below steps assume your Coder control plane is running in Google Cloud and has +the relevant service account assigned. + +> For steps on assigning a service account to a resource like Coder, +> [see the Google documentation here](https://cloud.google.com/iam/docs/attach-service-accounts#attaching-new-resource) + +## 1. Get your Google service account OAuth Client ID + +> (Optional): If you do not yet have a service account, +> [here is the Google IAM documentation on creating a service account](https://cloud.google.com/iam/docs/service-accounts-create). + +Navigate to the Google Cloud console, and select **IAM & Admin** > **Service +Accounts**. View the service account you want to use, and copy the **OAuth 2 +Client ID** value shown on the right-hand side of the row. + +## 1. Create AWS role + +Create an AWS role that is configured for Web Identity Federation, with Google +as the identity provider, as shown below: + +![AWS Create Role](../images/guides/aws-create-role.png) + +Once created, edit the **Trust Relationship** section to look like the +following: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "Federated": "accounts.google.com" + }, + "Action": "sts:AssumeRoleWithWebIdentity", + "Condition": { + "StringEquals": { + "accounts.google.com:aud": " Note: Your `gcloud` client may needed elevated permissions to run this +> command. + +## 1. Set identity token in Coder control plane + +You will need to set the token created in the previous step on a location in the +Coder control plane. Follow the below steps for your specific deployment type: + +### VM control plane + +- Write the token to a file on the host, preferably inside the `/home/coder` + directory: + +```console +/home/coder/.aws/gcp-identity-token +``` + +### Kubernetes control plane + +- Create the Kubernetes secret to house the token value: + +```console +kubectl create secret generic gcp-identity-token -n coder --from-literal=token= +``` + +Make sure the secret is created inside the same namespace where Coder is +running. + +- Mount the token file into the Coder pod using the values below: + +```yaml +volumes: + - name: "gcp-identity-mount" + secret: + secretName: "gcp-identity-token" +volumeMounts: + - name: "gcp-identity-mount" + mountPath: "/home/coder/.aws/gcp-identity-token" + readOnly: true +``` + +## 1. Configure the AWS Terraform provider + +Navigate to your EC2 workspace template in Coder, and configure the AWS provider +using the block below: + +```hcl +provider "aws" { + assume_role_with_web_identity { + # enter role ARN here - copy from AWS console + role_arn = "arn:aws:iam::123456789:role/gcp-to-aws" + # arbitrary value for logging + session_name = "coder-session" + # define location of token file on control plane here + web_identity_token_file = "/home/coder/.aws/gcp-identity-token" + } +} +``` + +This provider block is equivalent to running this `aws` CLI command: + +```console +aws sts assume-role-with-web-identity \ + --role-arn arn:aws:iam::123456789:role/gcp-to-aws \ + --role-session-name coder-session \ + --web-identity-token xxx +``` + +You can run this command with the identity token string to validate or +troubleshoot the call to AWS. diff --git a/docs/images/guides/gcp-to-aws/aws-create-role.png b/docs/images/guides/gcp-to-aws/aws-create-role.png new file mode 100644 index 0000000000000..fb1555e850596 Binary files /dev/null and b/docs/images/guides/gcp-to-aws/aws-create-role.png differ diff --git a/docs/manifest.json b/docs/manifest.json index 5248d8dc4158a..131f0a03f2896 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1039,6 +1039,11 @@ "title": "Configuring Okta", "description": "Custom claims/scopes with Okta for group/role sync", "path": "./guides/configuring-okta.md" + }, + { + "title": "Google to AWS Federation", + "description": "Federating a Google Cloud service account to AWS", + "path": "./guides/gcp-to-aws.md" } ] }