Backstage Kubernetes Plugin: A Practical Guide

A Backstage software catalog is only useful if it reflects reality. To build a true internal developer platform, catalog entities must be tied to their live Kubernetes workloads. The Backstage Kubernetes plugin provides this connection by linking catalog components to running resources in your clusters. It surfaces real-time signals like workload health, deployment status, and pod logs directly in Backstage, reducing context switching for developers. This guide walks through the plugin’s core capabilities, installation model, and common operational pitfalls so you can move from static metadata to an operationally aware developer experience.

Key takeaways:

• Provide developers with self-service visibility: The Backstage Kubernetes plugin offers a service-centric view of application health, logs, and deployment status directly in the developer portal, reducing the need for kubectl for routine operational checks.
• Standardize metadata for accurate linking: The plugin's functionality depends on a precise match between annotations in your catalog-info.yaml files and the labels on your Kubernetes resources. A consistent naming convention is critical to ensure services appear correctly.
• Scale beyond the plugin with a dedicated platform: While the plugin is useful for basic visibility, it has limitations for managing large fleets, particularly around real-time data and security. For enterprise-grade control, a platform like Plural provides a secure, agent-based architecture for true operational efficiency at scale.

What Is the Backstage Kubernetes Plugin?

The Backstage Kubernetes Plugin connects your Backstage software catalog to live Kubernetes clusters. Instead of treating the catalog as static metadata, the plugin augments each component with real operational state pulled directly from the cluster. Developers get a service-centric view of their workloads (health, deployment status, and logs) without dropping into kubectl or a separate dashboard.

For platform teams, this shifts routine operational visibility left. Developers can self-serve common checks without direct cluster access, while the plugin remains read-only, preserving security boundaries. The result is fewer interruptions for the platform team and faster feedback loops for service owners.

What Does It Do?

At a practical level, the plugin answers a single question: is my service running correctly? It queries Kubernetes APIs and renders the most relevant resources—Deployments, Pods, ReplicaSets, and related objects—directly on a component’s page in Backstage.

By consolidating this information in one place, developers can quickly assess application health, spot rollout issues, and inspect pod logs without context switching. This tight feedback loop is especially valuable in production and staging environments where speed of diagnosis matters.

How It Integrates with the Backstage Portal

The integration relies on metadata-driven mapping between catalog components and cluster resources. Each component declares annotations in catalog-info.yaml that act as selectors. These selectors must match labels applied to resources in Kubernetes.

When the plugin runs, it uses this label-matching mechanism to discover the correct resources for a given component and display their state inside Backstage. Accurate and consistent labeling in your clusters is therefore critical—misaligned labels result in missing or misleading data.

Key Features for Monitoring Your Services

The Backstage Kubernetes plugin brings runtime visibility into the developer portal, centralizing operational data that usually lives across multiple tools. By connecting catalog components to live cluster resources, it gives service owners a clear view of application health, status, and basic performance signals. Developers can answer common questions—is my service healthy, what’s deployed, is anything failing—without leaving Backstage or needing deep Kubernetes expertise. For platform teams, this reduces ad-hoc support and enables safer self-service through a read-only interface.

Monitor Resources and Health in Real Time

The plugin pulls live data from Kubernetes and renders a consolidated view of key resources like Deployments, Pods, and Services directly on a component’s page. Developers can quickly see rollout status, pod readiness, and failures across one or more clusters. This is ideal for service-level ownership. For fleet-wide visibility and operations, platforms like Plural complement this view with a true single pane of glass, SSO-integrated dashboards, and operator-focused controls.

Access Logs and Metrics

Developers can view container logs directly in Backstage instead of running kubectl logs, accelerating first-pass debugging. When a metrics server is available, the plugin also exposes basic CPU and memory usage to provide a quick performance snapshot. This doesn’t replace full observability stacks, but it’s sufficient for fast checks and reduces context switching during incidents.

Detect Errors and Troubleshoot Issues

Kubernetes events and pod states (for example, failed deployments or CrashLoopBackOff) are surfaced inline on the component page. Service owners can immediately inspect pod details and logs to diagnose common issues, shortening time to resolution and minimizing escalations to the platform team—especially during rollouts.

Track Deployment Status and Insights

The plugin links catalog components in Backstage to running workloads using annotations in catalog-info.yaml. These selectors match labels or identifiers on cluster resources, enabling precise mapping. With this connection, developers can see what version is running, when it was deployed, and whether the rollout succeeded—providing clear traceability between code, catalog, and runtime state.

How to Install and Configure the Backstage Kubernetes Plugin

Installing the Backstage Kubernetes plugin connects your developer portal to live clusters and requires careful configuration to balance visibility with security. The process spans package installation, cluster definitions, RBAC, and authentication. Each step builds toward a read-only, production-safe integration that exposes runtime state without granting developers direct cluster access.

Install Frontend and Backend Packages

The plugin is split into two parts. The frontend package renders Kubernetes views inside the Backstage UI, while the backend package handles communication with the Kubernetes API. Both are required. The backend acts as the trust boundary: it authenticates to clusters, queries resources, and returns filtered data to the frontend. Without the backend plugin, no cluster data can be surfaced in Backstage.

Configure app-config.yaml for Cluster Connections

Cluster connectivity is defined in app-config.yaml. For each cluster, you specify a logical name, API server endpoint, and authentication method. This configuration tells the backend plugin where clusters live and how to authenticate against them. In most setups, Backstage authenticates using a Kubernetes service account token, allowing it to read resource state. Misconfiguration here is the most common cause of “empty” Kubernetes tabs in the UI.

Set Up Service Accounts and RBAC

Backstage needs explicit permissions to read data from each cluster. Create a dedicated service account and bind it to a Role or ClusterRole using RBAC. Follow least-privilege principles: start with read-only access to workloads, pods, logs, and events. Write or delete permissions are rarely necessary and increase risk. At scale, managing consistent RBAC across many clusters becomes operationally expensive. Platforms like Plural simplify this by synchronizing a single RBAC policy across fleets, keeping access consistent and auditable.

Configure Authentication and Security

Authentication between Backstage and clusters should avoid long-lived static credentials. In cloud environments, prefer short-lived credentials and identity-based access. For example, with AWS EKS, Backstage can assume an IAM role to obtain temporary credentials instead of storing tokens. This reduces blast radius if credentials are compromised. Plural’s agent-based model goes further by executing requests using local, per-cluster credentials, eliminating the need for a central store of cluster secrets while maintaining strong isolation and security.

How to Connect Backstage Components to Kubernetes Resources

The Backstage Kubernetes plugin links catalog components to live workloads using metadata-based discovery. By annotating components in Backstage and applying matching labels to Kubernetes resources, the plugin can reliably discover and display runtime state in the Backstage UI. This mechanism ensures the catalog reflects what’s actually running in your clusters and is foundational to exposing deployment health, pod status, and logs.

Use backstage.io/kubernetes-id Annotations

Each component declares its Kubernetes identity using the backstage.io/kubernetes-id annotation in catalog-info.yaml. The value is an arbitrary but stable identifier for the service. The plugin uses this value as a selector when querying clusters. This single annotation is the entry point that tells Backstage which workloads belong to a given component.

Link Components with Label Matching

Discovery works only if Kubernetes resources carry a matching label. Apply the backstage.io/kubernetes-id label to Deployments, StatefulSets, Services, or other relevant manifests with the exact same value used in the catalog annotation. Any mismatch breaks discovery, making label consistency critical. This approach leverages native Kubernetes labels, keeping the integration simple and non-invasive.

Map Resources Across Multiple Clusters

Once multiple clusters are configured in app-config.yaml, the plugin applies the same label-matching logic across all environments—development, staging, and production. Service owners get a unified view of their application regardless of where it’s deployed. At scale, maintaining consistent labels, RBAC, and configuration across fleets becomes operationally complex. Plural helps by providing a centralized control plane to standardize these concerns, ensuring your Backstage-to-Kubernetes mapping remains reliable as your cluster footprint grows.

