From a2518e3dbe4aab77dfb4e050a21c376d976d38ee Mon Sep 17 00:00:00 2001
From: Himanshu Mishra <himanshu@orkohunter.net>
Date: Tue, 16 Feb 2021 19:03:07 +0100
Subject: [PATCH] docs(TechDocs): Update docs around AWS SDK downgrade to v2

---
 docs/features/techdocs/using-cloud-storage.md | 26 ++++++++++---------
 .../src/stages/publish/awsS3.ts               | 15 ++++++-----
 2 files changed, 22 insertions(+), 19 deletions(-)

diff --git a/docs/features/techdocs/using-cloud-storage.md b/docs/features/techdocs/using-cloud-storage.md
index de2d505c87..7d735c72ab 100644
--- a/docs/features/techdocs/using-cloud-storage.md
+++ b/docs/features/techdocs/using-cloud-storage.md
@@ -142,6 +142,8 @@ variables**
 You should follow the
 [AWS security best practices guide for authentication](https://docs.aws.amazon.com/general/latest/gr/aws-access-keys-best-practices.html).
 
+TechDocs needs access to read files and metadata of the S3 bucket.
+
 If the environment variables
 
 - `AWS_ACCESS_KEY_ID`
@@ -149,15 +151,21 @@ If the environment variables
 - `AWS_REGION`
 
 are set and can be used to access the bucket you created in step 2, they will be
-used by the AWS SDK v3 Node.js client for authentication.
-[Refer to the official documentation.](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/loading-node-credentials-environment.html)
+used by the AWS SDK V2 Node.js client for authentication.
+[Refer to the official documentation.](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/loading-node-credentials-environment.html)
 
 If the environment variables are missing, the AWS SDK tries to read the
 `~/.aws/credentials` file for credentials.
-[Refer to the official documentation.](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/loading-node-credentials-shared.html)
+[Refer to the official documentation.](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/loading-node-credentials-shared.html)
 
-Note that the region of the bucket has to be set for the AWS SDK to work.
-[See this](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-region.html).
+If you are using Amazon EC2 instance to deploy Backstage, you do not need to
+obtain the access keys separately. They can be made available in the environment
+automatically by defining appropriate IAM role with access to the bucket. Read
+more
+[here](https://docs.aws.amazon.com/general/latest/gr/aws-access-keys-best-practices.html#use-roles).
+
+The AWS Region of the bucket is optional since TechDocs uses AWS SDK V2 and not
+V3.
 
 **3b. Authentication using app-config.yaml**
 
@@ -181,13 +189,7 @@ techdocs:
 ```
 
 Refer to the
-[official AWS documentation for obtaining the credentials](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/getting-your-credentials.html).
-
-Note: If you are using Amazon EC2 instance to deploy Backstage, you do not need
-to obtain the access keys separately. They can be made available in the
-environment automatically by defining appropriate IAM role with access to the
-bucket. Read more
-[here](https://docs.aws.amazon.com/general/latest/gr/aws-access-keys-best-practices.html#use-roles).
+[official AWS documentation for obtaining the credentials](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/getting-your-credentials.html).
 
 **4. That's it!**
 
diff --git a/packages/techdocs-common/src/stages/publish/awsS3.ts b/packages/techdocs-common/src/stages/publish/awsS3.ts
index 6c0cadcfae..b0b29e8654 100644
--- a/packages/techdocs-common/src/stages/publish/awsS3.ts
+++ b/packages/techdocs-common/src/stages/publish/awsS3.ts
@@ -52,10 +52,13 @@ export class AwsS3Publish implements PublisherBase {
       );
     }
 
-    // Credentials is an optional config. If missing, default AWS environment variables
-    // or AWS shared credentials file at ~/.aws/credentials will be used to authenticate
-    // https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/loading-node-credentials-environment.html
-    // https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/loading-node-credentials-shared.html
+    // Credentials is an optional config. If missing, the default ways of authenticating AWS SDK V2 will be used.
+    // 1. AWS environment variables
+    // https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/loading-node-credentials-environment.html
+    // 2. AWS shared credentials file at ~/.aws/credentials
+    // https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/loading-node-credentials-shared.html
+    // 3. IAM Roles for EC2
+    // https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/loading-node-credentials-iam.html
     const credentials = config.getOptionalConfig(
       'techdocs.publisher.awsS3.credentials',
     );
@@ -67,9 +70,7 @@ export class AwsS3Publish implements PublisherBase {
     }
 
     // AWS Region is an optional config. If missing, default AWS env variable AWS_REGION
-    // or AWS shared credentials file at ~/.aws/credentials will be used. Any way, AWS SDK v3 client needs
-    // to have the AWS Region information for it to work.
-    // https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-region.html
+    // or AWS shared credentials file at ~/.aws/credentials will be used.
     const region = config.getOptionalString('techdocs.publisher.awsS3.region');
 
     const storageClient = new aws.S3({