feat: Add docs on exposing the kubernetes-api with the ngrok-operator#2078
feat: Add docs on exposing the kubernetes-api with the ngrok-operator#2078
Conversation
Signed-off-by: Jonathan Stacks <jonstacks@users.noreply.github.com>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| description: Learn how to expose the Kubernetes API server externally using the ngrok Kubernetes Operator, covering each Kubernetes authentication strategy and how to update your kubeconfig. | ||
| --- | ||
|
|
||
| Exposing the Kubernetes API server through ngrok lets you reach your cluster's control plane from anywhere — no VPN, no bastion host, no firewall rules required. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[StyleRules.EmDash] Don't put a space before or after a dash.
| - The [ngrok Kubernetes Operator installed](/k8s/installation) in your cluster | ||
| - `kubectl` configured with access to the cluster you want to expose | ||
|
|
||
| ## Kubernetes Authentication Strategies |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[StyleRules.Headings] 'Kubernetes Authentication Strategies' should use sentence-style capitalization.
| | Authentication Strategy | kubeconfig Indicator | ngrok Compatible? | Required Endpoint Type | | ||
| |---|---|---|---| | ||
| | Bearer Token (Service Account, Static) | `token` or `tokenFile` field | ✅ Yes | HTTPS | | ||
| | OIDC Token (via `exec` plugin) | `exec` block (e.g. `kubelogin`) | ✅ Yes | HTTPS | |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[StyleRules.Latin] Use 'for example' instead of 'e.g.'.
| |---|---|---|---| | ||
| | Bearer Token (Service Account, Static) | `token` or `tokenFile` field | ✅ Yes | HTTPS | | ||
| | OIDC Token (via `exec` plugin) | `exec` block (e.g. `kubelogin`) | ✅ Yes | HTTPS | | ||
| | Cloud Provider Token (EKS, GKE, AKS) | `exec` block (e.g. `aws`, `gke-gcloud-auth-plugin`) | ✅ Yes | HTTPS | |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[StyleRules.Latin] Use 'for example' instead of 'e.g.'.
|
|
||
| **HTTPS endpoints** terminate TLS at the ngrok edge. The `Authorization: Bearer <token>` header passes through transparently to the Kubernetes API server, so any token-based strategy works. | ||
|
|
||
| **TLS endpoints** pass the raw TLS stream through to the upstream without ngrok terminating it. This means the full TLS handshake — including the client certificate — travels end-to-end from `kubectl` to the Kubernetes API server. This is required for X.509 client certificate authentication. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[StyleRules.EmDash] Don't put a space before or after a dash.
|
|
||
| If you use HTTPS with client certificate auth, ngrok will terminate TLS before the client cert reaches the API server and authentication will fail. | ||
|
|
||
| ## Identifying Your Authentication Strategy |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[StyleRules.Headings] 'Identifying Your Authentication Strategy' should use sentence-style capitalization.
|
|
||
| → Use the **[TLS passthrough setup](#scenario-2-x509-client-certificate-or-exec-plugin-producing-a-certificate-tls-passthrough)**. | ||
|
|
||
| ## Scenario 1: Bearer Token or Exec Plugin Producing a Token (HTTPS) |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[StyleRules.Headings] 'Scenario 1: Bearer Token or Exec Plugin Producing a Token (HTTPS)' should use sentence-style capitalization.
|
|
||
|
|
||
|
|
||
| ## Scenario 2: X.509 Client Certificate or Exec Plugin Producing a Certificate (TLS Passthrough) |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[StyleRules.Headings] 'Scenario 2: X.509 Client Certificate or Exec Plugin Producing a Certificate (TLS Passthrough)' should use sentence-style capitalization.
| certificate-authority-data: <your-existing-cluster-ca-base64> # Keep as-is | ||
| ``` | ||
|
|
||
| The `user` section (with `client-certificate-data` and `client-key-data`) stays unchanged — these are passed through to the API server via the TLS handshake. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[StyleRules.EmDash] Don't put a space before or after a dash.
|
|
||
| ### Kubernetes RBAC remains your primary authorization layer | ||
|
|
||
| ngrok handles transport security — the existing Kubernetes RBAC rules still control what any authenticated user can do. Ensure that service accounts and user accounts exposed through the ngrok endpoint follow the principle of least privilege. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[StyleRules.EmDash] Don't put a space before or after a dash.
sg-writer
added
area/k8s
kind/net-new
2 participants
Adds documentation on how to expose the Kubernetes API using the ngrok-operator