From f1f708ce2ca48e70980f4824c7df55ff7165c221 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Wed, 9 Apr 2025 02:14:07 +0200 Subject: [PATCH 1/3] Modularize modules/dynamic-plugins/proc-topology-configur --- ...-managing-labels-annotations-topology.adoc | 20 ++ .../assembly-topology-plugin-configure.adoc | 14 + .../assembly-configuring-rhdh-plugins.adoc | 7 +- .../dynamic-plugins/proc-app-grouping.adoc | 11 + .../proc-enabling-the-source-code-editor.adoc | 34 ++ .../proc-entity-annotation-or-label.adoc | 24 ++ .../proc-icon-displayed-in-the-node.adoc | 52 +++ .../proc-label-selector-query-annotation.adoc | 31 ++ ...nking-to-source-code-editor-or-source.adoc | 33 ++ .../proc-namespace-annotation.adoc | 15 + .../dynamic-plugins/proc-node-connector.adoc | 11 + .../proc-topology-configure.adoc | 333 ------------------ .../proc-viewing-openshift-routes.adoc | 33 ++ .../proc-viewing-pod-logs.adoc | 23 ++ .../proc-viewing-tekton-pipelineruns.adoc | 42 +++ .../proc-viewing-virtual-machines.adoc | 39 ++ 16 files changed, 387 insertions(+), 335 deletions(-) create mode 100644 assemblies/assembly-managing-labels-annotations-topology.adoc create mode 100644 assemblies/assembly-topology-plugin-configure.adoc create mode 100644 modules/dynamic-plugins/proc-app-grouping.adoc create mode 100644 modules/dynamic-plugins/proc-enabling-the-source-code-editor.adoc create mode 100644 modules/dynamic-plugins/proc-entity-annotation-or-label.adoc create mode 100644 modules/dynamic-plugins/proc-icon-displayed-in-the-node.adoc create mode 100644 modules/dynamic-plugins/proc-label-selector-query-annotation.adoc create mode 100644 modules/dynamic-plugins/proc-linking-to-source-code-editor-or-source.adoc create mode 100644 modules/dynamic-plugins/proc-namespace-annotation.adoc create mode 100644 modules/dynamic-plugins/proc-node-connector.adoc delete mode 100644 modules/dynamic-plugins/proc-topology-configure.adoc create mode 100644 modules/dynamic-plugins/proc-viewing-openshift-routes.adoc create mode 100644 modules/dynamic-plugins/proc-viewing-pod-logs.adoc create mode 100644 modules/dynamic-plugins/proc-viewing-tekton-pipelineruns.adoc create mode 100644 modules/dynamic-plugins/proc-viewing-virtual-machines.adoc diff --git a/assemblies/assembly-managing-labels-annotations-topology.adoc b/assemblies/assembly-managing-labels-annotations-topology.adoc new file mode 100644 index 0000000000..ca5d269af6 --- /dev/null +++ b/assemblies/assembly-managing-labels-annotations-topology.adoc @@ -0,0 +1,20 @@ +:_mod-docs-content-type: ASSEMBLY +[id="assembly-managing-labels-annotations-topology"] += Managing labels and annotations for Topology plugins +:context: assembly-managing-labels-annotations-topology + +include::modules/dynamic-plugins/proc-linking-to-source-code-editor-or-source.adoc[leveloffset=+1] + +include::modules/dynamic-plugins/proc-entity-annotation-or-label.adoc[leveloffset=+1] + +include::modules/dynamic-plugins/proc-namespace-annotation.adoc[leveloffset=+1] + +include::modules/dynamic-plugins/proc-label-selector-query-annotation.adoc[leveloffset=+1] + +include::modules/dynamic-plugins/proc-icon-displayed-in-the-node.adoc[leveloffset=+1] + +include::modules/dynamic-plugins/proc-app-grouping.adoc[leveloffset=+1] + +include::modules/dynamic-plugins/proc-node-connector.adoc[leveloffset=+1] + +For more information about the labels and annotations, see _Guidelines for labels and annotations for OpenShift applications_. \ No newline at end of file diff --git a/assemblies/assembly-topology-plugin-configure.adoc b/assemblies/assembly-topology-plugin-configure.adoc new file mode 100644 index 0000000000..ad1157b65d --- /dev/null +++ b/assemblies/assembly-topology-plugin-configure.adoc @@ -0,0 +1,14 @@ +:_mod-docs-content-type: ASSEMBLY +[id="assembly-topology-plugin-configure"] += Configuring the Topology plugin +:context: assembly-topology-plugin-configure + +include::modules/dynamic-plugins/proc-viewing-openshift-routes.adoc[leveloffset=+1] + +include::modules/dynamic-plugins/proc-viewing-pod-logs.adoc[leveloffset=+1] + +include::modules/dynamic-plugins/proc-viewing-tekton-pipelineruns.adoc[leveloffset=+1] + +include::modules/dynamic-plugins/proc-viewing-virtual-machines.adoc[leveloffset=+1] + +include::modules/dynamic-plugins/proc-enabling-the-source-code-editor.adoc[leveloffset=+1] \ No newline at end of file diff --git a/assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc b/assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc index e4740b72ff..81e0f4d9c2 100644 --- a/assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc +++ b/assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc @@ -20,9 +20,12 @@ include::../../artifacts/rhdh-plugins-reference/nexus-repository-manager/nexus-r include::../../artifacts/rhdh-plugins-reference/tekton/tekton-plugin-admin.adoc[leveloffset=+1] // Topology -== Installing and configuring the Topology plugin +== Installing the Topology plugin include::../modules/dynamic-plugins/proc-topology-install.adoc[leveloffset=+2] -include::../modules/dynamic-plugins/proc-topology-configure.adoc[leveloffset=+2] + +include::../assembly-topology-plugin-configure.adoc[leveloffset=+1] + +include::../assembly-managing-labels-annotations-topology.adoc[leveloffset=+1] include::../assembly-bulk-importing-from-github.adoc[leveloffset=+1] diff --git a/modules/dynamic-plugins/proc-app-grouping.adoc b/modules/dynamic-plugins/proc-app-grouping.adoc new file mode 100644 index 0000000000..89d7bccb05 --- /dev/null +++ b/modules/dynamic-plugins/proc-app-grouping.adoc @@ -0,0 +1,11 @@ +[id="proc-app-grouping"] + += App grouping + +To display workload resources such as deployments or pods in a visual group, add the following label: + +[source,yaml] +---- +labels: + app.kubernetes.io/part-of: +---- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-enabling-the-source-code-editor.adoc b/modules/dynamic-plugins/proc-enabling-the-source-code-editor.adoc new file mode 100644 index 0000000000..6b85f376c5 --- /dev/null +++ b/modules/dynamic-plugins/proc-enabling-the-source-code-editor.adoc @@ -0,0 +1,34 @@ +[id="proc-enabling-the-source-code-editor_{context}"] += Enabling the source code editor + +To enable the source code editor, you must grant read access to the CheClusters resource in the `ClusterRole` as shown in the following example code: + +[source,yaml] +---- + ... + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRole + metadata: + name: backstage-read-only + rules: + ... + - apiGroups: + - org.eclipse.che + resources: + - checlusters + verbs: + - get + - list +---- + +To use the source code editor, you must add the following configuration to the `kubernetes.customResources` property in your `{my-app-config-file}` file: + +[source,yaml] +---- + kubernetes: + ... + customResources: + - group: 'org.eclipse.che' + apiVersion: 'v2' + plural: 'checlusters' +---- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-entity-annotation-or-label.adoc b/modules/dynamic-plugins/proc-entity-annotation-or-label.adoc new file mode 100644 index 0000000000..75f9275c57 --- /dev/null +++ b/modules/dynamic-plugins/proc-entity-annotation-or-label.adoc @@ -0,0 +1,24 @@ +[id="proc-entity-annotation-or-label"] + += Entity annotation/label + +For RHDH to detect that an entity has Kubernetes components, add the following annotation to the entity's `catalog-info.yaml`: + +[source,yaml] +---- +annotations: + backstage.io/kubernetes-id: +---- + +The following label is added to the resources so that the Kubernetes plugin gets the Kubernetes resources from the requested entity, add the following label to the resources: + +[source,yaml] +---- +labels: + backstage.io/kubernetes-id: ` +---- + +[NOTE] +==== +When using the label selector, the mentioned labels must be present on the resource. +==== \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-icon-displayed-in-the-node.adoc b/modules/dynamic-plugins/proc-icon-displayed-in-the-node.adoc new file mode 100644 index 0000000000..a81c526f1b --- /dev/null +++ b/modules/dynamic-plugins/proc-icon-displayed-in-the-node.adoc @@ -0,0 +1,52 @@ +[id="proc-icon-displayed-in-the-node"] + += Icon displayed in the node + +To display a runtime icon in the topology nodes, add the following label to workload resources, such as Deployments: + +[source,yaml] +---- +labels: + app.openshift.io/runtime: +---- +Alternatively, you can include the following label to display the runtime icon: + +[source,yaml] +---- +labels: + app.kubernetes.io/name: +---- + +Supported values of `` include: + +* 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 + +[NOTE] +==== +Other values result in icons not being rendered for the node. +==== \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-label-selector-query-annotation.adoc b/modules/dynamic-plugins/proc-label-selector-query-annotation.adoc new file mode 100644 index 0000000000..eb270e6b29 --- /dev/null +++ b/modules/dynamic-plugins/proc-label-selector-query-annotation.adoc @@ -0,0 +1,31 @@ +[id="proc-label-selector-query-annotation"] + += Label selector query annotation + +You can write your own custom label, which RHDH uses to find the Kubernetes resources. The label selector takes precedence over the ID annotations: + +[source,yaml] +---- +annotations: + backstage.io/kubernetes-label-selector: 'app=my-app,component=front-end' +---- + +If you have multiple entities while Red Hat Dev Spaces is configured and want multiple entities to support the edit code decorator that redirects to the Red Hat Dev Spaces instance, you can add the backstage.io/kubernetes-label-selector annotation to the catalog-info.yaml file for each entity. + +[source,yaml] +---- +annotations: + backstage.io/kubernetes-label-selector: 'component in (,che)' +---- + +If you are using the previous label selector, you must add the following labels to your resources so that the Kubernetes plugin gets the Kubernetes resources from the requested entity: + +[source,yaml] +---- +labels: + component: che # add this label to your che cluster instance +labels: + component: # 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. \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-linking-to-source-code-editor-or-source.adoc b/modules/dynamic-plugins/proc-linking-to-source-code-editor-or-source.adoc new file mode 100644 index 0000000000..da90a2ff1b --- /dev/null +++ b/modules/dynamic-plugins/proc-linking-to-source-code-editor-or-source.adoc @@ -0,0 +1,33 @@ +[id="proc-linking-to-source-code-editor-or-source"] + += Linking to the source code editor or the source + +Add the following annotations to workload resources, such as Deployments to navigate to the Git repository of the associated application using the source code editor: + +[source,yaml] +---- +annotations: + app.openshift.io/vcs-uri: +---- + +Add the following annotation to navigate to a specific branch: + +[source,yaml] +---- +annotations: + app.openshift.io/vcs-ref: +---- + +[NOTE] +==== +If Red Hat OpenShift Dev Spaces is installed and configured and git URL annotations are also added to the workload YAML file, then clicking on the edit code decorator redirects you to the Red Hat OpenShift Dev Spaces instance. +==== + +[NOTE] +==== +When you deploy your application using the OCP Git import flows, then you do not need to add the labels as import flows do that. Otherwise, you need to add the labels manually to the workload YAML file. +==== + +//The labels are not similar to `backstage.io/edit-url` annotations as it points to the catalog entity metadata source file and is applied to RHDH catalog entity metadata YAML file, but not Kubernetes resources. + +You can also add the `app.openshift.io/edit-url` annotation with the edit URL that you want to access using the decorator. \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-namespace-annotation.adoc b/modules/dynamic-plugins/proc-namespace-annotation.adoc new file mode 100644 index 0000000000..a039972c80 --- /dev/null +++ b/modules/dynamic-plugins/proc-namespace-annotation.adoc @@ -0,0 +1,15 @@ +[id="proc-namespace-annotation"] + += Namespace annotation + +To identify the Kubernetes resources using the defined namespace, add the `backstage.io/kubernetes-namespace` annotation: + +[source,yaml] +---- +annotations: + backstage.io/kubernetes-namespace: +---- + +The Red Hat OpenShift Dev Spaces instance is not accessible using the source code editor if the `backstage.io/kubernetes-namespace` annotation is added to the `catalog-info.yaml` file. + +To retrieve the instance URL, you require the CheCluster custom resource (CR). As the CheCluster CR is created in the openshift-devspaces namespace, the instance URL is not retrieved if the namespace annotation value is not openshift-devspaces. \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-node-connector.adoc b/modules/dynamic-plugins/proc-node-connector.adoc new file mode 100644 index 0000000000..be63238d10 --- /dev/null +++ b/modules/dynamic-plugins/proc-node-connector.adoc @@ -0,0 +1,11 @@ +[id="proc-node-connector"] + += Node connector + +To display the workload resources such as deployments or pods with a visual connector, add the following annotation: + +[source,yaml] +---- +annotations: + app.openshift.io/connects-to: '[{"apiVersion": ,"kind": ,"name": }]' +---- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-topology-configure.adoc b/modules/dynamic-plugins/proc-topology-configure.adoc deleted file mode 100644 index 96781c5fd6..0000000000 --- a/modules/dynamic-plugins/proc-topology-configure.adoc +++ /dev/null @@ -1,333 +0,0 @@ -= Configuration - -== Viewing OpenShift routes -To view OpenShift routes, you must grant read access to the routes resource in the Cluster Role: - -[source,yaml] ----- - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRole - metadata: - name: backstage-read-only - rules: - ... - - apiGroups: - - route.openshift.io - resources: - - routes - verbs: - - get - - list ----- - -You must also add the following in `kubernetes.customResources` property in your `{my-app-config-file}` file: - -[source,yaml] ----- -kubernetes: - ... - customResources: - - group: 'route.openshift.io' - apiVersion: 'v1' - plural: 'routes' ----- - -== Viewing pod logs -To view pod logs, you must grant the following permission to the `ClusterRole`: - -[source,yaml] ----- - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRole - metadata: - name: backstage-read-only - rules: - ... - - apiGroups: - - '' - resources: - - pods - - pods/log - verbs: - - get - - list - - watch ----- - -== Viewing Tekton PipelineRuns -To view the Tekton PipelineRuns you must grant read access to the `pipelines`, `pipelinesruns`, and `taskruns` resources in the `ClusterRole`: - -[source,yaml] ----- - ... - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRole - metadata: - name: backstage-read-only - rules: - ... - - apiGroups: - - tekton.dev - resources: - - pipelines - - pipelineruns - - taskruns - verbs: - - get - - list ----- - -To view the Tekton PipelineRuns list in the side panel and the latest PipelineRuns status in the Topology node decorator, you must add the following code to the `kubernetes.customResources` property in your `{my-app-config-file}` file: - -[source,yaml] ----- -kubernetes: - ... - customResources: - - group: 'tekton.dev' - apiVersion: 'v1' - plural: 'pipelines' - - group: 'tekton.dev' - apiVersion: 'v1' - plural: 'pipelineruns' - - group: 'tekton.dev' - apiVersion: 'v1' - plural: 'taskruns' ----- - -== Viewing virtual machines -To view virtual machines, the OpenShift Virtualization operator must be installed and configured on a Kubernetes cluster. -You must also grant read access to the `VirtualMachines` resource in the `ClusterRole`: - -[source,yaml] ----- - ... - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRole - metadata: - name: backstage-read-only - rules: - ... - - apiGroups: - - kubevirt.io - resources: - - virtualmachines - - virtualmachineinstances - verbs: - - get - - list ----- - -To view the virtual machine nodes on the topology plugin, you must add the following code to the `kubernetes.customResources` property in the `{my-app-config-file}` file: - -[source,yaml] ----- -kubernetes: - ... - customResources: - - group: 'kubevirt.io' - apiVersion: 'v1' - plural: 'virtualmachines' - - group: 'kubevirt.io' - apiVersion: 'v1' - plural: 'virtualmachineinstances' ----- - -== Enabling the source code editor -To enable the source code editor, you must grant read access to the CheClusters resource in the `ClusterRole` as shown in the following example code: - -[source,yaml] ----- - ... - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRole - metadata: - name: backstage-read-only - rules: - ... - - apiGroups: - - org.eclipse.che - resources: - - checlusters - verbs: - - get - - list ----- - -To use the source code editor, you must add the following configuration to the `kubernetes.customResources` property in your `{my-app-config-file}` file: - -[source,yaml] ----- - kubernetes: - ... - customResources: - - group: 'org.eclipse.che' - apiVersion: 'v2' - plural: 'checlusters' ----- - -== Labels and annotations -=== Linking to the source code editor or the source -Add the following annotations to workload resources, such as Deployments to navigate to the Git repository of the associated application using the source code editor: - -[source,yaml] ----- -annotations: - app.openshift.io/vcs-uri: ----- - -Add the following annotation to navigate to a specific branch: - -[source,yaml] ----- -annotations: - app.openshift.io/vcs-ref: ----- - -[NOTE] -==== -If Red Hat OpenShift Dev Spaces is installed and configured and git URL annotations are also added to the workload YAML file, then clicking on the edit code decorator redirects you to the Red Hat OpenShift Dev Spaces instance. -==== - -[NOTE] -==== -When you deploy your application using the OCP Git import flows, then you do not need to add the labels as import flows do that. Otherwise, you need to add the labels manually to the workload YAML file. -==== - -//The labels are not similar to `backstage.io/edit-url` annotations as it points to the catalog entity metadata source file and is applied to RHDH catalog entity metadata YAML file, but not Kubernetes resources. - -You can also add the `app.openshift.io/edit-url` annotation with the edit URL that you want to access using the decorator. - -=== Entity annotation/label -For RHDH to detect that an entity has Kubernetes components, add the following annotation to the entity's `catalog-info.yaml`: - -[source,yaml] ----- -annotations: - backstage.io/kubernetes-id: ----- - -The following label is added to the resources so that the Kubernetes plugin gets the Kubernetes resources from the requested entity, add the following label to the resources: - -[source,yaml] ----- -labels: - backstage.io/kubernetes-id: ` ----- - -[NOTE] -==== -When using the label selector, the mentioned labels must be present on the resource. -==== - -=== Namespace annotation -To identify the Kubernetes resources using the defined namespace, add the `backstage.io/kubernetes-namespace` annotation: - -[source,yaml] ----- -annotations: - backstage.io/kubernetes-namespace: ----- - -The Red Hat OpenShift Dev Spaces instance is not accessible using the source code editor if the `backstage.io/kubernetes-namespace` annotation is added to the `catalog-info.yaml` file. - -To retrieve the instance URL, you require the CheCluster custom resource (CR). As the CheCluster CR is created in the openshift-devspaces namespace, the instance URL is not retrieved if the namespace annotation value is not openshift-devspaces. - -=== Label selector query annotation -You can write your own custom label, which RHDH uses to find the Kubernetes resources. The label selector takes precedence over the ID annotations: - -[source,yaml] ----- -annotations: - backstage.io/kubernetes-label-selector: 'app=my-app,component=front-end' ----- - -If you have multiple entities while Red Hat Dev Spaces is configured and want multiple entities to support the edit code decorator that redirects to the Red Hat Dev Spaces instance, you can add the backstage.io/kubernetes-label-selector annotation to the catalog-info.yaml file for each entity. - -[source,yaml] ----- -annotations: - backstage.io/kubernetes-label-selector: 'component in (,che)' ----- - -If you are using the previous label selector, you must add the following labels to your resources so that the Kubernetes plugin gets the Kubernetes resources from the requested entity: - -[source,yaml] ----- -labels: - component: che # add this label to your che cluster instance -labels: - component: # 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. - -=== Icon displayed in the node -To display a runtime icon in the topology nodes, add the following label to workload resources, such as Deployments: - -[source,yaml] ----- -labels: - app.openshift.io/runtime: ----- -Alternatively, you can include the following label to display the runtime icon: - -[source,yaml] ----- -labels: - app.kubernetes.io/name: ----- - -Supported values of `` include: - -* 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 - -[NOTE] -==== -Other values result in icons not being rendered for the node. -==== - -=== App grouping -To display workload resources such as deployments or pods in a visual group, add the following label: - -[source,yaml] ----- -labels: - app.kubernetes.io/part-of: ----- - -=== Node connector -To display the workload resources such as deployments or pods with a visual connector, add the following annotation: - -[source,yaml] ----- -annotations: - app.openshift.io/connects-to: '[{"apiVersion": ,"kind": ,"name": }]' ----- - -For more information about the labels and annotations, see _Guidelines for labels and annotations for OpenShift applications_. diff --git a/modules/dynamic-plugins/proc-viewing-openshift-routes.adoc b/modules/dynamic-plugins/proc-viewing-openshift-routes.adoc new file mode 100644 index 0000000000..293b5dbe8a --- /dev/null +++ b/modules/dynamic-plugins/proc-viewing-openshift-routes.adoc @@ -0,0 +1,33 @@ +[id="proc-viewing-openshift-routes_{context}"] += Viewing OpenShift routes + +To view OpenShift routes, you must grant read access to the routes resource in the Cluster Role: + +[source,yaml] +---- + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRole + metadata: + name: backstage-read-only + rules: + ... + - apiGroups: + - route.openshift.io + resources: + - routes + verbs: + - get + - list +---- + +You must also add the following in `kubernetes.customResources` property in your `{my-app-config-file}` file: + +[source,yaml] +---- +kubernetes: + ... + customResources: + - group: 'route.openshift.io' + apiVersion: 'v1' + plural: 'routes' +---- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-viewing-pod-logs.adoc b/modules/dynamic-plugins/proc-viewing-pod-logs.adoc new file mode 100644 index 0000000000..bf2bf7ffde --- /dev/null +++ b/modules/dynamic-plugins/proc-viewing-pod-logs.adoc @@ -0,0 +1,23 @@ +[id="proc-viewing-pod-logs_{context}"] += Viewing pod logs + +To view pod logs, you must grant the following permission to the `ClusterRole`: + +[source,yaml] +---- + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRole + metadata: + name: backstage-read-only + rules: + ... + - apiGroups: + - '' + resources: + - pods + - pods/log + verbs: + - get + - list + - watch +---- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-viewing-tekton-pipelineruns.adoc b/modules/dynamic-plugins/proc-viewing-tekton-pipelineruns.adoc new file mode 100644 index 0000000000..4add25eaf4 --- /dev/null +++ b/modules/dynamic-plugins/proc-viewing-tekton-pipelineruns.adoc @@ -0,0 +1,42 @@ +[id="proc-viewing-tekton-pipelineruns_{context}"] += Viewing Tekton PipelineRuns + +To view the Tekton PipelineRuns you must grant read access to the `pipelines`, `pipelinesruns`, and `taskruns` resources in the `ClusterRole`: + +[source,yaml] +---- + ... + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRole + metadata: + name: backstage-read-only + rules: + ... + - apiGroups: + - tekton.dev + resources: + - pipelines + - pipelineruns + - taskruns + verbs: + - get + - list +---- + +To view the Tekton PipelineRuns list in the side panel and the latest PipelineRuns status in the Topology node decorator, you must add the following code to the `kubernetes.customResources` property in your `{my-app-config-file}` file: + +[source,yaml] +---- +kubernetes: + ... + customResources: + - group: 'tekton.dev' + apiVersion: 'v1' + plural: 'pipelines' + - group: 'tekton.dev' + apiVersion: 'v1' + plural: 'pipelineruns' + - group: 'tekton.dev' + apiVersion: 'v1' + plural: 'taskruns' +---- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-viewing-virtual-machines.adoc b/modules/dynamic-plugins/proc-viewing-virtual-machines.adoc new file mode 100644 index 0000000000..f4cba66724 --- /dev/null +++ b/modules/dynamic-plugins/proc-viewing-virtual-machines.adoc @@ -0,0 +1,39 @@ +[id="proc-viewing-virtual-machines_{context}"] += Viewing virtual machines + +To view virtual machines, the OpenShift Virtualization operator must be installed and configured on a Kubernetes cluster. +You must also grant read access to the `VirtualMachines` resource in the `ClusterRole`: + +[source,yaml] +---- + ... + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRole + metadata: + name: backstage-read-only + rules: + ... + - apiGroups: + - kubevirt.io + resources: + - virtualmachines + - virtualmachineinstances + verbs: + - get + - list +---- + +To view the virtual machine nodes on the topology plugin, you must add the following code to the `kubernetes.customResources` property in the `{my-app-config-file}` file: + +[source,yaml] +---- +kubernetes: + ... + customResources: + - group: 'kubevirt.io' + apiVersion: 'v1' + plural: 'virtualmachines' + - group: 'kubevirt.io' + apiVersion: 'v1' + plural: 'virtualmachineinstances' +---- \ No newline at end of file From 2a378953d838b10730dda8edd7355c336f551138 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Wed, 23 Apr 2025 14:41:34 +0200 Subject: [PATCH 2/3] Modularize modules/dynamic-plugins/proc-topology-configur --- .../assembly-configuring-rhdh-plugins.adoc | 13 +------------ .../assembly-install-topology-plugin.adoc | 14 ++++++++++++++ .../dynamic-plugins/proc-namespace-annotation.adoc | 9 +++++---- modules/dynamic-plugins/proc-node-connector.adoc | 3 ++- .../proc-viewing-openshift-routes.adoc | 10 +++++----- modules/dynamic-plugins/proc-viewing-pod-logs.adoc | 5 +++-- .../proc-viewing-tekton-pipelineruns.adoc | 10 +++++----- .../proc-viewing-virtual-machines.adoc | 13 +++++++------ 8 files changed, 42 insertions(+), 35 deletions(-) create mode 100644 assemblies/dynamic-plugins/assembly-install-topology-plugin.adoc diff --git a/assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc b/assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc index 81e0f4d9c2..922c7e2fdb 100644 --- a/assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc +++ b/assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc @@ -20,18 +20,7 @@ include::../../artifacts/rhdh-plugins-reference/nexus-repository-manager/nexus-r include::../../artifacts/rhdh-plugins-reference/tekton/tekton-plugin-admin.adoc[leveloffset=+1] // Topology -== Installing the Topology plugin -include::../modules/dynamic-plugins/proc-topology-install.adoc[leveloffset=+2] - -include::../assembly-topology-plugin-configure.adoc[leveloffset=+1] - -include::../assembly-managing-labels-annotations-topology.adoc[leveloffset=+1] - -include::../assembly-bulk-importing-from-github.adoc[leveloffset=+1] - -include::../assembly-using-servicenow.adoc[leveloffset=+1] - -include::../assembly-using-kubernetes-custom-actions.adoc[leveloffset=+1] +include::../dynamic-plugins/assembly-install-topology-plugin.adoc[leveloffset=+1] // Overriding Core Backend Service Configuration include::../modules/dynamic-plugins/con-overriding-core-backend-services.adoc[leveloffset=+1] diff --git a/assemblies/dynamic-plugins/assembly-install-topology-plugin.adoc b/assemblies/dynamic-plugins/assembly-install-topology-plugin.adoc new file mode 100644 index 0000000000..8cd66db051 --- /dev/null +++ b/assemblies/dynamic-plugins/assembly-install-topology-plugin.adoc @@ -0,0 +1,14 @@ +[id="install-topology-plugin_{context}"] += Installing the Topology plugin + +include::../modules/dynamic-plugins/proc-topology-install.adoc[leveloffset=+2] + +include::../assembly-topology-plugin-configure.adoc[leveloffset=+1] + +include::../assembly-managing-labels-annotations-topology.adoc[leveloffset=+1] + +include::../assembly-bulk-importing-from-github.adoc[leveloffset=+1] + +include::../assembly-using-servicenow.adoc[leveloffset=+1] + +include::../assembly-using-kubernetes-custom-actions.adoc[leveloffset=+1] \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-namespace-annotation.adoc b/modules/dynamic-plugins/proc-namespace-annotation.adoc index a039972c80..22d296db83 100644 --- a/modules/dynamic-plugins/proc-namespace-annotation.adoc +++ b/modules/dynamic-plugins/proc-namespace-annotation.adoc @@ -2,14 +2,15 @@ = Namespace annotation -To identify the Kubernetes resources using the defined namespace, add the `backstage.io/kubernetes-namespace` annotation: - +.Procedure +* To identify the Kubernetes resources using the defined namespace, add the `backstage.io/kubernetes-namespace` annotation: ++ [source,yaml] ---- annotations: backstage.io/kubernetes-namespace: ---- - ++ The Red Hat OpenShift Dev Spaces instance is not accessible using the source code editor if the `backstage.io/kubernetes-namespace` annotation is added to the `catalog-info.yaml` file. - ++ To retrieve the instance URL, you require the CheCluster custom resource (CR). As the CheCluster CR is created in the openshift-devspaces namespace, the instance URL is not retrieved if the namespace annotation value is not openshift-devspaces. \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-node-connector.adoc b/modules/dynamic-plugins/proc-node-connector.adoc index be63238d10..961857e174 100644 --- a/modules/dynamic-plugins/proc-node-connector.adoc +++ b/modules/dynamic-plugins/proc-node-connector.adoc @@ -2,8 +2,9 @@ = Node connector +.Procedure To display the workload resources such as deployments or pods with a visual connector, add the following annotation: - ++ [source,yaml] ---- annotations: diff --git a/modules/dynamic-plugins/proc-viewing-openshift-routes.adoc b/modules/dynamic-plugins/proc-viewing-openshift-routes.adoc index 293b5dbe8a..81322932ea 100644 --- a/modules/dynamic-plugins/proc-viewing-openshift-routes.adoc +++ b/modules/dynamic-plugins/proc-viewing-openshift-routes.adoc @@ -1,8 +1,9 @@ [id="proc-viewing-openshift-routes_{context}"] = Viewing OpenShift routes -To view OpenShift routes, you must grant read access to the routes resource in the Cluster Role: - +.Procedure +. To view OpenShift routes, grant read access to the routes resource in the Cluster Role: ++ [source,yaml] ---- apiVersion: rbac.authorization.k8s.io/v1 @@ -19,9 +20,8 @@ To view OpenShift routes, you must grant read access to the routes resource in t - get - list ---- - -You must also add the following in `kubernetes.customResources` property in your `{my-app-config-file}` file: - +. Also add the following in `kubernetes.customResources` property in your `{my-app-config-file}` file: ++ [source,yaml] ---- kubernetes: diff --git a/modules/dynamic-plugins/proc-viewing-pod-logs.adoc b/modules/dynamic-plugins/proc-viewing-pod-logs.adoc index bf2bf7ffde..083428bb2c 100644 --- a/modules/dynamic-plugins/proc-viewing-pod-logs.adoc +++ b/modules/dynamic-plugins/proc-viewing-pod-logs.adoc @@ -1,8 +1,9 @@ [id="proc-viewing-pod-logs_{context}"] = Viewing pod logs -To view pod logs, you must grant the following permission to the `ClusterRole`: - +.Procedure +* To view pod logs, you must grant the following permission to the `ClusterRole`: ++ [source,yaml] ---- apiVersion: rbac.authorization.k8s.io/v1 diff --git a/modules/dynamic-plugins/proc-viewing-tekton-pipelineruns.adoc b/modules/dynamic-plugins/proc-viewing-tekton-pipelineruns.adoc index 4add25eaf4..320013681b 100644 --- a/modules/dynamic-plugins/proc-viewing-tekton-pipelineruns.adoc +++ b/modules/dynamic-plugins/proc-viewing-tekton-pipelineruns.adoc @@ -1,8 +1,9 @@ [id="proc-viewing-tekton-pipelineruns_{context}"] = Viewing Tekton PipelineRuns -To view the Tekton PipelineRuns you must grant read access to the `pipelines`, `pipelinesruns`, and `taskruns` resources in the `ClusterRole`: - +.Procedure +. To view the Tekton PipelineRuns, grant read access to the `pipelines`, `pipelinesruns`, and `taskruns` resources in the `ClusterRole`: ++ [source,yaml] ---- ... @@ -22,9 +23,8 @@ To view the Tekton PipelineRuns you must grant read access to the `pipelines`, ` - get - list ---- - -To view the Tekton PipelineRuns list in the side panel and the latest PipelineRuns status in the Topology node decorator, you must add the following code to the `kubernetes.customResources` property in your `{my-app-config-file}` file: - +. To view the Tekton PipelineRuns list in the side panel and the latest PipelineRuns status in the Topology node decorator, add the following code to the `kubernetes.customResources` property in your `{my-app-config-file}` file: ++ [source,yaml] ---- kubernetes: diff --git a/modules/dynamic-plugins/proc-viewing-virtual-machines.adoc b/modules/dynamic-plugins/proc-viewing-virtual-machines.adoc index f4cba66724..a0a51e02e8 100644 --- a/modules/dynamic-plugins/proc-viewing-virtual-machines.adoc +++ b/modules/dynamic-plugins/proc-viewing-virtual-machines.adoc @@ -1,9 +1,11 @@ [id="proc-viewing-virtual-machines_{context}"] = Viewing virtual machines -To view virtual machines, the OpenShift Virtualization operator must be installed and configured on a Kubernetes cluster. -You must also grant read access to the `VirtualMachines` resource in the `ClusterRole`: - +.Prerequisites +. The OpenShift Virtualization operator is installed and configured on a Kubernetes cluster. +.Procedure +. Grant read access to the `VirtualMachines` resource in the `ClusterRole`: ++ [source,yaml] ---- ... @@ -22,9 +24,8 @@ You must also grant read access to the `VirtualMachines` resource in the `Cluste - get - list ---- - -To view the virtual machine nodes on the topology plugin, you must add the following code to the `kubernetes.customResources` property in the `{my-app-config-file}` file: - +. To view the virtual machine nodes on the topology plugin, add the following code to the `kubernetes.customResources` property in the `{my-app-config-file}` file: ++ [source,yaml] ---- kubernetes: From 23996fbbab9bc48a5e287250ea2f258e0f5f1709 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Wed, 30 Apr 2025 13:11:49 +0200 Subject: [PATCH 3/3] Modularize modules/dynamic-plugins/proc-topology-configur --- modules/dynamic-plugins/proc-entity-annotation-or-label.adoc | 4 ++-- .../dynamic-plugins/proc-label-selector-query-annotation.adoc | 2 +- .../proc-linking-to-source-code-editor-or-source.adoc | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/dynamic-plugins/proc-entity-annotation-or-label.adoc b/modules/dynamic-plugins/proc-entity-annotation-or-label.adoc index 75f9275c57..76776a84c6 100644 --- a/modules/dynamic-plugins/proc-entity-annotation-or-label.adoc +++ b/modules/dynamic-plugins/proc-entity-annotation-or-label.adoc @@ -2,7 +2,7 @@ = Entity annotation/label -For RHDH to detect that an entity has Kubernetes components, add the following annotation to the entity's `catalog-info.yaml`: +For {product-very-short} to detect that an entity has Kubernetes components, add the following annotation to the `catalog-info.yaml` file of the entity: [source,yaml] ---- @@ -10,7 +10,7 @@ annotations: backstage.io/kubernetes-id: ---- -The following label is added to the resources so that the Kubernetes plugin gets the Kubernetes resources from the requested entity, add the following label to the resources: +Add the following label to the resources so that the Kubernetes plugin gets the Kubernetes resources from the requested entity: [source,yaml] ---- diff --git a/modules/dynamic-plugins/proc-label-selector-query-annotation.adoc b/modules/dynamic-plugins/proc-label-selector-query-annotation.adoc index eb270e6b29..3c36157df2 100644 --- a/modules/dynamic-plugins/proc-label-selector-query-annotation.adoc +++ b/modules/dynamic-plugins/proc-label-selector-query-annotation.adoc @@ -2,7 +2,7 @@ = Label selector query annotation -You can write your own custom label, which RHDH uses to find the Kubernetes resources. The label selector takes precedence over the ID annotations: +You can write your own custom label, which {product-very-short} uses to find the Kubernetes resources. The label selector takes precedence over the ID annotations: [source,yaml] ---- diff --git a/modules/dynamic-plugins/proc-linking-to-source-code-editor-or-source.adoc b/modules/dynamic-plugins/proc-linking-to-source-code-editor-or-source.adoc index da90a2ff1b..417e1af3d8 100644 --- a/modules/dynamic-plugins/proc-linking-to-source-code-editor-or-source.adoc +++ b/modules/dynamic-plugins/proc-linking-to-source-code-editor-or-source.adoc @@ -20,7 +20,7 @@ annotations: [NOTE] ==== -If Red Hat OpenShift Dev Spaces is installed and configured and git URL annotations are also added to the workload YAML file, then clicking on the edit code decorator redirects you to the Red Hat OpenShift Dev Spaces instance. +If Red Hat OpenShift Dev Spaces is installed and configured and Git URL annotations are also added to the workload YAML file, then clicking on the edit code decorator redirects you to the Red Hat OpenShift Dev Spaces instance. ==== [NOTE]