Skip to content

Commit 138d316

Browse files
ericpaulsenericpaulsen
authored
docs: add guide for Google to AWS federation (#11429)
* feat: add docs for Google to AWS federation * make: fmt
1 parent dd05a6b commit 138d316

File tree

3 files changed

+189
-0
lines changed

3 files changed

+189
-0
lines changed

‎docs/guides/gcp-to-aws.md

+184
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
# Federating a Google Cloud service account to AWS
2+
3+
This guide will walkthrough how to use a Google Cloud service account to
4+
authenticate the Coder control plane to AWS and create an EC2 workspace. The
5+
below steps assume your Coder control plane is running in Google Cloud and has
6+
the relevant service account assigned.
7+
8+
> For steps on assigning a service account to a resource like Coder,
9+
> [see the Google documentation here](https://cloud.google.com/iam/docs/attach-service-accounts#attaching-new-resource)
10+
11+
## 1. Get your Google service account OAuth Client ID
12+
13+
> (Optional): If you do not yet have a service account,
14+
> [here is the Google IAM documentation on creating a service account](https://cloud.google.com/iam/docs/service-accounts-create).
15+
16+
Navigate to the Google Cloud console, and select **IAM & Admin** > **Service
17+
Accounts**. View the service account you want to use, and copy the **OAuth 2
18+
Client ID** value shown on the right-hand side of the row.
19+
20+
## 1. Create AWS role
21+
22+
Create an AWS role that is configured for Web Identity Federation, with Google
23+
as the identity provider, as shown below:
24+
25+
![AWS Create Role](../images/guides/aws-create-role.png)
26+
27+
Once created, edit the **Trust Relationship** section to look like the
28+
following:
29+
30+
```json
31+
{
32+
"Version": "2012-10-17",
33+
"Statement": [
34+
{
35+
"Effect": "Allow",
36+
"Principal": {
37+
"Federated": "accounts.google.com"
38+
},
39+
"Action": "sts:AssumeRoleWithWebIdentity",
40+
"Condition": {
41+
"StringEquals": {
42+
"accounts.google.com:aud": "<enter-OAuth-client-ID-here"
43+
}
44+
}
45+
}
46+
]
47+
}
48+
```
49+
50+
## 1. Assign permissions to the AWS role
51+
52+
In this example, Coder will need permissions to create the EC2 instance. Add the
53+
following policy to the role:
54+
55+
```json
56+
{
57+
"Version": "2012-10-17",
58+
"Statement": [
59+
{
60+
"Sid": "VisualEditor0",
61+
"Effect": "Allow",
62+
"Action": [
63+
"ec2:GetDefaultCreditSpecification",
64+
"ec2:DescribeIamInstanceProfileAssociations",
65+
"ec2:DescribeTags",
66+
"ec2:DescribeInstances",
67+
"ec2:DescribeInstanceTypes",
68+
"ec2:CreateTags",
69+
"ec2:RunInstances",
70+
"ec2:DescribeInstanceCreditSpecifications",
71+
"ec2:DescribeImages",
72+
"ec2:ModifyDefaultCreditSpecification",
73+
"ec2:DescribeVolumes"
74+
],
75+
"Resource": "*"
76+
},
77+
{
78+
"Sid": "CoderResources",
79+
"Effect": "Allow",
80+
"Action": [
81+
"ec2:DescribeInstanceAttribute",
82+
"ec2:UnmonitorInstances",
83+
"ec2:TerminateInstances",
84+
"ec2:StartInstances",
85+
"ec2:StopInstances",
86+
"ec2:DeleteTags",
87+
"ec2:MonitorInstances",
88+
"ec2:CreateTags",
89+
"ec2:RunInstances",
90+
"ec2:ModifyInstanceAttribute",
91+
"ec2:ModifyInstanceCreditSpecification"
92+
],
93+
"Resource": "arn:aws:ec2:*:*:instance/*",
94+
"Condition": {
95+
"StringEquals": {
96+
"aws:ResourceTag/Coder_Provisioned": "true"
97+
}
98+
}
99+
}
100+
]
101+
}
102+
```
103+
104+
## 1. Generate the identity token for the service account
105+
106+
Run the following `gcloud` command to generate the service account identity
107+
token. This is a JWT token with a payload that includes the service account
108+
email, audience, issuer, and expiration.
109+
110+
```console
111+
gcloud auth print-identity-token --audiences=https://aws.amazon.com --impersonate-service-account 12345-compute@de
112+
veloper.gserviceaccount.com --include-email
113+
```
114+
115+
> Note: Your `gcloud` client may needed elevated permissions to run this
116+
> command.
117+
118+
## 1. Set identity token in Coder control plane
119+
120+
You will need to set the token created in the previous step on a location in the
121+
Coder control plane. Follow the below steps for your specific deployment type:
122+
123+
### VM control plane
124+
125+
- Write the token to a file on the host, preferably inside the `/home/coder`
126+
directory:
127+
128+
```console
129+
/home/coder/.aws/gcp-identity-token
130+
```
131+
132+
### Kubernetes control plane
133+
134+
- Create the Kubernetes secret to house the token value:
135+
136+
```console
137+
kubectl create secret generic gcp-identity-token -n coder --from-literal=token=<enter-token-here>
138+
```
139+
140+
Make sure the secret is created inside the same namespace where Coder is
141+
running.
142+
143+
- Mount the token file into the Coder pod using the values below:
144+
145+
```yaml
146+
volumes:
147+
- name: "gcp-identity-mount"
148+
secret:
149+
secretName: "gcp-identity-token"
150+
volumeMounts:
151+
- name: "gcp-identity-mount"
152+
mountPath: "/home/coder/.aws/gcp-identity-token"
153+
readOnly: true
154+
```
155+
156+
## 1. Configure the AWS Terraform provider
157+
158+
Navigate to your EC2 workspace template in Coder, and configure the AWS provider
159+
using the block below:
160+
161+
```hcl
162+
provider "aws" {
163+
assume_role_with_web_identity {
164+
# enter role ARN here - copy from AWS console
165+
role_arn = "arn:aws:iam::123456789:role/gcp-to-aws"
166+
# arbitrary value for logging
167+
session_name = "coder-session"
168+
# define location of token file on control plane here
169+
web_identity_token_file = "/home/coder/.aws/gcp-identity-token"
170+
}
171+
}
172+
```
173+
174+
This provider block is equivalent to running this `aws` CLI command:
175+
176+
```console
177+
aws sts assume-role-with-web-identity \
178+
--role-arn arn:aws:iam::123456789:role/gcp-to-aws \
179+
--role-session-name coder-session \
180+
--web-identity-token xxx
181+
```
182+
183+
You can run this command with the identity token string to validate or
184+
troubleshoot the call to AWS.

‎docs/images/guides/gcp-to-aws/aws-create-role.png

119 KB
Loading

‎docs/manifest.json

+5
Original file line numberDiff line numberDiff line change
@@ -1039,6 +1039,11 @@
10391039
"title": "Configuring Okta",
10401040
"description": "Custom claims/scopes with Okta for group/role sync",
10411041
"path": "./guides/configuring-okta.md"
1042+
},
1043+
{
1044+
"title": "Google to AWS Federation",
1045+
"description": "Federating a Google Cloud service account to AWS",
1046+
"path": "./guides/gcp-to-aws.md"
10421047
}
10431048
]
10441049
}

0 commit comments

Comments
 (0)