From 42494c7e91650459cd1fe5158b5ee9ec38bcd0ba Mon Sep 17 00:00:00 2001 From: vitorgrenzel Date: Wed, 20 Jan 2021 17:21:07 -0300 Subject: [PATCH] feat(docs): add Azure Blob Storage --- .changeset/chilly-dodos-drop.md | 2 +- docs/features/techdocs/README.md | 2 +- docs/features/techdocs/configuration.md | 20 +++++----- docs/features/techdocs/using-cloud-storage.md | 40 ++++++++++--------- 4 files changed, 34 insertions(+), 30 deletions(-) diff --git a/.changeset/chilly-dodos-drop.md b/.changeset/chilly-dodos-drop.md index b262c14e4d..2af5255e70 100644 --- a/.changeset/chilly-dodos-drop.md +++ b/.changeset/chilly-dodos-drop.md @@ -3,4 +3,4 @@ '@backstage/plugin-techdocs-backend': patch --- -1. Added option to use Azure Storage as a choice to store the static generated files for TechDocs. +1. Added option to use Azure Blob Storage as a choice to store the static generated files for TechDocs. diff --git a/docs/features/techdocs/README.md b/docs/features/techdocs/README.md index 24b4410092..f81f41668d 100644 --- a/docs/features/techdocs/README.md +++ b/docs/features/techdocs/README.md @@ -113,7 +113,7 @@ providers are used. | Local Filesystem of Backstage app | Yes ✅ | | Google Cloud Storage (GCS) | Yes ✅ | | Amazon Web Services (AWS) S3 | Yes ✅ | -| Azure Storage | Yes ✅ | +| Azure Blob Storage | Yes ✅ | [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 index 8d5906b18f..efed37fc69 100644 --- a/docs/features/techdocs/configuration.md +++ b/docs/features/techdocs/configuration.md @@ -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. @@ -85,16 +85,18 @@ techdocs: region: $env: AWS_REGION - # Required when techdocs.publisher.type is set to 'azureStorage'. Skip otherwise. + # Required when techdocs.publisher.type is set to 'azureBlobStorage'. Skip otherwise. - azureStorage: - # An API key is required to write to a storage container. + azureBlobStorage: + # (Required) Azure Blob Storage Container Name + containerName: 'techdocs-storage' + + # (Optional) An API key is required to write to a storage container. + # If not set, environment variables will be used to authenticate. + #https://docs.microsoft.com/en-us/azure/storage/common/storage-auth?toc=/azure/storage/blobs/toc.json credentials: account: - $env: TECHDOCS_AZURE_STORAGE_ACCOUNT + $env: TECHDOCS_AZURE_BLOB_STORAGE_ACCOUNT accountKey: - $env: TECHDOCS_AZURE_STORAGE_ACCOUNT_KEY - - # Azure Storage Container Name - containerName: 'techdocs-storage' + $env: TECHDOCS_AZURE_BLOB_STORAGE_ACCOUNT_KEY ``` diff --git a/docs/features/techdocs/using-cloud-storage.md b/docs/features/techdocs/using-cloud-storage.md index 2d906ca1b9..9ae14abfe3 100644 --- a/docs/features/techdocs/using-cloud-storage.md +++ b/docs/features/techdocs/using-cloud-storage.md @@ -196,20 +196,20 @@ 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 Storage Container with TechDocs +## Configuring Azure Blob Storage Container with TechDocs Follow the -[official Azure Storage documentation](https://docs.microsoft.com/pt-br/javascript/api/@azure/storage-blob/?view=azure-node-latest) -for the latest instructions on the following steps involving Azure Storage. +[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 `'azureStorage'`. +Set `techdocs.publisher.type` to `'azureBlobStorage'`. ```yaml techdocs: publisher: - type: 'azureStorage' + type: 'azureBlobStorage' ``` **2. Service account credentials** @@ -220,14 +220,14 @@ and get your Storage account name and Primary Key. ```yaml techdocs: publisher: - type: 'azureStorage' - azureStorage: + type: 'azureBlobStorage' + azureBlobStorage: credentials: account: 'account' accountKey: 'accountKey' ``` -**3. Azure Storage Container** +**3. Azure Blob Storage Container** Create a dedicated container for TechDocs sites. techdocs-backend will publish documentation to this container. TechDocs will fetch files from here to serve @@ -236,23 +236,25 @@ documentation in Backstage. To create a new container, access "Blob Service > Containers > New Container". Set the name of the container to -`techdocs.publisher.azureStorage.containerName`. +`techdocs.publisher.azureBlobStorage.containerName`. ```yaml techdocs: publisher: - type: 'azureStorage' - azureStorage: - credentials: - account: 'account' - accountKey: 'accountKey' + type: 'azureBlobStorage' + azureBlobStorage: containerName: 'name-of-techdocs-storage-container' + credentials: + account: + $env: TECHDOCS_AZURE_BLOB_STORAGE_ACCOUNT + accountKey: + $env: TECHDOCS_AZURE_BLOB_STORAGE_ACCOUNT_KEY ``` **4. That's it!** -Your Backstage app is now ready to use Azure 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 Storage container` in the -logs. +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.