paulasilvatech Backstage Kubernetes
Expose workload health to service owners without turning Backstage into a cluster-administration console.
When to invoke
- "Add the Kubernetes tab to catalog entities."
- "Configure cluster discovery and authentication."
- "Fix missing workloads or cluster access."
- "Restrict Kubernetes resources and proxy permissions."
Procedure
- Confirm Backstage version, frontend mode, cluster topology, and security boundary.
- Install
@backstage/plugin-kubernetesin the app and@backstage/plugin-kubernetes-backendin the backend. - Register the backend plugin and confirm frontend feature discovery or explicit installation.
- Choose a service locator and cluster locator based on tenancy and catalog ownership.
- Configure cluster authentication with the least privilege needed for read-only service views.
- Link entities to workloads using supported annotations or catalog relations.
- Keep service-account tokens out of catalog entity annotations.
- Configure custom resources, metrics lookup, TLS verification, and failure behavior explicitly.
- Enable pod deletion only when required, permission-protected, and approved.
- Apply the permission framework for clusters, resources, and proxy access.
- Validate multiple clusters, missing annotations, partial locator failures, denied users, and representative workloads.
Permission surface
kubernetes.clusters.readkubernetes.resources.readkubernetes.proxy
Treat proxy access as higher risk because it can forward arbitrary Kubernetes API requests.
Output template
## Backstage Kubernetes result
| Cluster source | Auth | Service locator | Entity mapping | Validation |
| --- | --- | --- | --- | --- |
### Permissions
- Clusters:
- Resources:
- Proxy:
Quality gate
- Frontend and backend packages match the target version.
- Locator and tenancy choices are documented.
- Tokens and credentials are external to catalog entities.
- TLS and metrics behavior are explicit.
- Cluster, resource, and proxy permissions are least-privilege.
- Positive, missing, partial-failure, and denied-access paths are tested.