Kubernetes logo

Backstage Kubernetes Plugin

Visualize your services no matter how or where those services are deployed.

Created by Spotify

Available on Roadie

Get SaaS Backstage

Don't want to spend your time installing and upgrading Backstage plugins? Get managed Backstage from Roadie.

Self-hosted Backstage installation steps

The Kubernetes plugin is made up of @backstage/plugin-kubernetes and @backstage/plugin-kubernetes-backend. To make it work, you will need to install and configure them.

Install the Kubernetes frontend plugin into Backstage.

cd packages/app
yarn add @backstage/plugin-kubernetes

Add plugin API to your Backstage instance.

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

const serviceEntityPage = (
    // ...
    <EntityLayout.Route path="/kubernetes" title="Kubernetes">
      <EntityKubernetesContent />

Install the Kubernetes Backend plugin into Backstage.

cd packages/backend
yarn add @backstage/plugin-kubernetes-backend

Create a new file called kubernetes.ts with the following content.

// packages/backend/src/plugins/kubernetes.ts
import { createRouter } from '@backstage/plugin-kubernetes-backend';
import { PluginEnvironment } from '../types';

export default async function createPlugin({
}: PluginEnvironment) {
  return await createRouter({ logger, config });

Import the plugin.

// packages/backend/src/index.ts
import kubernetes from './plugins/kubernetes';

const kubernetesEnv = useHotMemoize(module, () => createEnv('kubernetes'));

apiRouter.use('/kubernetes', await kubernetes(kubernetesEnv));

Found a mistake? Update these instructions.

How it looks

A screenshot of the Kubernetes plugin.

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:

# app-config.yaml
  serviceLocatorMethod: 'multiTenant'
    - 'config'
    - url:
      name: minikube
      authProvider: 'serviceAccount'
        $env: K8S_MINIKUBE_TOKEN
    - url:
      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:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
  namespace: default
  name: pod-reader
  - 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.

# catalog-info.yaml
        '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:

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

# catalog-info.yaml
  '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

    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

    # catalog-info.yaml
    apiVersion: backstage.io/v1alpha1
    kind: Component
      name: <ENTITY_NAME>
        'backstage.io/kubernetes-id': <ENTITY_NAME>
      type: service
      lifecycle: production
      owner: guest
  4. Add or update app-config.local.yaml with the following:

    # app-config.local.yaml
      serviceLocatorMethod: 'multiTenant'
        - 'config'
          name: minikube
          serviceAccountToken: <TOKEN_FROM_STEP_2>
          authProvider: 'serviceAccount'

Become a Backstage expert

To get the latest news, deep dives into Backstage features, and a roundup of recent open-source action, sign up for Roadie's Backstage Weekly. See recent editions.

We will never sell or share your email address.