Merge pull request #4743 from gazandic/docs/refine-kubernetes

docs: refine kubernetes core feature docs

docs/features/kubernetes/configuration.md

@@ -73,10 +73,17 @@ cluster. Valid values are:
 | `serviceAccount` | This will use a Kubernetes [service account](https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin/) to access the Kubernetes API. When this is used the `serviceAccountToken` field should also be set. |
 | `google`         | This will use a user's Google auth token from the [Google auth plugin](https://backstage.io/docs/auth/) to access the Kubernetes API.                                                                                             |
 
-### `clusters.\*.serviceAccount` (optional)
+### `clusters.\*.serviceAccountToken` (optional)
 
 The service account token to be used when using the `serviceAccount` auth
-provider.
+provider. You could get the service account token with:
+
+```sh
+kubectl -n <NAMESPACE> get secret $(kubectl -n <NAMESPACE> get sa <SERVICE_ACCOUNT_NAME> -o=json \
+| jq -r '.secrets[0].name') -o=json \
+| jq -r '.data["token"]' \
+| base64 --decode
+```
 
 ### Role Based Access Control
 

docs/features/kubernetes/installation.md

@@ -117,3 +117,8 @@ Start the frontend and the backend app by
 
 After installing the plugins in the code, you'll need to then
 [configure them](configuration.md).
+
+## Troubleshooting
+
+After installing the plugins in the code, if the Kubernetes information is not
+showing up, you'll need to [troubleshoot it](troubleshooting.md).

docs/features/kubernetes/troubleshooting.md

@@ -0,0 +1,99 @@
+---
+id: troubleshooting
+title: Troubleshooting Kubernetes
+sidebar_label: Troubleshooting
+description: Troubleshooting for Kubernetes
+---
+
+## Kubernetes is not showing up on Service Entities
+
+This can be debugged by checking whether your Kubernetes cluster are connected
+to Backstage as follows:
+
+```curl
+curl --location --request POST '{{backstage-backend-url}}:{{backstage-backend-port}}/api/kubernetes/services/:service-entity-name' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "entity": {
+        "metadata": {
+            "name": <service-entity-name>
+        }
+    }
+}
+'
+```
+
+The curl response should have resources from Kubernetes:
+
+```json
+# curl response
+{
+  "items": [
+    {
+      "cluster": {
+        "name": <cluster-name>
+      },
+      "resources": [
+        {
+          "type": "services",
+          "resources": [
+            {
+              "metadata": {
+                "creationTimestamp": "2022-03-13T13:52:46.000Z",
+                "labels": {
+                  "app": <k8s-app-name>,
+                  "backstage": <selector>,
+                  "backstage.io/kubernetes-id": <service-entity-name>
+                },
+                "name": <k8s-app-name>,
+                "namespace": <namespace>
+              },
+              ....
+            }
+          ]
+        },
+        ....
+        {
+          "type": "pods",
+          "resources": [
+            ,,,,
+          ]
+        }
+      ],
+      "errors": []
+    }
+  ]
+}
+
+```
+
+The Kubernetes tab will not show anything when the catalog info annotation does
+not match the related Kubernetes resource. We recommend you add the following
+labels to your resources and use the label selector annotation as follows:
+
+`backstage.io/kubernetes-id: <entity-service-name>`for get k8s service-related
+objects.
+[See the plugin code](https://github.com/backstage/backstage/blob/a1f587c/plugins/kubernetes-backend/src/service/KubernetesFetcher.ts#L119)
+
+```yaml
+# k8s related yaml (service.yaml, deployment.yaml, ingress.yaml)
+metadata:
+  creationTimestamp: '2022-03-13T13:52:46.000Z'
+  labels:
+    app: <k8s-app-name>
+    env: <environment>
+    backstage.io/kubernetes-id: <service-entity-name>
+  name: <k8s-app-name>
+  namespace: <namespace>
+```
+
+k8s-app-name and service-entity-name could be different, but if you would like
+to have consistent names between k8s and backstage, we recommend use same name.
+
+and the catalog info annotations would use label selector:
+
+```yaml
+# catalog-info.yaml (backstage)
+annotations:
+  backstage.io/kubernetes-label-selector: '<label-selector>'
+```

microsite/sidebars.json

@@ -36,15 +36,6 @@
     ],
     "CLI": ["cli/index", "cli/commands"],
     "Core Features": [
-      {
-        "type": "subcategory",
-        "label": "Kubernetes",
-        "ids": [
-          "features/kubernetes/overview",
-          "features/kubernetes/installation",
-          "features/kubernetes/configuration"
-        ]
-      },
       {
         "type": "subcategory",
         "label": "Software Catalog",
@@ -62,6 +53,16 @@
           "features/software-catalog/software-catalog-api"
         ]
       },
+      {
+        "type": "subcategory",
+        "label": "Kubernetes",
+        "ids": [
+          "features/kubernetes/overview",
+          "features/kubernetes/installation",
+          "features/kubernetes/configuration",
+          "features/kubernetes/troubleshooting"
+        ]
+      },
       {
         "type": "subcategory",
         "label": "Software Templates",