Tanzu Application Platform – Tech Docs using Azure Storage

Eknath - 4 January 20235 January 2023

Reading Time: 4 mins

Contents

Overview

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

## Install Node js

$ curl -sL https://deb.nodesource.com/setup_18.x | sudo -E bash -

$ sudo apt-get install -y nodejs

## Verify node js version

$ node -v
v18.12.1

## Install npm

$ sudo npm install -g npm

##  Verify npm version

$ npm -v
9.2.0

Register Entity

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.

Create

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 techdocs.publisher.type to 'azureBlobStorage'
Set the config techdocs.publisher.azureBlobStorage.containerName in your app-config.yaml to the name of the container you just created.
If you like to use a service account, set the config techdocs.publisher.azureBlobStorage.credentials.accountName in your app-config.yaml to the your account name and techdocs.publisher.azureBlobStorage.credentials.accountKey to your account name collected in earlier steps.

tech docs config

## Add this under tap_gui section of tap-values file by updating the  container name, accountName and accountKey:  
  app_config:
    techdocs:
      builder: 'external'
      publisher:
        type: 'azureBlobStorage'
        azureBlobStorage:
          containerName: '<Azure storage account container name>'
          credentials:
            accountName: "<Azure storage account name>"
            accountKey: "<Azure storage account key>"

Note: For multi cluster deployment, just update the packages of view cluster.

https://github.com/Eknathreddy09/capv-techdocs

## Github repo

azureuser@capv-tapmc-jb:~$ git clone https://github.com/Eknathreddy09/capv-techdocs
Cloning into 'capv-techdocs'...
remote: Enumerating objects: 1733, done.
remote: Counting objects: 100% (1733/1733), done.
remote: Compressing objects: 100% (545/545), done.
remote: Total 1733 (delta 1042), reused 1733 (delta 1042), pack-reused 0
Receiving objects: 100% (1733/1733), 82.36 MiB | 32.55 MiB/s, done.
Resolving deltas: 100% (1042/1042), done.

azureuser@capv-tapmc-jb:~$ cd capv-techdocs/
azureuser@capv-tapmc-jb:~/capv-techdocs$ ls
README.md  catalog-info.yaml  components  docs  domains  groups  mkdocs.yml  systems

# Generate the TechDocs for the root of the catalog by running:

## Syntax: npx @techdocs/cli generate --source-dir DIRECTORY-CONTAINING-THE-ROOT-YAML-FILE --output-dir ./site

# Example: 

azureuser@capv-tapmc-jb:~/capv-techdocs$ npx @techdocs/cli generate --source-dir .  --output-dir /home/azureuser/site-component
Need to install the following packages:
  @techdocs/cli@1.2.4
Ok to proceed? (y) y
npm WARN deprecated har-validator@5.1.5: this library is no longer supported
npm WARN deprecated querystring@0.2.0: The querystring API is considered Legacy. new code should use the URLSearchParams API instead.
npm WARN deprecated request@2.88.2: request has been deprecated, see https://github.com/request/request/issues/3142
npm WARN deprecated uuid@3.4.0: Please upgrade  to version 7 or higher.  Older versions may use Math.random() in certain circumstances, which is known to be problematic.  See https://v8.dev/blog/math-random for details.
npm WARN deprecated core-js@2.6.12: core-js@<3.23.3 is no longer maintained and not recommended for usage due to the number of issues. Because of the V8 engine whims, feature detection in old core-js versions could cause a slowdown up to 100x even if nothing is polyfilled. Some versions have web compatibility issues. Please, upgrade your dependencies to the actual version of core-js.
info: Using source dir /home/azureuser/capv-techdocs
info: Will output generated files in /home/azureuser/site-component
info: Generating documentation...
info: Successfully generated docs from /home/azureuser/capv-techdocs into /home/azureuser/site-component using techdocs-container
info: Done!

azureuser@capv-tapmc-jb:~$ cd site-component/
azureuser@capv-tapmc-jb:~/site-component$ ls
404.html  assets  index.html  search  sitemap.xml  sitemap.xml.gz  techdocs_metadata.json  tkg-workshop

## Publish the TechDocs for the root of the catalog to the Azure Storage container you created earlier by running:

## Syntax: npx @techdocs/cli publish --publisher-type awsS3 --storage-name BUCKET-NAME --entity NAMESPACE/KIND/NAME --directory ./site

# Example: 

azureuser@capv-tapmc-jb:~$ npx @techdocs/cli publish --publisher-type azureBlobStorage --storage-name capvtaptechdoocs-container --azureAccountName capvtaptechdocs --azureAccountKey AjzlZ4rJTiru0FWZ6zGI2ZZdkOAqCnN6b0qc/5CFgyAcI4IoRtpBMRwqVe4t4QULrwwFIX79DQ0y+AStwkW05g== --entity default/Component/tap-gui-component --directory /home/azureuser/site-component
info: Creating Azure Blob Storage Container publisher for TechDocs
info: Successfully uploaded all the generated files for Entity tap-gui-component. Total number of files: 42
info: Successfully deleted stale files for Entity tap-gui-component. Total number of files: 0

Update the tap packages using updated values for changes to take affect

tanzu package installed update tap -f tap-values-view.yaml -n tap-install
 Updating installed package 'tap'
 Getting package install for 'tap'
 Getting package metadata for 'tap.tanzu.vmware.com'
 Updating secret 'tap-tap-install-values'
 Updating package install for 'tap'
 Waiting for 'PackageInstall' reconciliation for 'tap'
 'PackageInstall' resource install status: ReconcileSucceeded
Updated installed package 'tap' in namespace 'tap-install'

Once the packages are updated successfully, verify the Docs section in TAP GUI under the tap-gui-component

Here you go: