docs(k8s-proxy): document connecting a cluster over the egress tunnel - #902
Open
manasmanohar wants to merge 2 commits into
Open
docs(k8s-proxy): document connecting a cluster over the egress tunnel#902manasmanohar wants to merge 2 commits into
manasmanohar wants to merge 2 commits into
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Adds and integrates documentation for connecting a Kubernetes cluster to Keploy via an outbound “Keploy tunnel” (egress-only) path, and updates the existing K8s Proxy quickstart to reflect the tunnel as the default connectivity option.
Changes:
- Add a new quickstart page describing egress-only tunnel connectivity, including decision guidance, Helm values, network requirements, migration, and troubleshooting.
- Update the existing
k8s-proxyquickstart to lead with tunnel-based onboarding and re-scope ingress/port-forward instructions to ingress-only usage. - Add the new page to the v4.0.0 sidebar under K8s Proxy.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| versioned_sidebars/version-4.0.0-sidebars.json | Adds the new egress-only quickstart page to the K8s Proxy sidebar section. |
| versioned_docs/version-4.0.0/quickstart/k8s-proxy.md | Reworks cluster-connection and port-forward guidance to match the tunnel-default onboarding flow. |
| versioned_docs/version-4.0.0/quickstart/k8s-proxy-egress-only.md | New detailed guide for connecting clusters over the outbound tunnel (no ingress). |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+41
to
+44
| This page covers the tunnel: when to pick it, what it does and does not carry, | ||
| and how to install a cluster that uses it. If you already have a public route to | ||
| the proxy, see [K8s Record Replay](./k8s-proxy.md), which uses the ingress path | ||
| throughout. |
Comment on lines
+154
to
+158
| cluster. The **Helm Command** button on the cluster's own page rebuilds the | ||
| command from the agent's last heartbeat, so on a cluster that has never | ||
| connected it cannot yet know the install was egress-only and leaves | ||
| `keploy.tunnel.enabled` out. `helm upgrade` does not merge previous values, so | ||
| running that command would install an agent with no route in either direction. |
Comment on lines
+228
to
+232
| - **If you front the tunnel with your own hostname** (`keploy.tunnel.url`), that | ||
| edge must forward the `Connection` and `Upgrade` headers verbatim and allow | ||
| long-idle connections — for `nginx`, `proxy_read_timeout 3600`. The connection is | ||
| kept alive by HTTP/2 pings every 20 seconds, but a single request can | ||
| legitimately block for minutes before its first byte. |
Comment on lines
+230
to
+234
| <!-- TODO(screenshot): the previous cluster_config.png predates the connectivity | ||
| dropdown — it shows a mandatory Cluster Name and an Ingress URL field, which | ||
| now contradicts the text above. Removed rather than left stale. Replace with | ||
| the capture at docs-screenshots/staging/01-connect-cluster-tunnel-default.png | ||
| once it is uploaded to the keploy-devrel S3 bucket. --> |
Comment on lines
+113
to
+116
| <!-- TODO(screenshot): captured from a local rig, pending upload to the | ||
| keploy-devrel S3 bucket then swap this comment for an <img> tag. | ||
| Source: ~/workspace/kd-testing/docs-screenshots/01b-dialog-only.png | ||
| (Connect New Cluster dialog, tunnel selected by default, no Ingress URL field). --> |
Customers can now connect a Kubernetes cluster to Keploy without opening any inbound route: the proxy dials out and the dashboard reaches it back down that connection. The Connect Cluster screen asks the question directly with a new "How should Keploy reach this cluster?" dropdown, defaulting to the tunnel. Adds quickstart/k8s-proxy-egress-only.md covering when to pick the tunnel, the keploy.tunnel.* Helm values, network requirements, what the tunnel does and does not carry, the two combinations the chart refuses, migration and troubleshooting. Reworks step 3 of the k8s-proxy quickstart, which told readers to fill in a mandatory Ingress URL field that no longer appears by default. It now leads with the tunnel and keeps ingress as a sub-section naming the case where it is required (self-hosted). Step 5's port-forward is marked ingress-only, since the tunnel path does not need it, and the HowTo schema is updated to match. Cluster Name is now optional, so the quickstart says so. Behaviour verified against the released build on staging rather than read from source: the dropdown defaults to the tunnel, the Ingress URL field appears only on the other option, self-hosted forces ingress and disables the dropdown, the generated Helm command carries --set keploy.tunnel.enabled=true alongside a blank keploy.ingressUrl, and the API Docs button is disabled on an egress-only cluster with a tooltip explaining why. Two screenshots are pending upload to the keploy-devrel bucket and are marked with TODO comments. The previous cluster_config.png is removed rather than left in place: it predates the dropdown and now contradicts the text above it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: Manas Manohar <21006907+manasmanohar@users.noreply.github.com>
Captured from the released build on staging, committed to static/img rather than the keploy-devrel bucket — both conventions are in use here and the k8s-proxy pages already carry local images. Referenced with markdown image syntax, not a raw <img> tag: baseUrl is "/docs/" and only the markdown path gets rewritten through it, so JSX with an absolute src resolves against the site root and 404s. The quickstart regains an image where the stale cluster_config.png was removed, and gains one for the ingress alternative. The egress page gets the dialog and the no-route troubleshooting state. Still outstanding: the connected-cluster shot on the egress page. The only capture available is from a local rig with localhost URLs on the Agent URL card, which would be misleading here. It needs a re-shoot once the tunnel is reachable on staging (keploy/k8s-env#211). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: Manas Manohar <21006907+manasmanohar@users.noreply.github.com>
manasmanohar
force-pushed
the
docs/k8s-proxy-egress-only-onboarding
branch
from
September 1, 2026 05:59
b31d58a to
2310ba3
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Customers can now connect a Kubernetes cluster to Keploy without opening any inbound route — the proxy dials out and the dashboard reaches it back down that connection. The Connect Cluster screen asks the question directly with a new "How should Keploy reach this cluster?" dropdown, which defaults to the tunnel.
Documents the feature shipped by:
keploy.tunnel.*Helm values (released in chart/image3.7.30)v1.8.17)Changes
New page —
quickstart/k8s-proxy-egress-only.md, "Connect a cluster without an ingress": why the tunnel exists, a decision table against ingress, step-by-step onboarding, thekeploy.tunnel.*values reference, network requirements, what the tunnel does and does not carry, the two combinations the chart refuses, migration, and troubleshooting for the three new error states.Reworked step 3 of
quickstart/k8s-proxy.md. It told readers to fill in a mandatory Ingress URL field that no longer appears by default, so a reader following it hit a dropdown already set to "Keploy tunnel" and was told to change it. It now leads with the tunnel — matching both the UI default and the chart README, which marks the tunnel "Keploy Cloud. Start here." — and keeps ingress as a sub-section naming the one case where it is required (Self-hosted). Step 5's port-forward is marked ingress-only, since the tunnel path does not need it. Cluster Name is now documented as optional. The<HowTo>structured-data block is updated to match.Sidebar: the new page sits under K8s Proxy, after the quickstart.
Verification
Every product claim was checked against the released build on staging, not read from source:
disabled: true)--set keploy.tunnel.enabled=truealongside a blank--set keploy.ingressUrl=""Docs tooling:
prettier@2.8.8 --check,vale(0 errors) and an MDX compile all pass on both changed pages; both render locally with no broken links.Reviewer notes
Screenshots are pending. Two
TODO(screenshot)markers remain — captures exist but need uploading to thekeploy-devrelS3 bucket first. The oldcluster_config.pngis removed rather than left in place: it predates the dropdown, showing a mandatory Cluster Name and an Ingress URL being typed in, which now contradicts the text above it. A stale screenshot seemed worse than a temporary gap, but happy to restore it if you disagree.One product gap found while testing, not fixed here. The Helm Command button on a cluster page omits
--set keploy.tunnel.enabled=truewhen that cluster has never connected —isEgressOnlyInstallreturnsfalsefor a missing heartbeat (services/proxyBaseUrl.ts:187), which is deliberate, but sincehelm upgradedoes not merge previous values, copying that command installs an agent with no route in either direction. The page warns readers to copy from the provisioning dialog instead. Probably worth a UI fix too.Rollout dependency — one env var, not a release. api-server
v1.8.17is deployed to both prod and staging: each servesAccess-Control-Expose-Headers: … X-Keploy-Tunnel-Error, X-Keploy-Tunnel-Not-Allowlisted, a list that matches released commit9ccfe36exactly.But the tunnel entry is still unreachable, so no customer can complete this flow yet:
GET /tunnel/v1/connect(Upgrade: keploy-tunnel+ bearer)tunnel.*.keploy.ioTLSSAN: ingress.local)keploy/k8s-proxy:3.7.30,KEPLOY_TUNNEL_ENABLED=trueA 404 rather than a 401 means the route does not exist, and the nginx fallback certificate means no Ingress rule matches that hostname. Consistent with the acceptor sitting behind
KEPLOY_TUNNEL_LISTEN_ADDR, which is empty by default and binds no port until set, on its own listener and ServeMux rather than the chi root router.So two deploy-side actions remain, neither a code change:
KEPLOY_TUNNEL_LISTEN_ADDRon the api-server deployment;api.*/tunnel/v1/connect, or thetunnel.*host with a real certificate.Since the tunnel is now the default path in the quickstart, worth confirming both before this merges.
🤖 Generated with Claude Code