Open Horizons Backstage Kubernetes

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

1. Confirm Backstage version, frontend mode, cluster topology, and security boundary.
2. Install @backstage/plugin-kubernetes in the app and @backstage/plugin-kubernetes-backend in the backend.
3. Register the backend plugin and confirm frontend feature discovery or explicit installation.
4. Choose a service locator and cluster locator based on tenancy and catalog ownership.
5. Configure cluster authentication with the least privilege needed for read-only service views.
6. Link entities to workloads using supported annotations or catalog relations.
7. Keep service-account tokens out of catalog entity annotations.
8. Configure custom resources, metrics lookup, TLS verification, and failure behavior explicitly.
9. Enable pod deletion only when required, permission-protected, and approved.
10. Apply the permission framework for clusters, resources, and proxy access.
11. Validate multiple clusters, missing annotations, partial locator failures, denied users, and representative workloads.

Permission surface

• kubernetes.clusters.read
• kubernetes.resources.read
• kubernetes.proxy

Treat proxy access as higher risk because it can forward arbitrary Kubernetes API requests.

Open Horizons integration

• Scope Kubernetes changes to the Developer IDP or Agent IDP objective and current Horizon stage.
• Preserve Open Horizons AKS, managed-identity, Backstage, and evidence boundaries where applicable.
• Route cross-domain sequencing through open-horizons-orchestration (skill).

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.

References

• Backstage Kubernetes
• Kubernetes configuration