Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(topology): update README.md #678

Merged
merged 4 commits into from
Aug 29, 2023
Merged

docs(topology): update README.md #678

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0f2a988
docs(topology): update README.md
Zaperex Aug 25, 2023
07bf0c1
docs(topology): update README
Zaperex Aug 28, 2023
597a532
Merge branch 'main' of https://github.com/janus-idp/backstage-plugins…
Zaperex Aug 29, 2023
a93782e
docs(topology): update README.md
Zaperex Aug 29, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
125 changes: 76 additions & 49 deletions plugins/topology/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,18 +14,17 @@ The Topology plugin enables you to visualize the workloads such as Deployment, J
- The following must be added in`customResources` component in the [`app-config.yaml`](https://backstage.io/docs/features/kubernetes/configuration#configuring-kubernetes-clusters) file to view the OpenShift route as well:

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

Also, ensure that the route is granted a [`ClusterRole`](https://backstage.io/docs/features/kubernetes/configuration#role-based-access-control). You can use the following code to grant the `ClusterRole` to the route :

```yaml
...
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
Expand All @@ -45,37 +44,38 @@ The Topology plugin enables you to visualize the workloads such as Deployment, J
- The following permission must be granted to the [`ClusterRole`](https://backstage.io/docs/features/kubernetes/configuration#role-based-access-control) to be able to view the pod logs:

```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: backstage-read-only
rules:
- apiGroups:
- ''
resources:
- pods
- pods/log
verbs:
- get
- list
- watch
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`](https://backstage.io/docs/features/kubernetes/configuration#configuring-kubernetes-clusters) file to view the Tekton PipelineRuns list in the side panel and to view the latest PipelineRun status in the Topology node decorator:

```yaml
kubernetes:
...
customResources:
- group: 'tekton.dev'
apiVersion: 'v1beta1'
plural: 'pipelines'
- group: 'tekton.dev'
apiVersion: 'v1beta1'
plural: 'pipelineruns'
- group: 'tekton.dev'
apiVersion: 'v1beta1'
plural: 'taskruns'
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`](https://backstage.io/docs/features/kubernetes/configuration#role-based-access-control). You can use the following code to grant the `ClusterRole` to Pipeline, PipelineRun, and TaskRun:
Expand Down Expand Up @@ -103,9 +103,9 @@ The Topology plugin enables you to visualize the workloads such as Deployment, J
- The following configuration must be added in`customResources` component in the [`app-config.yaml`](https://backstage.io/docs/features/kubernetes/configuration#configuring-kubernetes-clusters) file to view the edit code decorator:

```yaml
kubernetes:
...
customResources:
kubernetes:
...
customResources:
- group: 'org.eclipse.che'
apiVersion: 'v2'
plural: 'checlusters'
Expand Down Expand Up @@ -134,35 +134,62 @@ The Topology plugin enables you to visualize the workloads such as Deployment, J
- The following annotations are added to workload resources, such as Deployments to navigate to the Git repository of the associated application using the edit code decorator:

```yaml title="deployment.yaml"
...
labels:
app.openshift.io/vcs-uri: <GIT_REPO_URL>
annotations:
app.openshift.io/vcs-uri: <GIT_REPO_URL>
```

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

```yaml title="deployment.yaml"
...
labels:
app.openshift.io/vcs-ref: <GIT_REPO_BRANCH>
annotations:
app.openshift.io/vcs-ref: <GIT_REPO_BRANCH>
```

- The following label is added to workload resources, such as Deployments to display runtime icon in the topology nodes:

```yaml title="deployment.yaml"
...
labels:
app.openshift.io/runtime: <RUNTIME_NAME>
labels:
app.openshift.io/runtime: <RUNTIME_NAME>
```

As another option, you can include the following label to display the runtime icon:

```yaml title="deployment.yaml"
...
labels:
app.kubernetes.io/name: <RUNTIME_NAME>
labels:
app.kubernetes.io/name: <RUNTIME_NAME>
```

Supported values of `<RUNTIME_NAME>` 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

Other values result in icons not being rendered for the node.

> Note: If Red Hat OpenShift Dev Spaces is [installed and configured](https://access.redhat.com/documentation/en-us/red_hat_openshift_dev_spaces/3.7/html/administration_guide/installing-devspaces) and Git URL annotations are also present on 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 the application using the OCP Git import flows, then you do not need to add the labels as import flows add the labels to the workload YAML file. Otherwise, you need to add the labels manually to the workload YAML file.
Expand All @@ -189,7 +216,7 @@ The Topology plugin enables you to visualize the workloads such as Deployment, J

> The Red Hat OpenShift Dev Spaces instance is not accessible using the edit code decorator if the `backstage.io/kubernetes-namespace` annotation is added to the `catalog-info.yaml` file.

To retrieve the instance URL, CheCluster 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.
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.

Expand Down