docs(k8s-proxy): add DaemonSet architecture + auto-replay environments guide#842
Merged
khareyash05 merged 5 commits intomainfrom Apr 27, 2026
Merged
Conversation
…s guide A single behind-the-scenes doc for the Kubernetes Proxy's two recording modes and three auto-replay environments. Reads as one continuous narrative — Part 1 walks DaemonSet recording (the three components, CR lifecycle, eBPF target maps with the TGID + cgroup-id dual-targeting) and Part 2 covers each replay environment (`crd` / `runner` / `cluster`) with diagrams, RBAC requirements, env config, and a "when to use it" note. Lands at versioned_docs/version-4.0.0/running-keploy/ k8s-proxy-daemonset-architecture.md and is wired into the v4 sidebar under "API Reference" alongside the existing k8s-proxy-api guide. Vale vocab additions cover the new technical terms (TGID, kubelet, GitOps, ConfigMap, NetworkPolicy, SPDY, mTLS, randAlphaNum, etc.) so Vale.Spelling doesn't flag them on the Vale + reviewdog run. Signed-off-by: Yash Khare <khareyash05@gmail.com>
Vale flagged a handful of technical terms still missing from the vocabulary on PR #842 plus one en-dash that snuck in: - Add cgroup, userspace, teardown, replayer, rehydrate(d|s), reachability, walkthrough, dev, CRs, subresource(s) to the Base vocab. - Replace en-dash "1–2" with "1 or 2" in the cluster-mode sizing note (Google.EnDash wants em-dash; "1 or 2" reads better here anyway since it's a discrete count). Signed-off-by: Yash Khare <khareyash05@gmail.com>
The K8s Proxy quickstart had been buried under Integration Testing > QuickStarts > Python (it is not Python-specific — the proxy is language-agnostic), and the new daemonset-architecture page sat in "API Reference" alongside REST API guides. Two reorganizations: - Drop "quickstart/k8s-proxy" from the Python QuickStarts list. It never belonged there — the page demonstrates a Python e-commerce sample only because that's the example app, not because the proxy itself is Python-tied. - Add a new top-level "K8s Proxy" category inside Integration Testing, placed right after QuickStarts. It contains both the quickstart and the daemonset-architecture page so all K8s Proxy material is one click away. - Remove the daemonset-architecture entry from API Reference now that it lives under the new K8s Proxy category. The REST API guide (k8s-proxy-api) stays in API Reference where it fits the surface alongside public-api. Signed-off-by: Yash Khare <khareyash05@gmail.com>
…re page
The page listed three auto-replay environments (`crd`, `runner`,
`cluster`); the `crd` mode is the legacy in-cluster path that
mutates the source cluster and is being phased out. Remove it from
the explanation:
- Drop the dedicated "Mode A — `crd` (legacy in-cluster)" section.
- Update the comparison table at the top of Part 2 to two modes
instead of three.
- Renumber Mode C → Mode B for cluster mode.
- Replace `crd` references in the dispatch overview, the
"what stays the same" line, the graceful-fallback note, and the
closing combination matrix.
- Adjust the intro sentence ("two recording modes and two
independent auto-replay environments").
Also drop the closing "For the dev loop on kind, see the local-
testing notes in the Keploy enterprise repo" line — that note
points at internal documentation customers don't have access to.
Signed-off-by: Yash Khare <khareyash05@gmail.com>
Cut "Lifecycle of a recording session" and "Targeting in eBPF: TGIDs and cgroup IDs" from the DaemonSet architecture page. Both went deeper into Keploy internals (handler call paths, BPF map names, refcount semantics) than a customer-facing architecture page should — the "Three components" + "What you don't get without the DaemonSet" sections are sufficient for the reader to understand the shape of DaemonSet mode without exposing implementation detail that will move. Signed-off-by: Yash Khare <khareyash05@gmail.com>
officialasishkumar
approved these changes
Apr 27, 2026
6 tasks
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
2 participants
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.
Summary
Adds a single behind-the-scenes doc covering the K8s Proxy's two recording modes and three auto-replay environments — read as one continuous narrative:
Part 1 — DaemonSet recording architecture
/record/startto/record/stopPart 2 — Auto-replay environments
crdmode (legacy in-cluster)runnermode (Docker daemon, with the keploy-replay-runner binary)clustermode (separate replay cluster reached via mounted kubeconfig — the recommended production default)Each environment includes a flow diagram, RBAC requirements, env config, and a "when to use it" note. Closes the gap where the K8s Proxy REST API guide referenced these concepts without ever explaining them.
Lands at
versioned_docs/version-4.0.0/running-keploy/k8s-proxy-daemonset-architecture.mdand is wired into the v4 sidebar's "API Reference" section.Test plan
/docs/quickstart/k8s-proxy/,/docs/running-keploy/k8s-proxy-api/) resolve🤖 Generated with Claude Code