paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 36 Packages Projects Releases Wiki Activity

docs(techdocs): Azure Storage Account Auth Guide Update (#30304)

Browse Source 
* Azure Storage Account Auth Guide Update

Describe how any method supported by `DefaultAzureCredential ` can be used to authenticate.

Signed-off-by: Jonas Mai <hubwoop@users.noreply.github.com>

* Update using-cloud-storage.md

Signed-off-by: Jonas Mai <hubwoop@users.noreply.github.com>

* Replace VMs with Virtual Machines

As recommended by code-review

Co-authored-by: Andre Wanlin <67169551+awanlin@users.noreply.github.com>
Signed-off-by: Jonas Mai <hubwoop@users.noreply.github.com>

---------

Signed-off-by: Jonas Mai <hubwoop@users.noreply.github.com>
Co-authored-by: Andre Wanlin <67169551+awanlin@users.noreply.github.com>
This commit is contained in:
Jonas Mai
2025-07-28 19:52:47 +02:00
committed by GitHub
parent 3ef648c259
commit c118dcda83
1 changed files with 36 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features/techdocs/using-cloud-storage.md
+36 -12
View File
@@ -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!**