TechDocs is Spotify’s homegrown docs-like-code solution built directly into Backstage. Engineers write their documentation in Markdown files which live together with their code – and with little configuration get a nice-looking doc site in Backstage.
For this post, I have TAP GUI running as part of view profile in multi cluster setup. To confirm any existing docs, Navigate to Docs section and I don’t have any documentations as shown below:
Install node, npm
The catalogs appearing in Tanzu Application Platform GUI are listed in the config values under
app_config.catalog.locations or can be registered manually as shown in below steps:
- In TAP GUI, navigate to Home > Register Entity
- Provide the path to catalog-info.yaml, for this demo I have used an example tech docs repo i.e., https://github.com/Eknathreddy09/capv-techdocs/blob/main/catalog-info.yaml
- Click Analyze and Import
- You can now see the tap-gui-component listed under the catalog section once successfully imported.
Create Azure Storage
- Sign in to the Azure portal.
- In search bar, type Storage accounts and select the same as shown below, to display a list of your storage accounts.
- Click on Create to initiate the storage account creation
- Select the Subscription, resource group
- Provide Storage account name and region
- Preview and Create
Note: For more advanced config for storage account creation, read the doc https://learn.microsoft.com/en-us/azure/storage/common/storage-account-create?tabs=azure-portal
Create Storage Container
- Once the storage account is successfully created, navigate to Containers section under Data storage and click on + Container to create new container
- Provide a name
Note: 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.
Collect the Access Keys
- Once the storage account is successfully created, navigate to Access keys section under Security + networking and copy the Storage account name, Key ( by clicking Show )
- Collect the container name, Storage account name and key for later use.
Tech Docs config
In TechDocs you have the option to choose where you want to store the Generated static files which TechDocs uses to render documentation. In both the “Basic” and “Recommended” setup, you can add cloud storage providers like Google GCS, Amazon AWS S3, Azure storage etc .. In this post, let’s see the steps to use Azure Blob Storage Container.
- Set the config
app-config.yamlto the name of the container you just created.
- If you like to use a service account, set the config
app-config.yamlto the your account name and
techdocs.publisher.azureBlobStorage.credentials.accountKeyto your account name collected in earlier steps.
Note: For multi cluster deployment, just update the packages of view cluster.
- Update the tap packages using updated values for changes to take affect
- Once the packages are updated successfully, verify the Docs section in TAP GUI under the tap-gui-component
Here you go: