Skip to content

docs(k8s-proxy): add Kubernetes Proxy REST API and DaemonSet recording mode #838

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
khareyash05 merged 7 commits into from
Apr 27, 2026
Merged

docs(k8s-proxy): add Kubernetes Proxy REST API and DaemonSet recording mode #838

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
d780b16
docs(k8s-proxy): add Kubernetes Proxy REST API guide
officialasishkumar Apr 27, 2026
dd877be
docs(k8s-proxy): add Sidecar/DaemonSet mode intro, drop self-hosted-o…
khareyash05 Apr 27, 2026
679bfe7
docs(k8s-proxy quickstart): document DaemonSet recording mode
khareyash05 Apr 27, 2026
3eabfee
docs(k8s-proxy): satisfy Vale + Prettier on DaemonSet additions
khareyash05 Apr 27, 2026
7024a2f
docs(vale): disable Google.Units to allow "k8s" tokens
khareyash05 Apr 27, 2026
488bde7
docs(k8s-proxy): correct shared-token provisioning, drop public-API line
khareyash05 Apr 27, 2026
a9caf10
docs(k8s-proxy): vale fixes on the token-provisioning rewrite
khareyash05 Apr 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .vale.ini
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ Google.Will = NO # Allow "will" usage
Google.Exclamation = NO # Allow exclamation points
Google.Ellipses = NO # Allow ellipses in text
Google.Latin = NO # Allow "e.g." and "i.e." instead of "for example"
Google.Units = NO # Allow "k8s" — Google.Units' \d+s regex matches "8s" inside the token

# Allow specific terms:
Vale.Terms=NO
Expand Down
19 changes: 19 additions & 0 deletions vale_styles/config/vocabularies/Base/accept.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,10 +106,29 @@ shipping_address_id
[Ll]inux
[Ee]nv
[Kk]8s
IPs
[Dd]edup
[Dd]edups
[Rr]ollout[s]?
[Pp]refill[s]?
[Aa]uditable
[Cc]ooldown
[Ll]iveness
[Cc]ron
[Tt]oolchain
[Rr]untime[s]?
MongoIDs
initialised
normalisation
behaviour
polyglot
[Dd]aemon[Ss]et[s]?
[Cc]RD[s]?
eBPF
[Mm]utatingAdmissionWebhook
RecordingSession[s]?
ReplaySession[s]?
keploy-daemonset
keploy-agent
recordingsessions
replaysessions
46 changes: 46 additions & 0 deletions versioned_docs/version-3.0.0/quickstart/k8s-proxy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,6 +135,20 @@ At this point, your e-commerce application is live and ready to receive traffic.

## Enable Live Record & Replay with Keploy Proxy

### Pick a recording mode

The Keploy Proxy supports two ways to capture traffic from your application Pods. Both modes drive the **same Console UI and REST API**—the rest of this guide works identically in either case. Pick whichever fits your environment.

| | **Sidecar mode (default)** | **DaemonSet mode** |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| How traffic is captured | A `keploy-agent` sidecar container is injected into your application Pod via a `MutatingAdmissionWebhook`. The agent intercepts traffic alongside your container. | A `keploy-daemonset` Pod runs on each node and captures traffic from existing application Pods using **eBPF**—no sidecar, no application Pod restart. |
| What happens on `Start Recording` | The proxy injects the agent and rolls the application Deployment. | The proxy creates a `RecordingSession` Custom Resource. The DaemonSet picks it up and programs its BPF target maps to capture matching Pods on each node. |
| Pod mutation on the application namespace | Required (`patch` on Deployments). | **Not required.** Application Pods are never modified. |
| Application restart at recording start | Yes, on first recording. | No. |
| Best for | Dev/staging, teams happy to grant write RBAC to Keploy on the application namespace. | Production with read-only RBAC on the application namespace; environments where rolling the application Pod has unacceptable cost; or when you want cluster-mode auto-replay (replay runs in a separate cluster you provide). |

The screenshots below show the **Sidecar** flow because that is the default. To use **DaemonSet** mode instead, set the daemonset values when you run the Helm command in step 4 below—every other step is identical.

### 1. Open Keploy Dashboard

Visit:
Expand Down Expand Up @@ -175,6 +189,38 @@ Once you have provided the cluster details, you can install the Keploy Proxy in

<img src="https://keploy-devrel.s3.us-west-2.amazonaws.com/k8s-proxy/k8s_helm_command.png" alt="Sample Keploy K8s proxy" width="100%" style={{ borderRadius: '5px' }}/>

#### DaemonSet mode (optional)

If you want to use **DaemonSet mode** instead of the default Sidecar mode, append the daemonset values to the Helm command shown in the dashboard. The Helm chart installs the `recordingsessions.keploy.io` and `replaysessions.keploy.io` Custom Resource Definitions, and the per-node DaemonSet that performs the eBPF capture.

```bash
# add these flags to the Helm command from the dashboard:
--set daemonset.enabled=true \
--set daemonset.crds.install=true
```

