[v12] docs: Add advisory and troubleshooting on non-tls mode for machineid kube

docs/pages/includes/machine-id/kubernetes-machineidnote.mdx

@@ -0,0 +1,30 @@
+<Admonition type="note"
+  title="Kubernetes Public Address Required for non-TLS Routing"
+  scope={["oss", "enterprise"]} scopeOnly
+>
+For self-hosted Teleport Clusters that have non-TLS routing the Kubernetes public
+address must be set for Machine ID Kubernetes connections.
+
+To confirm the TLS routing mode check the `proxy.tls_routing_enabled` from this
+command with your proxy address:
+
+```code
+$ curl https://teleport.example.com:443/webapi/ping | jq
+```
+
+The optional tool [`jq`](https://stedolan.github.io/jq/) is used here to help display the JSON output.
+If the value `proxy.tls_routing_enabled` is `false` then non-TLS routing
+is set and a Kubernetes public address is required so Machine ID
+will connect to the right port. You can confirm the Kubernetes public
+address is set if `proxy.kube.public_addr` is populated.
+
+The `kube_public_addr` is set within the `proxy_service` by Teleport administrators:
+
+```yaml
+proxy_service:
+  enabled: true
+  kube_listen_addr: 0.0.0.0:3026
+  kube_public_addr: teleport.example.com:3026
+```
+
+</Admonition>

docs/pages/machine-id/guides/github-actions-kubernetes.mdx

@@ -38,7 +38,9 @@ In our examples, this Kubernetes cluster will be named `my-kubernetes-cluster`.
 `gravitational/example`, and this value should be replaced with your own unique
 repository.
 
-### 1/4. Create a join token for GitHub Actions
+(!docs/pages/includes/machine-id/kubernetes-machineidnote.mdx!)
+
+## Step 1/4. Create a join token for GitHub Actions
 
 (!docs/pages/includes/machine-id/github-actions-create-token.mdx!)
 

docs/pages/machine-id/guides/kubernetes.mdx

@@ -22,6 +22,8 @@ You will need a running Teleport cluster version 10.1.0 or later.
 If you have not already connected your Kubernetes cluster to Teleport, follow
 the [Kubernetes Access Getting Started Guide](../../kubernetes-access/getting-started.mdx).
 
+(!docs/pages/includes/machine-id/kubernetes-machineidnote.mdx!)
+
 If you're not already familiar with Machine ID, follow the
 [Getting Started Guide](../getting-started.mdx) to familiarize yourself with
 Machine ID. You'll also need `tctl` access to initially configure the bot.

docs/pages/machine-id/troubleshooting.mdx

@@ -292,3 +292,51 @@ flag:
 $ tctl bots rm example
 $ tctl bots add example --roles=foo,bar,machine-id-db
 ```
+
+## Kubernetes connections are failing with `Unable to connect to the server: x509: certificate signed by unknown authority`
+
+### Symptoms
+
+A self-hosted Teleport cluster is connecting Machine ID to Kubernetes clusters
+with the following errors. This can happen for non-TLS configured Teleport clusters.
+
+```bash
+E0322 22:53:31.653051    1699 memcache.go:265] couldn't get current server API group list: Get "https://teleport.example.com:443/api?timeout=32s": x509: certificate signed by unknown authority
+```
+
+To confirm the TLS routing mode check the value of the `proxy.tls_routing_enabled`
+key with this command, substituting your proxy address:
+
+```bash
+curl https://teleport.example.com:443/webapi/ping | jq
+```
+
+If the value is `false` then this is a non-TLS routing configuration.
+
+### Explanation
+
+Proxies configured with non-TLS routing use specific ports for various types
+of traffic. That requires that a Kubernetes
+connection use its designated port. Currently Machine ID requires that the Kubernetes
+public address is set to use the correct port. Otherwise it will use the Proxy web port
+which can cause these type of errors.
+
+### Resolution
+
+The Kubernetes public address is via the `kube_public_addr` within the 
+Teleport `proxy_service` configuration by administrators. The proxy will
+require a restart after the configuration is updated.
+
+  ```yaml
+  proxy_service:
+    enabled: true
+    kube_listen_addr: 0.0.0.0:3026
+    kube_public_addr: teleport.example.com:3026
+  ```
+
+Retrieve the configuration listing from the proxy web address to confirm the
+Kubernetes public address is populated in `proxy.kube.public_addr`.
+
+```bash
+curl https://teleport.example.com:443/webapi/ping | jq
+```