Skip to content

Commit dc0126a

Browse files
aliokaliok
authored
Add docs for Backstage plugin with SO (#116)
* Add docs for Backstage plugin with SO * Fix nav * Problem statement * More docs * Usage docs * Fix nav * Specify the necessary permissions * Fix broken link
1 parent 830b946 commit dc0126a

File tree

3 files changed

+292
-0
lines changed

3 files changed

+292
-0
lines changed

‎modules/ROOT/nav.adoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@
88
** Eventing
99
*** xref:serverless:eventing/transport-encryption-setup.adoc[Setup transport encryption in Eventing]
1010
*** xref:serverless:eventing/kafka-scaling-setup.adoc[Setup Autoscaling For Eventing Kafka Components]
11+
*** xref:serverless:eventing/backstage-setup.adoc[Setup Backstage for Eventing]
12+
*** xref:serverless:eventing/backstage-usage.adoc[Knative Event Mesh Backstage Plugin]
1113
** Serving
1214
*** xref:serverless:serving/serving-with-ingress-sharding.adoc[Use Serving with OpenShift ingress sharding]
1315
*** xref:serverless:serving/scaleability-and-performance-of-serving.adoc[Scalability and performance of {serverlessproductname} Serving]

‎modules/serverless/pages/eventing/backstage-setup.adoc

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
= Setup Backstage for Eventing
2+
:compat-mode!:
3+
// Metadata:
4+
:description: Setup Backstage for Eventing in {serverlessproductname}
5+
6+
This page describes how to set up Backstage for Eventing in {serverlessproductname}, which allows you to discover your Eventing resources in Backstage.
7+
8+
In an event driven architecture, events are the first-class citizens. They are the building blocks of your application. {serverlessproductname} provides a way to create, manage, and consume events in a cloud-native way. {serverlessproductname} Eventing is built on top of Knative Eventing, which is a Kubernetes-based eventing system that provides composable primitives to build event-driven systems.
9+
10+
However, as the number of events and event sources grow, it becomes difficult to manage them. You need a way to discover and manage these resources. This is where Backstage comes in. Backstage is an open-source platform for building developer portals. It provides a way to discover, share, and collaborate on your services and APIs.
11+
12+
[IMPORTANT]
13+
====
14+
{serverlessproductname} Backstage integration is a Developer Preview feature only.
15+
16+
Developer Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete.
17+
Red Hat does not recommend using them in production.
18+
These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
19+
20+
For more information about the support scope of Red Hat Developer Preview features, see https://access.redhat.com/support/offerings/devpreview/.
21+
====
22+
23+
== Prerequisites
24+
25+
* You have access to an {product-title} account with cluster administrator access.
26+
27+
* Install the OpenShift CLI (`oc`).
28+
29+
* Install the {serverlessoperatorname}.
30+
31+
* Install the https://developers.redhat.com/rhdh/overview[Red Hat Developer Hub Operator] and create a `Backstage` instance.
32+
33+
== Enable Backstage backend for Eventing
34+
35+
. Configure `KnativeEventing` to create the necessary backend resources for Backstage:
36+
+
37+
[source,yaml]
38+
----
39+
apiVersion: operator.knative.dev/v1
40+
kind: KnativeEventing
41+
metadata:
42+
name: knative-eventing
43+
namespace: knative-eventing
44+
spec:
45+
46+
# Other spec fields omitted ...
47+
# ...
48+
49+
config:
50+
features:
51+
backstage-backend: enabled <1>
52+
----
53+
<1> Enables Backstage backend deployment in Eventing namespace.
54+
55+
. Apply the `KnativeEventing` resource:
56+
+
57+
[source,terminal]
58+
----
59+
$ oc apply -f <filename>
60+
----
61+
62+
== Create necessary tokens for Backstage backend and {serverlessproductname} communication
63+
64+
Backstage backend will communicate with the {serverlessproductname} Backstage backend using a token. That token will be passed to the {serverlessproductname} backend and the it will use it to talk to the Kubernetes API server.
65+
66+
. Create a `ServiceAccount`:
67+
+
68+
[source,terminal]
69+
----
70+
$ oc -n knative-eventing create serviceaccount backstage-admin
71+
----
72+
73+
. Create a `ClusterRole` that allows the `ServiceAccount` to list and get the necessary resources in the cluster:
74+
+
75+
[source,yaml]
76+
----
77+
apiVersion: rbac.authorization.k8s.io/v1
78+
kind: ClusterRole
79+
metadata:
80+
name: backstage-admin
81+
rules:
82+
- apiGroups:
83+
- eventing.knative.dev
84+
resources:
85+
- brokers
86+
- eventtypes
87+
- triggers
88+
verbs:
89+
- get
90+
- list
91+
----
92+
93+
+
94+
[IMPORTANT]
95+
====
96+
The `ClusterRole` should be scoped to only allow the necessary permissions.
97+
====
98+
99+
. Apply the `ClusterRole` resource:
100+
+
101+
[source,terminal]
102+
----
103+
$ oc apply -f <filename>
104+
----
105+
106+
. Bind the `ServiceAccount` to the `ClusterRole`:
107+
+
108+
[source,terminal]
109+
----
110+
$ oc create clusterrolebinding backstage-admin --clusterrole=backstage-admin --serviceaccount=knative-eventing:backstage-admin
111+
----
112+
113+
. Create a secret:
114+
+
115+
[source,yaml]
116+
----
117+
apiVersion: v1
118+
kind: Secret
119+
metadata:
120+
name: backstage-admin
121+
namespace: knative-eventing
122+
annotations:
123+
kubernetes.io/service-account.name: backstage-admin
124+
type: kubernetes.io/service-account-token
125+
----
126+
. Apply the `Secret` resource:
127+
+
128+
[source,terminal]
129+
----
130+
$ oc apply -f <filename>
131+
----
132+
133+
. Get the token from the secret:
134+
+
135+
[source,terminal]
136+
----
137+
$ oc get secret backstage-admin -n knative-eventing -o jsonpath='{.data.token}' | base64 --decode
138+
----
139+
We are going to give this token to Red Hat Developer Hub.
140+
141+
142+
== Install the Backstage plugin on Red Hat Developer Hub
143+
144+
. Add the `BACKSTAGE_KNATIVE_BACKEND_TOKEN` environment variable to the Red Hat Developer Hub deployment by modifying the Red Hat Developer Hub secret such as `secrets-rhdh`:
145+
+
146+
[source,yaml]
147+
----
148+
kind: Secret
149+
apiVersion: v1
150+
metadata:
151+
name: secrets-rhdh
152+
namespace: rhdh-operator
153+
# more metadata ...
154+
data:
155+
BACKSTAGE_KNATIVE_BACKEND_TOKEN: SECRET-TOKEN <1>
156+
# more data ...
157+
# more fields ...
158+
----
159+
<1> The token we got from the `backstage-admin` secret.
160+
161+
. Modify the https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.3/html-single/installing_and_viewing_dynamic_plugins/index[dynamic plugins configmap] such as `dynamic-plugins-rhdh` and add an entry for the Backstage plugin:
162+
+
163+
[source,yaml]
164+
----
165+
kind: ConfigMap
166+
apiVersion: v1
167+
metadata:
168+
name: dynamic-plugins-rhdh
169+
namespace: rhdh-operator
170+
# more metadata ...
171+
data:
172+
dynamic-plugins.yaml: |-
173+
includes:
174+
- dynamic-plugins.default.yaml
175+
plugins:
176+
# - Other plugins omitted
177+
# - ...
178+
- package: "@knative-extensions/plugin-knative-event-mesh-backend-dynamic@1.16.0" <1>
179+
integrity: "sha512-Rnw7o2UyS8X7YklwhHYEtr/yHLnDHJizIACpKaDuqddW/2+WBWrdg8geAYGAeW8u/RnXwgpkcFW27DmoQ460gQ==" <2>
180+
disabled: false
181+
pluginConfig:
182+
catalog:
183+
providers:
184+
knativeEventMesh:
185+
dev:
186+
token: "${BACKSTAGE_KNATIVE_BACKEND_TOKEN}" <3>
187+
baseUrl: "http://eventmesh-backend.knative-eventing.svc.cluster.local:8080" <4>
188+
schedule:
189+
frequency: { minutes: 1 } <5>
190+
timeout: { minutes: 1 } <6>
191+
----
192+
<1> The full package name of the plugin. You can find the list of available versions in https://www.npmjs.com/package/@knative-extensions/plugin-knative-event-mesh-backend-dynamic?activeTab=versions[NPM].
193+
<2> The integrity of the plugin package. You can find the integrity of the package by running `npm view @knative-extensions/plugin-knative-event-mesh-backend-dynamic@1.16.0 dist.integrity`.
194+
<3> This will be replaced by an environment variable we have created in the previous step.
195+
<4> This is the URL of the Backstage backend.
196+
<5> The frequency at which the plugin will poll the backend for new data.
197+
<6> The timeout for the polling.
198+
199+
. Apply the `ConfigMap` resource:
200+
+
201+
[source,terminal]
202+
----
203+
$ oc apply -f <filename>
204+
----
205+
206+
207+
[NOTE]
208+
====
209+
The changes will not be applied to the Red Hat Developer Hub deployment automatically.
210+
You need to restart the Red Hat Developer Hub deployment to apply the changes.
211+
====
212+
213+
[NOTE]
214+
====
215+
The default installation of Red Hat Developer Hub might not have the https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.3/html-single/installing_and_viewing_dynamic_plugins/index[dynamic plugins configmap] such as `dynamic-plugins-rhdh` and the https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.3/html-single/administration_guide_for_red_hat_developer_hub/index#proc-add-custom-app-config-file-ocp-operator_admin-rhdh[secret such as `secrets-rhdh`] created. See the Red Hat Developer Hub documentation for more information on how to create these resources and to reference them in the Red Hat Developer Hub instance.
216+
====

‎modules/serverless/pages/eventing/backstage-usage.adoc

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
= Knative Event Mesh Backstage Plugin
2+
:compat-mode!
3+
4+
This page describes how to use the Knative Event Mesh Backstage plugin to manage and discover Knative Eventing resources in Backstage.
5+
6+
The Knative Event Mesh plugin is a Backstage plugin that allows you to view and manage Knative Eventing resources. It communicates with a backend service that runs in the Kubernetes cluster and interacts with the Kubernetes API server.
7+
8+
Backstage is an open-source platform for building developer portals. It provides a unified way to manage and visualize the different resources that developers use in their daily work. While Backstage is not intended to replace Kubernetes dashboards, it can partially manage Knative resources and provide insights relevant to developers.
9+
10+
[IMPORTANT]
11+
====
12+
The Knative Event Mesh plugin is a Developer Preview feature.
13+
14+
Developer Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete.
15+
Red Hat does not recommend using them in production.
16+
These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
17+
18+
For more information about the support scope of Red Hat Developer Preview features, see https://access.redhat.com/support/offerings/devpreview/.
19+
====
20+
21+
== How it works
22+
23+
The plugin is the frontend component of Backstage, responsible for rendering the UI and communicating with the backend. The backend service retrieves data from the Kubernetes API server and sends it to the frontend for display.
24+
25+
This plugin leverages Backstage's link:https://backstage.io/docs/features/software-catalog/external-integrations/#custom-entity-providers[entity provider] and link:https://backstage.io/docs/features/software-catalog/external-integrations/#custom-processors[entity processor] concepts:
26+
27+
* The entity provider fetches resources from the backend.
28+
* The entity processor processes these resources and makes them available to the Backstage frontend.
29+
30+
Instead of directly showing raw Kubernetes resources, the plugin provides a more user-friendly representation of Knative Eventing resources. Certain fields are excluded, combined, or transformed for better usability.
31+
32+
== Features
33+
34+
The plugin shows the following Knative resources:
35+
36+
* Brokers: Represented as Backstage link:https://backstage.io/docs/features/software-catalog/system-model#component[`Component`] entities.
37+
* EventTypes: Represented as Backstage link:https://backstage.io/docs/features/software-catalog/system-model#api[`API`] entities.
38+
* Trigger subscribers: Shown as Backstage `Component` entities if:
39+
** They are registered in Backstage.
40+
** They include the link:https://backstage.io/docs/features/kubernetes/configuration#surfacing-your-kubernetes-components-as-part-of-an-entity[`backstage.io/kubernetes-id`] annotation with the Kubernetes resource name.
41+
42+
Triggers pointing to generic `Addressable` endpoints or URLs are not displayed unless explicitly registered in Backstage.
43+
44+
Backstage's graph capabilities can visualize relationships between Brokers, EventTypes, and Triggers, making it easier to understand how resources are interconnected.
45+
46+
== Security
47+
48+
The plugin requires the administrator to configure the backend URL and a token to authenticate with the Kubernetes API server. Similar to the link:https://backstage.io/docs/features/kubernetes/configuration#configuring-kubernetes-clusters[Backstage Kubernetes plugin], the token is stored in Backstage's configuration and passed with each request to the backend.
49+
50+
[source,yaml]
51+
----
52+
catalog:
53+
providers:
54+
knativeEventMesh:
55+
dev:
56+
token: '${KNATIVE_EVENT_MESH_TOKEN}'
57+
baseUrl: "http://eventmesh-backend.knative-eventing.svc:8080"
58+
schedule: # optional; same options as in TaskScheduleDefinition
59+
frequency: { minutes: 1 }
60+
timeout: { minutes: 1 }
61+
----
62+
63+
The `token` is retrieved from the `KNATIVE_EVENT_MESH_TOKEN` environment variable. For information on creating a `ServiceAccount`, `ClusterRole`, `ClusterRoleBinding`, and the corresponding token, see the link:./backstage-setup.adoc[plugin installation documentation].
64+
65+
== Usage
66+
67+
The plugin displays all `Broker` and `EventType` resources in the cluster. The subscribers of `Trigger` resources are displayed if they meet the requirements specified above.
68+
69+
* Brokers: Shown as Backstage `Component` entities.
70+
* EventTypes: Shown as Backstage `API` entities.
71+
* Trigger subscribers: Shown as `Component` entities if they are registered in Backstage and include the `backstage.io/kubernetes-id` annotation.
72+
73+
For more information on how to install and configure this plugin, refer to the link:./backstage-setup[installation guide].
74+

0 commit comments

Comments
 (0)