What the Backstage Kubernetes plugin shows and when to set it up
The Backstage Kubernetes plugin shows a service's Kubernetes workloads, including deployments and pods, inside its catalog entity, so developers no longer have to switch to cluster tools to find out whether a service is running. It works by reading the catalog: a workload appears only when the component's entity carries the annotation that tells the plugin which labels identify its resources, so the Software Catalog is the foundation for everything the plugin shows. Kubernetes is one of the plugins the Backstage architecture overview lists alongside the core built-in features, which means it sits next to the catalog rather than replacing it. Backstage is an open source framework released under the Apache License 2.0 (SPDX: Apache-2.0), and the project offers no paid edition, so the cost of this work is the engineering time to connect clusters, map entities and control access.
Set this up when developers regularly ask where a service is running and what state its pods are in, and when your catalog already holds reliable ownership and component data. If the catalog is incomplete, the plugin will show empty or wrong views, and fixing the catalog first is the cheaper path. The plugin also forces a cluster access decision early. It must read Kubernetes resources, so you need to choose which identity it uses, which clusters it can reach and which namespaces it can see. Those choices determine what a developer can learn from the portal, so treat them as security decisions and not only as configuration. Confirm with your platform team which clusters are in scope and who approves read access before you connect the first one.
Plan the rollout in the order the risk demands. Start with one cluster and a small set of catalog components, verify that each entity shows only its own workloads, and only then widen the cluster list. Ask your platform team to confirm which Kubernetes version and distribution your clusters run, because Kubernetes maintains only its three most recent minor releases and the plugin's expectations must match what those clusters serve. Also record who will own the Backstage side of the configuration, since catalog annotations, cluster entries and RBAC bindings change as teams and services change. A clear owner for each of those three areas prevents the common situation where the portal shows stale or overly broad data long after the cluster behind it has changed.
Cluster credential and authentication options compared
This table compares the three ways the Backstage backend can reach cluster APIs: a service account token held by the backend, user-delegated credentials passed through sign-in, and an external cloud auth provider. Read each row against your clusters' RBAC model and your audit requirements, then choose the option that matches who should be accountable for each API call.
| Option | When it fits | Who it limits | Main trade-off |
|---|---|---|---|
| Service account token held by the backend | Read-only views of workloads where every developer may see the same resources for a given entity | Anyone with access to the Backstage backend view can see what the service account can read, so scope it narrowly per cluster | Simple to run, but API calls are attributed to one identity and per-user visibility must be enforced in Backstage itself |
| User-delegated credentials passed through sign-in | Teams that need Kubernetes RBAC to decide what each person sees, and where audit logs should name the individual | Users without cluster RBAC rights see empty or partial results, so access requests become a platform task | Accurate per-user access, but depends on the sign-in provider issuing tokens the cluster accepts and on token lifetime handling |
| External cloud auth provider | Managed clusters on a major cloud where the provider already issues short-lived identities to workloads | Limits use to clusters and identity types the provider supports, so confirm the option names and version support for your platform | Avoids long-lived secrets in the backend, but adds cloud IAM setup and ties the design to that provider's model |
| Long-lived static token in configuration | Short-term proof of concept on a non-production cluster only | Anyone who can read backend configuration or secrets can use the token, so it cannot be scoped per user | Fastest to set up, but leaves a credential that rarely rotates and is hard to audit |
| Scope of visibility | Decide whether developers see only workloads tied to their catalog entities or every workload the credential reads | Determines whether the Kubernetes tab filters by entity label or by namespace | Narrow scopes reduce exposure but need labels that teams keep current |
| Credential rotation and revocation | Any option that uses a token or certificate the backend stores | Platform operators who must revoke access when someone leaves or a cluster is retired | Ask how rotation runs without a backend restart and how revocation reaches cached sessions |
| Provider-specific setup | Choose after you pick one of the options above | Depends on each cloud's identity model, so details belong on the multi-cluster page | Confirm plugin option names and supported versions in the Backstage Kubernetes plugin documentation before you configure anything |
How to set up the Kubernetes plugin step by step
This sequence takes a Backstage instance from no cluster visibility to a verified view of one service's deployments and pods, with credentials kept out of config files and each cluster reached through a read-only identity. Each step closes with a check you can run before moving on.
Install the Kubernetes plugin packages
Add the Kubernetes backend and frontend plugin packages to the Backstage app using the Backstage CLI so that they match the core @backstage package versions already in the repository. Wire the backend plugin into the backend entry point and the frontend component into the entity page layout. Done means the app builds and starts locally, and the Kubernetes tab appears on a catalog entity page, even if it reports that no clusters are configured yet. If you upgrade Backstage later, keep these packages on the same release line as the rest of the @backstage packages.
Create a read-only service account per cluster
For each cluster, create a dedicated service account in a管理 namespace that Backstage uses only for reading workloads. Bind it to a ClusterRole that grants get and list on the workload resources the plugin displays, such as pods, deployments, replica sets, services, ingresses and horizontal pod autoscalers, and avoid write verbs and wildcards. Have the cluster owner review the role before it is applied. Done means that
kubectl auth can-ireturns yes for the listed read verbs and no for create, update and delete, run while impersonating the service account.Store cluster tokens in a secret source
Generate the token for each service account and place it in your organization's secret store, such as the store your platform team already uses for application secrets. Reference it from the Backstage environment at runtime so that the value is injected into the backend process and never committed to the repository or written into app-config files. Restrict who can read the secret to the team that runs the Backstage backend. Done means that a search of the repository and the rendered configuration files finds no token value, and the backend starts with the secret supplied from the environment.
Register each cluster in the plugin configuration
Add one entry per cluster under the Kubernetes plugin configuration, giving each a name, the API server URL, the reference to the injected token and the cluster's CA data. Choose a cluster locator method that matches how you want Backstage to find the clusters, and confirm the exact option names against the Kubernetes plugin documentation for your Backstage version. Keep the API server addresses reachable from the Backstage backend network. Done means the backend log reports each cluster as connected, and the Kubernetes API endpoint responds to a read request from the backend host.
Annotate catalog entities with kubernetes-id
Add the kubernetes-id annotation to each component's catalog descriptor, with a value that matches the label your workloads carry for that service. The label on the Kubernetes objects and the annotation on the entity are the join key, so agree on the naming convention with the teams that own deployments before editing many descriptors. Ask owners to confirm the label value in their manifests. Done means the catalog shows the annotation on the entity, and the label value appears in a sample deployment manifest for that service.
Verify with a test service
Pick one service with a known deployment, open its catalog entity and confirm that the Kubernetes tab lists the expected deployments, replica sets and pods across the clusters it runs in. Compare the pod names and counts against
kubectl get podsusing the same label selector. Then sign in as a user outside the owning team and confirm what they see, since this check shows whether the read scope matches your intent. Done means the counts match in every cluster, and the cross-team test returns only the scope you approved.Roll out to remaining services and record ownership
After the test service passes, extend the annotation to the remaining components in batches, and assign a named owner for the cluster configuration and the service account rotation. Record the cluster list, the RBAC role version and the secret reference in your runbook so that a future upgrade or cluster change has a single place to check. Done means every in-scope entity shows workloads or a clear reason for missing data, and the runbook names the owners who will rotate the credentials.
Mapping catalog entities to workloads without false matches
The label or annotation convention is the most common reason a Backstage Kubernetes view is empty or wrong. The plugin finds workloads by matching selectors that you define on each catalog entity, so a single mismatch in a key or value means the entity shows nothing, or shows another team's pods. Before you configure the plugin, agree one naming scheme across teams and write it down. Most teams use the backstage.io/kubernetes-id annotation on the Component, with the same value applied as a label on the Deployment, StatefulSet or other workload. Confirm the exact annotation and label keys, and the matching rules, in the Kubernetes plugin documentation for the Backstage release you run, because these details change between releases. Decide who owns the scheme, where it is enforced (a template, a policy check in CI or an admission rule), and how a team requests an exception.
Some Components span several namespaces or clusters, such as an API served from a regional cluster and a worker running in another. Model these as one Component with a single kubernetes-id value, and make sure every workload that belongs to it carries that value, regardless of namespace or cluster. Do not create a separate Component per cluster unless each one is an independently owned service, because that splits the view and inflates the catalog. Where a namespace or cluster is shared by many services, a label that is too generic, such as app: web, will match workloads from several Components at once. Use values that are unique within the organization, and have the catalog owner review any label reused across teams.
Run two checks before you rely on the views. First, list every Component that declares the annotation and confirm that the plugin returns at least one workload for it, since an entity that matches nothing usually points to a typo, a missing label or a cluster that is not in the configured cluster list. Second, look for shared labels that match too much, by confirming that each Component's view lists only its own Deployments and pods. Ask each team to name the workloads they expect to see, then compare that list with what Backstage shows. Repeat these checks after a template change or a new cluster joins, and keep the results as evidence of your ownership model.
Scoping what developers can see in the Kubernetes view
The Kubernetes view is only as narrow as the credentials behind it and the permissions that gate it in Backstage. Five controls shape what a developer can see: the cluster identity, the Secrets exposure in the cluster, catalog-based read access, sign-in mode, and audit trails for backend access.
Least-privilege service account
The Backstage backend reads workloads through a Kubernetes service account or a cluster credential, and whatever that identity can read, the portal can show. Grant read-only access to the resource types the plugin needs, such as Deployments, Pods, ReplicaSets and Services, in the namespaces each entity owns, rather than a cluster-wide admin role. Ask your platform team to write the role as a ClusterRole or Role manifest and review it before the first deployment. Confirm the exact resource list against the plugin's README for your version.
Secrets exposure in etcd
Kubernetes stores Secrets unencrypted in etcd by default. Anyone who can list or watch Secrets through the API, or read an etcd snapshot, can recover their values. The Backstage service account should never be granted access to Secrets, and the plugin should not render Secret objects. Confirm that encryption at rest is enabled on each cluster, and that backups of etcd are protected with the same care as the cluster itself. The Kubernetes secrets good practices guidance covers the controls to check.
Catalog permissions govern who sees the view
The Kubernetes tab appears on a catalog entity, so a user who can read the entity in the catalog can usually reach its workload view. Until the permission framework is enabled, the default policy allows everyone to see every entity. Decide which groups may read each system or component before you rely on the Kubernetes view for sensitive services. Test the policy with a user from each team to confirm they see their own workloads and not those of other teams.
No guest access in production
The authentication guidance advises against offering guest access in production. A guest identity has no real organizational group membership, so group-scoped catalog rules cannot restrict it correctly. Remove the guest provider from production configuration and require sign-in through your identity provider. Configure sign-in resolvers so each provider maps to the same user identity, otherwise the same person can appear as two users with different entity access.
Auditing backend cluster access
Record which cluster APIs the backend calls, which identity it uses, and which entities trigger those calls. Kubernetes audit logging, configured on the API server, shows the requests made with the Backstage service account, so you can detect unusual list operations across namespaces. Ask your platform team whether audit policy captures read requests from that account and where logs are retained. Review these logs against the catalog ownership model on a regular schedule.
Questions teams ask before setting up the Kubernetes plugin
How much effort does a Backstage Kubernetes plugin setup take, and what drives the cost?
Effort depends mainly on four factors: how many clusters the plugin must reach, which credential model you choose, how consistently teams label their workloads, and how much permission design you need before developers see anything. A single cluster with one service account and clean labels is a small job. Many clusters across several cloud providers, with per-user credentials and inconsistent labels, adds work at each step. Cost is paid for the engineering time to design, configure, test and document the setup, plus any remediation of labels and catalog entries. Ask any partner for a written scope that lists clusters, credential types, label changes and permission rules, since those items set the quote.
Can our internal platform team set up the Kubernetes plugin without outside help?
Often yes, if the team already runs the clusters, understands Kubernetes RBAC and has someone who can own the Backstage configuration. The plugin itself is documented, but the decisions around it are where teams usually get stuck: which identity the backend uses to read cluster state, how far that identity reaches, and how developers' views are limited. A team that has never reviewed Kubernetes authentication, or that lacks time to test permissions before rollout, may benefit from a partner for design and review. Compare the internal time needed for these decisions against your current backlog before choosing.
What do we need to provide for the work to go smoothly?
Plan to provide cluster admin access, or a named person with that access, for every cluster in scope. You will also need to make RBAC decisions: which namespaces and resources the backend may read, and whether developers see workloads under their own identity or through a shared service account. Catalog ownership matters too, because each workload must map to a catalog entity owned by a team. Confirm who approves permission changes, who maintains labels on Kubernetes objects, and where the Backstage configuration and secrets will live. Missing answers to these questions are the most common cause of delays.
How do we scope what developers can see in Kubernetes views?
Start by deciding the visibility model before connecting any cluster. The backend's credential sets the upper limit of what the plugin can read, so it should be limited to the resources the plugin needs, typically read-only access to workloads and related objects in chosen namespaces. Decide whether developers see only workloads tied to their own catalog entities, or whether platform teams see broader views. Test the result with accounts from each team before rollout, and review the design whenever clusters or teams change. Confirm with your identity and Backstage owners how group membership is resolved at sign-in.
How long does the setup take, and what changes the timeline?
Duration depends on scope, not on a fixed period. A single-cluster pilot with a settled credential model and consistent labels can move quickly. Timing lengthens with each additional cluster, each cloud provider's authentication method, each team that needs its own permission rules, and each label or catalog cleanup needed first. Test and review cycles also add time, especially where security teams must approve credentials. Ask for a timeline tied to the written scope, with milestones for cluster connection, label mapping, permission testing and rollout.
Does DeployOpen work on fixed-scope terms with a written quote?
Yes. Most DeployOpen engagements are fixed-scope, meaning the scope, deliverables and timeline are agreed in writing before work starts. A quote follows from that written scope, so the more clearly you define clusters, credential models, label expectations and permission rules, the more specific the quote can be. DeployOpen does not publish a price list. Ongoing support, upgrades and continuous testing are available as retainers, which is a separate agreement from the initial setup. Ask for the written scope and quote to list what is excluded as well as included.
How DeployOpen scopes and delivers this work
Every Kubernetes plugin engagement starts with a written, fixed scope that names the clusters, credentials and catalog entities in play. The cards below follow the work in order, from the cluster and credential review through catalog mapping, verification and handover, with optional retainer support after go-live.
Written fixed scope first
Before any work starts, the scope names the clusters to be connected, the entity types to be mapped, the namespaces and resource kinds to display, and the deliverables and timeline agreed in writing. Ask for the list of clusters and the owner of each one, since an unnamed cluster is the most common source of later change requests. The scope also records what is out of scope, such as building the Kubernetes distribution itself or changing the cluster's own RBAC model.
Cluster and credential review
We review each cluster's API endpoint, authentication method and the identity Backstage will use to read it. The question to settle is whether the portal reads with a single service account or passes through each user's own identity, because that choice decides what developers can see. Confirm which secret store holds the tokens and who can read them, since Kubernetes Secrets are unencrypted in etcd unless encryption at rest is configured.
Catalog mapping conventions
We agree on the label conventions that link each catalog component to its workloads, usually a backstage.io/kubernetes-id label on the Deployment or pod template, and on any namespace or cluster annotations. Defining these before rollout means a team can onboard a service by changing its manifest rather than filing a ticket. Ask who owns the convention, how new services are checked against it, and what happens to entities that have no matching labels.
Verification on representative services
Testing uses a representative set of services chosen by your teams, covering multiple clusters, namespaces and workload types such as Deployments, StatefulSets and CronJobs. We check that each entity shows the right pods and that a user without access to a namespace sees nothing from it. We also confirm that the portal behaves when a cluster API is unreachable, so the failure is visible and bounded.
Access scoping for developers
Developers should see the workloads of services they own, and the scope of that view needs to match your existing Kubernetes access model. We map catalog ownership to the groups that hold cluster read permissions, and we test that the portal does not show resources beyond those groups. Confirm with your security team whether pod logs and exec-style actions are exposed, since those widen the access surface considerably.
Handover and optional retainer
At handover you receive documentation covering cluster connections, credential rotation steps, the label convention, the test cases used and the known limits. Backstage and the Kubernetes API both move on their own release schedules, so the plugin configuration will need upkeep. A retainer can cover upgrades, credential rotation and new cluster onboarding, and its scope and cost are agreed in writing like any other engagement.
