backstage-kubernetes

Backstage Kubernetes

Make a service's real cluster workloads — including your own custom resources — appear on its entity page. Four things must line up: the cluster is reachable, Backstage is authorised on it, the entity is annotated, and the object type is requested. A miss on any one shows as an empty tab.

Preconditions

• Backend generation known. New backend system: backend.add(import('@backstage/plugin-kubernetes-backend')) in packages/backend/src/index.ts. Legacy: a createRouter under packages/backend/src/plugins/, which must be migrated before adding modules (backstage-plugin-migrate). Frontend: NFS consumes the plugin's /alpha export; legacy imports EntityKubernetesContent into the entity page.
• Cluster reachability from the backend, not from your laptop. A cluster behind a VPN the backend pod cannot reach fails identically to a wrong URL.
• Exact config shapes read from the installed @backstage/plugin-kubernetes-backend config.schema.json, and exact annotation constants from @backstage/plugin-kubernetes-common. Both move.
• Read access to the cluster's RBAC, because surfacing a CRD needs an explicit grant and that grant is usually the missing piece.
• Any change to a real cluster's RBAC or service accounts is external mutation: stop and return a BLOCKED report with the exact Role and ClusterRole rules needed, rather than applying them.

Procedure

1. Establish which of the four layers is missing before editing config. Query the backend directly: POST /api/kubernetes/services/<entity-name> with a user token. A 200 with an empty array is an annotation or selector problem; a 500 naming a cluster is reachability or auth; a 404 means the plugin is not wired at all.
2. Choose a cluster locator method. config lists clusters inline and is right for a handful. catalog reads them from Resource entities of type kubernetes-cluster, which scales and keeps cluster inventory in the catalog. gke discovers GKE clusters in a project. localKubectlProxy is development only — it assumes kubectl proxy on the developer's machine and must never reach a deployed config.
3. Declare clusters under kubernetes.clusterLocatorMethods. Per cluster the fields are url, name, and one of the auth arrangements: a serviceAccountToken, or an authProvider with authMetadata. Optional: title, skipTLSVerify, skipMetricsLookup, caData, caFile, oidcTokenProvider, and a per-cluster customResources. Every credential is ${ENV_VAR} or a $env/$file reference — never a literal.
4. Pick serviceLocatorMethod deliberately. multiTenant queries every cluster for every entity and is the usual default. singleTenant and catalogRelation narrow that. On a large fleet multiTenant is a latency and rate-limit problem before it is a correctness one.
5. Annotate the entities. backstage.io/kubernetes-id matches objects carrying the backstage.io/kubernetes-id label with the same value — the label goes on your workloads, in your manifests or Helm chart, and is the half people forget. backstage.io/kubernetes-label-selector replaces that with an arbitrary selector and wins when both are present. Namespace can be narrowed with the namespace annotation. Validate with backstage-catalog.
6. Request the object types you want. kubernetes.objectTypes accepts pods, services, configmaps, deployments, limitranges, resourcequotas, replicasets, horizontalpodautoscalers, jobs, cronjobs, ingresses, statefulsets, daemonsets and customresources. Setting it at all replaces the default set — a list that omits pods hides pods, which reads as a broken plugin.
7. Declare each CRD you want surfaced in kubernetes.customResources as { group, apiVersion, plural }. All three are required, apiVersion is the version alone (not group/version), and plural is the CRD's spec.names.plural — not the Kind. Declare them per cluster instead when only some clusters have the operator installed. See kubernetes-crd-author when the CRD is one you own.
8. Grant RBAC for the custom resources. The default guidance grants the core workload types only; a CRD needs its own apiGroups/resources rule with get, list and watch. This is the most common reason a correctly declared CRD stays invisible. Prepare the ClusterRole and stop for authorization before anything is applied to a real cluster.
9. Restrict what reaches the frontend. The plugin returns whole objects, so a Secret-adjacent CRD or one with credentials in spec exposes them to every user who can see the entity. Decide per CRD whether it should be surfaced at all, and treat that as a data-exposure review, not a config change.
10. Wire the frontend for the repo's generation and confirm the tab renders for an entity you know has workloads, not for an arbitrary one.