OnCallReadyStart learning

Infrastructure as code Lesson 42.20 · Platform Engineering: Backstage & Crossplane · 13 min read

TechDocs and the Kubernetes plugin

In plain words

Instead of keeping the instruction manual in a drawer in another building, TechDocs staples it to the machine. The manual lives next to the code, gets updated in the same change as the code, and Backstage shows it on the service's page. The Kubernetes tab is a window into the factory floor showing which copies of the machine are running right now.

TechDocs: documentation next to the code

Documentation in a wiki rots, because nobody updates a wiki in the same merge request as the code. TechDocs is Backstage's "docs like code" system: the docs are Markdown files in the service's repository, built with MkDocs into a static site and shown on the entity's Docs tab. A change to the runbook goes through the same review as the change to the code it describes.

Three things make a repository's docs appear in Backstage:

orders/
├── catalog-info.yaml      annotations:  backstage.io/techdocs-ref: dir:.
├── mkdocs.yml             site_name, nav, plugins: [techdocs-core]
└── docs/
    ├── index.md           the home page
    └── runbook.md
site_name: orders
site_description: How the orders service works and how to run it
nav:
  - Home: index.md
  - Runbook: runbook.md
plugins:
  - techdocs-core
  • backstage.io/techdocs-ref: dir:. on the entity says "the docs source is in this directory" (relative to the catalog-info.yaml). Without the annotation the entity has no Docs tab.
  • mkdocs.yml configures MkDocs. The techdocs-core plugin (the mkdocs-techdocs-core Python package) bundles the theme and the Markdown extensions Backstage expects; the generator adds it if it is missing.
  • docs/index.md is the first page. Without it the site has no home page (--legacyCopyReadmeMdToIndexMd makes the generator copy a README.md there instead - a crutch for old repositories).

Building the site

The @techdocs/cli builds exactly what Backstage would build. By default it runs MkDocs inside the spotify/techdocs container (v1.2.8 for CLI 1.13.0), so the only local requirement is Docker:

$ npx @techdocs/cli generate
info: Using engine: mkdocs (binary: mkdocs)
info: Using source dir /home/learner/xp
info: Will output generated files in /home/learner/xp/site
info: Generating documentation...
info: Successfully generated docs from /home/learner/xp into /home/learner/xp/site using techdocs-container
info: Computed generated site content hash: 9a0a26bac120e6b5284f815a74f410d3702a1cf624a3d642e90a223a2e4ce9ab
info: Done!
$ cat mkdocs.yml
site_name: orders
nav:
  - Home: index.md
plugins:
  - techdocs-core

Look at mkdocs.yml afterwards: the generator wrote the techdocs-core plugin into your file (it patches the source directory, not a copy). Commit that line yourself so the file in git is the file that builds; --omitTechdocsCoreMkdocsPlugin turns the patching off.

With --legacyCopyReadmeMdToIndexMd and no docs/index.md, the generator warns and copies the first README it finds into docs/index.md - also in your source directory:

$ npx @techdocs/cli generate --legacyCopyReadmeMdToIndexMd
...
warn: docs/index.md not found.
warn: docs/README.md not found.
warn: docs/readme.md not found.
info: Successfully generated docs from /home/learner/xp into /home/learner/xp/site using techdocs-container
...

Commit a real docs/index.md instead.

--verbose (-v) also prints MkDocs' own log, which is where the real reason for a failed build is (the non-verbose error is only Docker container returned a non-zero exit code (1)):

$ npx @techdocs/cli generate --verbose
...
verbose: INFO    -  Cleaning site directory
verbose: INFO    -  Building documentation to directory: /output
verbose: INFO    -  Documentation built in 0.54 seconds
...

The output in ./site/ is a static website plus techdocs_metadata.json (site name, description, the list of files and an etag, a hash of the generated content Backstage uses to decide whether its copy is stale).

--no-docker runs a locally installed mkdocs (pip install mkdocs-techdocs-core) instead.

Basic and recommended setups

Where does Backstage build the docs?

SetupWho buildsWhere the site is stored
Basicthe Backstage backend, the first time someone opens the Docs tab (and again when the source changed)local disk of the backend
RecommendedCI, on every merge: techdocs-cli generate, then techdocs-cli publishobject storage: S3, GCS, Azure Blob