What Challenges Might You Face During Implementation?

Integrating the Backstage Kubernetes plugin is a powerful step, but it’s not always a straight path. You might encounter a few common hurdles related to permissions, configuration, and connectivity. Understanding these potential issues ahead of time can save you hours of troubleshooting and help you get your implementation right from the start. Let's walk through the most frequent challenges and how to solve them.

Troubleshoot Authentication and Permissions

One of the first places teams get stuck is with authentication and permissions. The service account Backstage uses to communicate with your Kubernetes clusters needs the correct RBAC permissions to function. If the plugin can’t display pods or logs, it’s likely a permissions issue. For example, the account needs get, list, and watch permissions on resources like Pods and Deployments to display them. If you want to enable actions like deleting pods from the UI, it will need delete permissions, too.

Start by granting the minimum required permissions and add more as needed. A common mistake is creating a service account without binding it to the right roles. Double-check your Role or ClusterRole and RoleBinding configurations to ensure the Backstage service account is properly authorized.

Resolve Annotation and Label Mismatches

For Backstage to link a component in its software catalog to a resource running in Kubernetes, it relies on a precise matching system of annotations and labels. Your component’s catalog-info.yaml file must contain an annotation like backstage.io/kubernetes-id: my-service, which must exactly match a label on your Kubernetes resources. If there’s a typo, a case difference, or any other mismatch, the connection will fail, and your component won't show any Kubernetes information.

This is one of the most common and frustrating issues during setup. Always verify that the annotation value in your component definition is identical to the label value on your Kubernetes Deployment, StatefulSet, or other resources. A consistent naming convention across your organization can prevent these errors from happening in the first place.

Fix Resource Visibility and Connectivity Issues

If your permissions and labels are correct but resources still aren't appearing, the problem may be connectivity. Backstage needs to know how to find and authenticate with your clusters, which you define in your app-config.yaml file. This configuration includes the cluster’s API server URL and authentication details. If Backstage is running in a separate network from your Kubernetes clusters, you may face firewall or proxy issues that block communication.

This is where Plural’s agent-based architecture offers a distinct advantage. Instead of requiring direct network access to your clusters, Plural uses a secure agent that communicates via egress-only traffic. This design eliminates the need to expose your Kubernetes API or manage complex network rules, providing seamless visibility into private and on-prem clusters from a single control plane.

Avoid Common Configuration Pitfalls

Most implementation issues boil down to small configuration errors that are easy to overlook. When troubleshooting, start with the basics. Check for typos in your app-config.yaml file, especially in cluster URLs or authentication provider details. Confirm that the backstage.io/kubernetes-id annotation in your catalog file perfectly matches the corresponding label on your live Kubernetes resources. Ensure your service account token is valid and has the necessary RBAC permissions applied in the target cluster. A systematic check of these key configuration points will often reveal the root cause of the problem quickly.

Best Practices for a Smooth Implementation

Implementing the Backstage Kubernetes plugin is straightforward, but a few best practices can make the difference between a useful tool and a source of frustration. By thinking through your configuration from the start, you can ensure the plugin remains secure, performant, and easy to manage as your Kubernetes environment grows. These practices focus on creating consistency in how you identify services, securing access to your clusters, optimizing performance for large-scale deployments, and providing clear, relevant views for your developers. Getting these details right early on will save you significant time and effort down the road, turning the plugin into a reliable part of your internal developer platform.

Standardize Annotation Naming

The connection between a Backstage component and its corresponding Kubernetes resources relies on a simple but strict matching system. To link them, you add an annotation like backstage.io/kubernetes-id to your component's catalog-info.yaml file. The value of this annotation must exactly match a label on your Kubernetes pods. Establishing a clear, organization-wide naming convention for these annotations and labels is critical. Without standardization, you’ll face inconsistent linking, leaving developers unable to see their services in Backstage. A simple standard, like app-name: my-service, applied consistently as both the annotation value and the pod label, ensures a reliable connection every time.

