TechDocs

This guide explains how to generate and publish TechDocs for catalogs. For more information, see the Backstage.io documentation.

Create an Amazon S3 bucket

To create an Amazon S3 bucket:

  1. Go to Amazon S3.
  2. Click Create bucket.
  3. Give the bucket a name.
  4. Select the AWS region.
  5. Keep Block all public access checked.
  6. Click Create bucket.

Configure Amazon S3 access

The TechDocs are published to the S3 bucket that was recently created. You need an AWS user’s access key to read from the bucket when viewing TechDocs. To configure Amazon S3 access:

  1. Create an AWS IAM User Group:

    1. Click Create Group.
    2. Give the group a name.
    3. Click Create Group.
    4. Click the new group and navigate to Permissions.
    5. Click Add permissions and click Create Inline Policy.
    6. Click the JSON tab and replace contents with this JSON replacing BUCKET-NAME with the bucket name.

      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Sid": "ReadTechDocs",
                  "Effect": "Allow",
                  "Action": [
                      "s3:ListBucket",
                      "s3:GetObject"
                  ],
                  "Resource": [
                      "arn:aws:s3:::BUCKET-NAME",
                      "arn:aws:s3:::BUCKET-NAME/*"
                  ]
              }
          ]
      }
      
    7. Click Review policy.

    8. Give the policy a name and click Create policy.
  2. Create an AWS IAM User to add to this group:

    1. Click Add users.
    2. Give the user a name.
    3. Verify Access key - Programmatic access and click Next: Permissions.
    4. Verify the IAM Group to add the user to and click Next: Tags.
    5. Click Next: Review then click Create user.
    6. Record the Access key ID (AWS_READONLY_ACCESS_KEY_ID) and the Secret access key (AWS_READONLY_SECRET_ACCESS_KEY) and click Close.

Find the catalog locations and their entities’ namespace/kind/name

TechDocs are generated for catalogs that have markdown source files for TechDocs. To find the catalog locations and their entities’ namespace/kind/name:

  1. The catalogs appearing in Tanzu Application Platform GUI are listed in the config values under app_config.catalog.locations.
  2. For a given catalog, clone the catalog’s repository to the local file system.
  3. Find the mkdocs.yml that is at the root of the catalog. There is a YAML file describing the catalog at the same level called catalog-info.yaml.
  4. Record the values for namespace, kind, and metadata.name, and the directory path containing the YAML file.
  5. Record the spec.targets in that file.
  6. Find the namespace/kind for each of the targets:
    1. Navigate to the target’s YAML file.
    2. The namespace value is the value of namespace. If it is not specified, it has the value default.
    3. The kind value is the value of kind.
    4. The name value is the value of metadata.name.
    5. Record the directory path containing the YAML file.

Use the TechDocs CLI to generate and publish TechDocs

VMware uses npx to run the TechDocs CLI, which requires Node.js and npm. To generate and publish TechDocs by using the TechDocs CLI:

  1. Download and install Node.js and npm.
  2. Install npx by running:

    npm install -g npx
    
  3. Generate the TechDocs for the root of the catalog by running:

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

    This creates a temporary site directory in your current working directory that contains the generated TechDocs files.

  4. Review the contents of the site directory to verify the TechDocs were generated successfully.

  5. Set environment variables for authenticating with Amazon S3 with an account that has read/write access:

    export AWS_ACCESS_KEY_ID=AWS-ACCESS-KEY-ID
    export AWS_SECRET_ACCESS_KEY=AWS-SECRET-ACCESS-KEY
    export AWS_REGION=AWS-REGION
    
  6. Publish the TechDocs for the root of the catalog to the Amazon S3 bucket you created earlier by running:

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

    Where NAMESPACE/KIND/NAME are the values for namespace, kind, and metadata.name you recorded earlier. For example, default/location/yelb-catalog-info.

  7. For each of the spec.targets found earlier, repeat the generate and publish commands.

    The generate command erases the contents of the site directory before creating new TechDocs files. Therefore, the publish command must follow the generate command for each target.

Update techdocs section in app-config.yaml to point to the Amazon S3 bucket

Update the config values you used during installation to point to the Amazon S3 bucket that has the published TechDocs files:

  1. Add or edit the techdocs section under app_config in the config values with the following YAML, replacing placeholders with the appropriate values.

    techdocs:
      builder: 'external'
      publisher:
        type: 'awsS3'
        awsS3:
          bucketName: BUCKET-NAME
          credentials:
            accessKeyId: AWS-READONLY-ACCESS-KEY-ID
            secretAccessKey: AWS-READONLY-SECRET-ACCESS-KEY
          region: AWS-REGION
          s3ForcePathStyle: false
    
  2. Update your installation from the Tanzu CLI.

    • If you installed Tanzu Application Platform GUI as part of the Tanzu Application Platform package (in other words, if you installed it by running tanzu package install tap ...) then run:

      tanzu package installed update tap \
      --version PACKAGE-VERSION \
      -f VALUES-FILE
      

      Where:

      • PACKAGE-VERSION is your package version
      • VALUES-FILE is your values file
    • If you installed Tanzu Application Platform GUI as its own package (in other words, if you installed it by running tanzu package install tap-gui ...) then run:

      tanzu package installed update tap-gui \
      --version PACKAGE-VERSION \
      -f VALUES-FILE
      

      Where:

      • PACKAGE-VERSION is your package version
      • VALUES-FILE is your values file
  3. Verify the status of this update by running:

    tanzu package installed list
    
  4. Navigate to the Docs section of your catalog and view the TechDocs pages to verify the content is loaded from the S3 bucket successfully.

check-circle-line exclamation-circle-line close-line
Scroll to top icon