Backstage Backstage Kubernetes Plugin

Backstage Kubernetes brings your cluster view into the Backstage catalog. It is built for service owners. You can check the health of a service in one place across many clusters. The plugin highlights problems and lets you drill into deployments and pods for that service.

It connects to Kubernetes through the API and works with any cloud provider or managed platform.Use it to watch rollouts during a release. See errors sooner and reduce context switching. Bring runtime details next to docs, APIs, and ownership so teams can act faster.

For most teams the value is a clear picture of what is running, where it runs, and whether it is healthy.

Installation Instructions

These instructions apply to self-hosted Backstage only. To use this plugin on Roadie, visit the docs.

Install the packages

Copy

yarn --cwd packages/app add @backstage/plugin-kubernetes
yarn --cwd packages/backend add @backstage/plugin-kubernetes-backend

Backend setup new backend system

Add the backend plugin to your backend bootstrap. Open packages/backend/src/index.ts and add this feature.

Copy

// packages/backend/src/index.ts
import { createBackend } from '@backstage/backend-defaults';

const backend = createBackend();

// Other plugin features...
backend.add(import('@backstage/plugin-kubernetes-backend'));

backend.start();

Add Kubernetes config to your app-config.yaml. Pick one of these setups.

Local kubectl proxy for local work

Copy

kubernetes:
  serviceLocatorMethod:
    type: multiTenant
  clusterLocatorMethods:
    - type: localKubectlProxy

Direct cluster config

Copy

kubernetes:
  serviceLocatorMethod:
    type: multiTenant
  clusterLocatorMethods:
    - type: config
      clusters:
        - url: https://your.cluster.example
          name: prod-cluster
          authProvider: serviceAccount
          serviceAccountToken:
            $env: K8S_SERVICE_ACCOUNT_TOKEN
          skipTLSVerify: false
          # Optional per cluster custom resources
          # customResources:
          #   - group: "example.mycompany.com"
          #     apiVersion: "v1"
          #     plural: "widgets"

The backend exposes endpoints that require permissions. Users need kubernetes.clusters.read and kubernetes.resources.read.

Backend setup old backend system

Not supported by this plugin version. Use the new backend system.

Frontend setup new frontend system

Register the plugin feature in your app. Open packages/app/src/App.tsx and add it to features.

Copy

// packages/app/src/App.tsx
import { createApp } from '@backstage/app-defaults';
import kubernetesPlugin from '@backstage/plugin-kubernetes/alpha';

export const app = createApp({
  features: [
    kubernetesPlugin,
  ],
});

Enable the entity content extension in app-config.yaml. This shows a Kubernetes tab on entity pages.

Copy

app:
  extensions:
    - entity-content:kubernetes/kubernetes

Optional filter to control which entity kinds show the tab. You can also set a custom title or path.

Copy

app:
  extensions:
    - entity-content:kubernetes/kubernetes:
        config:
          filter: kind:component,resource
          title: Kubernetes
          path: kubernetes

Frontend setup old frontend system

Add the Kubernetes tab on the entity page. Edit packages/app/src/components/catalog/EntityPage.tsx.

Copy

// packages/app/src/components/catalog/EntityPage.tsx
import React from 'react';
import { EntityLayout } from '@backstage/plugin-catalog';
import {
  EntityKubernetesContent,
  isKubernetesAvailable,
} from '@backstage/plugin-kubernetes';

export const EntityPage = () => {
  return (
    <EntityLayout>
      {/* other routes */}
      <EntityLayout.Route
        if={isKubernetesAvailable}
        path="/kubernetes"
        title="Kubernetes"
      >
        <EntityKubernetesContent />
      </EntityLayout.Route>
    </EntityLayout>
  );
};

Add catalog annotations to your entities

Add Kubernetes annotations to each entity you want to show in the Kubernetes tab. These help the plugin find the right objects.

Copy

# catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-service
  annotations:
    backstage.io/kubernetes-id: my-service
    backstage.io/kubernetes-namespace: my-namespace
    backstage.io/kubernetes-label-selector: app=my-service
    # Optional single cluster selection
    # backstage.io/kubernetes-cluster: prod-cluster
spec:
  type: service
  owner: team-a
  lifecycle: production

Notes

The frontend and backend work together. Install both.
The Kubernetes tab only appears when annotations exist and the user has the needed permissions.

Things to Know

The Backstage Kubernetes plugin has two separate components:

frontend: it will take care of displaying the information to the user.
backend: it will take care of connecting to the Kubernetes clusters and sending the information to the frontend.

After installing the plugins, you have to configure them in two steps:

Allow the backend to collect objects from your Kubernetes cluster(s).
Surfacing your Kubernetes objects in catalog entities

Configuring Kubernetes Clusters

Here is a complete example of a configuration entry:

Copy

### app-config.yaml
kubernetes:
  serviceLocatorMethod: 'multiTenant'
  clusterLocatorMethods:
    - 'config'
  clusters:
    - url: http://127.0.0.1:9999
      name: minikube
      authProvider: 'serviceAccount'
      serviceAccountToken:
        $env: K8S_MINIKUBE_TOKEN
    - url: http://127.0.0.2:9999
      name: gke-cluster-1
      authProvider: 'google'

You can find the complete list of fields in the the official Backstage documentation.

Using RBAC Authorization

The current RBAC permissions required are read-only cluster wide, for the following objects:

pods
services
configmaps
deployments
replicasets
horizontalpodautoscalers
ingresses

An example of a Role to grant read access to pods:

Copy

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: default
  name: pod-reader
rules:
  - apiGroups: ['']
    resources: ['pods']
    verbs: ['get', 'watch', 'list']

Surfacing your Kubernetes components as part of an entity

There are two ways to surface your Kubernetes components as part of an entity.
NOTE: The label selector takes precedence over the annotation/service id.

Common `backstage.io/kubernetes-id` label

Adding the metadata annotation

The following annotation must be added so that Backstage can detect that an entity has Kubernetes components.

Copy

### catalog-info.yaml
metadata:
    annotations:
        'backstage.io/kubernetes-id': <ENTITY_NAME>
    ...

Labeling your Kubernetes components

In order for your Kubernetes components to show up in the service catalog as a part of an entity, your Kubernetes components themselves can have the following label:

Copy

"metadata": {
  "labels": {
    "backstage.io/kubernetes-id": <ENTITY_NAME>
    ...
  }
}

Label selector query annotation

Via a label selector, the user can identify a set of objects.
You can write your own custom label selector query that Backstage will use to lookup the objects. You can read Labels and Selectors documentation for more info.

Copy

### catalog-info.yaml
annotations:
  'backstage.io/kubernetes-label-selector': 'app=my-app,component=front-end'

Example of steps to follow

Get the Kubernetes master base url kubectl cluster-info

Get the service account token

Copy

kubectl get secret $(kubectl get sa <SERVICE_ACCOUNT_NAME> -o=json \
| jq -r '.secrets[0].name') -o=json \
| jq -r '.data["token"]' \
| base64 --decode \
| pbcopy

Register existing component in Backstage

Copy

# catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: <ENTITY_NAME>
  annotations:
    'backstage.io/kubernetes-id': <ENTITY_NAME>
spec:
  type: service
  lifecycle: production
  owner: guest

Add or update app-config.local.yaml with the following:

Copy

# app-config.local.yaml
kubernetes:
  serviceLocatorMethod: 'multiTenant'
  clusterLocatorMethods:
    - 'config'
  clusters:
    - url: <KUBERNETES_MASTER_BASE_URL_FROM_STEP_1>
      name: minikube
      serviceAccountToken: <TOKEN_FROM_STEP_2>
      authProvider: 'serviceAccount'

Changelog

This changelog is produced from commits made to the Backstage Kubernetes plugin since 9 months ago. It may not contain information about all commits. Releases and version bumps are intentionally omitted. This changelog is generated by AI.

Breaking changes

Update Kubernetes client library to 1.1.2 in the plugin dependency tree. This library is now ESM only. If you import it in custom code you may need to adjust your imports or build setup. See #28198 merged 5 months ago

Bug fixes

Remove double padding on the Kubernetes entity page. Content now aligns with the entity page layout. See #30490 merged 2 months ago

Dependencies

Switch to the scoped @xterm packages in the Kubernetes plugin. Replaces deprecated xterm packages. See #29623 merged 4 months ago
Bump @kubernetes client node to 1.1.2. See #28198 merged 5 months ago

Installation Instructions

Install the packages

Backend setup new backend system

Backend setup old backend system

Frontend setup new frontend system

Frontend setup old frontend system

Add catalog annotations to your entities

Notes

Things to Know

Configuring Kubernetes Clusters

Using RBAC Authorization

Surfacing your Kubernetes components as part of an entity

Common backstage.io/kubernetes-id label

Adding the metadata annotation

Labeling your Kubernetes components

Label selector query annotation

Example of steps to follow

Changelog

Breaking changes

Bug fixes

Dependencies

Set up Backstage in minutes with Roadie

Common `backstage.io/kubernetes-id` label