Installing Knative Backstage Plugins

Knative community is planning to provide a set of Backstage plugins for Knative and their respective backends. Currently there is one plugin available, the Event Mesh plugin.

Event Mesh plugin

The Event Mesh plugin is a Backstage plugin that allows you to view and manage Knative Eventing resources.

The Backstage plugin talks to a special backend that runs in the Kubernetes cluster and communicates with the Kubernetes API server.

A demo setup for this plugin is available at https://github.com/aliok/knative-backstage-demo.

The plugin has 2 distributions: static and dynamic. In this document, we will focus on the static distribution. For the dynamic distribution, please see the Dynamic Plugin README file in the plugin repository.

Installation

The plugin needs to be installed in the Backstage instance and the backend it talks to needs to be installed in the Kubernetes cluster.

Plugin backend controller installation

  1. VERSION="latest" # or a specific version like knative-v1.15.0
  2. kubectl apply -f https://github.com/knative-extensions/backstage-plugins/releases/${VERSION}/download/eventmesh.yaml

This will install the backend controller in the Kubernetes cluster. The backend’s responsibility is to talk to the Kubernetes API server and provide the necessary information to the plugin.

The Backstage plugin installation

In your Backstage directory, run the following command to install the plugin:

  1. VERSION="latest" # or a specific version like 1.15.0 from https://www.npmjs.com/package/@knative-extensions/plugin-knative-event-mesh-backend
  2. yarn workspace backend add @knative-extensions/plugin-knative-event-mesh-backend@${VERSION}

Backstage has a legacy backend system that is being replaced with a new system. If you are using the legacy backend system, you can follow the instructions below to install the plugin.

To learn more about the new and the legacy backend systems, see the Backstage documentation.

Info

We are aware there is a Backend term used in both the Kubernetes controller and the Backstage backend system. Backstage backend system is different from the Kubernetes controller we’ve installed before. The controller is a Kubernetes controller that runs in the Kubernetes cluster and talks to the Kubernetes API server. Backstage backend system is a framework to run backend plugins that talk to data providers, such as the Kubernetes controller mentioned above.

Enabling the plugin on the new Backstage backend system

To install on the new backend system, add the following into the packages/backend/index.ts file:

  1. import { createBackend } from '@backstage/backend-defaults';
  3. const backend = createBackend();
  5. // Other plugins/modules
  7. backend.add(import('@knative-extensions/plugin-knative-event-mesh-backend/alpha'));

Warning

If you have made any changes to the schedule in the app-config.yaml file, then restart to apply the changes.

Enabling the plugin on the legacy Backstage backend system

Configure the scheduler for the entity provider and enable the processor. Add the following code to packages/backend/src/plugins/catalog.ts file:

  1. import {CatalogClient} from "@backstage/catalog-client";
  2. import {
  3.     KnativeEventMeshProcessor,
  4.     KnativeEventMeshProvider
  5. } from '@knative-extensions/plugin-knative-event-mesh-backend';
  7. export default async function createPlugin(
  8.     env:PluginEnvironment,
  9. ):Promise<Router> {
  10.     const builder = await CatalogBuilder.create(env);
  12.     /* ... other processors and/or providers ... */
  14.     // ADD THESE
  15.     builder.addEntityProvider(
  16.         KnativeEventMeshProvider.fromConfig(env.config, {
  17.             logger: env.logger,
  18.             scheduler: env.scheduler,
  19.         }),
  20.     );
  21.     const catalogApi = new CatalogClient({
  22.         discoveryApi: env.discovery,
  23.     });
  24.     const knativeEventMeshProcessor = new KnativeEventMeshProcessor(catalogApi, env.logger);
  25.     builder.addProcessor(knativeEventMeshProcessor);
  27.     /* ... other processors and/or providers ... */
  29.     const {processingEngine, router} = await builder.build();
  30.     await processingEngine.start();
  31.     return router;
  32. }

Configuration

Info

NOTE: The backend needs to be accessible from the Backstage instance. If you are running the backend without exposing it, you can use kubectl port-forward to forward the port of the backend service to your local machine for testing purposes.

  1. kubectl port-forward -n knative-eventing svc/eventmesh-backend 8080:8080

The plugin needs to be configured to talk to the backend. It can be configured in the app-config.yaml file of the Backstage instance and allows configuration of one or multiple providers.

Use a knativeEventMesh marker to start configuring the app-config.yaml file of Backstage:

  1. catalog:
  2.   providers:
  3.     knativeEventMesh:
  4.       dev:
  5.         token: '${KNATIVE_EVENT_MESH_TOKEN}'     # SA token to authenticate to the backend
  6.         baseUrl: '${KNATIVE_EVENT_MESH_BACKEND}' # URL of the backend installed in the cluster
  7.         schedule: # optional; same options as in TaskScheduleDefinition
  8.           # supports cron, ISO duration, "human duration" as used in code
  9.           frequency: { minutes: 1 }
  10.           # supports ISO duration, "human duration" as used in code
  11.           timeout: { minutes: 1 }

