Backstage Kubernetes logo

Backstage Backstage Kubernetes Plugin

Created by Spotify

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.

A screenshot of the Kubernetes plugin.

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:

  1. Allow the backend to collect objects from your Kubernetes cluster(s).
  2. 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

  1. 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>
    ...
  1. 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

  1. Get the Kubernetes master base url kubectl cluster-info

  2. 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
  3. 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
  4. 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

Set up Backstage in minutes with Roadie