From ccb027609c5a540a21c99d04dd418c73d6be8f5d Mon Sep 17 00:00:00 2001
From: Ole Markus With <o.with@sportradar.com>
Date: Tue, 28 Apr 2020 20:41:43 +0200
Subject: [PATCH] Update the cross-account example with working policy

---
 docs/state.md | 19 ++++++++++++-------
 1 file changed, 12 insertions(+), 7 deletions(-)

diff --git a/docs/state.md b/docs/state.md
index fc59b77414..62443caf2c 100644
--- a/docs/state.md
+++ b/docs/state.md
@@ -103,11 +103,10 @@ The state store can easily be moved to a different s3 bucket. The steps for a si
 
 Repeat for each cluster needing to be moved.
 
-#### Cross Account State-store (AWS S3)
+#### Cross Account State-store
 
-There are situations in which the entity executing kops to create the cluster is not in the same account as the owner of the state store bucket. In this case, you must explicitly grant the permission: `s3:getBucketLocation` to the ARN that is running kops.
-
-You can use the following policy to guide your implementation:
+Many enterprises prefer to run many AWS accounts. In these setups, having a shared cross-account S3 bucket for state may make inventory and management easier.
+In order to achieve this, you first need to let the other accounts access the s3 bucket. This is done by adding the following _bucket policy_ on the S3 bucket:
 
 ```
 {
@@ -117,13 +116,16 @@ You can use the following policy to guide your implementation:
         {
             "Sid": "123",
             "Action": [
-                "s3:GetBucketLocation"
+                "s3:*"
             ],
             "Effect": "Allow",
-            "Resource": "arn:aws:s3:::state-store-bucket",
+            "Resource": [
+                "arn:aws:s3:::<state-store-bucket>",
+                "arn:aws:s3:::<state-store-bucket>/*",
+            }
             "Principal": {
                 "AWS": [
-                    "arn:aws:iam::123456789:user/kopsuser"
+                    "arn:aws:iam::<remote-account>:root"
                 ]
             }
         }
@@ -131,6 +133,9 @@ You can use the following policy to guide your implementation:
 }
 ```
 
+Kops will then use that bucket as if it was in the remote account, including creating appropriate IAM policies that limits nodes from doing bad things.
+Note that any user/role with full S3 access will be able to delete any cluster from the state store, but may not delete any instances or other things outside of S3.
+
 ## Digital Ocean (do://)
 
 DigitalOcean storage is configured as a flavor of a S3 store.