Customizing the Backstage Kubernetes Plugin

Backstage, the open-source platform from Spotify, has become a popular choice for building a unified developer portal. One of its key features is the Kubernetes plugin, providing a centralized view of your Kubernetes resources. But what if the default functionality doesn’t quite fit your specific needs? The good news is, the Backstage Kubernetes plugin offers a high degree of customization.

Understanding the Backstage Kubernetes Plugin

The Backstage Kubernetes Plugin serves as a bridge between Backstage and Kubernetes clusters, enabling developers to interact with and manage Kubernetes resources directly from the Backstage UI. This integration simplifies the deployment, monitoring, and management of applications running on Kubernetes, offering a centralized hub for developers to access and control their Kubernetes resources.

Customizing the Plugin for Enhanced Functionality

Customizing the Backstage Kubernetes Plugin allows organizations to tailor the integration to their specific needs and workflows. Here are some key aspects to consider when customizing the plugin:

  1. UI Customization: Modify the visual representation of Kubernetes resources within Backstage to align with your organization’s branding or to enhance usability for developers.
  2. Integration with External Tools: Extend the plugin to integrate with external monitoring, logging, or security tools to provide a comprehensive view of your Kubernetes ecosystem directly within Backstage.
  3. Role-Based Access Control: Implement role-based access control (RBAC) to restrict access to certain Kubernetes resources based on user roles and permissions, ensuring security and compliance.
  4. Automated Workflows: Configure automated workflows within the plugin to streamline common tasks such as deploying applications, scaling resources, or updating configurations, improving efficiency and reducing manual errors.

Best Practices for Customizing the Backstage Kubernetes Plugin

When customizing the Backstage Kubernetes Plugin, it is essential to follow best practices to ensure a seamless integration and optimal performance:

  1. Version Compatibility: Ensure that the plugin is compatible with the version of Backstage and Kubernetes you are using to avoid compatibility issues and potential errors.
  2. Testing and Validation: Thoroughly test any customizations made to the plugin in a staging environment before deploying them to production to identify and address any issues proactively.
  3. Documentation: Document all customizations, configurations, and workflows implemented in the plugin to facilitate knowledge sharing and troubleshooting for developers within your organization.
  4. Community Engagement: Leverage the vibrant Backstage community to seek guidance, share insights, and contribute back to the ecosystem by sharing your customizations and best practices with the community.

Installing The Backstage Kubernetes Plugin

To install the Backstage Kubernetes plugin, follow these steps:

  1. Add the frontend plugin to your Backstage application:
# From your Backstage root directory yarn –cwd packages/app add @backstage/plugin-kubernetes

This installs the @backstage/plugin-kubernetes package in your packages/app directory.

  1. Import the plugin in your app by adding the “Kubernetes” tab to the respective catalog pages:
import { EntityKubernetesContent } from ‘@backstage/plugin-kubernetes’; const serviceEntityPage = ( {/* other tabs… */} );

The refreshIntervalMs property on EntityKubernetesContent defines the interval in which the content automatically refreshes, defaulting to 10 seconds if not set.

  1. Add the backend plugin to your Backstage application:
# From your Backstage root directory yarn –cwd packages/backend add @backstage/plugin-kubernetes-backend

This installs the @backstage/plugin-kubernetes-backend package in your packages/backend directory.

  1. Create a kubernetes.ts file in packages/backend/src/plugins/ with the following content:
import { KubernetesBuilder } from ‘@backstage/plugin-kubernetes-backend’; import { Router } from ‘express’; import { PluginEnvironment } from ‘../types’; import { CatalogClient } from ‘@backstage/catalog-client’; export default async function createPlugin( env: PluginEnvironment, ): Promise { const catalogApi = new CatalogClient({ discoveryApi: env.discovery }); const { router } = await KubernetesBuilder.createBuilder({ logger: env.logger, config: env.config, catalogApi, discovery: env.discovery, permissions: env.permissions, }).build(); return router; }

This sets up the backend plugin.

  1. Import the plugin in packages/backend/src/index.ts:
import kubernetes from ‘./plugins/kubernetes’; async function main() { // … const kubernetesEnv = useHotMemoize(module, () => createEnv(‘kubernetes’)); // … apiRouter.use(‘/kubernetes’, await kubernetes(kubernetesEnv)); }

This adds the Kubernetes plugin to the backend1.After following these steps, the Backstage Kubernetes plugin will be installed and ready for configuration in your Backstage application.

Configure The Backstage Kubernetes Plugin After Installation

To configure the Backstage Kubernetes plugin after installation, follow these steps:

  1. Allow the backend to collect objects from your Kubernetes cluster(s):
# app-config.yaml kubernetes: serviceLocatorMethod: ‘multiTenant’ clusterLocatorMethods: – ‘config’ clusters: – url: name: minikube authProvider: ‘serviceAccount’ serviceAccountToken: $env: K8S_MINIKUBE_TOKEN – url: name: gke-cluster-1 authProvider: ‘google’

This configuration entry specifies the Kubernetes clusters that the backend should connect to.

  1. Grant the required RBAC permissions to the backend:
apiVersion: kind: Role metadata: namespace: default name: pod-reader rules: – apiGroups: [”] resources: [‘pods’] verbs: [‘get’, ‘watch’, ‘list’]

The backend requires read-only access to pods, services, configmaps, deployments, replicasets, horizontalpodautoscalers, and ingresses.

  1. Surface your Kubernetes objects in catalog entities:
apiVersion: kind: Component metadata: name: example-component spec: type: service lifecycle: production owner: user:guest system: example-system kubernetes: authProvider: ‘google’ clusterSelector: matchLabels: team: devops

Annotate your catalog entities with the kubernetes field to specify the cluster and authentication details.

After configuring the backend and catalog, the Backstage Kubernetes plugin will be able to display the Kubernetes resources associated with each component in the Backstage interface.


Customizing the Backstage Kubernetes Plugin offers a unique opportunity to enhance the integration between Backstage and Kubernetes, empowering developers with a robust set of tools to manage Kubernetes resources efficiently. By following best practices and leveraging the flexibility of the plugin, organizations can create a tailored experience that aligns with their specific requirements and accelerates the software development lifecycle.