Backstage Application Topology for Kubernetes Plugin

Install the topology frontend in your app

1. Add the package to the app workspace

   Copy

   yarn workspace app add @backstage-community/plugin-topology

2. Add the Topology tab to the service entity page

   Edit packages/app/src/components/catalog/EntityPage.tsx

   Copy

   import { TopologyPage } from '@backstage-community/plugin-topology';
   import React from 'react';
   import { EntityLayout } from '@backstage/plugin-catalog';
   
   const serviceEntityPage = (
     <EntityLayout>
       {/* other tabs */}
       <EntityLayout.Route path="/topology" title="Topology">
         <TopologyPage />
       </EntityLayout.Route>
     </EntityLayout>
   );
   
   export default serviceEntityPage;

The Topology tab appears on each service entity page at path topology.

Ensure the Kubernetes backend is installed and configured

The topology plugin reads data through the Backstage Kubernetes plugin. Install and configure the Kubernetes backend first. Use the path that matches your backend system.

Old backend system

1. Add the backend package

   Copy

   yarn workspace backend add @backstage/plugin-kubernetes-backend

2. Create the backend plugin router

   Create packages/backend/src/plugins/kubernetes.ts

   Copy

   import { createRouter } from '@backstage/plugin-kubernetes-backend';
   import { PluginEnvironment } from '../types';
   import { Router } from 'express';
   
   export default async function createPlugin(env: PluginEnvironment): Promise<Router> {
     return await createRouter({
       logger: env.logger,
       config: env.config,
       catalogApi: env.catalogClient,
     });
   }

3. Mount the router

   Edit packages/backend/src/index.ts

   Copy

   import kubernetes from './plugins/kubernetes';
   
   // inside the main function after creating apiRouter
   apiRouter.use('/kubernetes', await kubernetes(env));

4. Configure cluster access in app config

   Edit app-config.yaml. Add your clusters under the kubernetes key to use a ServiceAccount. Match the Backstage Kubernetes configuration you already use. Add any customResources you need as shown later in this guide.

New backend system

1. Add the backend package

   Copy

   yarn workspace backend add @backstage/plugin-kubernetes-backend

2. Register the plugin in the backend

   Edit packages/backend/src/index.ts

   Copy

   import { createBackend } from '@backstage/backend-defaults';
   
   const backend = createBackend();
   
   // other plugins
   backend.add(import('@backstage/plugin-kubernetes-backend'));
   
   await backend.start();

3. Configure cluster access in app config

   Edit app-config.yaml. Add your clusters under the kubernetes key to use a ServiceAccount. Add any customResources you need as shown below.

Grant cluster permissions

Use a ServiceAccount for the Backstage Kubernetes plugin. Grant a ClusterRole with read access. Add extra rules when you want the features below.

View OpenShift routes

Add these rules to the ClusterRole

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: backstage-read-only
rules:
  - apiGroups:
      - route.openshift.io
    resources:
      - routes
    verbs:
      - get
      - list

Add customResources in app-config.yaml

kubernetes:
  customResources:
    - group: 'route.openshift.io'
      apiVersion: 'v1'
      plural: 'routes'

View pods and pod logs

Add these rules to the ClusterRole

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: backstage-read-only
rules:
  - apiGroups:
      - ''
    resources:
      - pods
      - pods/log
    verbs:
      - get
      - list
      - watch

View Tekton PipelineRuns

Add these rules to the ClusterRole

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: backstage-read-only
rules:
  - apiGroups:
      - tekton.dev
    resources:
      - pipelines
      - pipelineruns
      - taskruns
    verbs:
      - get
      - list

Add customResources in app-config.yaml

kubernetes:
  customResources:
    - group: 'tekton.dev'
      apiVersion: 'v1'
      plural: 'pipelines'
    - group: 'tekton.dev'
      apiVersion: 'v1'
      plural: 'pipelineruns'
    - group: 'tekton.dev'
      apiVersion: 'v1'
      plural: 'taskruns'

View Virtual Machines

Make sure OpenShift Virtualization Operator is installed on the cluster

Add these rules to the ClusterRole

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: backstage-read-only
rules:
  - apiGroups:
      - kubevirt.io
    resources:
      - virtualmachines
      - virtualmachineinstances
    verbs:
      - get
      - list

Add customResources in app-config.yaml

kubernetes:
  customResources:
    - group: 'kubevirt.io'
      apiVersion: 'v1'
      plural: 'virtualmachines'
    - group: 'kubevirt.io'
      apiVersion: 'v1'
      plural: 'virtualmachineinstances'

Enable the source code editor decorator

Add these rules to the ClusterRole

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: backstage-read-only
rules:
  - apiGroups:
      - org.eclipse.che
    resources:
      - checlusters
    verbs:
      - get
      - list

Add customResources in app-config.yaml

kubernetes:
  customResources:
    - group: 'org.eclipse.che'
      apiVersion: 'v2'
      plural: 'checlusters'

Add entity annotations and labels

Add this annotation to catalog entities so Backstage can map the entity to Kubernetes resources

# catalog-info.yaml
annotations:
  backstage.io/kubernetes-id: <BACKSTAGE_ENTITY_NAME>

Add this label to your Kubernetes resources so the Kubernetes plugin can find them

# resource manifest
metadata:
  labels:
    backstage.io/kubernetes-id: <BACKSTAGE_ENTITY_NAME>

You can also set a namespace for lookups

# catalog-info.yaml
annotations:
  backstage.io/kubernetes-namespace: <RESOURCE_NS>

You can use a label selector for lookups. This takes precedence over the id annotation

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

If you want to support a shared Dev Spaces editor across many entities you can use a selector like this and label your resources accordingly

# catalog-info.yaml
annotations:
  backstage.io/kubernetes-label-selector: 'component in (<BACKSTAGE_ENTITY_NAME>,che)'

# checluster.yaml
metadata:
  labels:
    component: che

# other resources
metadata:
  labels:
    component: <BACKSTAGE_ENTITY_NAME>

Add a runtime icon to nodes with one of these labels

# deployment.yaml
metadata:
  labels:
    app.openshift.io/runtime: <RUNTIME_NAME>

or

# deployment.yaml
metadata:
  labels:
    app.kubernetes.io/name: <RUNTIME_NAME>

Supported values

django
dotnet
drupal
go-gopher
golang
grails
jboss
jruby
js
nginx
nodejs
openjdk
perl
phalcon
php
python
quarkus
rails
redis
rh-spring-boot
rust
java
rh-openjdk
ruby
spring
spring-boot

Group related workloads in the view

# any resource
metadata:
  labels:
    app.kubernetes.io/part-of: <GROUP_NAME>

Draw a connector between workloads

# any resource
metadata:
  annotations:
    app.openshift.io/connects-to: '[{"apiVersion": <RESOURCE_APIVERSION>,"kind": <RESOURCE_KIND>,"name": <RESOURCE_NAME>}]'

Optional Backstage RBAC policy

If RBAC is enabled, allow users to view topology and pod logs with this policy

g, user:default/<YOUR_USERNAME>, role:default/topology-viewer
p, role:default/topology-viewer, kubernetes.clusters.read, read, allow
p, role:default/topology-viewer, kubernetes.resources.read, read, allow
p, role:default/topology-viewer, kubernetes.proxy, use, allow
p, role:default/topology-viewer, catalog-entity, read, allow