Secure Your Setup with Access Control

The service account Backstage uses to query the Kubernetes API server is a potential security risk if not configured correctly. It’s essential to follow the principle of least privilege. The account needs specific permissions to read information, and if you want to enable actions like deleting pods from the UI, it will need delete permissions as well. Start by granting read-only access and only add more permissions as needed. For managing access across many clusters, a centralized approach is better. Plural, for example, simplifies this by letting you define fleet-wide RBAC policies that sync to every cluster, ensuring consistent and secure permissions for all users and services.

Optimize Performance for Large Clusters

In large Kubernetes environments with thousands of pods, the Backstage plugin can face performance challenges. Fetching data for every resource can slow down the UI and place a heavy load on the Kubernetes API server. To prevent this, use label selectors in your app-config.yaml to filter which resources the plugin queries. This narrows the scope to only the services you want to display in Backstage, improving responsiveness. The goal is to give developers a clear, fast picture of what's running and where it is. For organizations managing extensive Kubernetes fleets, a dedicated platform with an agent-based architecture can offer better performance and scalability than a plugin-based approach.

Manage Resources with Filtering and Namespaces

To avoid overwhelming developers with irrelevant information, you can control which Kubernetes resources appear in Backstage. By configuring the plugin to fetch resources from specific namespaces or those matching certain labels, you can create tailored views for different teams. This is particularly useful in multi-tenant clusters, as it ensures developers only see the services they are responsible for. This filtering capability allows you to monitor services running in any environment, from a local test setup to a global production deployment, while keeping the interface clean and focused. This practice helps create a more efficient and less confusing experience for everyone using the platform.

Explore Advanced Monitoring Capabilities

Once you have the basics down, you can extend the Backstage Kubernetes plugin for more complex scenarios. These advanced capabilities help create a more comprehensive monitoring experience that fits your specific tooling and infrastructure, from custom resources to multi-cloud deployments.

Work with Custom Resource Definitions

The plugin isn’t limited to default Kubernetes objects. You can configure it to display the status of your Custom Resource Definitions (CRDs), which is essential for teams using operators or specialized tooling. For example, you can set up the plugin to show Argo Rollouts for progressive delivery or Tekton Pipelines for CI/CD. This gives developers visibility into the entire application lifecycle, not just the deployed resources. By surfacing CRDs in the Backstage UI, you provide a richer view that aligns with the tools your teams already use, reducing context switching.

Integrate with Your Existing Monitoring Tools

The Backstage plugin provides visibility into Kubernetes resources, but it isn't a replacement for dedicated observability platforms like Prometheus. Its strength lies in integration, acting as a central hub that links out to your existing monitoring tools. While this centralizes access, it requires developers to switch between UIs. In contrast, platforms like Plural embed a unified observability solution directly into the management console. This provides a true single-pane-of-glass experience for logs, metrics, and traces alongside deployment status, keeping your team in one place.

Deploy Across Multiple Environments

Most organizations operate multiple Kubernetes clusters across different environments. The Backstage plugin can connect to all of them, offering a consolidated view of a service across its lifecycle. A developer can switch between clusters in the UI to verify a deployment in staging before promoting it to production. However, managing credentials for many clusters in app-config.yaml becomes cumbersome. This is a common challenge in Kubernetes fleet management, where maintaining consistency and security at scale requires a more robust, automated approach.

Configure Proxies and Network Settings

Connecting Backstage to clusters in private networks often requires a proxy to route traffic from the Backstage backend to the Kubernetes API server. While the plugin supports this, it adds operational overhead. This complexity is why Plural was designed with a different architecture. Plural uses an agent-based model where all communication is egress-only, initiated from the managed cluster. This design eliminates the need for inbound firewall rules or proxies, simplifying network security while providing full visibility and control over your entire fleet from a central control plane.

Backstage vs. Dedicated Kubernetes Management Platforms