You can either manually change the placeholders in the app-config.yaml file or use environment variables to set the values. The environment variables can be set as following before starting the Backstage instance:

  1. export KNATIVE_EVENT_MESH_TOKEN=<your-token>
  2. export KNATIVE_EVENT_MESH_BACKEND=<backend-url>

The value of KNATIVE_EVENT_MESH_BACKEND should be the URL of the backend service. If you are running the backend service in the same cluster as the Backstage instance, you can use the service name as the URL such as http://eventmesh-backend.knative-eventing.svc.cluster.local. If the Backstage instance is not running in the same cluster, you can use the external URL of the backend service. Or, if you are running the backend without exposing it for testing purposes, you can use kubectl port-forward as mentioned above.

The value of KNATIVE_EVENT_MESH_TOKEN should be a service account token that has the necessary permissions to list the Knative Eventing resources in the cluster. The backend will use this token to authenticate to the Kubernetes API server. This is required for security reasons as otherwise (if the backend is running with a SA token directly) the backend would have full access to the cluster will be returning all resources to anyone who can access the backend.

The token will require the following permissions to work properly:

  • get, list and watch permissions for eventing.knative.dev/brokers, eventing.knative.dev/eventtypes and eventing.knative.dev/triggers resources
  • get permission for all resources to fetch subscribers for triggers

You can create a ClusterRole with the necessary permissions and bind it to the service account token.

An example configuration is as follows:

  1. apiVersion: v1
  2. kind: ServiceAccount
  3. metadata:
  4.   name: my-eventmesh-backend-service-account
  5.   namespace: default
  6. ---
  7. apiVersion: rbac.authorization.k8s.io/v1
  8. kind: ClusterRole
  9. metadata:
  10.   name: my-eventmesh-backend-cluster-role
  11. rules:
  12.   # permissions for eventtypes, brokers and triggers
  13.   - apiGroups:
  14.       - "eventing.knative.dev"
  15.     resources:
  16.       - brokers
  17.       - eventtypes
  18.       - triggers
  19.     verbs:
  20.       - get
  21.       - list
  22.       - watch
  23.   # permissions to get subscribers for triggers
  24.   # as subscribers can be any resource, we need to give access to all resources
  25.   # we fetch subscribers one by one, we only need `get` verb
  26.   - apiGroups:
  27.       - "*"
  28.     resources:
  29.       - "*"
  30.     verbs:
  31.       - get
  32. ---
  33. apiVersion: rbac.authorization.k8s.io/v1
  34. kind: ClusterRoleBinding
  35. metadata:
  36.   name: my-eventmesh-backend-cluster-role-binding
  37. subjects:
  38.   - kind: ServiceAccount
  39.     name: my-eventmesh-backend-service-account
  40.     namespace: default
  41. roleRef:
  42.   kind: ClusterRole
  43.   name: my-eventmesh-backend-cluster-role
  44.   apiGroup: rbac.authorization.k8s.io
  45. ---
  46. apiVersion: v1
  47. kind: Secret
  48. metadata:
  49.   name: my-eventmesh-backend-secret
  50.   namespace: default
  51.   annotations:
  52.     kubernetes.io/service-account.name: my-eventmesh-backend-service-account
  53. type: kubernetes.io/service-account-token

To get the token, you can run the following command:

  1. kubectl get secret my-eventmesh-backend-secret -o jsonpath='{.data.token}' | base64 --decode

Run a quick check to see if the token works with the Kubernetes API server:

  1. export KUBE_API_SERVER_URL=$(kubectl config view --minify --output jsonpath="{.clusters[*].cluster.server}") # e.g. "https://192.168.2.151:16443"
  2. export KUBE_SA_TOKEN=$(kubectl get secret my-eventmesh-backend-secret -o jsonpath='{.data.token}' | base64 --decode)
  3. curl -k -H "Authorization: Bearer $KUBE_SA_TOKEN" -X GET "${KUBE_API_SERVER_URL}/apis/eventing.knative.dev/v1/namespaces/default/brokers"
  4. # Should see the brokers, or nothing if there are no brokers
  5. # But, should not see an error

Run a second quick check to see if the token works with the Backstage backend:

  1. export KNATIVE_EVENT_MESH_BACKEND=http://localhost:8080 # or the URL of the backend
  2. export KUBE_SA_TOKEN=$(kubectl get secret my-eventmesh-backend-secret -o jsonpath='{.data.token}' | base64 --decode)
  3. curl -k -H "Authorization: Bearer $KUBE_SA_TOKEN" -X GET "${KNATIVE_EVENT_MESH_BACKEND}"
  4. # Should see the response from the backend such as
  5. # {
  6. #   "brokers" : [...],
  7. #   "eventTypes" : [...]
  8. #}

If these quick checks work, you can use the token in the app-config.yaml file as the value of KNATIVE_EVENT_MESH_TOKEN.

Troubleshooting

When you start your Backstage application, you can see some log lines as follows:

  1. [1] 2024-01-04T09:38:08.707Z knative-event-mesh-backend info Found 1 knative event mesh provider configs with ids: dev type=plugin

Usage

See the plugin documentation for more information about using the plugin.