feat(techdocs): update docs

jeremyguarini · Dec 30, 2020 · 77102b4 · 77102b4
1 parent c4fcd8b
commit 77102b4
Show file tree

Hide file tree

Showing 5 changed files with 181 additions and 8 deletions.
diff --git a/app-config.yaml b/app-config.yaml
@@ -76,7 +76,7 @@ techdocs:
   generators:
     techdocs: 'docker' # Alternatives - 'local'
   publisher:
-    type: 'local' # Alternatives - 'googleGcs'. Read documentation for using alternatives.
+    type: 'local' # Alternatives - 'googleGcs' - 'awsS3'. Read documentation for using alternatives.
 
 sentry:
   organization: my-company

diff --git a/docs/assets/techdocs/aws-s3.png b/docs/assets/techdocs/aws-s3.png
diff --git a/docs/features/techdocs/README.md b/docs/features/techdocs/README.md
@@ -110,12 +110,12 @@ providers are used.
 | GitLab                       | Yes ✅         |
 | GitLab Enterprise            | Yes ✅         |
 
-| File Storage Provider             | Support Status | Track status                                                |
-| --------------------------------- | -------------- | ----------------------------------------------------------- |
-| Local Filesystem of Backstage app | Yes ✅         |                                                             |
-| Google Cloud Storage (GCS)        | Yes ✅         |                                                             |
-| Amazon Web Services (AWS) S3      | No ❌          | [#3714](https://github.com/backstage/backstage/issues/3714) |
-| Azure Storage                     | No ❌          |                                                             |
+| File Storage Provider             | Support Status |
+| --------------------------------- | -------------- |
+| Local Filesystem of Backstage app | Yes ✅         |
+| Google Cloud Storage (GCS)        | Yes ✅         |
+| Amazon Web Services (AWS) S3      | Yes ✅         |
+| Azure Storage                     | No ❌          |
 
 [Reach out to us](#feedback) if you want to request more platforms.
 

diff --git a/docs/features/techdocs/configuration.md b/docs/features/techdocs/configuration.md
@@ -52,7 +52,7 @@ techdocs:
 
     # techdocs.publisher.type can be - 'local' or 'googleGcs' (awsS3, azureStorage, etc. to be available as well).
     # When set to 'local', techdocs-backend will create a 'static' directory at its root to store generated documentation files.
-    # When set to 'googleGcs', techdocs-backend will use a Google Cloud Storage Bucket to store generated documentation files.
+    # When set to 'googleGcs' or 'awsS3', techdocs-backend will use a Google Cloud Storage Bucket to store generated documentation files.
 
     type: 'local'
 
@@ -70,4 +70,14 @@ techdocs:
       # Cloud Storage Bucket Name
       bucketName: 'techdocs-storage',
 
+    # Required when techdocs.publisher.type is set to 'awsS3'. Skip otherwise.
+
+    awsS3:
+      # An API key is required to write to a storage bucket.
+      credentials:
+        $file: '/path/to/aws_application_credentials.json',
+
+      # AWS S3 Bucket Name
+      bucketName: 'techdocs-storage',
+
 ```
diff --git a/docs/features/techdocs/using-cloud-storage.md b/docs/features/techdocs/using-cloud-storage.md
@@ -93,3 +93,166 @@ techdocs:
 
 Your Backstage app is now ready to use Google Cloud Storage for TechDocs, to
 store the static generated documentation files.
+
+## Configuring AWS S3 Bucket with TechDocs
+
+Follow the
+[official AWS S3 documentation](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html)
+for the latest instructions on the following steps involving AWS S3.
+
+**1. Set `techdocs.publisher.type` config in your `app-config.yaml`**
+
+Set `techdocs.publisher.type` to `'awsS3'`.
+
+```yaml
+techdocs:
+  publisher:
+    type: 'awsS3'
+```
+
+**2. AWS Policies**
+
+AWS Policies lets you **control access** to Amazon Web Services (AWS) products and ressources.   
+Here we will use a user policy **and** a bucket policy to show you the different possibilities you have but you can use only one.
+
+<img data-zoomable src="../../assets/techdocs/aws-s3.png" alt="AWS S3" />
+
+This is an example of how you can manage your poilicies:
+
+a. Admin user creates a **bucket policy** granting a set of permissions to our TechDocs user.
+
+b. Admin user attaches a **user policy** to the TechDocs user granting additional permissions.
+
+c. TechDocs User then tries permissions granted via both the **bucket** policy and the **user** policy.
+
+**2.1 Creation**
+
+**2.1.1 Create an Admin user** (if you don't have one yet)
+
+Create an **administrator user** `ADMIN_USER` and grant him administrator privileges by attaching a user policy giving him **full access**.   
+Note down the Admin User credentials and IAM User Sign-In URL as you will need to use these informations in the next step.
+
+**2.1.2 Create an AWS S3 Bucket**
+
+Using the credentials of your Admin User `ADMIN_USER`, and the special IAM user sign-in URL, create a dedicated **bucket** for TechDocs sites. techdocs-backend will publish
+documentation to this bucket. TechDocs will fetch files from here to serve
+documentation in Backstage.
+
+Set the name of the bucket to `techdocs.publisher.awsS3.bucketName`.
+
+```yaml
+techdocs:
+  publisher:
+    type: 'awsS3'
+    awsS3:
+      credentials:
+        $file: '/path/to/aws_application_credentials.json'
+      bucketName: 'name-of-techdocs-storage-bucket'
+```
+
+**2.1.3 Create the `TechDocs` user**
+
+This user will be used to interact with your bucket, it will only have permissions to **get - put** objects.
+
+In the IAM console, do the following:
+
+- Create a new user, `TechDocs`
+- Note down the TechDocs User credentials
+- Note down the Amazon Resource Name (ARN) for the TechDocs user. In the IAM console, select the TechDocs user, and you can find the user ARN in the Summary tab.
+
+**2.2 Attach policies**
+
+Remember that you can use Bucket policy **or** User policy.   
+Just make sure that you grant all the permissions to the TechDocs user: `3:PutObject`, `s3:GetObject`, `s3:ListBucket` and `s3:GetBucketLocation`.
+
+**2.2.1 Create the bucket policy**
+
+You now have to attach the following policity to your bucket in the Permission section:
+
+```json
+{
+   "Version": "2012-10-17",
+   "Statement": [
+      {
+         "Sid": "statement1",
+         "Effect": "Allow",
+         "Principal": {
+            "AWS": "arn:aws:iam::YOUR_ACCOUNT_ID:user/TechDocs"
+         },
+         "Action": [
+            "s3:GetBucketLocation",
+            "s3:ListBucket"
+         ],
+         "Resource": [
+            "arn:aws:s3:::name-of-techdocs-storage-bucket"
+         ]
+      },
+      {
+         "Sid": "statement2",
+         "Effect": "Allow",
+         "Principal": {
+            "AWS": "arn:aws:iam::YOUR_ACCOUNT_ID:user/TechDocs"
+         },
+         "Action": [
+             "s3:GetObject"
+         ],
+         "Resource": [
+            "arn:aws:s3:::name-of-techdocs-storage-bucket/*"
+         ]
+      }
+   ]
+}
+```
+
+- The first statement grants **TechDocs User** the bucket operation permissions `s3:GetBucketLocation` and `s3:ListBucket` which are permissions required by the console.
+- The second statement grants the `s3:GetObject` permission.   
+(**NOTE :** if you do not use the user policy defined below you must also add the `s3:PutObject` permission to allow the TechDocs user to add objects.)
+
+**2.2.2 Create the user policy**
+
+Create an inline policy for the TechDocs user by using the following policy:
+
+```json
+{
+   "Version": "2012-10-17",
+   "Statement": [
+      {
+         "Sid": "PermissionForObjectOperations",
+         "Effect": "Allow",
+         "Action": [
+            "s3:PutObject"
+         ],
+         "Resource": [
+            "arn:aws:s3:::name-of-techdocs-storage-bucket/*"
+         ]
+      }
+   ]
+}
+```
+
+See more details in the section [Working with Inline Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage.html).
+
+Now you need to create your credentials file (`.json`) with the `TechDocs` User credentials:
+
+```json
+{
+  "accessKeyId": "TECHDOCS_USER_ACCESS_KEY_ID",
+  "secretAccessKey": "TECHDOCS_USER_SECRET_ACCESS_KEY"
+}
+```
+
+Make it available in your Backstage server and/or your local development server and set it in the app config techdocs.publisher.awsS3.credentials.
+
+```yaml
+techdocs:
+  publisher:
+    type: 'awsS3'
+    awsS3:
+      credentials:
+        $file: '/path/to/aws_application_credentials.json'
+```
+
+**3. That's it!**
+
+Your Backstage app is now ready to use AWS S3 for TechDocs, to
+store the static generated documentation files.