From 579732def4b730673fad9a259bc5302bd551d590 Mon Sep 17 00:00:00 2001
From: Alex Lin <57118637+lnregalias@users.noreply.github.com>
Date: Mon, 22 Mar 2021 14:29:21 +1100
Subject: [PATCH] Add information on regional STS endpoints for IRSA

IRSA in a private cluster requires the use of STS VPC endpoints. However, the most AWS SDKs use the global STS endpoint by default for the STS `AssumeRoleWithWebIdentity` call, which bypasses the STS VPC endpoint (and fails in a private cluster).

To make this work correctly, we may need to explicitly instruct the SDK to use the regional STS endpoint. Usually this is done by passing some environment variables:

```yaml
      - env:
        - name: AWS_REGION
          value: <REGION>
        - name: AWS_STS_REGIONAL_ENDPOINTS
          value: regional
```

Relevant info:
https://github.com/aws/amazon-eks-pod-identity-webhook/pull/55 (Note: `eks.amazonaws.com/sts-regional-endpoints` doesn't appear to be supported yet in EKS)
https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_sts_vpce.html#id_credentials_sts_vpce_create
---
 doc_source/private-clusters.md | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/doc_source/private-clusters.md b/doc_source/private-clusters.md
index 4a6f76d8..8af00a09 100644
--- a/doc_source/private-clusters.md
+++ b/doc_source/private-clusters.md
@@ -69,4 +69,25 @@ The following [VPC endpoints](https://docs.aws.amazon.com/vpc/latest/userguide/v
 + `com.amazonaws.<region>.sts` – If using AWS Fargate or IAM roles for service accounts
 + `com.amazonaws.<region>.elasticloadbalancing` – If using Application Load Balancers
 + `com.amazonaws.<region>.autoscaling` – If using Cluster Autoscaler
-+ `com.amazonaws.<region>.appmesh-envoy-management` – If using App Mesh
\ No newline at end of file
++ `com.amazonaws.<region>.appmesh-envoy-management` – If using App Mesh
+
+## STS endpoints for IAM Roles for Service Accounts<a name="irsa-regional-endpoint"></a>
+
+Pods configured with [IAM roles for service accounts](iam-roles-for-service-accounts.md) acquire credentials from an STS API call\. If there is no outbound internet access, you must create and use an [STS VPC endpoint](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_sts_vpce.html#id_credentials_sts_vpce_create) in your VPC\.
+
+Note that most AWS v1 SDKs will use the global STS endpoint by default (`sts.amazonaws.com`), which will not use the STS VPC endpoint\. To use the STS VPC endpoint, you may need to configure the SDK to use the regional STS endpoint (`sts.<region-code>.amazonaws.com`)\. You can do this by setting the `AWS_STS_REGIONAL_ENDPOINTS` environment variable with a value of `regional`, along with the AWS region\.
+
+For example, in a pod spec:
+
+```yaml
+...
+  containers:
+    - env:
+      - name: AWS_REGION
+        value: <region-code>
+      - name: AWS_STS_REGIONAL_ENDPOINTS
+        value: regional
+      ...
+```
+
+Replace `<region-code>` with the Region that your cluster is in (`us-west-2` for example)\.