Merge pull request #4017 from viavarejo/feature/techdocs-azure-storage

2021-01-31 16:03:24 +01:00
parent 9a5244a3f3 ee271bf86e
commit 8eb862c58e
15 changed files with 747 additions and 9 deletions
@@ -108,12 +108,12 @@ providers are used.
 | GitLab                       | Yes ✅         |
 | GitLab Enterprise            | Yes ✅         |

-| 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 ❌ [#3938](https://github.com/backstage/backstage/issues/3938) |
+| File Storage Provider             | Support Status |
+| --------------------------------- | -------------- |
+| Local Filesystem of Backstage app | Yes ✅         |
+| Google Cloud Storage (GCS)        | Yes ✅         |
+| Amazon Web Services (AWS) S3      | Yes ✅         |
+| Azure Blob Storage                | Yes ✅         |

 [Reach out to us](#feedback) if you want to request more platforms.

@@ -44,7 +44,7 @@ techdocs:
  # or you want to use External storage providers like Google Cloud Storage, AWS S3, etc.

  publisher:
-    # techdocs.publisher.type can be - 'local' or 'googleGcs' or 'awsS3' (azureStorage to be available in future).
+    # techdocs.publisher.type can be - 'local' or 'googleGcs' or 'awsS3' or 'azureBlobStorage'.
    # 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 'awsS3', techdocs-backend will use an Amazon Web Service (AWS) S3 bucket to store generated documentation files.
@@ -84,4 +84,21 @@ techdocs:
      # https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-region.html
      region:
        $env: AWS_REGION
+
+    # Required when techdocs.publisher.type is set to 'azureBlobStorage'. Skip otherwise.
+
+    azureBlobStorage:
+      # (Required) Azure Blob Storage Container Name
+      containerName: 'techdocs-storage'
+
+      # (Required) An account name is required to write to a storage blob container.
+      # https://docs.microsoft.com/en-us/rest/api/storageservices/authorize-with-shared-key
+      credentials:
+        accountName:
+          $env: TECHDOCS_AZURE_BLOB_STORAGE_ACCOUNT_NAME
+        # (Optional) An account key is required to write to a storage container.
+        # If missing,AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET environment variable will be used.
+        # https://docs.microsoft.com/en-us/azure/storage/common/storage-auth?toc=/azure/storage/blobs/toc.json
+        accountKey:
+          $env: TECHDOCS_AZURE_BLOB_STORAGE_ACCOUNT_KEY
 ```
@@ -195,3 +195,94 @@ Your Backstage app is now ready to use AWS S3 for TechDocs, to store and read
 the static generated documentation files. When you start the backend of the app,
 you should be able to see
 `techdocs info Successfully connected to the AWS S3 bucket` in the logs.
+
+## Configuring Azure Blob Storage Container with TechDocs
+
+Follow the
+[official Azure Blob Storage documentation](https://docs.microsoft.com/en-us/azure/storage/common/storage-auth?toc=/azure/storage/blobs/toc.json)
+for the latest instructions on the following steps involving Azure Blob Storage.
+
+**1. Set `techdocs.publisher.type` config in your `app-config.yaml`**
+
+Set `techdocs.publisher.type` to `'azureBlobStorage'`.
+
+```yaml
+techdocs:
+  publisher:
+    type: 'azureBlobStorage'
+```
+
+**2. Create an Azure Blob Storage Container**
+
+Create a dedicated container for TechDocs sites.
+[Refer to the official documentation](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal).
+
+TechDocs will publish documentation to this container and will fetch files from
+here to serve documentation in Backstage. Note that the container names are
+globally unique.
+
+Set the config `techdocs.publisher.azureBlobStorage.containerName` in your
+`app-config.yaml` to the name of the container you just created.
+
+```yaml
+techdocs:
+  publisher:
+    type: 'azureBlobStorage'
+    azureBlobStorage:
+      containerName: 'name-of-techdocs-storage-container'
+```
+
+**3a. (Recommended) Authentication using environment variable**
+
+Set the config `techdocs.publisher.azureBlobStorage.credentials.accountName` in
+your `app-config.yaml` to the your account name.
+
+The storage blob client will automatically use the environment variable
+`AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET` to authenticate with
+Azure Blob Storage.
+[Steps to create the service where the variables can be retrieved from](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal).
+
+https://docs.microsoft.com/en-us/azure/storage/common/storage-auth-aad for more
+details.
+
+```yaml
+techdocs:
+  publisher:
+    type: 'azureBlobStorage'
+    azureBlobStorage:
+      containerName: 'name-of-techdocs-storage-bucket'
+      credentials:
+        accountName:
+          $env: TECHDOCS_AZURE_BLOB_STORAGE_ACCOUNT_NAME
+```
+
+**3b. Authentication using app-config.yaml**
+
+If you do not prefer (3a) and optionally like to use a service account, you can
+follow these steps.
+
+To get credentials, access the Azure Portal and go to "Settings > Access Keys",
+and get your Storage account name and Primary Key.
+https://docs.microsoft.com/en-us/rest/api/storageservices/authorize-with-shared-key
+for more details.
+
+```yaml
+techdocs:
+  publisher:
+    type: 'azureBlobStorage'
+    azureBlobStorage:
+      containerName: 'name-of-techdocs-storage-bucket'
+      credentials:
+        accountName:
+          $env: TECHDOCS_AZURE_BLOB_STORAGE_ACCOUNT_NAME
+        accountKey:
+          $env: TECHDOCS_AZURE_BLOB_STORAGE_ACCOUNT_KEY
+```
+
+**4. That's it!**
+
+Your Backstage app is now ready to use Azure Blob Storage for TechDocs, to store
+and read the static generated documentation files. When you start the backend of
+the app, you should be able to see
+`techdocs info Successfully connected to the Azure Blob Storage container` in
+the logs.