Backstage is an excellent open-source framework for building internal developer portals, and its Kubernetes plugin offers a solid starting point for service visibility. It connects to your clusters via the Kubernetes API, allowing developers to see deployments and pods associated with their services. However, as your organization's use of Kubernetes matures and your fleet expands, the plugin's limitations become more apparent. It's designed for basic visibility, not comprehensive, enterprise-grade fleet management.

When you need more than just a surface-level view—when you require real-time data, robust security controls, and scalable management workflows—it’s time to consider a dedicated platform. These solutions are purpose-built to handle the operational complexity of managing Kubernetes at scale, addressing the gaps left by the Backstage plugin. They provide the deep observability, automation, and security posture management that platform teams need to effectively support a growing number of clusters and developer teams. Understanding the trade-offs between a general-purpose portal plugin and a specialized management platform is key to building a scalable and resilient cloud-native infrastructure.

Understand the Limitations of the Backstage Plugin

The Backstage Kubernetes plugin provides basic visibility into services, but it has technical constraints that can impede teams managing production workloads. A significant issue is that the plugin does not provide real-time data, which limits its utility for monitoring the immediate health of Kubernetes workloads. For incident response or performance tuning, stale data is a critical blind spot.

Furthermore, extracting detailed information, such as resource requests and limits, can be cumbersome. Developers often have to navigate through large, raw YAML files within the UI to find the specific details they need. This process is inefficient and error-prone, especially for those less familiar with Kubernetes manifests. These limitations mean that while the plugin can show you that a service is running, it struggles to provide the deep, real-time context needed for effective operational management and troubleshooting.

When to Choose an Enterprise Solution like Plural

When your organization’s needs surpass basic service discovery, a dedicated Kubernetes management platform becomes essential. Enterprise solutions like Plural are built to provide the comprehensive features required for managing complex environments. Unlike the Backstage plugin, which requires significant configuration for a partial view, Plural offers a fully integrated and secure Kubernetes dashboard out of the box. This provides real-time monitoring, advanced analytics, and a unified control plane for all your clusters.

Plural’s architecture is designed for security and operational efficiency. It uses an agent-based model with unidirectional egress traffic, allowing you to securely manage clusters in private networks without exposing them. All access is managed through your existing SSO provider and Kubernetes RBAC, using impersonation to ensure that developers only see what they’re authorized to. This approach streamlines operations and strengthens your security posture, providing a robust alternative when you outgrow the capabilities of a general-purpose plugin.

Address Scaling Challenges for Large Fleets

As your Kubernetes fleet grows, the limitations of the Backstage plugin are magnified. Its reliance on a static data model and YAML files for cataloging services creates significant operational overhead. Manually maintaining an accurate, up-to-date inventory of services and their corresponding Kubernetes resources across tens or hundreds of clusters becomes unsustainable. This can lead to configuration drift and an incomplete picture of your environment, making fleet-wide changes or audits incredibly difficult.

Dedicated platforms are engineered to solve these scaling challenges. Plural, for instance, uses a GitOps-based approach with an agent architecture that scales to manage thousands of clusters efficiently. Features like Global Services allow you to define a configuration once—such as RBAC policies or monitoring agents—and ensure it is consistently applied across your entire fleet. This automation eliminates manual effort, reduces the risk of human error, and provides a reliable mechanism for maintaining uniformity as your infrastructure expands.

How to Monitor Workloads in the Backstage UI

Once the Backstage Kubernetes plugin is configured, you can monitor your services directly from the component catalog. This integration provides developers with a self-service view into their running applications, reducing their reliance on platform teams for basic operational tasks. The UI centralizes key information, helping you track application health, performance, and deployment status without leaving the Backstage portal.

Use the Centralized Dashboard

The primary benefit of the Kubernetes plugin is its ability to create a centralized dashboard for your services. Instead of juggling multiple tools and terminals, developers can view essential Kubernetes information directly on their component’s catalog page. The plugin displays deployments, pods, ReplicaSets, and other relevant resources associated with a service. This unified view gives teams a clear and immediate understanding of their application’s state in a given cluster. By consolidating this data, the Backstage plugin helps reduce context switching and simplifies the developer experience for interacting with Kubernetes.

