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
yarn --cwd packages/app add @backstage/plugin-kubernetes
yarn --cwd packages/backend add @backstage/plugin-kubernetes-backendBackend setup new backend system
Add the backend plugin to your backend bootstrap. Open packages/backend/src/index.ts and add this feature.
// 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
kubernetes:
serviceLocatorMethod:
type: multiTenant
clusterLocatorMethods:
- type: localKubectlProxyDirect cluster config
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.
// 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.
app:
extensions:
- entity-content:kubernetes/kubernetesOptional filter to control which entity kinds show the tab. You can also set a custom title or path.
app:
extensions:
- entity-content:kubernetes/kubernetes:
config:
filter: kind:component,resource
title: Kubernetes
path: kubernetesFrontend setup old frontend system
Add the Kubernetes tab on the entity page. Edit packages/app/src/components/catalog/EntityPage.tsx.
// 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.
# 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: productionNotes
- 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:
### 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:
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
The following annotation must be added so that Backstage can detect that an entity has Kubernetes components.
### catalog-info.yaml
metadata:
annotations:
'backstage.io/kubernetes-id': <ENTITY_NAME>
...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
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
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
# 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.yamlwith the following:# 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
Set up Backstage in minutes with Roadie
Focus on using Backstage, rather than building and maintaining it.