Chapter 1. Topology plugin for Backstage

Prerequisites

• The Kubernetes plugins including @backstage/plugin-kubernetes and @backstage/plugin-kubernetes-backend are installed and configured by following the installation and configuration guides.
• The Kubernetes plugin is configured and connects to the cluster using a ServiceAccount.
• The ClusterRole must be granted to ServiceAccount accessing the cluster. If you have the Backstage Kubernetes plugin configured, then the ClusterRole is already granted.

• The following must be added incustomResources component in the app-config.yaml file to view the OpenShift route:

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

  Also, ensure that the route is granted a ClusterRole. You can use the following code to grant the ClusterRole to the route :

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

• The following code must be added incustomResources component in the app-config.yaml file to view the Tekton PipelineRuns list in side panel:

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

  Also, ensure that the Pipeline and PipelineRun are granted a ClusterRole. You can use the following code to grant the ClusterRole to Pipeline and PipelineRun:

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

• The following annotation is added to the entity’s catalog-info.yaml file to identify whether an entitiy contains the Kubernetes resources:

    ```yaml title="catalog-info.yaml"
    annotations:
    backstage.io/kubernetes-id: <BACKSTAGE_ENTITY_NAME>
    ```

  You can also add the backstage.io/kubernetes-namespace annotation to identify the Kubernetes resources using the defined namespace.

    ```yaml title="catalog-info.yaml"
    annotations:
      backstage.io/kubernetes-namespace: <RESOURCE_NS>
    ```

• A custom label selector is added, which Backstage uses to find the Kubernetes resources. The label selector takes precedence over the ID annotations.

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

• The following label is added to the resources so that the Kubernetes plugin gets the Kubernetes resources from the requested entity:

    ```yaml title="catalog-info.yaml"
    labels:
      backstage.io/kubernetes-id: <BACKSTAGE_ENTITY_NAME>`
    ```

  Note

  When using the label selector, the mentioned labels must be present on the resource.

• The following label is added to display the workload resources such as Deployments and Pods in a visual group:

    ```yaml title="catalog-info.yaml"
    labels:
      app.kubernetes.io/part-of: <GROUP_NAME>
    ```

• The following annotation is added to display the workload resources such as Deployments and Pods with a visual connector:

    ```yaml title="catalog-info.yaml"
    annotations:
      app.openshift.io/connects-to: '[{"apiVersion": <RESOURCE_APIVERSION>,"kind": <RESOURCE_KIND>,"name": <RESOURCE_NAME>}]'
    ```

  For more information about the labels and annotations, see Guidelines for labels and annotations for OpenShift applications.

Prerequisites

• Your Backstage application is installed and running.
• You have installed the Topology plugin. For the installation process, see Section 1.1.1, “Installation”.