From 30b75f6b5d8621e0de36e41529eccbb866bcf875 Mon Sep 17 00:00:00 2001
From: Sedef Savas <ssavas@ucdavis.edu>
Date: Tue, 12 Apr 2022 21:59:59 -0700
Subject: [PATCH] Add role assumption trust policy example to doc

---
 docs/book/src/topics/multitenancy.md | 44 +++++++++++++++++++++++-----
 1 file changed, 36 insertions(+), 8 deletions(-)

diff --git a/docs/book/src/topics/multitenancy.md b/docs/book/src/topics/multitenancy.md
index 8467b9e67f..8ea08bfa8f 100644
--- a/docs/book/src/topics/multitenancy.md
+++ b/docs/book/src/topics/multitenancy.md
@@ -6,6 +6,7 @@ For details, see the [multi-tenancy proposal](https://github.com/kubernetes-sigs
 
 For multi-tenancy support, a reference field (`identityRef`) is added to `AWSCluster`, which informs the controller of which identity to be used when reconciling the cluster.
 If the identity provided exists in a different AWS account, this is the mechanism which informs the controller to provision a cluster in a different account.
+Identities should have adequate permissions for CAPA to reconcile clusters.
 
 
 ```yaml
@@ -179,6 +180,41 @@ spec:
     name: multi-tenancy-role
 ```
 
+
+### Necessary permissions for assuming a role:
+
+There are multiple AWS assume role permissions that need to be configured in order for the assume role to work:
+- The source identity (user/role specified in the source identity field) should have IAM policy permissions that enable it to perform sts:AssumeRole operation.
+  ```json
+  {
+      "Version": "2012-10-17",
+      "Statement": [
+          {
+              "Effect": "Allow",
+              "Action": "sts:AssumeRole",
+              "Resource": "*"
+          }
+      ]
+  }
+  ```
+
+- The target role (can be in a different AWS account) must be configured to allow the source user/role (or all users in an AWS account) to assume into it by setting a trust policy:
+    ``` json
+  {
+    "Version": "2012-10-17",
+    "Statement": [
+      {
+        "Effect": "Allow",
+        "Principal": {
+          "AWS": "arn:aws:iam::111111111111:root"
+            // "AWS": "arn:aws:iam::111111111111:role/role-used-during-cluster-bootstrap"
+        },
+        "Action": "sts:AssumeRole"
+      }
+    ]
+  }
+  ```
+
 ### Examples
 
 This is a deployable example which uses the `AWSClusterRoleIdentity` "test-account-role" to assume into the `arn:aws:iam::123456789:role/CAPARole` role in the target account.
@@ -239,14 +275,6 @@ In order to use the [EC2 template](../../../../templates/cluster-template.yaml)
 
 Similarly, to use the [EKS template](../../../../templates/cluster-template-eks.yaml) with identity type, you can add the `identityRef` section to `kind: AWSManagedControlPlane` spec section in the template. If you do not, CAPA will automatically add the default identity provider (which is usually your local account credentials).
 
-#### Permissions
-
-There are multiple AWS assume role permissions that need to be configured in order for the assume role to work
-- The Primary role in the management account must be allowed to assume role into the target role account
-  - This is traditionally the controller role, but the operator can configure it to be any role
-- The target account role must be configured to allow the management role to assume into it
-- The target account role must have adequate permissions for cluster-api to build both EC2 and EKS based clusters
-
 ## Secure Access to Identities
 `allowedNamespaces` field is used to grant access to the namespaces to use Identities.
 Only AWSClusters that are created in one of the Identity's allowed namespaces can use that Identity.