Clean up TODOs and improve instructions (#18)

* Clean up TODOs and improve instructions Signed-off-by: Ali Ok <[email protected]> * Move instructions to the NPM package readme Signed-off-by: Ali Ok <[email protected]> * Fix the tests Signed-off-by: Ali Ok <[email protected]> --------- Signed-off-by: Ali Ok <[email protected]>
knative-extensions · Jan 4, 2024 · 1371cea · 1371cea
1 parent 3865edb
commit 1371cea
Show file tree

Hide file tree

Showing 13 changed files with 122 additions and 77 deletions.
diff --git a/README.md b/README.md
@@ -1,10 +1,12 @@
 # Knative Backstage Plugins
 
-TODO: Description
+This repository contains a set of Backstage plugins for Knative and their respective backends.
 
-## Setup
+## Installation and usage
 
-TODO: Setup instructions for using the plugins
+### Event Mesh plugin
+
+See [Event Mesh plugin README file](./backstage/plugins/knative-event-mesh-backend/README.md) for more information.
 
 ## Development
 

diff --git a/backends/config/100-eventmesh/100-clusterrole.yaml b/backends/config/100-eventmesh/100-clusterrole.yaml
@@ -25,7 +25,6 @@ rules:
     resources:
       - brokers
       - eventtypes
-      # TODO: - triggers
     verbs:
       - get
       - list

diff --git a/backends/config/100-eventmesh/500-controller.yaml b/backends/config/100-eventmesh/500-controller.yaml
@@ -50,18 +50,6 @@ spec:
           image: ko://knative.dev/backstage-plugins/backends/cmd/eventmesh
           imagePullPolicy: IfNotPresent
           env:
-            # TODO - necessary?
-            # - name: CONFIG_LEADERELECTION_NAME
-            #  value: config-kafka-leader-election
-            # TODO - necessary?
-            # - name: CONFIG_LOGGING_NAME
-            #  value: config-logging
-            # TODO - necessary?
-            #- name: CONFIG_OBSERVABILITY_NAME
-            #  value: config-observability
-            # TODO - necessary?
-            #- name: METRICS_DOMAIN
-            #  value: knative.dev/eventing
             - name: SYSTEM_NAMESPACE
               valueFrom:
                 fieldRef:

diff --git a/backends/pkg/reconciler/eventmesh/controller.go b/backends/pkg/reconciler/eventmesh/controller.go
@@ -59,7 +59,6 @@ func startWebServer(ctx context.Context, listers Listers) {
 	r.HandleFunc("/", EventMeshHandler(ctx, listers)).Methods("GET")
 	http.Handle("/", r)
 
-	// TODO: port
 	log.Fatal(http.ListenAndServe(":8080", r))
 }
 

diff --git a/backends/pkg/reconciler/eventmesh/eventmesh.go b/backends/pkg/reconciler/eventmesh/eventmesh.go
@@ -12,6 +12,7 @@ type Reconciler struct {
 }
 
 func (r *Reconciler) ReconcileKind(_ context.Context, _ *eventingv1beta2.EventType) pkgreconciler.Event {
-	// TODO: do we actually need the reconciler?
+	// we don't actually need a reconciler.
+	// but the sharedmain from knative/pkg requires one to inject informers, which we use for the eventmesh.
 	return nil
 }
diff --git a/backends/pkg/reconciler/eventmesh/eventtype.go b/backends/pkg/reconciler/eventmesh/eventtype.go
@@ -22,7 +22,6 @@ func (et EventType) NameAndNamespace() string {
 }
 
 func convertEventType(et *v1beta2.EventType) EventType {
-	// TODO: more information!
 	return EventType{
 		Name:        et.Name,
 		Namespace:   et.Namespace,

diff --git a/backends/pkg/reconciler/eventmesh/handler.go b/backends/pkg/reconciler/eventmesh/handler.go
@@ -21,8 +21,6 @@ type EventMesh struct {
 	// not every event type is tied to a broker. thus, we need to send event types as well.
 	EventTypes []*EventType `json:"eventTypes"`
 	Brokers    []*Broker    `json:"brokers"`
-	// TODO: triggers
-	// Triggers   []Trigger   `json:"triggers"`
 }
 
 type EventTypeMap = map[string]*EventType

diff --git a/backstage/app-config.yaml b/backstage/app-config.yaml
@@ -32,6 +32,17 @@ backend:
     connection: ':memory:'
   # workingDirectory: /tmp # Use this to configure a working directory for the scaffolder, defaults to the OS temp-dir
 
+# Reference documentation http://backstage.io/docs/features/techdocs/configuration
+# Note: After experimenting with basic setup, use CI/CD to generate docs
+# and an external cloud storage when deploying TechDocs for production use-case.
+# https://backstage.io/docs/features/techdocs/how-to-guides#how-to-migrate-from-techdocs-basic-to-recommended-deployment-approach
+techdocs:
+  builder: 'local' # Alternatives - 'external'
+  generator:
+    runIn: 'docker' # Alternatives - 'local'
+  publisher:
+    type: 'local' # Alternatives - 'googleGcs' or 'awsS3'. Read documentation for using alternatives.
+
 catalog:
   providers:
     knativeEventMesh:

diff --git a/backstage/plugins/knative-event-mesh-backend/README.md b/backstage/plugins/knative-event-mesh-backend/README.md
@@ -1,14 +1,99 @@
-# knative-event-mesh
+# Knative Event Mesh plugin
 
-Welcome to the knative-event-mesh backend plugin!
+The Event Mesh plugin is a Backstage plugin that allows you to view and manage Knative Eventing resources.
 
-_This plugin was created through the Backstage CLI_
+The Backstage plugin talks to a special backend that runs in the Kubernetes cluster and communicates with the Kubernetes
+API server.
 
-## Getting started
+## Installation
 
-Your plugin has been added to the example app in this repository, meaning you'll be able to access it by running `yarn
-start` in the root directory, and then navigating to [/knative-event-mesh](http://localhost:3000/knative-event-mesh).
+Install the backend and the relevant configuration in the Kubernetes cluster
 
-You can also serve the plugin in isolation by running `yarn start` in the plugin directory.
-This method of serving the plugin provides quicker iteration speed and a faster startup and hot reloads.
-It is only meant for local development, and the setup for it can be found inside the [/dev](/dev) directory.
+```bash
+kubectl apply -f https://github.com/knative-extensions/backstage-plugins/releases/download/v0.1.0/eventmesh.yaml
+```
+
+In your Backstage directory, run the following command to install the plugin:
+
+```bash
+yarn workspace backend add @knative-extensions/plugin-knative-event-mesh-backend
+```
+
+## Configuration
+
+> **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.
+> ```bash
+> 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:
+
+```yaml
+catalog:
+  providers:
+    knativeEventMesh:
+      dev:
+        baseUrl: 'http://localhost:8080' # URL of the backend installed in the cluster
+        schedule: # optional; same options as in TaskScheduleDefinition
+          # supports cron, ISO duration, "human duration" as used in code
+          frequency: { minutes: 1 }
+          # supports ISO duration, "human duration" as used in code
+          timeout: { minutes: 1 }
+```
+
+Configure the scheduler for the entity provider. Add the following code to `packages/backend/src/plugins/catalog.ts`
+file:
+
+In file `packages/backend/src/plugins/catalog.ts`:
+
+```ts
+import {KnativeEventMeshProvider} from '@knative-extensions/plugin-knative-event-mesh-backend';
+
+export default async function createPlugin(
+    env:PluginEnvironment,
+):Promise<Router> {
+    const builder = await CatalogBuilder.create(env);
+
+    /* ... other processors and/or providers ... */
+
+    // ADD THIS
+    builder.addEntityProvider(
+        KnativeEventMeshProvider.fromConfig(env.config, {
+            logger: env.logger,
+            scheduler: env.scheduler,
+        }),
+    );
+
+    /* ... other processors and/or providers ... */
+
+    const {processingEngine, router} = await builder.build();
+    await processingEngine.start();
+    return router;
+}
+```
+
+> **NOTE**: If you have made any changes to the schedule in the `app-config.yaml` file, then restart to apply the
+> changes.
+
+## Troubleshooting
+
+When you start your Backstage application, you can see some log lines as follows:
+
+```text
+[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
+
+The plugin will register a few entities in the Backstage catalog.
+
+Screenshots:
+
+- ![Event Mesh plugin](./event-mesh-plugin-components-view.png)
+
+- ![Event Mesh plugin](./event-mesh-plugin-apis-view.png)
diff --git a/backstage/plugins/knative-event-mesh-backend/src/providers/knativeEventMeshProvider.test.ts b/backstage/plugins/knative-event-mesh-backend/src/providers/knativeEventMeshProvider.test.ts
@@ -40,8 +40,8 @@ describe('KnativeEventMeshProvider', () => {
                         title: 'test-type - (test-ns/test-name)',
                         description: undefined,
                         annotations: {
-                            "backstage.io/managed-by-location": "url:http://example.com/eventtype/test-ns/test-name",
-                            "backstage.io/managed-by-origin-location": "url:http://example.com/eventtype/test-ns/test-name",
+                            "backstage.io/managed-by-location": "url:http://example.com",
+                            "backstage.io/managed-by-origin-location": "url:http://example.com",
                         },
                         labels: {},
                         tags: [],
@@ -85,8 +85,8 @@ describe('KnativeEventMeshProvider', () => {
                         description: 'test-description',
                         annotations: {
                             "test-annotation": "test-annotation-value",
-                            "backstage.io/managed-by-location": "url:http://example.com/eventtype/test-ns/test-name",
-                            "backstage.io/managed-by-origin-location": "url:http://example.com/eventtype/test-ns/test-name",
+                            "backstage.io/managed-by-location": "url:http://example.com",
+                            "backstage.io/managed-by-origin-location": "url:http://example.com",
                         },
                         labels: {
                             "test-label": "test-label-value",
@@ -151,8 +151,8 @@ describe('KnativeEventMeshProvider', () => {
                         name: 'test',
                         namespace: 'test',
                         annotations: {
-                            "backstage.io/managed-by-location": "url:http://example.com/broker/test/test",
-                            "backstage.io/managed-by-origin-location": "url:http://example.com/broker/test/test",
+                            "backstage.io/managed-by-location": "url:http://example.com",
+                            "backstage.io/managed-by-origin-location": "url:http://example.com",
                         },
                         labels: {},
                         tags: [],
@@ -190,8 +190,8 @@ describe('KnativeEventMeshProvider', () => {
                         namespace: 'test-ns',
                         annotations: {
                             "test-annotation": "test-annotation-value",
-                            "backstage.io/managed-by-location": "url:http://example.com/broker/test-ns/test-broker",
-                            "backstage.io/managed-by-origin-location": "url:http://example.com/broker/test-ns/test-broker",
+                            "backstage.io/managed-by-location": "url:http://example.com",
+                            "backstage.io/managed-by-origin-location": "url:http://example.com",
                         },
                         labels: {
                             "test-label": "test-label-value",

diff --git a/backstage/plugins/knative-event-mesh-backend/src/providers/knativeEventMeshProvider.ts b/backstage/plugins/knative-event-mesh-backend/src/providers/knativeEventMeshProvider.ts
@@ -184,8 +184,7 @@ export class KnativeEventMeshProvider implements EntityProvider {
 
     buildEventTypeEntity(eventType:EventType):ApiEntity {
         const annotations = eventType.annotations ?? {} as Record<string, string>;
-        // TODO: no route exists yet
-        annotations[ANNOTATION_ORIGIN_LOCATION] = annotations[ANNOTATION_LOCATION] = `url:${this.baseUrl}/eventtype/${eventType.namespace}/${eventType.name}`;
+        annotations[ANNOTATION_ORIGIN_LOCATION] = annotations[ANNOTATION_LOCATION] = `url:${this.baseUrl}`;
 
         const links:EntityLink[] = [];
         if (eventType.schemaURL) {
@@ -196,37 +195,14 @@ export class KnativeEventMeshProvider implements EntityProvider {
             });
         }
 
-        // TODO: remove?
-        // let relations:EntityRelation[] = [];
-        // if (eventType.provider) {
-        //     relations = [...relations, {
-        //         // type: RELATION_API_PROVIDED_BY,
-        //         type: 'apiProvidedBy',
-        //         // TODO: ref should point to the Backstage Broker provider
-        //         // targetRef: `${this.getProviderName()}:${eventType.provider.kind}:${eventType.provider.namespace}/${eventType.provider.name}`,
-        //         targetRef: `component:default/example-website`,
-        //     }];
-        //     console.log(relations);
-        //
-        //     // TODO:
-        //     // partOf: https://backstage.io/docs/features/software-catalog/well-known-relations/#partof-and-haspart
-        //     // - system?
-        //
-        //     // TODO:
-        //     // apiConsumedBy: https://backstage.io/docs/features/software-catalog/well-known-relations/#consumesapi-and-apiconsumedby
-        //     // - triggers?
-        // }
-
         return {
             apiVersion: 'backstage.io/v1alpha1',
             kind: 'API',
             metadata: {
                 name: eventType.name,
                 namespace: eventType.namespace,
                 description: eventType.description,
-                // TODO: is there a value showing Kubernetes labels in Backstage?
                 labels: eventType.labels || {} as Record<string, string>,
-                // TODO: is there a value showing Kubernetes annotations in Backstage?
                 annotations: annotations,
                 // we don't use tags
                 tags: [],
@@ -236,45 +212,32 @@ export class KnativeEventMeshProvider implements EntityProvider {
             spec: {
                 type: 'eventType',
                 lifecycle: this.env,
-                // TODO
                 system: 'knative-event-mesh',
-                // TODO
                 owner: 'knative',
                 definition: eventType.schemaData || "{}",
             },
-            // TODO: remove?
-            // Backstage doesn't like empty relations
-            // relations: relations.length > 0 ? relations : undefined,
         };
     }
 
     buildBrokerEntity(broker:Broker):ComponentEntity {
         const annotations = broker.annotations ?? {} as Record<string, string>;
-        // TODO: no route exists yet
-        annotations[ANNOTATION_ORIGIN_LOCATION] = annotations[ANNOTATION_LOCATION] = `url:${this.baseUrl}/broker/${broker.namespace}/${broker.name}`;
+        annotations[ANNOTATION_ORIGIN_LOCATION] = annotations[ANNOTATION_LOCATION] = `url:${this.baseUrl}`;
 
         return {
             apiVersion: 'backstage.io/v1alpha1',
             kind: 'Component',
             metadata: {
-                // TODO: names are too generic: default/default
                 name: broker.name,
                 namespace: broker.namespace,
-                // TODO: is there a value showing Kubernetes labels in Backstage?
                 labels: broker.labels || {} as Record<string, string>,
-                // TODO: is there a value showing Kubernetes annotations in Backstage?
                 annotations: annotations,
                 // we don't use tags
                 tags: [],
-                // TODO: any links?
-                // links: links,
             },
             spec: {
                 type: 'broker',
                 lifecycle: this.env,
-                // TODO
                 system: 'knative-event-mesh',
-                // TODO
                 owner: 'knative',
                 providesApis: !broker.providedEventTypes ? [] : broker.providedEventTypes.map((eventType:string) => `api:${eventType}`),
             }

diff --git a/event-mesh-plugin-apis-view.png b/event-mesh-plugin-apis-view.png
diff --git a/event-mesh-plugin-components-view.png b/event-mesh-plugin-components-view.png