From 567c95284ff796f3ef84ad91c0d65b2cdae458ad Mon Sep 17 00:00:00 2001
From: Eric Peterson <ericpeterson@spotify.com>
Date: Mon, 12 Jul 2021 11:46:10 +0200
Subject: [PATCH] Move AWS policy docs to documentation page.

Signed-off-by: Eric Peterson <ericpeterson@spotify.com>
---
 docs/features/techdocs/using-cloud-storage.md | 33 +++++++++++++++++++
 .../src/stages/publish/awsS3.ts               | 13 --------
 .../src/stages/publish/azureBlobStorage.ts    |  4 ---
 3 files changed, 33 insertions(+), 17 deletions(-)

diff --git a/docs/features/techdocs/using-cloud-storage.md b/docs/features/techdocs/using-cloud-storage.md
index 119629915e..159137c879 100644
--- a/docs/features/techdocs/using-cloud-storage.md
+++ b/docs/features/techdocs/using-cloud-storage.md
@@ -150,6 +150,39 @@ permissions to:
 - `s3:ListBucket` - To retrieve bucket metadata
 - `s3:GetObject` - To retrieve files from the bucket
 
+> Note: If you need to migrate documentation objects from an older-style path
+> format including case-sensitive entity metadata, you will need to add some
+> additional permissions to be able to perform the migration, including:
+>
+> - `s3:PutBucketAcl` (for copying files,
+>   [more info here](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObjectAcl.html))
+> - `s3:DeleteObject` and `s3:DeleteObjectVersion` (for deleting migrated files,
+>   [more info here](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObject.html))
+>
+> ...And you will need to ensure the permissions apply to the bucket itself, as
+> well as all resources under the bucket. See the example policy below.
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Sid": "TechDocsWithMigration",
+      "Effect": "Allow",
+      "Action": [
+        "s3:PutObject",
+        "s3:GetObject",
+        "s3:DeleteObjectVersion",
+        "s3:ListBucket",
+        "s3:DeleteObject",
+        "s3:PutObjectAcl"
+      ],
+      "Resource": ["arn:aws:s3:::your-bucket", "arn:aws:s3:::your-bucket/*"]
+    }
+  ]
+}
+```
+
 **4a. (Recommended) Setup authentication the AWS way, using environment
 variables**
 
diff --git a/packages/techdocs-common/src/stages/publish/awsS3.ts b/packages/techdocs-common/src/stages/publish/awsS3.ts
index b53bd0ca0a..55e968baac 100644
--- a/packages/techdocs-common/src/stages/publish/awsS3.ts
+++ b/packages/techdocs-common/src/stages/publish/awsS3.ts
@@ -313,19 +313,6 @@ export class AwsS3Publish implements PublisherBase {
     }
   }
 
-  /**
-   * todo: Put this documentation somewhere the user will actually see and read
-   * it.
-   *
-   * Note: In addition to the usual `PutObject`, `ListBucket` and `GetObject`
-   * actions, will need to add `PutObjectAcl` for copying files as well as
-   * `DeleteObject` if the removeOriginal flag is set to true. You may need to
-   * ensure access to the bucket resource in the following way:
-   * [
-   *   "arn:aws:s3:::your-bucket",
-   *   "arn:aws:s3:::your-bucket/*"
-   * ]
-   */
   async migrateDocsCase({
     removeOriginal = false,
     concurrency = 25,
diff --git a/packages/techdocs-common/src/stages/publish/azureBlobStorage.ts b/packages/techdocs-common/src/stages/publish/azureBlobStorage.ts
index e94589b8df..4e012a40d5 100644
--- a/packages/techdocs-common/src/stages/publish/azureBlobStorage.ts
+++ b/packages/techdocs-common/src/stages/publish/azureBlobStorage.ts
@@ -323,10 +323,6 @@ export class AzureBlobStoragePublish implements PublisherBase {
     }
   }
 
-  /**
-   * todo: Put this documentation somewhere the user will actually see and read
-   * it.
-   */
   async migrateDocsCase({
     removeOriginal = false,
     concurrency = 25,