Track Pod Status and Health

Within the Backstage UI, you can easily check if your services are running as expected. The plugin provides real-time status updates for pods, indicating whether they are running, pending, succeeded, or failed. You can drill down into individual pods to see more detailed information, such as container status, restart counts, and recent events. This granular visibility is critical for day-to-day operations, allowing developers to quickly confirm that a new deployment was successful or identify a pod that is stuck in a crash loop. This immediate feedback loop empowers developers to own the operational health of their services.

Gain Insights into Resource Utilization

The plugin also offers insights into how your services are consuming cluster resources. Once a component is correctly annotated, Backstage can display CPU and memory usage for its associated pods. This helps developers identify potential performance bottlenecks or opportunities for optimization. While Backstage provides a solid component-level view, platform teams managing large fleets often require more comprehensive observability. For fleet-wide resource management and advanced monitoring, a dedicated platform like Plural provides a single pane of glass to track utilization and costs across all your clusters.

Streamline Your Debugging Workflow

When issues arise, the Backstage Kubernetes plugin can significantly streamline the debugging process. Developers can access container logs directly from the UI, eliminating the need to use kubectl or log into a separate observability tool for initial troubleshooting. By having pod status, events, and logs available in one place, developers can quickly correlate information to diagnose problems. This integrated workflow reduces the mean time to resolution (MTTR) for common issues and makes the debugging process more accessible, especially for those less familiar with Kubernetes internals.

Related Articles

• The Ultimate Guide to kubectl plugins list
• 4 Best Tools Like Backstage for K8s in 2025

Frequently Asked Questions

What's the main difference between using the Backstage plugin and just giving developers kubectl access? The Backstage plugin is designed to improve the developer experience by abstracting away Kubernetes complexity. Instead of needing to learn kubectl commands and navigate cluster internals, developers get a simplified, service-centric view that answers their most common questions: "Is my service running?" and "What do the logs say?" This approach provides safe, read-only access to essential information directly within the developer portal, empowering developers to self-serve without granting them direct, potentially risky, cluster access.

How secure is it to connect Backstage to all of our Kubernetes clusters? The security of the connection depends entirely on your configuration. Best practice dictates using a dedicated service account for Backstage with a tightly scoped RBAC role that follows the principle of least privilege, starting with read-only permissions. For organizations managing a large fleet, this can become complex. Plural enhances this security model with its agent-based architecture, which uses egress-only communication from each cluster. This means you don't need to expose your Kubernetes API servers, and all operations are executed with local credentials, which avoids centralizing sensitive keys.

My team uses a lot of custom resources (CRDs). Can the Backstage plugin display those? Yes, the plugin is extensible and can be configured to display the status of your Custom Resource Definitions. This is a powerful feature for teams that rely on operators or specialized tools like Argo Rollouts for progressive delivery or Tekton for CI/CD pipelines. By configuring the plugin to recognize your CRDs, you can give developers visibility into the full lifecycle of their applications, not just standard Kubernetes objects like Pods and Deployments.

The plugin isn't showing my service's resources. What's the most common reason for this? The most frequent cause of this issue is a simple mismatch between metadata. The plugin links a Backstage component to its Kubernetes resources using an annotation in your catalog-info.yaml file, typically backstage.io/kubernetes-id. The value of this annotation must perfectly match the label applied to your Kubernetes manifests, such as your Deployment or Service. Even a minor typo or a difference in case will break the connection, so verifying that these two values are identical is the first place to check.

When should my team consider moving from the Backstage plugin to a platform like Plural? You should consider a dedicated platform when the operational overhead of managing your Kubernetes fleet outweighs the benefits of the plugin. This tipping point often occurs when you're managing multiple clusters and find it difficult to maintain consistent RBAC policies, configurations, and security standards. If your platform team is spending more time troubleshooting connectivity and permissions than enabling developers, or if you need a true single pane of glass for fleet-wide observability and management, a solution like Plural is designed to solve those scaling challenges.