How the Backstage Kubernetes plugin shows one service across several clusters
The Backstage Kubernetes plugin lets a developer open one catalog entity and see the deployments, pods and related objects for that service, even when the service runs in several clusters. It reads workloads from each cluster it is configured to reach and filters them to the entity. The link between the two is the backstage.io/kubernetes-id annotation on the catalog entity, which must carry the same value as the label set on the Kubernetes objects. Teams need this when one service is split across EKS, AKS or GKE clusters, for example by region or environment, and developers currently switch between kubectl contexts or cloud consoles to see where their code is running.
The plugin is open source and released under the Apache License 2.0, and the Backstage project itself has no paid edition. That means the cost of this feature is the engineering time to wire it up, the cluster access you grant, and the ongoing maintenance of labels and credentials, not a license fee for the plugin. Before you start, inventory which clusters hold each service and confirm that every workload carries the kubernetes-id label consistently across clusters. A label applied in one cluster but missed in another produces a partial service view that looks correct, which is the most common reason teams distrust the feature.
Your first design decision is how the plugin finds clusters. The locator method controls this, and the options include static configuration, the catalog, GKE discovery and a local kubectl proxy. Each method changes who maintains the cluster list and how credentials are supplied, so choose it together with the authProvider settings described in the next section. Confirm the exact option names and their behavior for your Backstage version in the Backstage Kubernetes plugin configuration before you commit to a design.
Choosing a cluster locator method
The Kubernetes plugin needs to know which clusters to query before it can show any workload. The four locator methods differ in where that cluster list lives, who maintains it and whether it can discover clusters on its own, so the choice shapes both your credential model and your day-two effort.
Fixed cluster list with config
The config locator reads cluster names, API server URLs and auth settings directly from the Backstage configuration file, so every cluster is declared by hand. It suits a small, stable set of EKS, AKS or GKE clusters that change rarely, because the list is reviewed like any other code change. The cost is that adding or retiring a cluster means a configuration change and a redeploy, so check who owns that process before you choose it. Confirm the exact keys against the Kubernetes plugin configuration docs for your Backstage version.
Discovery from the software catalog
The catalog locator takes cluster definitions from entities in the software catalog, typically Resource entities that describe each cluster. This fits organizations where platform teams already register infrastructure in the catalog and want clusters to appear or disappear as those entities change. The trade-off is that catalog entries become a control point: anyone who can edit a cluster entity can change which cluster the plugin queries, so pair it with catalog ownership and permission rules.
Project discovery for GKE
The gke locator asks Google Cloud for the clusters in a project or set of projects, so new GKE clusters are picked up without a manual entry. It fits teams that create clusters often and run them in a known set of Google Cloud projects. Check that the Backstage backend identity can list clusters in each project, and decide early how you will handle projects that hold clusters you do not want exposed in the portal.
Local development with kubectl proxy
The localKubectlProxy locator uses a kubectl proxy running on the developer's machine to reach the API server, which avoids exposing clusters to the backend during development. It is useful for building and testing catalog annotations and dashboards on a laptop. It is not a production pattern, because each developer depends on their own kubeconfig and proxy, and the backend cannot reach clusters through it on a shared server.
Matching locator to credential model
The locator decides where cluster data comes from, but the authProvider decides how requests are authenticated, and the two must fit together. A config list paired with a service account token is simple to operate, while GKE discovery paired with user tokens requires each user's Google identity to be authorized on the cluster. Map each cluster you plan to show to a locator and an authProvider before writing configuration, and record the pairing for your security review.
authProvider options for EKS, AKS, GKE and service accounts
This table compares each authProvider value by the cloud or identity it targets, the credential the Kubernetes plugin presents to the cluster, and the situations where it fits. Read the credential column first, because it decides which identity must hold RBAC permissions and which identity appears in the cluster audit log.
| authProvider | Targets | Credential used | When it fits |
|---|---|---|---|
| serviceAccount | Any cluster, using a token from a Kubernetes service account | A service account token configured in the plugin, shared by every request | Single-team portals or clusters without cloud identity federation. Audit logs show the service account, not the developer. |
| aws | Amazon EKS clusters | An AWS identity resolved to a cluster token, typically the identity configured on the backend | EKS estates where the backend role is mapped to Kubernetes RBAC. Confirm the mapping before you grant access. |
| azure | Azure Kubernetes Service clusters using service account credentials | A credential held by the backend for the cluster | AKS clusters where a backend identity, not each user, is authorized. Confirm current Azure options with Microsoft documentation. |
| aks | AKS clusters | The signed-in user's AKS token obtained through the Microsoft authentication provider | Teams that need each developer's own Kubernetes permissions and audit trail. Users must sign in with Microsoft. |
| Google Kubernetes Engine clusters | The signed-in user's Google token | GKE estates where per-user RBAC is wanted. Users need access to the cluster through their Google identity. | |
| googleServiceAccount | GKE clusters | A Google service account used by the backend | GKE portals where one backend identity reads workloads. Audit logs show the service account. |
| oidc | Clusters that accept OpenID Connect tokens, including EKS or self-managed clusters | The signed-in user's OIDC token passed from Backstage sign-in | Mixed estates where one identity provider issues tokens for both Backstage and the clusters. Confirm the API server trusts the issuer. |
User credentials or service credentials: who the plugin acts as
The core decision in this section is whether the Kubernetes plugin calls each cluster as the signed-in developer or as one shared identity. The user-token providers (google, aks and oidc) forward the caller's own credential, so the cluster's RBAC decides what each person sees. The shared options (serviceAccount, googleServiceAccount and the aws variants) use one credential held by the Backstage backend, so Backstage itself must filter what each user is allowed to view. A shared service account gives the portal broad read access by default, and any gap in Backstage's own permission checks becomes a gap in cluster visibility.
Least privilege therefore follows the credential model. With user tokens, each cluster's role bindings grant access per person or per group, and a developer who cannot list pods in a namespace in kubectl will not see them in the portal either. With a shared identity, scope it to read-only verbs on the resources the plugin displays, bind it per cluster, and avoid cluster-admin. Ask each cluster owner which namespaces and resource types must appear, and confirm the chosen credential can read only those. Confirm also how your identity provider maps group claims to Kubernetes groups before relying on user tokens, because a missing mapping produces empty views rather than errors.
Kubernetes does not store user accounts as API objects. It authenticates users through X.509 client certificates, bearer tokens (including OpenID Connect and JWT tokens), webhook token authentication or an authenticating proxy, then authorizes the resulting username and groups through RBAC. This is why the user-token path depends on the cluster's OIDC configuration, and why an identity from a provider that does not issue tokens the cluster trusts will fail there. Check the authentication method each cluster uses before you choose a authProvider per cluster, since EKS, AKS and GKE each accept different token types. The Kubernetes authentication documentation explains the methods your clusters may use.
Setting up the plugin across three clusters
This sequence takes the Kubernetes plugin from a verified Backstage install to a service view that lists pods from EKS, AKS and GKE clusters, each reached with a read-only identity. Each step closes with a check you can run before moving on.
Confirm the Backstage version and plugin install
The platform engineer confirms which Backstage release line the portal runs and that the Kubernetes plugin packages are installed in both the frontend and the backend, using the same @backstage release set as the rest of the app. Upgrade first if the app is behind, because plugin configuration keys can change between releases. Check: the app starts, the Kubernetes tab appears on a test entity, and the backend log shows the Kubernetes plugin loaded without errors. Confirm the exact version and upgrade steps against the Backstage versioning policy before you begin.
Choose a locator method for each cluster
Decide how the backend will find each cluster. The config locator lists clusters statically under kubernetes.clusters, the catalog locator reads Resource entities, and the gke locator discovers GKE clusters in a project. Use the localKubectlProxy locator only for local development. Mixing locators is possible, so assign one per cluster and record the choice in your design notes. Check: a dry-run of the plugin backend lists the expected cluster names, with one entry per EKS, AKS and GKE cluster and no missing clusters.
Create read-only RBAC identities in each cluster
Cluster administrators create a dedicated service account in each of the three clusters, bind it to a read-only ClusterRole or namespaced Role, and limit it to the namespaces where catalog workloads run. Avoid cluster-admin and avoid granting access to Secrets, since developers only need workload status. Record which identities are service credentials and which will be user tokens. Check: running kubectl auth can-i list pods and kubectl auth can-i get secrets with each identity returns yes for pods in scoped namespaces and no for secrets.
Configure the authProvider for each cluster
Set authProvider per cluster to match its platform: aws for EKS, aks for AKS when the user's Microsoft token should be used, google for GKE with the user's token, googleServiceAccount for GKE with a service account, and serviceAccount for a bearer token from a service account in any cluster. Keep the choice explicit in each cluster block so one cluster's setting cannot be applied to another. Check: the backend starts with all three cluster entries and the Kubernetes plugin health endpoint reports each cluster as reachable.
Add the kubernetes-id annotation to catalog entities
Catalog owners add the backstage.io/kubernetes-id annotation to each Component entity, with a value that identifies the service. The same value must be set as a label on the Deployment, StatefulSet or other workload objects in every cluster that runs the service, because the plugin matches on that label. Agree the naming convention with service owners before rollout so values do not drift. Check: the entity page shows the annotation, and kubectl get deployments -A -l backstage.io/kubernetes-id=<value> returns the workload in each cluster that should appear.
Verify a test service shows pods from every cluster
Pick a test service that runs in all three clusters, or deploy a small illustrative workload to each cluster with the same kubernetes-id label. Open the entity's Kubernetes tab and confirm that pods from EKS, AKS and GKE appear grouped under their cluster names, with status and restart counts. Then confirm a service with no label in a cluster shows only the clusters where it is labeled. Check: the tab lists pods from all three clusters, and the cluster filter shows one group per cluster without errors or authentication failures in the backend logs.
Linking catalog entities to workloads with kubernetes-id
The link between a catalog entity and its workloads depends on one rule: the backstage.io/kubernetes-id annotation on the entity must carry the same value as the label of the same name on every Kubernetes object that belongs to that service. The plugin uses that shared value to find Deployments, pods, services and other resources across all of the clusters it reads, so the value must be identical in EKS, AKS and GKE. Decide the naming convention before the first cluster is onboarded. A common approach is to derive the ID from the component's catalog name and keep it lowercase, DNS-compatible and stable across renames, but whatever scheme you choose, write it into the descriptor template and the Helm or Kustomize base that deploys the service so teams cannot hand-edit it.
Drift is the most common reason a service view shows zero workloads or the wrong ones. A label that reads payments-api in the production cluster and payments in the staging cluster will leave one environment blank, and a copied manifest that keeps the old value after a rename can make a service display another team's pods. Because the annotation and label are both plain strings, Backstage does not warn you when they disagree. Check the mapping during rollout by listing the labels on a sample of workloads per cluster, for example with kubectl get deploy -A -L backstage.io/kubernetes-id, and comparing them with the annotations in the catalog. Confirm the exact selector behavior for your plugin version in the Backstage Kubernetes plugin configuration before relying on it for ownership reporting.
Security risks in cross-cluster visibility
A Kubernetes plugin that reads several clusters concentrates privileges in one place. The cards below cover the credentials Backstage holds, how secrets are stored, how read access is scoped, how access is logged, and where cluster traffic is allowed to travel.
Scope of the credentials used
Each authProvider decides whose identity Backstage presents to a cluster. A service account token gives the plugin one fixed set of permissions across every user, while a user's own token (for example, the AKS token from the Microsoft provider or a Google token) limits reads to what that person already may see. Decide per cluster which model applies, and confirm that the chosen identity cannot write to workloads. Ask the cluster owner to document the exact permissions granted.
Secrets handling for kubeconfig material
Kubernetes stores Secrets unencrypted in etcd by default, so any service account token or kubeconfig value that Backstage needs in a Secret is readable by anyone with broad API access to that cluster. Configure encryption at rest for etcd, or keep the credential in an external store and mount it through the Secrets Store CSI Driver. Inject values into Backstage through environment configuration rather than committing them to the repository.
Least-privilege RBAC for list and watch
The plugin needs to list and watch pods, deployments, services and related objects to show a service view, so the reader role should be namespace-scoped where the catalog maps cleanly to namespaces. Broad cluster-wide list and watch access exposes every Secret name and workload label in the cluster to the portal. Remove any write verbs, exclude Secret resources from the role where the plugin does not need them, and review the role after each new cluster is added.
Audit trail of identity and cluster
Kubernetes audit logs record which identity made each read, but only if audit policy covers the reads Backstage performs. In a shared service account setup, every portal user appears as the same identity, so the log cannot show who viewed what without correlating with Backstage's own logs. Confirm with each cluster team that audit logging is enabled for the relevant API groups, that logs are retained in a system the portal team cannot alter, and that Backstage request logs can be matched to them by time.
Cluster access paths inside your network
The plugin must reach each API server over a path your security policy allows. For EKS, AKS and GKE clusters with private endpoints, the Backstage backend needs a network route to that endpoint, which often means a private link or an allowed egress path from the backend subnet. Avoid exposing API servers to the public internet just so the portal can reach them, and document each path with its owner. Confirm the route and TLS trust for every cluster before enabling the locator.
Limits to confirm in your environment
The Kubernetes plugin depends on three moving parts: the Backstage release line, the Kubernetes version on each cluster, and the cloud identity flow behind each authProvider. Confirm all three before you commit to a credential design, because a mismatch in any one of them breaks sign-in or hides workloads.
Backstage release line and Node.js
Confirm which Backstage release line your portal runs and which plugin version it pairs with, since plugin packages move with the core @backstage packages. The versioning policy supports two adjacent even-numbered Node.js releases, and as of Backstage 1.46.0 these are Node.js 22 and 24. Check your Node.js runtime against the release you plan to use before adding cluster locators, and plan to move the plugin with the rest of the app through yarn backstage-cli versions:bump.
Cloud authentication flow per provider
Each cloud authProvider (aws for EKS, azure or aks for AKS, google for GKE) relies on a different token path, and each path depends on how your identity provider issues tokens. Test every provider with a real user before rollout, including whether group claims reach the cluster. Confirm the sign-in resolver maps every provider to the same identity, because the Kubernetes plugin uses that identity to decide what a user can see.
Kubernetes version support window
Check each cluster's minor version against the Kubernetes support windows before you pick a locator and credential model. As of September 2026, 1.37 reaches end of life on October 28, 2027, 1.36 on June 28, 2027 and 1.35 on February 28, 2027. Clusters on a version past its end of life will not receive fixes, so schedule upgrades on the same cadence as your Backstage upgrades.
Certified distribution status
Ask whether each cluster is a CNCF Certified Kubernetes distribution, because certification confirms the required APIs are present, which the plugin expects when it reads Deployments, Pods and Services. Managed services and self-built clusters can differ in add-ons and API availability. Record the distribution name and version for every cluster in your inventory, and confirm the plugin's required API access works on each one.
Label coverage on workloads
The backstage.io/kubernetes-id annotation on entities must match a label on the Kubernetes objects they own. Confirm that your deployment pipelines set the label on every Deployment, ReplicaSet and Pod, including workloads created by Helm charts or GitOps tools. Workloads without the matching label will not appear in the service view, so audit a sample from each cluster before you publish the page to teams.
Service account scope and secrets
Decide who owns the service account used by the plugin, which namespaces it can read, and where its token is stored. Kubernetes stores Secrets unencrypted in etcd by default, so confirm encryption at rest is enabled on each control plane before the portal holds a credential for it. Restrict list and watch permissions to the namespaces your teams own, and review the RBAC bindings after each cluster upgrade.
Questions teams ask before building this
What drives the effort and cost of a multi-cluster Backstage Kubernetes setup?
The main drivers are the number of clusters, the identity provider in use, the RBAC design for what developers may see, and whether the plugin authenticates with service accounts or with each user's own cloud token. More clusters mean more locator configuration, more credential testing and more verification per cluster. A user-token design adds sign-in resolver work and per-provider testing, while a service account design shifts effort toward scoping the account and reviewing its permissions. Ask any partner to price these items separately in the written scope, and to state which items are one-time build work and which recur as cluster or credential changes arrive.
How long does a Kubernetes plugin setup take?
Duration depends on how many clusters are involved, how many identity and credential paths must be proven, how clean the catalog annotations already are, and how many teams need their workloads mapped. A small pilot with one cluster and one identity model is much shorter than a rollout across several clouds with differing access rules. Ask for a timeline that is tied to named milestones, such as cluster connectivity, credential verification, entity mapping and a review of what each group can see. Any duration should come from the written scope rather than a generic estimate.
Can our internal platform team set this up without a partner?
Yes, many teams can, provided they already operate EKS, AKS or GKE, understand Kubernetes authentication and RBAC, and have someone comfortable with Backstage configuration and its sign-in resolvers. The harder parts are usually cloud identity mapping, least-privilege service account design and keeping entity annotations consistent across teams. Skills to confirm include Kubernetes RBAC, the authentication model of each cloud provider, Backstage plugin configuration and Node.js operations. A partner is most useful when the team lacks one of these skills or needs a fixed-scope delivery with written verification steps.
What do we need to provide before the work starts?
You will need to provide access to the clusters in scope, with enough rights to create service accounts, roles and bindings, and to inspect the API server configuration. Identity administrators must confirm how cloud identities map to Kubernetes users and groups and approve any sign-in resolver logic. Catalog owners should confirm which entities correspond to which workloads and agree on the value of the backstage.io/kubernetes-id annotation. Also provide a list of teams and their expected visibility, and a staging environment where credential changes can be tested before production.
Should the plugin use service accounts or each user's own token?
Service accounts give one predictable credential per cluster, which simplifies configuration and makes the plugin work even when a user's token is unavailable. The trade-off is that the plugin then sees what that account can see, so visibility must be enforced through Backstage permissions and tight RBAC. User tokens, supplied through providers such as google or aks, let the Kubernetes API enforce each person's own access, but they depend on sign-in working for each provider and on token lifetimes. Many teams combine both. Confirm the choice with your security team before building.
How do Backstage and Kubernetes upgrades affect the plugin?
Backstage releases ship on a regular cadence, and upgrades should move all @backstage packages together using the project's version bump command, with the Upgrade Helper used to review template changes. Plugin configuration keys and authProvider behavior can change between versions, so every upgrade needs a regression test against each cluster and credential path. Kubernetes minor releases also matter, because the API server must be upgraded first and the plugin's client libraries must still work with the versions in use. Ask for a written upgrade procedure, a test list and a rollback plan as part of the scope.
Does DeployOpen handle ongoing support after go-live?
Most engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts. Ongoing support, upgrades and continuous testing are available as retainers, which can cover Backstage version moves, cluster additions and credential rotations. DeployOpen does not publish a price list, so the cost of any retainer follows from the written scope. Ask for the support boundaries in writing, including response expectations and which changes are covered.
How DeployOpen scopes and supports multi-cluster Backstage visibility
DeployOpen plans this work as a fixed-scope engagement, with the scope, deliverables and timeline agreed in writing before any build starts. For a Kubernetes plugin rollout across EKS, AKS and GKE, the written scope usually starts with a cluster inventory: every cluster, its cloud account or subscription, its owner, and the locator method each one will use (config, catalog, gke or localKubectlProxy). The scope then records the credential model for each authProvider in use, such as aws, azure, google or serviceAccount, along with who holds each credential and how it is rotated. Written this way, the quote reflects the clusters and identities you actually run, not a generic plugin install.
The credential and RBAC review is where most of the risk sits, and it is the part we would ask you to confirm first in your own environment. Teams need to decide whether developers see workloads through their own cloud identity, which depends on the user's token, or through a read-only service account that the backend holds, and which of those choices you can defend to an auditor. DeployOpen tests the access that results: that the backstage.io/kubernetes-id label is applied consistently, that service accounts can list only the namespaces and resources the plugin needs, and that a user without catalog access sees nothing. Verification steps are documented so your team can repeat them after each change.
The work runs in your own cloud accounts, subscriptions and clusters, with credentials kept under your control. Ongoing support, upgrades and continuous testing are available as retainers, which suit the period when cluster versions and the Backstage release line keep moving. Ask any partner, DeployOpen included, to confirm in writing which environments they will access, how long any elevated access lasts, and who signs off on RBAC changes. DeployOpen prepares the systems and evidence that your auditors will review, but it does not issue audit reports or certifications.
