docs: review for Topology plugin (#269)

* Doc review for Topology plugin Signed-off-by: hmanwani-rh <[email protected]> * Incorporated review suggestions Signed-off-by: hmanwani-rh <[email protected]> * Incorporated review suggestions Signed-off-by: hmanwani-rh <[email protected]> --------- Signed-off-by: hmanwani-rh <[email protected]>
janus-idp · May 8, 2023 · 10f0910 · 10f0910
1 parent fce1748
commit 10f0910
Showing 1 changed file with 55 additions and 30 deletions.
diff --git a/plugins/topology/README.md b/plugins/topology/README.md
@@ -1,44 +1,69 @@
 # Topology plugin for Backstage
 
-This plugin will help with visualizing the workloads like Deployment, Replicaset and Pods powering any service on the Kubernetes cluster.
+The Topology plugin visualizes the workloads such as Deployment, Replicaset, and Pods powering any service on the Kubernetes cluster.
 
 ## Prerequisites
 
-1. Install and configure Kubernetes plugin by following these guides:
-   https://backstage.io/docs/features/kubernetes/installation
-   https://backstage.io/docs/features/kubernetes/configuration
-2. Kubernetes plugin is properly configured and able to connect to the cluster via a `ServiceAccount`
-3. Following [ClusterRole](https://backstage.io/docs/features/kubernetes/configuration#role-based-access-control) must be granted to ServiceAccount accessing the cluster (This role is already granted if you have the Backstage Kubernetes Plugin properly configured)
-4. To get the resources from a k8s cluster add the following annotations to the entity's catalog-info.yaml as K8s plugin identifies if the provided entity has k8s resources and if yes from which namespace it should get the resources based on the following annotations.
-   ```yaml
-   annotations:
-     backstage.io/kubernetes-id: <BACKSTAGE_ENTITY_NAME>
-     backstage.io/kubernetes-namespace: <RESOURCE_NS>
-   ```
-5. A custom label selector can also be added which will then be used by Backstage to find the resources. The label selector takes precedence over the id annotation.
-   `'backstage.io/kubernetes-label-selector': 'app=my-app,component=front-end`
-6. For k8s plugin to get the desired entity's k8s resources the following label should be added to the resources(if label selector is used then the labels mentioned in that should be present on the resource):
-   ```yaml
-   'backstage.io/kubernetes-id': <BACKSTAGE_ENTITY_NAME>`
-   ```
-7. Workload resources like Deployments and Pods will be shown in a visual group based on below label
-   ```yaml
-   'app.kubernetes.io/part-of': <GROUP_NAME>
-   ```
-8. Workload resources like Deployment or Pod will be shown with a visual connector based on below annotations
-   ```yaml
-   'app.openshift.io/connects-to': '[{"apiVersion": <RESOURCE_APIVERSION>,"kind": <RESOURCE_KIND>,"name": <RESOURCE_NAME>}]'
-   ```
+- The Kubernetes plugins including `@backstage/plugin-kubernetes` and `@backstage/plugin-kubernetes-backend` are installed and configured by following the [installation](https://backstage.io/docs/features/kubernetes/installation) and [configuration](https://backstage.io/docs/features/kubernetes/configuration) guides.
+- The Kubernetes plugin is configured and connects to the cluster using a `ServiceAccount`.
+- The [`ClusterRole`](https://backstage.io/docs/features/kubernetes/configuration#role-based-access-control) must be granted to `ServiceAccount` accessing the cluster. If you have the Backstage Kubernetes plugin configured, then the `ClusterRole` is already granted.
+- The following annotation is added to the entity's `catalog-info.yaml` file to identify whether an entitiy contains the Kubernetes resources:
+  ```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
+  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
+  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
+  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
+  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
+  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](https://github.com/redhat-developer/app-labels/blob/master/labels-annotation-for-openshift.adoc).
 
-## Getting started
+## Using Topology plugin
 
-1. Install the plugin
+1. Install the Topology plugin using the following command:
 
    ```bash
    yarn workspace app add @janus-idp/backstage-plugin-topology
    ```
 
-2. Enable additional tab on the entity view page
+2. Enable **Topology** tab on the entity view page:
 
    ```ts
    // packages/app/src/components/catalog/EntityPage.tsx
@@ -56,7 +81,7 @@ This plugin will help with visualizing the workloads like Deployment, Replicaset
 
 ## Development
 
-In [Backstage plugin terminology](https://backstage.io/docs/local-dev/cli-build-system#package-roles), this is a `frontend-plugin`. You can start a live dev session from the repository root using below command:
+In [Backstage plugin terminology](https://backstage.io/docs/local-dev/cli-build-system#package-roles), the Topology plugin is a frontend plugin. You can start a live development session from the repository root using the following command:
 
 ```
 yarn workspace @janus-idp/backstage-plugin-topology run start