The recommended setup keeps MkDocs (and Docker) out of the Backstage pods and makes the docs available the moment CI finishes. In app-config.yaml: techdocs.builder: external and techdocs.publisher.type: awsS3, with a bucket - which you can, of course, create with a Crossplane StorageBucket.

The Kubernetes plugin

The Kubernetes tab of an entity shows what is running for it: Deployments, Pods, their status and recent errors, across clusters. The backend plugin asks each configured cluster for objects that carry a label matching the entity's annotation:

# catalog-info.yaml
metadata:
  annotations:
    backstage.io/kubernetes-id: orders
# the Deployment (and its pod template)
metadata:
  labels:
    backstage.io/kubernetes-id: orders
spec:
  template:
    metadata:
      labels:
        backstage.io/kubernetes-id: orders

Label the pod template too: Pods are found by their own labels, not their owner's. backstage.io/kubernetes-namespace limits the lookup to a namespace; backstage.io/kubernetes-label-selector replaces the id with any selector (app=orders,tier=backend).

The backend needs to reach the clusters: kubernetes.clusterLocatorMethods in app-config.yaml lists them (a fixed config list, or discovered from the catalog or a cloud API), each with an auth provider (serviceAccount, aws, google...). The ServiceAccount needs read access (get/list/watch) to the kinds the plugin shows. A missing label is the most common "Kubernetes tab is empty" ticket.

In an interview: TechDocs builds Markdown from the service's repository with MkDocs (techdocs-core plugin) into a static site shown on the entity; the entity points at it with backstage.io/techdocs-ref; in the recommended setup CI runs techdocs-cli generate and publish to object storage. The Kubernetes plugin finds workloads by the backstage.io/kubernetes-id label, on the Deployment and its pod template.

Why it helps

Runbooks and docs that live in the repository stay accurate because they are reviewed with the code they describe, and on call you need them next to the service's ownership and status. Knowing how techdocs-ref, mkdocs.yml and the techdocs CLI fit together, and how the Kubernetes plugin selects pods by label, fixes the two most common "the tab is empty" tickets.

Commands in this lesson

npx cat

FAQ

What makes the Docs tab appear?

The annotation backstage.io/techdocs-ref on the entity, usually dir:. to say the docs source is next to catalog-info.yaml, plus an mkdocs.yml and a docs folder with an index.md. Without the annotation the entity has no Docs tab at all.

What is techdocs-core?

An MkDocs plugin, the mkdocs-techdocs-core Python package, that bundles the theme and Markdown extensions Backstage expects. The generator adds it to mkdocs.yml if it is missing, so the site renders consistently inside Backstage for every team.

Why did my mkdocs.yml change after generate?

The generator patches the mkdocs.yml in your source directory, not a copy: when the techdocs-core plugin is missing it adds it and writes the file back. Commit the change so the file in git is the one that builds, or pass --omitTechdocsCoreMkdocsPlugin if you manage plugins yourself.

What is the recommended TechDocs setup?

CI builds the site on every merge with techdocs-cli generate and uploads it with techdocs-cli publish to object storage such as S3, and Backstage only reads it. The basic setup builds docs inside the Backstage backend when someone first opens the tab.

Why is the Kubernetes tab empty when the Deployment has the label?

The plugin selects each kind by its own labels, and Pods carry the labels of their template, not of their Deployment. Put backstage.io/kubernetes-id on the pod template too; changing the template rolls the pods, so plan it like any other deployment.

In an interview Mid

How do TechDocs and the Kubernetes plugin find a component's docs and pods?

TechDocs reads the backstage.io/techdocs-ref annotation, usually dir:., and builds the repository's Markdown with MkDocs and the techdocs-core plugin; in the recommended setup CI runs techdocs-cli generate and publish to object storage. The Kubernetes plugin queries each configured cluster for objects labelled backstage.io/kubernetes-id with the entity's value, per kind, so the Deployment and its pod template both need the label.

Also asked: What is the difference between the basic and recommended TechDocs setups? · Why keep documentation in the service repository? · How does the Kubernetes plugin authenticate to clusters?

Practise this lesson in the terminal Free, in your browser - a real Ubuntu terminal to try it in, with missions that check your work.