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 permission must be granted to the ClusterRole to be able to view the pod logs:

    apiVersion: rbac.authorization.k8s.io/v1
    kind: ClusterRole
    metadata:
      name: backstage-read-only
    rules:
      ...
      - apiGroups:
          - ''
        resources:
          - pods
          - pods/log
        verbs:
          - get
          - list
          - watch

• The following code must be added in customResources component in the app-config.yaml file to view the Tekton PipelineRuns list in the side panel and to view the latest PipelineRun status in the Topology node decorator:

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

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

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

• The following configuration must be added in`customResources` component in the app-config.yaml file to view the edit code decorator:

    kubernetes:
      ...
      customResources:
        - group: 'org.eclipse.che'
          apiVersion: 'v2'
          plural: 'checlusters'

  Also, ensure that the CheCluster is granted a ClusterRole as shown in the following example code:

    apiVersion: rbac.authorization.k8s.io/v1
    kind: ClusterRole
    metadata:
      name: backstage-read-only
    rules:
      ...
      - apiGroups:
          - org.eclipse.che
        resources:
          - checlusters
        verbs:
          - get
          - list

• The following annotations are added to workload resources in the deployment.yaml file to navigate to the GitHub repository of the associated application using the edit code decorator:

  annotations:
    app.openshift.io/vcs-uri: <GIT_REPO_URL>

  You can also add the following annotation to navigate to a specific branch:

  annotations:
    app.openshift.io/vcs-ref: <GIT_REPO_BRANCH>

  If Red Hat OpenShift Dev Spaces (RHODS) is installed and configured and Git URL annotations are also added in the workload YAML file, then clicking on the edit code decorator redirects you to the RHODS instance. For more information about installing RHODS, see Administration guide of RHODS.

  When you deploy your application using the OCP git import flow, then you do not need to add the labels as import flow to the workload YAML file. Otherwise, you would need to add the labels to the workload YAML file manually.

  The labels are not similar to backstage.io/edit-url annotations as the added labels point to the source file of catalog entity metadata and is applied to Backstage catalog entity metadata YAML file, but not to the Kubernetes resources.

  You can also add the app.openshift.io/edit-url annotation that you want to access using the decorator.

  Tip

  You can use the prepared manifest for a read-only ClusterRole, which provides access for both Kubernetes and Topology plugin.

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

  annotations:
    backstage.io/kubernetes-id: <BACKSTAGE_ENTITY_NAME>

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

  labels:
    backstage.io/kubernetes-id: <BACKSTAGE_ENTITY_NAME>`

  Note

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

• The backstage.io/kubernetes-namespace annotation is added as follows to identify that the Kubernetes resources are using the defined namespace:

  annotations:
    backstage.io/kubernetes-namespace: <RESOURCE_NS>

  If the backstage.io/kubernetes-namespace annotation is added to the catalog-info.yaml file, then the RHODS instance is not accessible using the edit code decorator.

  To retrieve the instance URL, CheCluster Custom Resource (CR) is required. The instance URL is not retrieved if the namespace annotation value is different from openshift-devspaces as CheCluster CR is created in openshift-devspaces namespace.

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

  annotations:
    backstage.io/kubernetes-label-selector: 'app=my-app,component=front-end'

  If you have multiple entities while RHODS is configured and want multiple entities to support the edit code decorator that redirects to the RHODS instance, you can add the backstage.io/kubernetes-label-selector annotation to the catalog-info.yaml file for each entity as follows:

  annotations:
    backstage.io/kubernetes-label-selector: 'component in (<BACKSTAGE_ENTITY_NAME>,che)'

  If you are using the previous custom label selector, then make sure that you add the following labels to your resources so that the Kubernetes plugin receives the Kubernetes resources from the requested entity:

  labels:
    component: che # add this label to your che cluster instance

  labels:
    component: <BACKSTAGE_ENTITY_NAME> # add this label to the other resources associated with your entity

  You can also write your own custom query for the label selector with unique labels to differentiate your entities. However, you need to ensure that you add those labels to the resources associated with your entities including your CheCluster instance.

• The following label is added to workload resources in the deployment.yaml file to display runtime icon in the topology nodes:

  labels:
    app.openshift.io/runtime: <RUNTIME_NAME>

  Alternatively, you can include the following label to display the runtime icon:

  labels:
    app.kubernetes.io/name: <RUNTIME_NAME>

  The <RUNTIME_NAME> parameter in the previous example label supports the following values:

  • django
  • dotnet
  • drupal
  • go-gopher
  • golang
  • grails
  • jboss
  • jruby
  • js
  • nginx
  • nodejs
  • openjdk
  • perl
  • phalcon
  • php
  • python
  • quarkus
  • rails
  • redis
  • rh-spring-boot
  • rust
  • java
  • rh-openjdk
  • ruby
  • spring
  • spring-boot

  Any other value for <RUNTIME_NAME> parameter results in icons not being rendered for the node.

• 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”.