diff --git a/docs/features/techdocs/using-cloud-storage.md b/docs/features/techdocs/using-cloud-storage.md index bdafb3532c..42024ffbb2 100644 --- a/docs/features/techdocs/using-cloud-storage.md +++ b/docs/features/techdocs/using-cloud-storage.md @@ -355,31 +355,53 @@ techdocs: **3a. (Recommended) Authentication using environment variable** -If you do not prefer (3a) and optionally like to use a service account, you can -set the config `techdocs.publisher.azureBlobStorage.credentials.accountName` in -your `app-config.yaml` to the your account name. +The Azure Blob Storage client in Backstage supports all credential types +provided by +[DefaultAzureCredential](https://azuresdkdocs.z19.web.core.windows.net/javascript/azure-identity/4.10.1/classes/DefaultAzureCredential.html). +This means you can authenticate using environment variables for a service +principal, managed identity, and other methods in the default credential +chain. -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). +For deployment on Kubernetes, you can use +[Azure Workload Identity Federation](https://learn.microsoft.com/en-us/azure/active-directory/workload-identities/workload-identity-federation-overview) +to grant your Backstage workload access to the storage account without +managing secrets. +If running in Azure Virtual Machines or Azure Kubernetes Service (AKS) with managed +identity, no additional configuration apart from the `accountName` and +`containerName` may be needed. +For other scenarios, you can use a +[service principal](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal) +by setting: -https://docs.microsoft.com/en-us/azure/storage/common/storage-auth-aad for more -details. +- `AZURE_CLIENT_ID` +- `AZURE_TENANT_ID` +- `AZURE_CLIENT_SECRET` + +Example configuration in `app-config.yaml`: ```yaml techdocs: publisher: type: 'azureBlobStorage' azureBlobStorage: - containerName: 'name-of-techdocs-storage-bucket' + containerName: 'name-of-techdocs-storage-container' credentials: accountName: ${TECHDOCS_AZURE_BLOB_STORAGE_ACCOUNT_NAME} ``` +> **Note:** The account or credentials used must have the +> `Storage Blob Data Owner` role on the container to read, write, and +> delete objects as needed. If you use an external publisher, the +> `Storage Blob Data Reader` role is sufficient. + +For more details, see the +[Azure Identity documentation](https://azuresdkdocs.z19.web.core.windows.net/javascript/azure-identity/4.10.1/classes/DefaultAzureCredential.html) +and +[Workload Identity Federation for Kubernetes](https://learn.microsoft.com/en-us/azure/active-directory/workload-identities/workload-identity-federation-overview). + **3b. Authentication using app-config.yaml** -If you do not prefer (3a) and optionally like to use a service account, you can +If you do not prefer (3a) and optionally like to use key-based access, you can follow these steps. To get credentials, access the Azure Portal and go to "Settings > Access Keys", @@ -400,7 +422,9 @@ techdocs: In either case, the account or credentials used to access your container and all TechDocs objects underneath it should have the `Storage Blog Data Owner` role -applied, in order to read, write, and delete objects as needed. +applied, in order to read, write, and delete objects as needed, unless you use +an external publisher, in this case the `Storage Blob Data Reader` role is +sufficient. **4. That's it!**