From c59ca656fa3622221020c332000f44f8b8a2b941 Mon Sep 17 00:00:00 2001
From: Friedrich Clausen <friedrich.clausen@blackboard.com>
Date: Tue, 26 May 2020 11:54:02 +1000
Subject: [PATCH] documentation: Add troubleshooting section about formatting
 port name correctly

---
 Documentation/troubleshooting.md | 46 ++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/Documentation/troubleshooting.md b/Documentation/troubleshooting.md
index 952b9a5ed..218d7901b 100644
--- a/Documentation/troubleshooting.md
+++ b/Documentation/troubleshooting.md
@@ -81,3 +81,49 @@ sed -e "s/- --address=127.0.0.1/- --address=0.0.0.0/" -i /etc/kubernetes/manifes
 sed -e "s/- --address=127.0.0.1/- --address=0.0.0.0/" -i /etc/kubernetes/manifests/kube-scheduler.yaml
 ```
 
+### Using textual port number instead of port name
+
+The ServiceMonitor expects to use the port name as defined on the Service. So, using the Service example from the
+diagram above, we have this Service definition:
+
+```
+kind: Service
+metadata:
+  labels:
+    k8s-app: my-app
+  name: my-app
+...
+  spec:
+    ports:
+      - name: metrics
+        port: 8080
+    selector:
+      k8s-app: my-app
+```
+
+We would then define the service monitor using `metrics` as the port not `"8080"`. E.g.
+
+**CORRECT**
+```
+kind: ServiceMonitor
+metadata:
+  name: my-app
+spec:
+...
+  endpoints:
+    - port: metrics
+```
+
+**INCORRECT**
+```
+kind: ServiceMonitor
+metadata:
+  name: my-app
+spec:
+...
+  endpoints:
+    - port: "8080"
+```
+
+The incorrect example will give an error along these lines `spec.endpoints.port in body must be of type string:
+"integer"`