After install you should see a per-node `k8s-proxy-daemonset-*` Pod alongside the regular proxy Deployment:

```bash
kubectl get pods -n keploy
# NAME READY STATUS RESTARTS AGE
# k8s-proxy-xxxxxxxxxx-xxxxx 1/1 Running 0 1m
# k8s-proxy-daemonset-xxxxx 1/1 Running 0 1m ← per node
# k8s-proxy-daemonset-yyyyy 1/1 Running 0 1m
# k8s-proxy-mongodb-xxxxxxxxxx-xxxxx 1/1 Running 0 1m
# k8s-proxy-minio-xxxxxxxxxx-xxxxx 1/1 Running 0 1m
```

Verify the CRDs registered:

```bash
kubectl get crd | grep keploy.io
# recordingsessions.keploy.io <date>
# replaysessions.keploy.io <date>
```

The rest of this quickstart proceeds identically—the Console **Start Recording** button creates a `RecordingSession` CR which the DaemonSet picks up; you do not need to interact with the CR yourself.

### 5. Verify the Installation

Paste the Helm command into the terminal. Once the installation is complete, verify that the Keploy Proxy is running.
Expand Down
46 changes: 46 additions & 0 deletions versioned_docs/version-4.0.0/quickstart/k8s-proxy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,6 +135,20 @@ At this point, your e-commerce application is live and ready to receive traffic.

## Enable Live Record & Replay with Keploy Proxy

### Pick a recording mode

The Keploy Proxy supports two ways to capture traffic from your application Pods. Both modes drive the **same Console UI and REST API**—the rest of this guide works identically in either case. Pick whichever fits your environment.

| | **Sidecar mode (default)** | **DaemonSet mode** |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| How traffic is captured | A `keploy-agent` sidecar container is injected into your application Pod via a `MutatingAdmissionWebhook`. The agent intercepts traffic alongside your container. | A `keploy-daemonset` Pod runs on each node and captures traffic from existing application Pods using **eBPF**—no sidecar, no application Pod restart. |
| What happens on `Start Recording` | The proxy injects the agent and rolls the application Deployment. | The proxy creates a `RecordingSession` Custom Resource. The DaemonSet picks it up and programs its BPF target maps to capture matching Pods on each node. |
| Pod mutation on the application namespace | Required (`patch` on Deployments). | **Not required.** Application Pods are never modified. |
| Application restart at recording start | Yes, on first recording. | No. |
| Best for | Dev/staging, teams happy to grant write RBAC to Keploy on the application namespace. | Production with read-only RBAC on the application namespace; environments where rolling the application Pod has unacceptable cost; or when you want cluster-mode auto-replay (replay runs in a separate cluster you provide). |

The screenshots below show the **Sidecar** flow because that is the default. To use **DaemonSet** mode instead, set the daemonset values when you run the Helm command in step 4 below—every other step is identical.

### 1. Open Keploy Dashboard

Visit:
Expand Down Expand Up @@ -175,6 +189,38 @@ Once you have provided the cluster details, you can install the Keploy Proxy in

<img src="https://keploy-devrel.s3.us-west-2.amazonaws.com/k8s-proxy/k8s_helm_command.png" alt="Sample Keploy K8s proxy" width="100%" style={{ borderRadius: '5px' }}/>

#### DaemonSet mode (optional)

If you want to use **DaemonSet mode** instead of the default Sidecar mode, append the daemonset values to the Helm command shown in the dashboard. The Helm chart installs the `recordingsessions.keploy.io` and `replaysessions.keploy.io` Custom Resource Definitions, and the per-node DaemonSet that performs the eBPF capture.

```bash
# add these flags to the Helm command from the dashboard:
--set daemonset.enabled=true \
--set daemonset.crds.install=true
```

After install you should see a per-node `k8s-proxy-daemonset-*` Pod alongside the regular proxy Deployment:

```bash
kubectl get pods -n keploy
# NAME READY STATUS RESTARTS AGE
# k8s-proxy-xxxxxxxxxx-xxxxx 1/1 Running 0 1m
# k8s-proxy-daemonset-xxxxx 1/1 Running 0 1m ← per node
# k8s-proxy-daemonset-yyyyy 1/1 Running 0 1m
# k8s-proxy-mongodb-xxxxxxxxxx-xxxxx 1/1 Running 0 1m
# k8s-proxy-minio-xxxxxxxxxx-xxxxx 1/1 Running 0 1m
```

Verify the CRDs registered:

```bash
kubectl get crd | grep keploy.io
# recordingsessions.keploy.io <date>
# replaysessions.keploy.io <date>
```

The rest of this quickstart proceeds identically—the Console **Start Recording** button creates a `RecordingSession` CR which the DaemonSet picks up; you do not need to interact with the CR yourself.

### 5. Verify the Installation

Paste the Helm command into the terminal. Once the installation is complete, verify that the Keploy Proxy is running.
Expand Down
Loading
Loading