From c8b37f93bd4238c01effc20c580b3a73c4456eac Mon Sep 17 00:00:00 2001
From: Gazandi <gazandic@gmail.com>
Date: Mon, 1 Mar 2021 23:17:20 +0700
Subject: [PATCH] doc: add troubleshoot md for kubernetes

Signed-off-by: gazandi <gazandi@ruangguru.com>
---
 docs/features/kubernetes/troubleshooting.md | 92 +++++++++++++++++++++
 1 file changed, 92 insertions(+)
 create mode 100644 docs/features/kubernetes/troubleshooting.md

diff --git a/docs/features/kubernetes/troubleshooting.md b/docs/features/kubernetes/troubleshooting.md
new file mode 100644
index 0000000000..eb262301b0
--- /dev/null
+++ b/docs/features/kubernetes/troubleshooting.md
@@ -0,0 +1,92 @@
+---
+id: troubleshooting-k8s
+title: Troubleshooting Kubernetes
+sidebar_label: Troubleshooting
+description: Troubleshooting for Kubernetes
+---
+
+## Kubernetes is not showing up on Service Entities 
+How to test your k8s cluster are already connected to backstage
+
+```curl
+# curl request
+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": <service-entity-name>,
+                  "backstage": <selector>,
+                  "backstage.io/kubernetes-id": <service-entity-name>
+                },
+                "name": <service-entity-name>,
+                "namespace": <namespace>
+              },
+              ....
+            }
+          ]
+        },
+        ....
+        {
+          "type": "pods",
+          "resources": [
+            ,,,,
+          ]
+        }
+      ],
+      "errors": []
+    }
+  ]
+}
+
+```
+
+Kubernetes will not be showing anything if annotations not match with annotations
+on k8s service.yaml / deployment.yaml / k8s related yaml. We recommend you for
+using label selector with adding two labels:  
+`backstage: <selector>` and `backstage.io/kubernetes-id: <entity-service-name>`.
+```yaml
+# k8s related yaml (service.yaml, deployment.yaml, ingress.yaml)
+metadata: {
+  creationTimestamp: "2022-03-13T13:52:46.000Z",
+  labels: {
+    "app": <entity-service-name>,
+    "backstage": <selector>,
+    "backstage.io/kubernetes-id": <entity-service-name>
+  },
+  "name": <service-entity-name>,
+  "namespace": <namespace>
+}
+```
+
+and the catalog info annotations would use label selector:
+
+```yaml
+# catalog-info.yaml (backstage)
+annotations:  
+  backstage.io/kubernetes-label-selector: 'backstage=<selectors'
+```