AWS resilience-hub: Add EKS resilience testing IAM/RBAC setup docs
Summary
Adds optional resilience testing setup instructions for Amazon EKS, including Kubernetes service account, RBAC role/role binding, execution role cluster access mapping, and verification steps for fault injection.
Security assessment
The change documents security-relevant IAM and Kubernetes RBAC configuration needed to grant fault-injection permissions and map an execution role to a Kubernetes identity. It is hardening/setup guidance rather than a fix for a specific vulnerability or incident.
Evidence
+This setup includes a Kubernetes service account with fault-injection permissions. It also includes cluster access for the test execution role. If your service has no Amazon EKS pods, or you don't use resilience testing, skip these parts.
Diff
diff --git a/resilience-hub/latest/userguide/next-gen-iam-permissions.md b/resilience-hub/latest/userguide/next-gen-iam-permissions.md index 65f5750..e0553f7 100644 --- a//resilience-hub/latest/userguide/next-gen-iam-permissions.md +++ b//resilience-hub/latest/userguide/next-gen-iam-permissions.md @@ -87,0 +88,29 @@ If you are including Amazon EKS clusters into your Next generation Resilience Hu +Each step also has a part labeled **(Optional) Resilience testing**. Complete these parts only if you run resilience tests that inject faults into Amazon EKS pods. Three test templates do this when they block dependencies: **Dependency validation** , **Multi-Region: isolation** , and **Multi-Region: recovery**. The Amazon EKS pod actions in these templates need setup inside your cluster that you can't configure from the next generation of Resilience Hub. This setup includes a Kubernetes service account with fault-injection permissions. It also includes cluster access for the test execution role. If your service has no Amazon EKS pods, or you don't use resilience testing, skip these parts. + +The resilience testing setup is separate from, and in addition to, the discovery setup. Discovery grants a read-only cluster role to a Kubernetes group that your service role maps to. Resilience testing grants fault-injection permissions to a Kubernetes service account and to a Kubernetes user that your test execution role maps to. A cluster that you both assess and test needs both. + +###### Important + +Because the resilience testing setup lives inside your cluster, the next generation of Resilience Hub can't validate it when you create a test or start a test run. Setup problems surface only when the test runs. + +If the service account is missing, or the execution role lacks cluster access, the test run still starts. The Amazon EKS pod action then fails during fault injection with a Kubernetes authorization error. + +**(Optional) Resilience testing: Prerequisites** + +Before you complete the resilience testing parts of the following steps, make sure that: + + * Your cluster runs Amazon EKS version 1.30 or later. + + * Your target pods run on Amazon EC2 nodes. The packet loss action that these tests use isn't supported on AWS Fargate. + + * The `securityContext` of your target pods sets `readOnlyRootFilesystem: false`. Amazon EKS pod actions fail without it. + + * You have `kubectl` configured for the cluster, and permissions to create RBAC resources in the namespaces you want to test. + + + + +###### Note + +In addition to the cluster setup, the test execution role needs `eks:DescribeCluster` on the cluster, along with the other permissions for the test template you're using. The permissions policies in [IAM execution roles for resilience testing](./next-gen-resilience-testing-iam.html) already include these for the templates that support Amazon EKS pods. + @@ -170,0 +200,68 @@ This grants Next generation Resilience Hub read-only access to the Kubernetes re +**(Optional) Resilience testing: Create the Kubernetes service account** + +Resilience tests run Amazon EKS pod actions as a Kubernetes service account named exactly `resilience-testing-service-account`. You can't change this name—the next generation of Resilience Hub uses it for every test run. + +###### Important + +Service accounts are scoped to a namespace. Create `resilience-testing-service-account` in every namespace that contains pods you want to test. If a test targets pods in a namespace where the service account doesn't exist, the Amazon EKS pod action fails for those pods. + +The following manifest creates the service account, a role granting the permissions that AWS FIS needs to inject faults, and a role binding that ties them together. Replace `namespace` with your target namespace. + + + kind: ServiceAccount + apiVersion: v1 + metadata: + namespace: namespace + name: resilience-testing-service-account + + --- + kind: Role + apiVersion: rbac.authorization.k8s.io/v1 + metadata: + namespace: namespace + name: resilience-testing-role + rules: + - apiGroups: [""] + resources: ["configmaps"] + verbs: ["get", "create", "patch", "delete"] + - apiGroups: [""] + resources: ["pods"] + verbs: ["create", "list", "get", "delete", "deletecollection"] + - apiGroups: [""] + resources: ["pods/ephemeralcontainers"] + verbs: ["update"] + - apiGroups: [""] + resources: ["pods/exec"] + verbs: ["create"] + - apiGroups: ["apps"] + resources: ["deployments"] + verbs: ["get"] + + --- + apiVersion: rbac.authorization.k8s.io/v1 + kind: RoleBinding + metadata: + name: resilience-testing-role-binding + namespace: namespace + subjects: + - kind: ServiceAccount + name: resilience-testing-service-account + namespace: namespace + - apiGroup: rbac.authorization.k8s.io + kind: User + name: resilience-testing-user + roleRef: + kind: Role + name: resilience-testing-role + apiGroup: rbac.authorization.k8s.io + + +Save the manifest as `rbac.yaml` and apply it: + + + kubectl apply -f rbac.yaml + +The role binding has two subjects. The service account is what the fault-injection pod runs as. The Kubernetes user is the identity that your test execution role maps to in Step 2. You choose the user name—`resilience-testing-user` in this example—but it must match the user name you use in Step 2. + +Repeat this part for each namespace you want to test. The role and role binding names can be the same in every namespace. Only the service account name is fixed by the next generation of Resilience Hub. + @@ -216,0 +314,38 @@ Add this under `mapRoles` in the data section: +**(Optional) Resilience testing: Grant the execution role access to the cluster** + +For resilience testing, you map a different IAM role and a different Kubernetes identity than you do for discovery. Map your _test execution role_ —not the service role you mapped above—to the Kubernetes _user_ in the role binding from Step 1, so that AWS FIS can create the fault-injection pod. Don't add the execution role to the `resilience-hub-eks-access-group` group. As with discovery, use an Amazon EKS access entry (recommended) or the `aws-auth` ConfigMap. The same authentication mode requirements apply: access entries need `API` or `API_AND_CONFIG_MAP`, and the `aws-auth` ConfigMap needs `CONFIG_MAP` or `API_AND_CONFIG_MAP`. + +###### Important + +Map the execution role from the account that contains the Amazon EKS cluster. For a multi-account test, this is the _target account_ role, not the orchestrator account role. Mapping the orchestrator role is a common mistake. It leaves the test failing with a Kubernetes authorization error. The role that actually reaches the cluster is the one AWS FIS assumes in the target account. For more information about multi-account execution roles, see [Multi-account execution roles](./next-gen-resilience-testing-iam-multi-account.html). + +Using an access entry (Option A): + + + aws eks create-access-entry \ + --cluster-name cluster-name \ + --principal-arn arn:aws:iam::cluster-account-id:role/execution-role-name \ + --username resilience-testing-user + + +Using the aws-auth ConfigMap with eksctl (Option B): + + + eksctl create iamidentitymapping \ + --cluster cluster-name \ + --region region \ + --arn arn:aws:iam::cluster-account-id:role/execution-role-name \ + --username resilience-testing-user + + +Or, if you edit the ConfigMap manually, add this under `mapRoles`: + + + - rolearn: arn:aws:iam::cluster-account-id:role/execution-role-name + username: resilience-testing-user + + +###### Note + +Entries in the `aws-auth` ConfigMap don't support a path component in the role ARN. Use `arn:aws:iam::`cluster-account-id`:role/`execution-role-name``, not `arn:aws:iam::`cluster-account-id`:role/service-role/`execution-role-name``. + @@ -239,0 +375,27 @@ If using aws-auth ConfigMap (Option B): +**(Optional) Resilience testing: Verify the service account and execution role mapping** + +Confirm the service account and role binding exist in each namespace you plan to test: + + + kubectl get serviceaccount resilience-testing-service-account -n namespace + kubectl describe rolebinding resilience-testing-role-binding -n namespace + + +If you created an access entry for the execution role (Option A), confirm the mapping: + + + aws eks describe-access-entry \ + --cluster-name cluster-name \ + --principal-arn arn:aws:iam::cluster-account-id:role/execution-role-name + + +If you used the aws-auth ConfigMap (Option B): + + + kubectl get configmap aws-auth -n kube-system -o yaml | grep -A 3 "execution-role-name" + + +###### Important + +Check that the user name in the access entry or ConfigMap entry matches a `User` subject in the role binding. Both halves of the setup can look correct on their own: the cluster authenticates the execution role, and the RBAC resources exist. If the two names differ, the Amazon EKS pod action fails at injection time with a Kubernetes authorization error. A mismatch here is the most common cause of Amazon EKS pod actions failing. +