Backstage TechDocs setup
Running docs-like-code with TechDocs in production: building MkDocs sites in CI, publishing to S3, GCS or Azure Blob Storage, linking docs to catalog entities and extending pages with addons.
Backstage features
Pages on Backstage core features that each need their own design and operations decisions: documentation, search, authorization and Kubernetes visibility.
Backstage search with Elasticsearch, OpenSearch or PostgreSQL
Choosing and running a search engine for Backstage: Lunr for small setups, PostgreSQL or Elasticsearch and OpenSearch for larger ones, collators for catalog and TechDocs, and indexing schedules.
Backstage permission framework and RBAC
Replacing the default allow-all policy with real authorization in Backstage: enabling permissions, writing policies on users and groups, resolving group membership at sign-in, and testing policies before rollout.
Backstage Kubernetes plugin setup
Showing each service's deployments and pods across clusters in Backstage: backend cluster connections and credentials, mapping catalog entities to workloads, and scoping what developers can see.
Backstage API catalog with OpenAPI, AsyncAPI, GraphQL and gRPC
Publishing API definitions as API entities: the four well-known spec types, embedding definitions with $text, the backend.reading.allow list for external hosts, base URLs, and linking providers and consumers.
Building and publishing Backstage TechDocs in CI with techdocs-cli
Moving TechDocs generation out of the Backstage server into CI: techdocs-cli generate and publish, the content hash and skip-if-unchanged option, write tokens for CI and read-only access for the backend.
Choosing TechDocs storage: S3, Google Cloud Storage or Azure Blob Storage
Where generated TechDocs sites should live in production: local storage limits, S3 and S3-compatible buckets, GCS and Azure Blob Storage, latency from the storage location and access separation between CI and the backend.
Restricting TechDocs visibility with catalog permissions
Keeping internal documentation visible only to the right teams: default all-users visibility, catalog read permissions that TechDocs follows, HTML sanitization in the reader and access to the storage bucket.
Caching TechDocs for faster page loads
Reducing TechDocs latency when docs live in remote object storage: caching backend responses in a supported cache store, what to cache, and how cache choice ties to the Backstage cache configuration.
Indexing custom sources in Backstage search with collators
Extending search beyond catalog and TechDocs: what collators do, adding sources from other plugins, choosing an engine that handles the index size, and the PostgreSQL 12 requirement for the Postgres engine.
Backstage Kubernetes plugin across EKS, AKS and GKE clusters
Showing workloads from several clusters in one service view: cluster locator methods, the authProvider options for EKS, AKS, GKE and service accounts, user versus service credentials, and the kubernetes-id label.
