Skip to content

Commit 4a9bf0c

Browse files
jaypipesjaypipes
authored
Merge pull request #565 from kumargauravsharma/ack-main-irsa
irsa setup details for ACK controller setup on EKS
2 parents cc3c433 + 84f7ec7 commit 4a9bf0c

File tree

1 file changed

+141
-0
lines changed

1 file changed

+141
-0
lines changed

‎docs/contents/user-docs/irsa.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,149 @@ to assume the IAM Role with reduced permissions.
3131
amazon-eks-pod-identity-webhook repository for setting up IRSA on your own
3232
Kubernetes installation.
3333

34+
## IRSA setup on EKS cluster and install ACK controller using Helm
35+
Following steps provide example to setup IRSA on EKS cluster to install ACK ElastiCache controller using Helm charts.
36+
By modifying the variables values as needed, these steps can be applied for other ACK controllers.
37+
38+
The steps include:
39+
40+
### 1. Create OIDC identity provider for cluster
41+
Create OIDC identity provider for cluster using CLI command.
42+
Example:
43+
```
44+
EKS_CLUSTER_NAME=<eks cluster name>
45+
eksctl utils associate-iam-oidc-provider --cluster $EKS_CLUSTER_NAME --approve
46+
```
47+
For detailed instructions, follow [Enabling IAM roles for service accounts on your cluster][3].
48+
49+
### 2. Create an IAM role and policy for service account
50+
For detailed instructions, follow instructions at [Creating an IAM role and policy for your service account][4].
51+
52+
#### 2(a) - Create IAM role
53+
```
54+
AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query "Account" --output text)
55+
OIDC_PROVIDER=$(aws eks describe-cluster --name $EKS_CLUSTER_NAME --query "cluster.identity.oidc.issuer" --output text | sed -e "s/^https:\/\///")
56+
ACK_K8S_NAMESPACE=ack-system
57+
ACK_K8S_SERVICE_ACCOUNT_NAME=ack-elasticache-controller
58+
59+
read -r -d '' TRUST_RELATIONSHIP <<EOF
60+
{
61+
"Version": "2012-10-17",
62+
"Statement": [
63+
{
64+
"Effect": "Allow",
65+
"Principal": {
66+
"Federated": "arn:aws:iam::${AWS_ACCOUNT_ID}:oidc-provider/${OIDC_PROVIDER}"
67+
},
68+
"Action": "sts:AssumeRoleWithWebIdentity",
69+
"Condition": {
70+
"StringEquals": {
71+
"${OIDC_PROVIDER}:sub": "system:serviceaccount:${ACK_K8S_NAMESPACE}:${ACK_K8S_SERVICE_ACCOUNT_NAME}"
72+
}
73+
}
74+
}
75+
]
76+
}
77+
EOF
78+
echo "${TRUST_RELATIONSHIP}" > trust.json
79+
80+
# update variables as needed
81+
AWS_SERVICE_NAME='elasticache'
82+
ACK_CONTROLLER_IAM_ROLE="ack-${AWS_SERVICE_NAME}-controller"
83+
ACK_CONTROLLER_IAM_ROLE_DESCRIPTION='IRSA role for ACK $AWS_SERVICE_NAME controller deployment on EKS cluster using Helm charts'
84+
aws iam create-role --role-name "${ACK_CONTROLLER_IAM_ROLE}" --assume-role-policy-document file://trust.json --description "${ACK_CONTROLLER_IAM_ROLE_DESCRIPTION}"
85+
```
86+
87+
#### 2(b) - Attach IAM policy to role
88+
```
89+
# This example uses pre-existing policy for ElastiCache
90+
# Create an IAM policy and use its ARN and update IAM_POLICY_ARN variable as needed
91+
IAM_POLICY_ARN='arn:aws:iam::aws:policy/AmazonElastiCacheFullAccess'
92+
aws iam attach-role-policy \
93+
--role-name "${ACK_CONTROLLER_IAM_ROLE}" \
94+
--policy-arn "$IAM_POLICY_ARN"
95+
```
96+
97+
### 3. Associate an IAM role to service account
98+
99+
For detailed instructions, follow instructions at [Associate an IAM role to a service account ][5].
100+
101+
#### 3(a) - If Helm charts available on local file system
102+
103+
Update `values.yaml` and set value for `aws.region`, `serviceAccount.annotations`.
104+
105+
```
106+
# update variables as needed
107+
ACK_CONTROLLER_HELM_CHARTS_DIR=<directory containing Helm chart for ACK service controller>
108+
AWS_SERVICE_NAME='elasticache'
109+
ACK_K8S_NAMESPACE=ack-system
110+
ACK_K8S_RELEASE_NAME=ack-$AWS_SERVICE_NAME-controller
111+
112+
kubectl create namespace "$ACK_K8S_NAMESPACE"
113+
cd "$ACK_CONTROLLER_HELM_CHARTS_DIR"
114+
115+
# dry run and view the resultant output
116+
helm install --debug --dry-run --namespace "$ACK_K8S_NAMESPACE" "$ACK_K8S_RELEASE_NAME" .
117+
# install on cluster
118+
helm install --namespace "$ACK_K8S_NAMESPACE" "$ACK_K8S_RELEASE_NAME" .
119+
```
120+
121+
Verify that the service account has been created on cluster and that its annotation include IAM Role
122+
(created during Step#2 above) arn:
123+
```
124+
kubectl describe serviceaccount/$ACK_K8S_SERVICE_ACCOUNT_NAME -n $ACK_K8S_NAMESPACE
125+
```
126+
127+
#### 3(b) - If Helm charts have already been installed on cluster without modifying `values.yaml`
128+
129+
For example, if installation was done as:
130+
```
131+
AWS_SERVICE_NAME='elasticache'
132+
ACK_K8S_NAMESPACE=ack-system
133+
ACK_K8S_RELEASE_NAME=ack-$AWS_SERVICE_NAME-controller
134+
helm install --namespace $ACK_K8S_NAMESPACE ack-$AWS_SERVICE_NAME-controller $ACK_K8S_RELEASE_NAME
135+
```
136+
Then service account would already exist on the cluster; however its association with IAM Role would be pending.
137+
Verify it using:
138+
```
139+
kubectl describe serviceaccount/$ACK_K8S_SERVICE_ACCOUNT_NAME -n $ACK_K8S_NAMESPACE
140+
```
141+
Observe that the arn of IAM Role (created during Step#2 above) is not set as annotation for the service account.
142+
143+
To associate an IAM role to service account:
144+
```
145+
# annotate service account with service role arn.
146+
ISRA_ROLE_ARN=<role arn>
147+
kubectl annotate serviceaccount -n $ACK_K8S_NAMESPACE $ACK_K8S_SERVICE_ACCOUNT_NAME $ISRA_ROLE_ARN
148+
```
149+
150+
Update aws region to use in the controller, if not done already:
151+
```
152+
# update desired AWS region. example: us-east-1
153+
AWS_REGION=<aws region id>
154+
kubectl -n $ACK_K8S_NAMESPACE set env deployment/$ACK_K8S_RELEASE_NAME \
155+
AWS_REGION="$AWS_ACCOUNT_ID"
156+
```
157+
158+
### Verify
159+
Describe one of the pods and verify that the `AWS_WEB_IDENTITY_TOKEN_FILE` and `AWS_ROLE_ARN` environment variables exist.
160+
```
161+
kubectl get pods -A
162+
kubectl exec -n kube-system aws-node-<9rgzw> env | grep AWS
163+
```
164+
verify the output, example:
165+
```
166+
AWS_VPC_K8S_CNI_LOGLEVEL=DEBUG
167+
AWS_ROLE_ARN=arn:aws:iam::<AWS_ACCOUNT_ID>:role/<IAM_ROLE_NAME>
168+
AWS_WEB_IDENTITY_TOKEN_FILE=/var/run/secrets/eks.amazonaws.com/serviceaccount/token
169+
```
170+
34171
##
35172

36173
[0]: https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html
37174
[1]: https://github.com/aws/amazon-eks-pod-identity-webhook/blob/master/SELF_HOSTED_SETUP.md
38175
[2]: https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html
176+
[3]: https://docs.aws.amazon.com/eks/latest/userguide/enable-iam-roles-for-service-accounts.html
177+
[4]: https://docs.aws.amazon.com/eks/latest/userguide/create-service-account-iam-policy-and-role.html
178+
[5]: https://docs.aws.amazon.com/eks/latest/userguide/specify-service-account-role.html
179+
[6]: https://docs.aws.amazon.com/eks/latest/userguide/eksctl.html#installing-eksctl

0 commit comments

Comments
 (0)