From bd80b17a681411a71a6bc065290b2cf3dc564da7 Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Wed, 1 Apr 2026 16:56:01 +0530 Subject: [PATCH 01/30] docs: add Installation dropdown and GitOps section to sidebar Group Installation, Enterprise Installation, and Kubernetes under a collapsible Installation category. Add GitOps Deployment subcategory under Kubernetes with ArgoCD and Flux placeholders. Signed-off-by: Asish Kumar --- .../version-4.0.0-sidebars.json | 34 ++++++++++++++++--- 1 file changed, 30 insertions(+), 4 deletions(-) diff --git a/versioned_sidebars/version-4.0.0-sidebars.json b/versioned_sidebars/version-4.0.0-sidebars.json index 2d72761c8..7e61c1a33 100644 --- a/versioned_sidebars/version-4.0.0-sidebars.json +++ b/versioned_sidebars/version-4.0.0-sidebars.json @@ -15,12 +15,38 @@ ] }, { - "type": "doc", + "type": "category", "label": "Installation", - "id": "server/installation" + "collapsible": true, + "collapsed": true, + "items": [ + { + "type": "doc", + "label": "Keploy OSS", + "id": "server/installation" + }, + "keploy-cloud/cloud-installation", + { + "type": "category", + "label": "Kubernetes", + "collapsible": true, + "collapsed": true, + "items": [ + "keploy-cloud/kubernetes-local-setup", + { + "type": "category", + "label": "GitOps Deployment", + "collapsible": true, + "collapsed": true, + "items": [ + "keploy-cloud/gitops-argocd", + "keploy-cloud/gitops-flux" + ] + } + ] + } + ] }, - "keploy-cloud/cloud-installation", - "keploy-cloud/kubernetes-local-setup", "running-keploy/cli-commands", "running-keploy/rename-testcases", "running-keploy/docker-tls", From afe6cd45c8b23f68f47b54c30327229933eafb54 Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Wed, 1 Apr 2026 16:57:04 +0530 Subject: [PATCH 02/30] docs: add ArgoCD GitOps deployment guide for Keploy k8s-proxy Covers Contour ingress with TLS passthrough, ArgoCD Application template, HTTPProxy setup, and step-by-step verification. Signed-off-by: Asish Kumar --- .../keploy-cloud/gitops-argocd.md | 322 ++++++++++++++++++ 1 file changed, 322 insertions(+) create mode 100644 versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md diff --git a/versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md b/versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md new file mode 100644 index 000000000..1c9abda96 --- /dev/null +++ b/versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md @@ -0,0 +1,322 @@ +--- +id: gitops-argocd +title: Deploy Keploy with ArgoCD +sidebar_label: ArgoCD +tags: + - explanation + - feature guide + - keploy enterprise + - kubernetes + - argocd + - gitops + - contour +keywords: + - keploy enterprise + - kubernetes + - argocd + - gitops + - helm + - contour + - ingress +--- + +import ProductTier from '@site/src/components/ProductTier'; + + + +This guide walks you through deploying **Keploy's k8s-proxy** using **ArgoCD** (GitOps) on a Kubernetes cluster, with **Contour** as the ingress controller. + +If you already use ArgoCD to manage your applications, adding Keploy requires **just two files** — an ArgoCD Application YAML and a Contour HTTPProxy YAML. No changes to your existing app code or manifests. + +> [!NOTE] +> This guide assumes you have already completed the [Kubernetes Local Setup](/docs/keploy-cloud/kubernetes-local-setup) and have a running Kind cluster with Keploy connected. + +--- + +## Prerequisites + +Ensure you have the following before you begin: + +1. **A running Kubernetes cluster** (Kind, EKS, GKE, AKS) +2. **ArgoCD** installed on the cluster +3. **kubectl** and **Helm** installed +4. **Keploy Enterprise account** (with an access key) + +--- + +## 1) Install ArgoCD + +> Skip this if ArgoCD is already installed on your cluster. + +```bash +kubectl create namespace argocd +kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml +kubectl -n argocd rollout status deployment/argocd-server +``` + +Get the admin password: + +```bash +kubectl -n argocd get secret argocd-initial-admin-secret \ + -o jsonpath="{.data.password}" | base64 -d; echo +``` + +Access the ArgoCD UI: + +```bash +kubectl -n argocd port-forward svc/argocd-server 8443:443 & +``` + +Open `https://localhost:8443` in your browser. Login with username `admin` and the password from above. + +--- + +## 2) Deploy Contour ingress controller + +Keploy's k8s-proxy serves **HTTPS natively** on its backend port. You need an ingress controller that supports **TLS passthrough** — forwarding the encrypted connection directly to the k8s-proxy without terminating it. + +[Contour](https://projectcontour.io/) is a CNCF ingress controller powered by Envoy that supports this via its **HTTPProxy** CRD. + +### 2.1 Install Contour + +```bash +kubectl apply -f https://projectcontour.io/quickstart/contour.yaml +``` + +Wait for it to be ready: + +```bash +kubectl -n projectcontour rollout status deployment/contour +kubectl -n projectcontour rollout status daemonset/envoy +``` + +### 2.2 Patch Envoy for Kind/VM clusters + +Kind only maps specific ports to the host. Since TLS passthrough uses Envoy's HTTPS listener (port 443), you need to assign it to the mapped NodePort: + +```bash +kubectl patch svc envoy -n projectcontour --type='json' -p='[ + {"op": "replace", "path": "/spec/type", "value": "NodePort"}, + {"op": "replace", "path": "/spec/ports/0/nodePort", "value": 30081}, + {"op": "replace", "path": "/spec/ports/1/nodePort", "value": 30080} +]' +``` + +This puts the **HTTPS listener on NodePort 30080** (mapped to the host) and the HTTP listener on 30081. + +> [!TIP] +> For cloud clusters (EKS/GKE/AKS), skip this patch. The default LoadBalancer type works — your cloud provider assigns an external IP automatically. + +### 2.3 Verify Contour + +```bash +kubectl get pods -n projectcontour +kubectl get svc -n projectcontour +``` + +Expected output: + +```text +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +envoy NodePort 10.96.65.35 80:30081/TCP,443:30080/TCP 2m +``` + +--- + +## 3) Create the Keploy access key secret + +> Skip if you already created this during the [Kubernetes Local Setup](/docs/keploy-cloud/kubernetes-local-setup). + +Go to the Keploy UI → **Clusters** → **Connect New Cluster**. Enter your cluster name and ingress URL (e.g. `https://your-host:30080`). Click **Connect** to get your access key. + +```bash +kubectl create namespace keploy + +kubectl -n keploy create secret generic keploy-credentials \ + --from-literal=access-key="" +``` + +> [!WARNING] +> Never commit access keys to Git. Use `existingSecret` in Helm values or a secrets manager (Sealed Secrets, Vault, External Secrets Operator). + +--- + +## 4) Create the ArgoCD Application for k8s-proxy + +Create a file named `keploy-k8s-proxy.yaml`: + +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: keploy-k8s-proxy + namespace: argocd + finalizers: + - resources-finalizer.argocd.argoproj.io +spec: + project: default + source: + chart: k8s-proxy-chart + repoURL: registry-1.docker.io/keploy + targetRevision: "3.3.10" + helm: + values: | + replicaCount: 1 + environment: "staging" + selfHosted: false + + keploy: + existingSecret: "keploy-credentials" + existingSecretKey: "access-key" + clusterName: "" + apiServerUrl: "https://api.keploy.io" + ingressUrl: "https://:30080" + + service: + type: ClusterIP + + mongodb: + enabled: false + minio: + enabled: false + destination: + server: https://kubernetes.default.svc + namespace: keploy + syncPolicy: + automated: + prune: true + selfHeal: true + syncOptions: + - CreateNamespace=true +``` + +Replace: +- `` — the name you entered in the Keploy UI +- `` — the hostname that resolves to your cluster (e.g. your VM IP or a DNS name) + +Apply it: + +```bash +kubectl apply -f keploy-k8s-proxy.yaml +``` + +--- + +## 5) Create the HTTPProxy for TLS passthrough + +The k8s-proxy serves HTTPS on its backend. A standard Kubernetes `Ingress` only supports HTTP backends, so you need Contour's **HTTPProxy** CRD with TLS passthrough. + +Create a file named `k8s-proxy-httpproxy.yaml`: + +```yaml +apiVersion: projectcontour.io/v1 +kind: HTTPProxy +metadata: + name: k8s-proxy-ingress + namespace: keploy +spec: + virtualhost: + fqdn: + tls: + passthrough: true + tcpproxy: + services: + - name: k8s-proxy + port: 8080 +``` + +Replace `` with the same hostname used in `keploy.ingressUrl`. + +Apply it: + +```bash +kubectl apply -f k8s-proxy-httpproxy.yaml +``` + +### How TLS passthrough works + +```text +Client (Keploy cloud) + │ + │ HTTPS (encrypted) + ▼ +Envoy (port 30080) ← reads SNI hostname, does NOT decrypt + │ + │ forwards encrypted bytes + ▼ +k8s-proxy (port 8080) ← terminates TLS itself +``` + +Envoy looks at the **SNI** (Server Name Indication) — the hostname in the TLS Client Hello — to decide where to route the connection. It then passes the encrypted bytes straight through to the k8s-proxy without inspecting them. This is why the `fqdn` in the HTTPProxy must match the hostname the client uses. + +> [!NOTE] +> SNI matching means you **must** access the k8s-proxy using the hostname (e.g. `https://your-host:30080`), not the raw IP address. Add an `/etc/hosts` entry if needed. + +--- + +## 6) Verify the deployment + +```bash +# Check ArgoCD sees the app +kubectl get applications -n argocd + +# Check HTTPProxy status +kubectl get httpproxy -A +# Should show status: valid + +# Check k8s-proxy is running +kubectl get pods -n keploy + +# Test connectivity through Contour +curl -sk https://:30080/healthz +# → {"status":"ok"} +``` + +✅ Open the Keploy UI → **Clusters** → your cluster should show as **Connected**. You can now record and replay traffic on any deployment. + +--- + +## 7) Deploy your application with ArgoCD + +Your application needs **no changes** for Keploy. Deploy it as you normally would with ArgoCD — either from Helm charts or raw K8s manifests: + +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: my-app + namespace: argocd +spec: + project: default + source: + repoURL: https://github.com/your-org/your-repo.git + targetRevision: main + path: k8s/ + destination: + server: https://kubernetes.default.svc + namespace: staging + syncPolicy: + automated: + prune: true + selfHeal: true + syncOptions: + - CreateNamespace=true +``` + +Once deployed, your application appears in the Keploy UI under your cluster's **Deployments** tab. Click **Record** to start capturing live traffic. + +--- + +## Summary + +To add Keploy to an existing ArgoCD setup, you need: + +| What | File | Purpose | +|------|------|---------| +| ArgoCD Application | `keploy-k8s-proxy.yaml` | Deploy k8s-proxy from Keploy's Helm chart | +| Contour HTTPProxy | `k8s-proxy-httpproxy.yaml` | Route HTTPS traffic via TLS passthrough | +| Kubernetes Secret | `kubectl create secret` (manual) | Access key for Keploy cloud authentication | + +Your existing application code, manifests, and ArgoCD Applications remain **completely untouched**. Keploy works alongside your app — not inside it. + +For a complete reference implementation, see the [keploy-argocd-demo](https://github.com/officialasishkumar/keploy-argocd-demo) repository. From adf7efa65eb4559f8fa4feaaf6f8cf3345a3c27c Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Wed, 1 Apr 2026 16:57:41 +0530 Subject: [PATCH 03/30] docs: add Flux CD GitOps deployment guide for Keploy k8s-proxy Covers Flux bootstrap, HelmRepository source, HelmRelease config, Contour HTTPProxy with TLS passthrough, and verification steps. Signed-off-by: Asish Kumar --- .../version-4.0.0/keploy-cloud/gitops-flux.md | 260 ++++++++++++++++++ 1 file changed, 260 insertions(+) create mode 100644 versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md diff --git a/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md b/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md new file mode 100644 index 000000000..946ad85b7 --- /dev/null +++ b/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md @@ -0,0 +1,260 @@ +--- +id: gitops-flux +title: Deploy Keploy with Flux CD +sidebar_label: Flux CD +tags: + - explanation + - feature guide + - keploy enterprise + - kubernetes + - flux + - gitops + - contour +keywords: + - keploy enterprise + - kubernetes + - flux + - gitops + - helm + - contour + - ingress +--- + +import ProductTier from '@site/src/components/ProductTier'; + + + +This guide walks you through deploying **Keploy's k8s-proxy** using **Flux CD** (GitOps) on a Kubernetes cluster, with **Contour** as the ingress controller. + +Flux watches your Git repository and automatically applies changes to the cluster. Adding Keploy requires a **HelmRelease** for the k8s-proxy and an **HTTPProxy** for Contour routing. + +> [!NOTE] +> This guide assumes you have already completed the [Kubernetes Local Setup](/docs/keploy-cloud/kubernetes-local-setup) and have a running Kind cluster with Keploy connected. For Contour setup details, see the [ArgoCD guide](/docs/keploy-cloud/gitops-argocd#2-deploy-contour-ingress-controller) — the Contour steps are identical. + +--- + +## Prerequisites + +Ensure you have the following before you begin: + +1. **A running Kubernetes cluster** (Kind, EKS, GKE, AKS) +2. **Flux CLI** installed ([installation guide](https://fluxcd.io/flux/installation/)) +3. **kubectl** and **Helm** installed +4. **A Git repository** (GitHub, GitLab, Bitbucket) for Flux to watch +5. **Keploy Enterprise account** (with an access key) +6. **Contour** deployed ([see step 2 in the ArgoCD guide](/docs/keploy-cloud/gitops-argocd#2-deploy-contour-ingress-controller)) + +--- + +## 1) Bootstrap Flux + +> Skip this if Flux is already installed on your cluster. + +Bootstrap Flux with your GitHub repository: + +```bash +flux bootstrap github \ + --owner= \ + --repository= \ + --branch=main \ + --path=clusters/staging \ + --personal +``` + +This installs Flux on your cluster and creates the `clusters/staging` directory in your Git repo where you'll add Keploy manifests. + +Verify Flux is running: + +```bash +flux check +``` + +--- + +## 2) Create the Keploy access key secret + +> Skip if you already created this during the [Kubernetes Local Setup](/docs/keploy-cloud/kubernetes-local-setup). + +Go to the Keploy UI → **Clusters** → **Connect New Cluster**. Enter your cluster name and ingress URL (e.g. `https://your-host:30080`). Click **Connect** to get your access key. + +```bash +kubectl create namespace keploy + +kubectl -n keploy create secret generic keploy-credentials \ + --from-literal=access-key="" +``` + +> [!WARNING] +> Never commit access keys to Git. For production, use [Flux SOPS](https://fluxcd.io/flux/guides/mozilla-sops/) or [Sealed Secrets](https://fluxcd.io/flux/guides/sealed-secrets/) to encrypt secrets in your repository. + +--- + +## 3) Add the Keploy Helm repository source + +Create `clusters/staging/keploy-source.yaml` in your Git repo: + +```yaml +apiVersion: source.toolkit.fluxcd.io/v1 +kind: HelmRepository +metadata: + name: keploy + namespace: flux-system +spec: + interval: 1h + type: oci + url: oci://docker.io/keploy +``` + +--- + +## 4) Create the HelmRelease for k8s-proxy + +Create `clusters/staging/keploy-k8s-proxy.yaml` in your Git repo: + +```yaml +apiVersion: helm.toolkit.fluxcd.io/v2 +kind: HelmRelease +metadata: + name: k8s-proxy + namespace: keploy +spec: + interval: 5m + chart: + spec: + chart: k8s-proxy-chart + version: "3.3.10" + sourceRef: + kind: HelmRepository + name: keploy + namespace: flux-system + install: + createNamespace: true + values: + replicaCount: 1 + environment: "staging" + selfHosted: false + + keploy: + existingSecret: "keploy-credentials" + existingSecretKey: "access-key" + clusterName: "" + apiServerUrl: "https://api.keploy.io" + ingressUrl: "https://:30080" + + service: + type: ClusterIP + + mongodb: + enabled: false + minio: + enabled: false +``` + +Replace: +- `` — the name you entered in the Keploy UI +- `` — the hostname that resolves to your cluster + +--- + +## 5) Create the HTTPProxy for TLS passthrough + +Create `clusters/staging/k8s-proxy-httpproxy.yaml` in your Git repo: + +```yaml +apiVersion: projectcontour.io/v1 +kind: HTTPProxy +metadata: + name: k8s-proxy-ingress + namespace: keploy +spec: + virtualhost: + fqdn: + tls: + passthrough: true + tcpproxy: + services: + - name: k8s-proxy + port: 8080 +``` + +Replace `` with the same hostname used in `keploy.ingressUrl`. + +> [!NOTE] +> TLS passthrough is required because the k8s-proxy serves HTTPS natively. Envoy forwards the encrypted connection directly to the k8s-proxy without terminating TLS. See the [ArgoCD guide](/docs/keploy-cloud/gitops-argocd#5-create-the-httpproxy-for-tls-passthrough) for a detailed explanation. + +--- + +## 6) Push and let Flux reconcile + +Commit and push all three files: + +```bash +git add clusters/staging/keploy-source.yaml \ + clusters/staging/keploy-k8s-proxy.yaml \ + clusters/staging/k8s-proxy-httpproxy.yaml +git commit -m "Add Keploy k8s-proxy deployment" +git push +``` + +Flux detects the changes and applies them automatically. Check the status: + +```bash +# Force immediate reconciliation (optional) +flux reconcile source git flux-system + +# Check HelmRelease status +flux get helmreleases -n keploy + +# Check HTTPProxy +kubectl get httpproxy -A +``` + +--- + +## 7) Verify the deployment + +```bash +# Check k8s-proxy is running +kubectl get pods -n keploy + +# Check HTTPProxy status (should show "valid") +kubectl get httpproxy -A + +# Test connectivity through Contour +curl -sk https://:30080/healthz +# → {"status":"ok"} +``` + +✅ Open the Keploy UI → **Clusters** → your cluster should show as **Connected**. You can now record and replay traffic on any deployment. + +--- + +## Git repository structure + +After adding Keploy, your Flux repo should look like: + +```text +clusters/ +└── staging/ + ├── keploy-source.yaml # OCI Helm repository for Keploy + ├── keploy-k8s-proxy.yaml # HelmRelease for k8s-proxy + ├── k8s-proxy-httpproxy.yaml # Contour HTTPProxy (TLS passthrough) + └── your-other-apps/ # Your existing Flux manifests +``` + +--- + +## Summary + +To add Keploy to an existing Flux setup, you need: + +| What | File | Purpose | +|------|------|---------| +| Helm source | `keploy-source.yaml` | OCI Helm repository for Keploy charts | +| HelmRelease | `keploy-k8s-proxy.yaml` | Deploy k8s-proxy from Keploy's Helm chart | +| Contour HTTPProxy | `k8s-proxy-httpproxy.yaml` | Route HTTPS traffic via TLS passthrough | +| Kubernetes Secret | `kubectl create secret` (manual) | Access key for Keploy cloud authentication | + +Your existing application manifests and Flux configurations remain **completely untouched**. Keploy works alongside your app — not inside it. + +For a reference implementation of the ArgoCD approach (the Contour and k8s-proxy config is identical), see the [keploy-argocd-demo](https://github.com/officialasishkumar/keploy-argocd-demo) repository. From 288e034e390f1067bd9ba3b9a695546d7a04690d Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Wed, 1 Apr 2026 17:05:48 +0530 Subject: [PATCH 04/30] fix: move Kubernetes to its own sidebar level, not nested under Installation Signed-off-by: Asish Kumar --- .../version-4.0.0-sidebars.json | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/versioned_sidebars/version-4.0.0-sidebars.json b/versioned_sidebars/version-4.0.0-sidebars.json index 7e61c1a33..e231ba848 100644 --- a/versioned_sidebars/version-4.0.0-sidebars.json +++ b/versioned_sidebars/version-4.0.0-sidebars.json @@ -25,24 +25,24 @@ "label": "Keploy OSS", "id": "server/installation" }, - "keploy-cloud/cloud-installation", + "keploy-cloud/cloud-installation" + ] + }, + { + "type": "category", + "label": "Kubernetes", + "collapsible": true, + "collapsed": true, + "items": [ + "keploy-cloud/kubernetes-local-setup", { "type": "category", - "label": "Kubernetes", + "label": "GitOps Deployment", "collapsible": true, "collapsed": true, "items": [ - "keploy-cloud/kubernetes-local-setup", - { - "type": "category", - "label": "GitOps Deployment", - "collapsible": true, - "collapsed": true, - "items": [ - "keploy-cloud/gitops-argocd", - "keploy-cloud/gitops-flux" - ] - } + "keploy-cloud/gitops-argocd", + "keploy-cloud/gitops-flux" ] } ] From 55d4451ba097b5f2c2b9b2e609fed3a2649a551d Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Wed, 1 Apr 2026 18:28:46 +0530 Subject: [PATCH 05/30] docs(flux): update demo repo reference to include Flux manifests - Updated the keploy-argocd-demo repo link description to mention the new flux/ directory with ready-to-use staging and production manifests. Signed-off-by: Asish Kumar Co-Authored-By: Claude Opus 4.6 Signed-off-by: Asish Kumar --- versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md b/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md index 946ad85b7..1d632bdea 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md @@ -257,4 +257,4 @@ To add Keploy to an existing Flux setup, you need: Your existing application manifests and Flux configurations remain **completely untouched**. Keploy works alongside your app — not inside it. -For a reference implementation of the ArgoCD approach (the Contour and k8s-proxy config is identical), see the [keploy-argocd-demo](https://github.com/officialasishkumar/keploy-argocd-demo) repository. +For a reference implementation with both ArgoCD and Flux CD manifests, see the [keploy-argocd-demo](https://github.com/officialasishkumar/keploy-argocd-demo) repository — the `flux/` directory contains ready-to-use HelmRepository, HelmRelease, and HTTPProxy manifests for staging and production. From c59f4ddd285323811872afa5ed15a5d4adb8f380 Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Wed, 1 Apr 2026 19:15:18 +0530 Subject: [PATCH 06/30] refactor(docs): consolidate Kubernetes guides into single Installation page - Merged kubernetes-local-setup, gitops-argocd, and gitops-flux into one combined kubernetes.md page under Installation. - Renamed "Keploy OSS" to "Local" and "Enterprise Installation" to "Enterprise" in the sidebar. - Removed separate Kubernetes sidebar category; it now lives as a single doc inside Installation alongside Local and Enterprise. Signed-off-by: Asish Kumar Co-Authored-By: Claude Opus 4.6 Signed-off-by: Asish Kumar --- .../version-4.0.0/keploy-cloud/kubernetes.md | 728 ++++++++++++++++++ .../version-4.0.0-sidebars.json | 28 +- 2 files changed, 737 insertions(+), 19 deletions(-) create mode 100644 versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md diff --git a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md new file mode 100644 index 000000000..ebfcce22d --- /dev/null +++ b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md @@ -0,0 +1,728 @@ +--- +id: kubernetes +title: Kubernetes Setup +sidebar_label: Kubernetes +tags: + - explanation + - feature guide + - keploy enterprise + - kubernetes + - kind + - argocd + - flux + - gitops + - contour +keywords: + - keploy enterprise + - kubernetes + - kind + - argocd + - flux + - gitops + - helm + - contour + - ingress + - local cluster + - live recording + - replay +--- + +import ProductTier from '@site/src/components/ProductTier'; + + + +This guide walks you through creating a local **Kind** Kubernetes cluster and connecting it to **Keploy** using a **NodePort** (example: `30080`) so you can **live record and replay traffic** for Pods. + +> [!NOTE] +> This documentation covers **local Kind cluster** setup. Documentation for **hosted cluster** setup is coming soon. + +--- + +## Prerequisites + +Ensure you have the following before you begin: + +1. **Keploy Enterprise account** (with an access key) +2. **kubectl** configured to access your Kubernetes cluster +3. **Helm** installed +4. **Kind** installed + +--- + +## 1) Create a Local Kind Cluster (with NodePort Mapping) + +### 1.1 Install Kind + +Install Kind using the official instructions: +https://kind.sigs.k8s.io/docs/user/quick-start/#installing-from-release-binaries + +### 1.2 Create Kind Cluster Config (NodePort: `30080`) + +Create a file named `kind-cluster.yaml` with the following contents: + +```yaml +kind: Cluster +apiVersion: kind.x-k8s.io/v1alpha4 +nodes: + - role: control-plane + extraPortMappings: + - containerPort: 30080 + hostPort: 30080 + protocol: TCP +``` + +### 1.3 Create the Cluster + +Run: + +```bash +kind create cluster --config kind-cluster.yaml +``` + +### 1.4 Verify the Cluster is Ready + +Confirm the cluster components are running: + +```bash +kubectl get pods --all-namespaces +``` + +Expected output should look similar to: + +```text +NAMESPACE NAME READY STATUS RESTARTS AGE +kube-system coredns-7d764666f9-r82lr 1/1 Running 0 42s +kube-system coredns-7d764666f9-rsjsv 1/1 Running 0 42s +kube-system etcd-local-k8s-control-plane 1/1 Running 0 49s +kube-system kindnet-c59v6 1/1 Running 0 42s +kube-system kube-apiserver-local-k8s-control-plane 1/1 Running 0 49s +kube-system kube-controller-manager-local-k8s-control-plane 1/1 Running 0 48s +kube-system kube-proxy-xkch5 1/1 Running 0 42s +kube-system kube-scheduler-local-k8s-control-plane 1/1 Running 0 49s +local-path-storage local-path-provisioner-67b8995b4b-csn49 1/1 Running 0 42s +``` + +✅ Your local Kind cluster is ready. + +--- + +## 2) Connect the Cluster to Keploy (NodePort Setup) + +### 2.1 Create Cluster Entry in Keploy + +1. Go to: https://app.keploy.io/clusters +2. Click **Connect New Cluster** +3. Enter: + - **Cluster Name** + - **Ingress URL**: Use `http://localhost:30080` + +> [!NOTE] +> This setup has been tested with **Google Chrome**. Browsers treat `localhost` as a secure context, which allows features that would otherwise require HTTPS. If you use an IP address instead, HTTPS would be required with a properly signed TLS certificate. +> +> If your cluster is running on a VM, see [SSH Port Forwarding](#23-optional-ssh-port-forwarding-access-keploy-nodeport-from-your-laptop) to access it via `localhost` from your laptop. + +4. Click **Connect** + +### 2.2 Install Keploy via Helm + +Keploy UI will provide a Helm command. Ensure you **set**: + +- `proxy.insecure.enabled=true` (**important for local NodePort**) +- `service.type=NodePort` +- `service.nodePort=30080` +- `ingressUrl` matches what you entered in the UI (e.g., `http://localhost:30080`) + +Example command: + +```bash +helm upgrade --install k8s-proxy oci://docker.io/keploy/k8s-proxy-chart --version \ + --namespace keploy \ + --create-namespace \ + --set accessKey="" \ + --set clusterName="doc-test-2" \ + --set apiServerUrl="https://api.keploy.io" \ + --set service.type=NodePort \ + --set ingressUrl="http://localhost:30080" \ + --set service.nodePort=30080 \ + --set environment="prod" \ + --set proxy.insecure.enabled=true +``` + +--- + +### 2.3 Optional: SSH Port Forwarding (Access Keploy NodePort from Your Laptop) + +If your Kubernetes cluster is running **inside a VM** and you want to use **Chrome on your local machine** to reach the Keploy NodePort (e.g., `30080`), you can tunnel the port over SSH. + +This is useful when: + +- The NodePort is reachable **from the VM**, but not directly from your laptop due to NAT / firewall rules, or +- You want to avoid exposing the NodePort to your LAN. + +#### Example: Forward Local `30080` → VM `30080` + +Run this on your **local machine**: + +```bash +ssh -N \ + -L 30080::30080 \ + @ -i /path/to/your/ssh/key +``` + +After this is running, you should be able to open the NodePort via: + +- `http://localhost:30080` + +…and use that value for `ingressUrl` in the Keploy UI / Helm values. + +#### Troubleshooting: `channel ... open failed: connect failed: Connection refused` + +If you see something like: + +```text +channel 2: open failed: connect failed: Connection refused +``` + +It typically means **the VM could not connect to the target IP:port** from _its own network namespace_. + +Common fixes: + +- **Verify the NodePort is actually listening** on the VM: + + ```bash + sudo ss -lntp | grep 30080 || true + sudo netstat -lntp | grep 30080 || true + ``` + +- **Confirm the Keploy NodePort service is created and uses the expected port**: + + ```bash + kubectl -n keploy get svc + kubectl -n keploy get svc k8s-proxy -o yaml | sed -n '1,160p' + ``` + +- **If the NodePort is only bound on localhost inside the VM**, forward to `127.0.0.1` instead: + + ```bash + ssh -N \ + -L 30080:127.0.0.1:30080 \ + @ -i /path/to/your/ssh/key + ``` + +- **If you're running Kind inside Docker on the VM**, ensure your Kind config includes the `extraPortMappings` and that `hostPort: 30080` is mapped correctly (as shown in this document). + +> [!TIP] +> If the VM's IP changes or you want the command to fail fast, add `-o ExitOnForwardFailure=yes`. + +--- + +## 3) Verify Keploy Pods Are Running + +Check all namespaces: + +```bash +kubectl get pods --all-namespaces +``` + +You should see Keploy components in the `keploy` namespace, similar to: + +```text +NAMESPACE NAME READY STATUS RESTARTS AGE +keploy k8s-proxy-65f4d8fd9-cmbmn 1/1 Running 0 72s +keploy k8s-proxy-minio-74849875b7-4w76s 1/1 Running 0 72s +keploy k8s-proxy-mongodb-6548798d96-2llzt 1/1 Running 0 72s +kube-system coredns-7d764666f9-r82lr 1/1 Running 0 8m7s +... +``` + +--- + +## 4) Confirm Cluster Visibility in Keploy UI + +1. Go back to: https://app.keploy.io/clusters +2. Open your connected cluster +3. Verify your **deployments** are visible + +✅ Once deployments are visible, you can start **recording on any Pod** and later **replay**. + +![Keploy Kubernetes Interface](/img/k8s-local-cluster-ui.png) + +--- + +## GitOps Deployment + +If you use a GitOps tool to manage your Kubernetes cluster, you can deploy Keploy's k8s-proxy declaratively. The sections below cover **ArgoCD** and **Flux CD** — both use **Contour** as the ingress controller for TLS passthrough. + +> [!NOTE] +> The GitOps guides below assume you have already completed the [local Kind cluster setup](#1-create-a-local-kind-cluster-with-nodeport-mapping) above and have a running cluster with Keploy connected. + +--- + +### Deploy Contour ingress controller + +Keploy's k8s-proxy serves **HTTPS natively** on its backend port. You need an ingress controller that supports **TLS passthrough** — forwarding the encrypted connection directly to the k8s-proxy without terminating it. + +[Contour](https://projectcontour.io/) is a CNCF ingress controller powered by Envoy that supports this via its **HTTPProxy** CRD. + +#### Install Contour + +```bash +kubectl apply -f https://projectcontour.io/quickstart/contour.yaml +``` + +Wait for it to be ready: + +```bash +kubectl -n projectcontour rollout status deployment/contour +kubectl -n projectcontour rollout status daemonset/envoy +``` + +#### Patch Envoy for Kind/VM clusters + +Kind only maps specific ports to the host. Since TLS passthrough uses Envoy's HTTPS listener (port 443), you need to assign it to the mapped NodePort: + +```bash +kubectl patch svc envoy -n projectcontour --type='json' -p='[ + {"op": "replace", "path": "/spec/type", "value": "NodePort"}, + {"op": "replace", "path": "/spec/ports/0/nodePort", "value": 30081}, + {"op": "replace", "path": "/spec/ports/1/nodePort", "value": 30080} +]' +``` + +This puts the **HTTPS listener on NodePort 30080** (mapped to the host) and the HTTP listener on 30081. + +> [!TIP] +> For cloud clusters (EKS/GKE/AKS), skip this patch. The default LoadBalancer type works — your cloud provider assigns an external IP automatically. + +#### Verify Contour + +```bash +kubectl get pods -n projectcontour +kubectl get svc -n projectcontour +``` + +Expected output: + +```text +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +envoy NodePort 10.96.65.35 80:30081/TCP,443:30080/TCP 2m +``` + +--- + +### Create the Keploy access key secret + +> Skip if you already created this during the [local setup above](#2-connect-the-cluster-to-keploy-nodeport-setup). + +Go to the Keploy UI → **Clusters** → **Connect New Cluster**. Enter your cluster name and ingress URL (e.g. `https://your-host:30080`). Click **Connect** to get your access key. + +```bash +kubectl create namespace keploy + +kubectl -n keploy create secret generic keploy-credentials \ + --from-literal=access-key="" +``` + +> [!WARNING] +> Never commit access keys to Git. Use `existingSecret` in Helm values or a secrets manager (Sealed Secrets, Vault, External Secrets Operator). + +--- + +### Create the HTTPProxy for TLS passthrough + +The k8s-proxy serves HTTPS on its backend. A standard Kubernetes `Ingress` only supports HTTP backends, so you need Contour's **HTTPProxy** CRD with TLS passthrough. + +Create a file named `k8s-proxy-httpproxy.yaml`: + +```yaml +apiVersion: projectcontour.io/v1 +kind: HTTPProxy +metadata: + name: k8s-proxy-ingress + namespace: keploy +spec: + virtualhost: + fqdn: + tls: + passthrough: true + tcpproxy: + services: + - name: k8s-proxy + port: 8080 +``` + +Replace `` with the hostname that resolves to your cluster. This must match the host used in `keploy.ingressUrl`. + +Apply it: + +```bash +kubectl apply -f k8s-proxy-httpproxy.yaml +``` + +#### How TLS passthrough works + +```text +Client (Keploy cloud) + │ + │ HTTPS (encrypted) + ▼ +Envoy (port 30080) ← reads SNI hostname, does NOT decrypt + │ + │ forwards encrypted bytes + ▼ +k8s-proxy (port 8080) ← terminates TLS itself +``` + +Envoy looks at the **SNI** (Server Name Indication) — the hostname in the TLS Client Hello — to decide where to route the connection. It then passes the encrypted bytes straight through to the k8s-proxy without inspecting them. This is why the `fqdn` in the HTTPProxy must match the hostname the client uses. + +> [!NOTE] +> SNI matching means you **must** access the k8s-proxy using the hostname (e.g. `https://your-host:30080`), not the raw IP address. Add an `/etc/hosts` entry if needed. + +--- + +### Option A: Deploy with ArgoCD + +If you already use ArgoCD to manage your applications, adding Keploy requires **just two files** — an ArgoCD Application YAML and a Contour HTTPProxy YAML. No changes to your existing app code or manifests. + +#### Prerequisites + +1. **ArgoCD** installed on the cluster +2. **Contour** deployed ([see above](#deploy-contour-ingress-controller)) + +#### Install ArgoCD + +> Skip this if ArgoCD is already installed on your cluster. + +```bash +kubectl create namespace argocd +kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml +kubectl -n argocd rollout status deployment/argocd-server +``` + +Get the admin password: + +```bash +kubectl -n argocd get secret argocd-initial-admin-secret \ + -o jsonpath="{.data.password}" | base64 -d; echo +``` + +Access the ArgoCD UI: + +```bash +kubectl -n argocd port-forward svc/argocd-server 8443:443 & +``` + +Open `https://localhost:8443` in your browser. Login with username `admin` and the password from above. + +#### Create the ArgoCD Application for k8s-proxy + +Create a file named `keploy-k8s-proxy.yaml`: + +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: keploy-k8s-proxy + namespace: argocd + finalizers: + - resources-finalizer.argocd.argoproj.io +spec: + project: default + source: + chart: k8s-proxy-chart + repoURL: registry-1.docker.io/keploy + targetRevision: "3.3.10" + helm: + values: | + replicaCount: 1 + environment: "staging" + selfHosted: false + + keploy: + existingSecret: "keploy-credentials" + existingSecretKey: "access-key" + clusterName: "" + apiServerUrl: "https://api.keploy.io" + ingressUrl: "https://:30080" + + service: + type: ClusterIP + + mongodb: + enabled: false + minio: + enabled: false + destination: + server: https://kubernetes.default.svc + namespace: keploy + syncPolicy: + automated: + prune: true + selfHeal: true + syncOptions: + - CreateNamespace=true +``` + +Replace: +- `` — the name you entered in the Keploy UI +- `` — the hostname that resolves to your cluster (e.g. your VM IP or a DNS name) + +Apply it: + +```bash +kubectl apply -f keploy-k8s-proxy.yaml +``` + +#### Verify ArgoCD deployment + +```bash +# Check ArgoCD sees the app +kubectl get applications -n argocd + +# Check HTTPProxy status +kubectl get httpproxy -A +# Should show status: valid + +# Check k8s-proxy is running +kubectl get pods -n keploy + +# Test connectivity through Contour +curl -sk https://:30080/healthz +# → {"status":"ok"} +``` + +✅ Open the Keploy UI → **Clusters** → your cluster should show as **Connected**. You can now record and replay traffic on any deployment. + +#### Deploy your application with ArgoCD + +Your application needs **no changes** for Keploy. Deploy it as you normally would with ArgoCD — either from Helm charts or raw K8s manifests: + +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: my-app + namespace: argocd +spec: + project: default + source: + repoURL: https://github.com/your-org/your-repo.git + targetRevision: main + path: k8s/ + destination: + server: https://kubernetes.default.svc + namespace: staging + syncPolicy: + automated: + prune: true + selfHeal: true + syncOptions: + - CreateNamespace=true +``` + +Once deployed, your application appears in the Keploy UI under your cluster's **Deployments** tab. Click **Record** to start capturing live traffic. + +#### ArgoCD summary + +To add Keploy to an existing ArgoCD setup, you need: + +| What | File | Purpose | +|------|------|---------| +| ArgoCD Application | `keploy-k8s-proxy.yaml` | Deploy k8s-proxy from Keploy's Helm chart | +| Contour HTTPProxy | `k8s-proxy-httpproxy.yaml` | Route HTTPS traffic via TLS passthrough | +| Kubernetes Secret | `kubectl create secret` (manual) | Access key for Keploy cloud authentication | + +Your existing application code, manifests, and ArgoCD Applications remain **completely untouched**. Keploy works alongside your app — not inside it. + +--- + +### Option B: Deploy with Flux CD + +Flux watches your Git repository and automatically applies changes to the cluster. Adding Keploy requires a **HelmRelease** for the k8s-proxy and an **HTTPProxy** for Contour routing. + +#### Prerequisites + +1. **Flux CLI** installed ([installation guide](https://fluxcd.io/flux/installation/)) +2. **A Git repository** (GitHub, GitLab, Bitbucket) for Flux to watch +3. **Contour** deployed ([see above](#deploy-contour-ingress-controller)) + +#### Bootstrap Flux + +> Skip this if Flux is already installed on your cluster. + +Bootstrap Flux with your GitHub repository: + +```bash +flux bootstrap github \ + --owner= \ + --repository= \ + --branch=main \ + --path=clusters/staging \ + --personal +``` + +This installs Flux on your cluster and creates the `clusters/staging` directory in your Git repo where you'll add Keploy manifests. + +Verify Flux is running: + +```bash +flux check +``` + +#### Add the Keploy Helm repository source + +Create `clusters/staging/keploy-source.yaml` in your Git repo: + +```yaml +apiVersion: source.toolkit.fluxcd.io/v1 +kind: HelmRepository +metadata: + name: keploy + namespace: flux-system +spec: + interval: 1h + type: oci + url: oci://docker.io/keploy +``` + +#### Create the HelmRelease for k8s-proxy + +Create `clusters/staging/keploy-k8s-proxy.yaml` in your Git repo: + +```yaml +apiVersion: helm.toolkit.fluxcd.io/v2 +kind: HelmRelease +metadata: + name: k8s-proxy + namespace: keploy +spec: + interval: 5m + chart: + spec: + chart: k8s-proxy-chart + version: "3.3.10" + sourceRef: + kind: HelmRepository + name: keploy + namespace: flux-system + install: + createNamespace: true + values: + replicaCount: 1 + environment: "staging" + selfHosted: false + + keploy: + existingSecret: "keploy-credentials" + existingSecretKey: "access-key" + clusterName: "" + apiServerUrl: "https://api.keploy.io" + ingressUrl: "https://:30080" + + service: + type: ClusterIP + + mongodb: + enabled: false + minio: + enabled: false +``` + +Replace: +- `` — the name you entered in the Keploy UI +- `` — the hostname that resolves to your cluster + +#### Create the HTTPProxy for TLS passthrough + +Create `clusters/staging/k8s-proxy-httpproxy.yaml` in your Git repo: + +```yaml +apiVersion: projectcontour.io/v1 +kind: HTTPProxy +metadata: + name: k8s-proxy-ingress + namespace: keploy +spec: + virtualhost: + fqdn: + tls: + passthrough: true + tcpproxy: + services: + - name: k8s-proxy + port: 8080 +``` + +Replace `` with the same hostname used in `keploy.ingressUrl`. + +> [!NOTE] +> TLS passthrough is required because the k8s-proxy serves HTTPS natively. Envoy forwards the encrypted connection directly to the k8s-proxy without terminating TLS. See the [TLS passthrough explanation](#how-tls-passthrough-works) above. + +#### Push and let Flux reconcile + +Commit and push all three files: + +```bash +git add clusters/staging/keploy-source.yaml \ + clusters/staging/keploy-k8s-proxy.yaml \ + clusters/staging/k8s-proxy-httpproxy.yaml +git commit -m "Add Keploy k8s-proxy deployment" +git push +``` + +Flux detects the changes and applies them automatically. Check the status: + +```bash +# Force immediate reconciliation (optional) +flux reconcile source git flux-system + +# Check HelmRelease status +flux get helmreleases -n keploy + +# Check HTTPProxy +kubectl get httpproxy -A +``` + +#### Verify Flux deployment + +```bash +# Check k8s-proxy is running +kubectl get pods -n keploy + +# Check HTTPProxy status (should show "valid") +kubectl get httpproxy -A + +# Test connectivity through Contour +curl -sk https://:30080/healthz +# → {"status":"ok"} +``` + +✅ Open the Keploy UI → **Clusters** → your cluster should show as **Connected**. You can now record and replay traffic on any deployment. + +#### Flux Git repository structure + +After adding Keploy, your Flux repo should look like: + +```text +clusters/ +└── staging/ + ├── keploy-source.yaml # OCI Helm repository for Keploy + ├── keploy-k8s-proxy.yaml # HelmRelease for k8s-proxy + ├── k8s-proxy-httpproxy.yaml # Contour HTTPProxy (TLS passthrough) + └── your-other-apps/ # Your existing Flux manifests +``` + +#### Flux CD summary + +To add Keploy to an existing Flux setup, you need: + +| What | File | Purpose | +|------|------|---------| +| Helm source | `keploy-source.yaml` | OCI Helm repository for Keploy charts | +| HelmRelease | `keploy-k8s-proxy.yaml` | Deploy k8s-proxy from Keploy's Helm chart | +| Contour HTTPProxy | `k8s-proxy-httpproxy.yaml` | Route HTTPS traffic via TLS passthrough | +| Kubernetes Secret | `kubectl create secret` (manual) | Access key for Keploy cloud authentication | + +Your existing application manifests and Flux configurations remain **completely untouched**. Keploy works alongside your app — not inside it. + +For a reference implementation with both ArgoCD and Flux CD manifests, see the [keploy-argocd-demo](https://github.com/officialasishkumar/keploy-argocd-demo) repository. diff --git a/versioned_sidebars/version-4.0.0-sidebars.json b/versioned_sidebars/version-4.0.0-sidebars.json index e231ba848..d7f173fe4 100644 --- a/versioned_sidebars/version-4.0.0-sidebars.json +++ b/versioned_sidebars/version-4.0.0-sidebars.json @@ -22,28 +22,18 @@ "items": [ { "type": "doc", - "label": "Keploy OSS", + "label": "Local", "id": "server/installation" }, - "keploy-cloud/cloud-installation" - ] - }, - { - "type": "category", - "label": "Kubernetes", - "collapsible": true, - "collapsed": true, - "items": [ - "keploy-cloud/kubernetes-local-setup", { - "type": "category", - "label": "GitOps Deployment", - "collapsible": true, - "collapsed": true, - "items": [ - "keploy-cloud/gitops-argocd", - "keploy-cloud/gitops-flux" - ] + "type": "doc", + "label": "Enterprise", + "id": "keploy-cloud/cloud-installation" + }, + { + "type": "doc", + "label": "Kubernetes", + "id": "keploy-cloud/kubernetes" } ] }, From fd8d54a2c43904e35d0884da3d36424a7241b757 Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Wed, 1 Apr 2026 19:40:17 +0530 Subject: [PATCH 07/30] fix(docs): correct sidebar labels and promote GitOps headings to h2 - Fixed sidebar doc ID reference (server/install) so label override works. - Sidebar now shows "Local", "Enterprise", "Kubernetes" under Installation. - Promoted ArgoCD and Flux CD sections to h2 headings so they appear as top-level TOC entries instead of being hidden under GitOps Deployment. - Renamed "Option A/B" to "Deploy with ArgoCD/Flux CD" since they are standalone guides, not alternatives. Signed-off-by: Asish Kumar Co-Authored-By: Claude Opus 4.6 Signed-off-by: Asish Kumar --- .../keploy-cloud/installation.md | 2 +- .../version-4.0.0/keploy-cloud/kubernetes.md | 48 +++++++++---------- .../version-4.0.0/server/installation.md | 2 +- .../version-4.0.0-sidebars.json | 2 +- 4 files changed, 27 insertions(+), 27 deletions(-) diff --git a/versioned_docs/version-4.0.0/keploy-cloud/installation.md b/versioned_docs/version-4.0.0/keploy-cloud/installation.md index c6e816f3f..22510c997 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/installation.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/installation.md @@ -1,7 +1,7 @@ --- id: cloud-installation title: Keploy Enterprise Installation -sidebar_label: Enterprise Installation +sidebar_label: Enterprise tags: - explanation - feature guide diff --git a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md index ebfcce22d..7352f3edd 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md @@ -258,13 +258,13 @@ If you use a GitOps tool to manage your Kubernetes cluster, you can deploy Keplo --- -### Deploy Contour ingress controller +## Deploy Contour Ingress Controller Keploy's k8s-proxy serves **HTTPS natively** on its backend port. You need an ingress controller that supports **TLS passthrough** — forwarding the encrypted connection directly to the k8s-proxy without terminating it. [Contour](https://projectcontour.io/) is a CNCF ingress controller powered by Envoy that supports this via its **HTTPProxy** CRD. -#### Install Contour +### Install Contour ```bash kubectl apply -f https://projectcontour.io/quickstart/contour.yaml @@ -277,7 +277,7 @@ kubectl -n projectcontour rollout status deployment/contour kubectl -n projectcontour rollout status daemonset/envoy ``` -#### Patch Envoy for Kind/VM clusters +### Patch Envoy for Kind/VM Clusters Kind only maps specific ports to the host. Since TLS passthrough uses Envoy's HTTPS listener (port 443), you need to assign it to the mapped NodePort: @@ -294,7 +294,7 @@ This puts the **HTTPS listener on NodePort 30080** (mapped to the host) and the > [!TIP] > For cloud clusters (EKS/GKE/AKS), skip this patch. The default LoadBalancer type works — your cloud provider assigns an external IP automatically. -#### Verify Contour +### Verify Contour ```bash kubectl get pods -n projectcontour @@ -310,7 +310,7 @@ envoy NodePort 10.96.65.35 80:30081/TCP,443:30080/TCP 2m --- -### Create the Keploy access key secret +## Create the Keploy Access Key Secret > Skip if you already created this during the [local setup above](#2-connect-the-cluster-to-keploy-nodeport-setup). @@ -328,7 +328,7 @@ kubectl -n keploy create secret generic keploy-credentials \ --- -### Create the HTTPProxy for TLS passthrough +## Create the HTTPProxy for TLS Passthrough The k8s-proxy serves HTTPS on its backend. A standard Kubernetes `Ingress` only supports HTTP backends, so you need Contour's **HTTPProxy** CRD with TLS passthrough. @@ -359,7 +359,7 @@ Apply it: kubectl apply -f k8s-proxy-httpproxy.yaml ``` -#### How TLS passthrough works +### How TLS Passthrough Works ```text Client (Keploy cloud) @@ -380,16 +380,16 @@ Envoy looks at the **SNI** (Server Name Indication) — the hostname in the TLS --- -### Option A: Deploy with ArgoCD +## Deploy with ArgoCD If you already use ArgoCD to manage your applications, adding Keploy requires **just two files** — an ArgoCD Application YAML and a Contour HTTPProxy YAML. No changes to your existing app code or manifests. -#### Prerequisites +### Prerequisites 1. **ArgoCD** installed on the cluster 2. **Contour** deployed ([see above](#deploy-contour-ingress-controller)) -#### Install ArgoCD +### Install ArgoCD > Skip this if ArgoCD is already installed on your cluster. @@ -414,7 +414,7 @@ kubectl -n argocd port-forward svc/argocd-server 8443:443 & Open `https://localhost:8443` in your browser. Login with username `admin` and the password from above. -#### Create the ArgoCD Application for k8s-proxy +### Create the ArgoCD Application for k8s-proxy Create a file named `keploy-k8s-proxy.yaml`: @@ -473,7 +473,7 @@ Apply it: kubectl apply -f keploy-k8s-proxy.yaml ``` -#### Verify ArgoCD deployment +### Verify ArgoCD Deployment ```bash # Check ArgoCD sees the app @@ -493,7 +493,7 @@ curl -sk https://:30080/healthz ✅ Open the Keploy UI → **Clusters** → your cluster should show as **Connected**. You can now record and replay traffic on any deployment. -#### Deploy your application with ArgoCD +### Deploy Your Application with ArgoCD Your application needs **no changes** for Keploy. Deploy it as you normally would with ArgoCD — either from Helm charts or raw K8s manifests: @@ -522,7 +522,7 @@ spec: Once deployed, your application appears in the Keploy UI under your cluster's **Deployments** tab. Click **Record** to start capturing live traffic. -#### ArgoCD summary +### ArgoCD Summary To add Keploy to an existing ArgoCD setup, you need: @@ -536,17 +536,17 @@ Your existing application code, manifests, and ArgoCD Applications remain **comp --- -### Option B: Deploy with Flux CD +## Deploy with Flux CD Flux watches your Git repository and automatically applies changes to the cluster. Adding Keploy requires a **HelmRelease** for the k8s-proxy and an **HTTPProxy** for Contour routing. -#### Prerequisites +### Prerequisites 1. **Flux CLI** installed ([installation guide](https://fluxcd.io/flux/installation/)) 2. **A Git repository** (GitHub, GitLab, Bitbucket) for Flux to watch 3. **Contour** deployed ([see above](#deploy-contour-ingress-controller)) -#### Bootstrap Flux +### Bootstrap Flux > Skip this if Flux is already installed on your cluster. @@ -569,7 +569,7 @@ Verify Flux is running: flux check ``` -#### Add the Keploy Helm repository source +### Add the Keploy Helm Repository Source Create `clusters/staging/keploy-source.yaml` in your Git repo: @@ -585,7 +585,7 @@ spec: url: oci://docker.io/keploy ``` -#### Create the HelmRelease for k8s-proxy +### Create the HelmRelease for k8s-proxy Create `clusters/staging/keploy-k8s-proxy.yaml` in your Git repo: @@ -632,7 +632,7 @@ Replace: - `` — the name you entered in the Keploy UI - `` — the hostname that resolves to your cluster -#### Create the HTTPProxy for TLS passthrough +### Create the HTTPProxy for TLS Passthrough Create `clusters/staging/k8s-proxy-httpproxy.yaml` in your Git repo: @@ -658,7 +658,7 @@ Replace `` with the same hostname used in `keploy.ingressUrl` > [!NOTE] > TLS passthrough is required because the k8s-proxy serves HTTPS natively. Envoy forwards the encrypted connection directly to the k8s-proxy without terminating TLS. See the [TLS passthrough explanation](#how-tls-passthrough-works) above. -#### Push and let Flux reconcile +### Push and Let Flux Reconcile Commit and push all three files: @@ -683,7 +683,7 @@ flux get helmreleases -n keploy kubectl get httpproxy -A ``` -#### Verify Flux deployment +### Verify Flux Deployment ```bash # Check k8s-proxy is running @@ -699,7 +699,7 @@ curl -sk https://:30080/healthz ✅ Open the Keploy UI → **Clusters** → your cluster should show as **Connected**. You can now record and replay traffic on any deployment. -#### Flux Git repository structure +### Flux Git Repository Structure After adding Keploy, your Flux repo should look like: @@ -712,7 +712,7 @@ clusters/ └── your-other-apps/ # Your existing Flux manifests ``` -#### Flux CD summary +### Flux CD Summary To add Keploy to an existing Flux setup, you need: diff --git a/versioned_docs/version-4.0.0/server/installation.md b/versioned_docs/version-4.0.0/server/installation.md index 2dfcd450e..c2d0eb050 100644 --- a/versioned_docs/version-4.0.0/server/installation.md +++ b/versioned_docs/version-4.0.0/server/installation.md @@ -1,7 +1,7 @@ --- id: install title: Keploy Installation -sidebar_label: Installation +sidebar_label: Local tags: - hello-world - linux diff --git a/versioned_sidebars/version-4.0.0-sidebars.json b/versioned_sidebars/version-4.0.0-sidebars.json index d7f173fe4..fb3fa24c6 100644 --- a/versioned_sidebars/version-4.0.0-sidebars.json +++ b/versioned_sidebars/version-4.0.0-sidebars.json @@ -23,7 +23,7 @@ { "type": "doc", "label": "Local", - "id": "server/installation" + "id": "server/install" }, { "type": "doc", From 36009524e4829349a3f804b6ff6287f7b382eee5 Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Wed, 1 Apr 2026 19:43:22 +0530 Subject: [PATCH 08/30] docs: update reference repo link to keploy-k8s-demo - Changed demo repo link from keploy-argocd-demo to keploy-k8s-demo which contains both ArgoCD and Flux CD manifests with a README. Signed-off-by: Asish Kumar Co-Authored-By: Claude Opus 4.6 Signed-off-by: Asish Kumar --- versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md index 7352f3edd..5371e4401 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md @@ -725,4 +725,4 @@ To add Keploy to an existing Flux setup, you need: Your existing application manifests and Flux configurations remain **completely untouched**. Keploy works alongside your app — not inside it. -For a reference implementation with both ArgoCD and Flux CD manifests, see the [keploy-argocd-demo](https://github.com/officialasishkumar/keploy-argocd-demo) repository. +For a reference implementation with both ArgoCD and Flux CD manifests, see the [keploy-k8s-demo](https://github.com/officialasishkumar/keploy-k8s-demo) repository. From 984be385e62da973a16d00acbed09262c387f6a6 Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Wed, 1 Apr 2026 20:08:01 +0530 Subject: [PATCH 09/30] style(docs): fix prettier formatting in GitOps guides - Auto-formatted markdown tables and line wrapping in gitops-argocd, gitops-flux, and kubernetes pages to pass prettier CI check. Signed-off-by: Asish Kumar Co-Authored-By: Claude Opus 4.6 Signed-off-by: Asish Kumar --- .../keploy-cloud/gitops-argocd.md | 11 +++++----- .../version-4.0.0/keploy-cloud/gitops-flux.md | 11 +++++----- .../version-4.0.0/keploy-cloud/kubernetes.md | 22 ++++++++++--------- 3 files changed, 24 insertions(+), 20 deletions(-) diff --git a/versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md b/versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md index 1c9abda96..a798500ec 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md @@ -191,6 +191,7 @@ spec: ``` Replace: + - `` — the name you entered in the Keploy UI - `` — the hostname that resolves to your cluster (e.g. your VM IP or a DNS name) @@ -311,11 +312,11 @@ Once deployed, your application appears in the Keploy UI under your cluster's ** To add Keploy to an existing ArgoCD setup, you need: -| What | File | Purpose | -|------|------|---------| -| ArgoCD Application | `keploy-k8s-proxy.yaml` | Deploy k8s-proxy from Keploy's Helm chart | -| Contour HTTPProxy | `k8s-proxy-httpproxy.yaml` | Route HTTPS traffic via TLS passthrough | -| Kubernetes Secret | `kubectl create secret` (manual) | Access key for Keploy cloud authentication | +| What | File | Purpose | +| ------------------ | -------------------------------- | ------------------------------------------ | +| ArgoCD Application | `keploy-k8s-proxy.yaml` | Deploy k8s-proxy from Keploy's Helm chart | +| Contour HTTPProxy | `k8s-proxy-httpproxy.yaml` | Route HTTPS traffic via TLS passthrough | +| Kubernetes Secret | `kubectl create secret` (manual) | Access key for Keploy cloud authentication | Your existing application code, manifests, and ArgoCD Applications remain **completely untouched**. Keploy works alongside your app — not inside it. diff --git a/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md b/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md index 1d632bdea..47ffdd980 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md @@ -151,6 +151,7 @@ spec: ``` Replace: + - `` — the name you entered in the Keploy UI - `` — the hostname that resolves to your cluster @@ -248,11 +249,11 @@ clusters/ To add Keploy to an existing Flux setup, you need: -| What | File | Purpose | -|------|------|---------| -| Helm source | `keploy-source.yaml` | OCI Helm repository for Keploy charts | -| HelmRelease | `keploy-k8s-proxy.yaml` | Deploy k8s-proxy from Keploy's Helm chart | -| Contour HTTPProxy | `k8s-proxy-httpproxy.yaml` | Route HTTPS traffic via TLS passthrough | +| What | File | Purpose | +| ----------------- | -------------------------------- | ------------------------------------------ | +| Helm source | `keploy-source.yaml` | OCI Helm repository for Keploy charts | +| HelmRelease | `keploy-k8s-proxy.yaml` | Deploy k8s-proxy from Keploy's Helm chart | +| Contour HTTPProxy | `k8s-proxy-httpproxy.yaml` | Route HTTPS traffic via TLS passthrough | | Kubernetes Secret | `kubectl create secret` (manual) | Access key for Keploy cloud authentication | Your existing application manifests and Flux configurations remain **completely untouched**. Keploy works alongside your app — not inside it. diff --git a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md index 5371e4401..535e233fa 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md @@ -464,6 +464,7 @@ spec: ``` Replace: + - `` — the name you entered in the Keploy UI - `` — the hostname that resolves to your cluster (e.g. your VM IP or a DNS name) @@ -526,11 +527,11 @@ Once deployed, your application appears in the Keploy UI under your cluster's ** To add Keploy to an existing ArgoCD setup, you need: -| What | File | Purpose | -|------|------|---------| -| ArgoCD Application | `keploy-k8s-proxy.yaml` | Deploy k8s-proxy from Keploy's Helm chart | -| Contour HTTPProxy | `k8s-proxy-httpproxy.yaml` | Route HTTPS traffic via TLS passthrough | -| Kubernetes Secret | `kubectl create secret` (manual) | Access key for Keploy cloud authentication | +| What | File | Purpose | +| ------------------ | -------------------------------- | ------------------------------------------ | +| ArgoCD Application | `keploy-k8s-proxy.yaml` | Deploy k8s-proxy from Keploy's Helm chart | +| Contour HTTPProxy | `k8s-proxy-httpproxy.yaml` | Route HTTPS traffic via TLS passthrough | +| Kubernetes Secret | `kubectl create secret` (manual) | Access key for Keploy cloud authentication | Your existing application code, manifests, and ArgoCD Applications remain **completely untouched**. Keploy works alongside your app — not inside it. @@ -629,6 +630,7 @@ spec: ``` Replace: + - `` — the name you entered in the Keploy UI - `` — the hostname that resolves to your cluster @@ -716,11 +718,11 @@ clusters/ To add Keploy to an existing Flux setup, you need: -| What | File | Purpose | -|------|------|---------| -| Helm source | `keploy-source.yaml` | OCI Helm repository for Keploy charts | -| HelmRelease | `keploy-k8s-proxy.yaml` | Deploy k8s-proxy from Keploy's Helm chart | -| Contour HTTPProxy | `k8s-proxy-httpproxy.yaml` | Route HTTPS traffic via TLS passthrough | +| What | File | Purpose | +| ----------------- | -------------------------------- | ------------------------------------------ | +| Helm source | `keploy-source.yaml` | OCI Helm repository for Keploy charts | +| HelmRelease | `keploy-k8s-proxy.yaml` | Deploy k8s-proxy from Keploy's Helm chart | +| Contour HTTPProxy | `k8s-proxy-httpproxy.yaml` | Route HTTPS traffic via TLS passthrough | | Kubernetes Secret | `kubectl create secret` (manual) | Access key for Keploy cloud authentication | Your existing application manifests and Flux configurations remain **completely untouched**. Keploy works alongside your app — not inside it. From 45ee3eb8f11687996694aeef4f2b270101185fd7 Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Wed, 1 Apr 2026 20:12:27 +0530 Subject: [PATCH 10/30] refactor(docs): remove unnecessary prerequisites from GitOps guides MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Removed Prerequisites sections from ArgoCD and Flux CD guides since the guide itself covers installation inline. - Made Contour optional — k8s-proxy works with any TLS passthrough ingress controller or direct NodePort/LoadBalancer. - Reframed Contour section as one example, not a requirement. Signed-off-by: Asish Kumar Co-Authored-By: Claude Opus 4.6 Signed-off-by: Asish Kumar --- .../version-4.0.0/keploy-cloud/kubernetes.md | 32 +++++-------------- 1 file changed, 8 insertions(+), 24 deletions(-) diff --git a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md index 535e233fa..1f569f2c4 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md @@ -251,18 +251,15 @@ kube-system coredns-7d764666f9-r82lr 1/1 R ## GitOps Deployment -If you use a GitOps tool to manage your Kubernetes cluster, you can deploy Keploy's k8s-proxy declaratively. The sections below cover **ArgoCD** and **Flux CD** — both use **Contour** as the ingress controller for TLS passthrough. - -> [!NOTE] -> The GitOps guides below assume you have already completed the [local Kind cluster setup](#1-create-a-local-kind-cluster-with-nodeport-mapping) above and have a running cluster with Keploy connected. +If you use a GitOps tool to manage your Kubernetes cluster, you can deploy Keploy's k8s-proxy declaratively instead of using `helm upgrade` manually. The sections below cover **ArgoCD** and **Flux CD**. --- -## Deploy Contour Ingress Controller +## Ingress with TLS Passthrough (Optional) -Keploy's k8s-proxy serves **HTTPS natively** on its backend port. You need an ingress controller that supports **TLS passthrough** — forwarding the encrypted connection directly to the k8s-proxy without terminating it. +Keploy's k8s-proxy serves **HTTPS natively** on its backend port. If you want to route external traffic through an ingress controller instead of a direct NodePort, you need one that supports **TLS passthrough** — forwarding the encrypted connection directly to the k8s-proxy without terminating it. -[Contour](https://projectcontour.io/) is a CNCF ingress controller powered by Envoy that supports this via its **HTTPProxy** CRD. +This section uses [Contour](https://projectcontour.io/) as an example. You can use any ingress controller that supports TLS passthrough (e.g. NGINX Ingress with `ssl-passthrough`, Traefik, HAProxy). If you're using a direct NodePort or LoadBalancer service, skip this section. ### Install Contour @@ -312,9 +309,7 @@ envoy NodePort 10.96.65.35 80:30081/TCP,443:30080/TCP 2m ## Create the Keploy Access Key Secret -> Skip if you already created this during the [local setup above](#2-connect-the-cluster-to-keploy-nodeport-setup). - -Go to the Keploy UI → **Clusters** → **Connect New Cluster**. Enter your cluster name and ingress URL (e.g. `https://your-host:30080`). Click **Connect** to get your access key. +If you haven't already created a cluster entry in the Keploy UI, go to **Clusters** → **Connect New Cluster**. Enter your cluster name and ingress URL. Click **Connect** to get your access key. ```bash kubectl create namespace keploy @@ -330,7 +325,7 @@ kubectl -n keploy create secret generic keploy-credentials \ ## Create the HTTPProxy for TLS Passthrough -The k8s-proxy serves HTTPS on its backend. A standard Kubernetes `Ingress` only supports HTTP backends, so you need Contour's **HTTPProxy** CRD with TLS passthrough. +If you're using Contour as your ingress controller, create an HTTPProxy resource to route traffic to the k8s-proxy via TLS passthrough. Create a file named `k8s-proxy-httpproxy.yaml`: @@ -382,12 +377,7 @@ Envoy looks at the **SNI** (Server Name Indication) — the hostname in the TLS ## Deploy with ArgoCD -If you already use ArgoCD to manage your applications, adding Keploy requires **just two files** — an ArgoCD Application YAML and a Contour HTTPProxy YAML. No changes to your existing app code or manifests. - -### Prerequisites - -1. **ArgoCD** installed on the cluster -2. **Contour** deployed ([see above](#deploy-contour-ingress-controller)) +If you already use ArgoCD to manage your applications, adding Keploy requires just an ArgoCD Application YAML for the k8s-proxy Helm chart. No changes to your existing app code or manifests. ### Install ArgoCD @@ -539,13 +529,7 @@ Your existing application code, manifests, and ArgoCD Applications remain **comp ## Deploy with Flux CD -Flux watches your Git repository and automatically applies changes to the cluster. Adding Keploy requires a **HelmRelease** for the k8s-proxy and an **HTTPProxy** for Contour routing. - -### Prerequisites - -1. **Flux CLI** installed ([installation guide](https://fluxcd.io/flux/installation/)) -2. **A Git repository** (GitHub, GitLab, Bitbucket) for Flux to watch -3. **Contour** deployed ([see above](#deploy-contour-ingress-controller)) +Flux watches your Git repository and automatically applies changes to the cluster. Adding Keploy requires a **HelmRelease** for the k8s-proxy Helm chart. ### Bootstrap Flux From a30246b4c8d3075cc2c7249c30e1db8014e6467d Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Wed, 1 Apr 2026 20:19:17 +0530 Subject: [PATCH 11/30] docs: remove reference repo link from Kubernetes guide Signed-off-by: Asish Kumar Co-Authored-By: Claude Opus 4.6 Signed-off-by: Asish Kumar --- versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md index 1f569f2c4..89d8454b6 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md @@ -710,5 +710,3 @@ To add Keploy to an existing Flux setup, you need: | Kubernetes Secret | `kubectl create secret` (manual) | Access key for Keploy cloud authentication | Your existing application manifests and Flux configurations remain **completely untouched**. Keploy works alongside your app — not inside it. - -For a reference implementation with both ArgoCD and Flux CD manifests, see the [keploy-k8s-demo](https://github.com/officialasishkumar/keploy-k8s-demo) repository. From 486972df2738661f3058aa1983108686ffe5389f Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Wed, 1 Apr 2026 20:20:19 +0530 Subject: [PATCH 12/30] docs: remove redundant access key secret section from GitOps guide - Already covered in the local setup section (step 2). Signed-off-by: Asish Kumar Co-Authored-By: Claude Opus 4.6 Signed-off-by: Asish Kumar --- .../version-4.0.0/keploy-cloud/kubernetes.md | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md index 89d8454b6..40e270706 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md @@ -307,22 +307,6 @@ envoy NodePort 10.96.65.35 80:30081/TCP,443:30080/TCP 2m --- -## Create the Keploy Access Key Secret - -If you haven't already created a cluster entry in the Keploy UI, go to **Clusters** → **Connect New Cluster**. Enter your cluster name and ingress URL. Click **Connect** to get your access key. - -```bash -kubectl create namespace keploy - -kubectl -n keploy create secret generic keploy-credentials \ - --from-literal=access-key="" -``` - -> [!WARNING] -> Never commit access keys to Git. Use `existingSecret` in Helm values or a secrets manager (Sealed Secrets, Vault, External Secrets Operator). - ---- - ## Create the HTTPProxy for TLS Passthrough If you're using Contour as your ingress controller, create an HTTPProxy resource to route traffic to the k8s-proxy via TLS passthrough. From 92d80b77b0e6a8eb2ada99602dde7b3c455254e3 Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Wed, 1 Apr 2026 20:25:33 +0530 Subject: [PATCH 13/30] docs: remove redundant summary tables from ArgoCD and Flux sections - The tables just repeated what the guide already covered. Signed-off-by: Asish Kumar Co-Authored-By: Claude Opus 4.6 Signed-off-by: Asish Kumar --- .../version-4.0.0/keploy-cloud/kubernetes.md | 25 ------------------- 1 file changed, 25 deletions(-) diff --git a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md index 40e270706..303f395e0 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md @@ -497,18 +497,6 @@ spec: Once deployed, your application appears in the Keploy UI under your cluster's **Deployments** tab. Click **Record** to start capturing live traffic. -### ArgoCD Summary - -To add Keploy to an existing ArgoCD setup, you need: - -| What | File | Purpose | -| ------------------ | -------------------------------- | ------------------------------------------ | -| ArgoCD Application | `keploy-k8s-proxy.yaml` | Deploy k8s-proxy from Keploy's Helm chart | -| Contour HTTPProxy | `k8s-proxy-httpproxy.yaml` | Route HTTPS traffic via TLS passthrough | -| Kubernetes Secret | `kubectl create secret` (manual) | Access key for Keploy cloud authentication | - -Your existing application code, manifests, and ArgoCD Applications remain **completely untouched**. Keploy works alongside your app — not inside it. - --- ## Deploy with Flux CD @@ -681,16 +669,3 @@ clusters/ ├── k8s-proxy-httpproxy.yaml # Contour HTTPProxy (TLS passthrough) └── your-other-apps/ # Your existing Flux manifests ``` - -### Flux CD Summary - -To add Keploy to an existing Flux setup, you need: - -| What | File | Purpose | -| ----------------- | -------------------------------- | ------------------------------------------ | -| Helm source | `keploy-source.yaml` | OCI Helm repository for Keploy charts | -| HelmRelease | `keploy-k8s-proxy.yaml` | Deploy k8s-proxy from Keploy's Helm chart | -| Contour HTTPProxy | `k8s-proxy-httpproxy.yaml` | Route HTTPS traffic via TLS passthrough | -| Kubernetes Secret | `kubectl create secret` (manual) | Access key for Keploy cloud authentication | - -Your existing application manifests and Flux configurations remain **completely untouched**. Keploy works alongside your app — not inside it. From 3e71f1442a515a7e89f1f941066efed836661ac9 Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Wed, 1 Apr 2026 20:28:46 +0530 Subject: [PATCH 14/30] docs: remove TLS passthrough architecture explanation - Not Keploy-specific, just Envoy/Contour internals. Signed-off-by: Asish Kumar Co-Authored-By: Claude Opus 4.6 Signed-off-by: Asish Kumar --- .../version-4.0.0/keploy-cloud/kubernetes.md | 19 ------------------- 1 file changed, 19 deletions(-) diff --git a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md index 303f395e0..fbe567346 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md @@ -338,25 +338,6 @@ Apply it: kubectl apply -f k8s-proxy-httpproxy.yaml ``` -### How TLS Passthrough Works - -```text -Client (Keploy cloud) - │ - │ HTTPS (encrypted) - ▼ -Envoy (port 30080) ← reads SNI hostname, does NOT decrypt - │ - │ forwards encrypted bytes - ▼ -k8s-proxy (port 8080) ← terminates TLS itself -``` - -Envoy looks at the **SNI** (Server Name Indication) — the hostname in the TLS Client Hello — to decide where to route the connection. It then passes the encrypted bytes straight through to the k8s-proxy without inspecting them. This is why the `fqdn` in the HTTPProxy must match the hostname the client uses. - -> [!NOTE] -> SNI matching means you **must** access the k8s-proxy using the hostname (e.g. `https://your-host:30080`), not the raw IP address. Add an `/etc/hosts` entry if needed. - --- ## Deploy with ArgoCD From 064e01114618d5a0c262e8ee819f2c3da280029d Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Wed, 1 Apr 2026 20:32:12 +0530 Subject: [PATCH 15/30] docs: remove Flux repo structure section - Developers know where they put their files. Signed-off-by: Asish Kumar Co-Authored-By: Claude Opus 4.6 Signed-off-by: Asish Kumar --- .../version-4.0.0/keploy-cloud/kubernetes.md | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md index fbe567346..b74d464b0 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md @@ -637,16 +637,3 @@ curl -sk https://:30080/healthz ``` ✅ Open the Keploy UI → **Clusters** → your cluster should show as **Connected**. You can now record and replay traffic on any deployment. - -### Flux Git Repository Structure - -After adding Keploy, your Flux repo should look like: - -```text -clusters/ -└── staging/ - ├── keploy-source.yaml # OCI Helm repository for Keploy - ├── keploy-k8s-proxy.yaml # HelmRelease for k8s-proxy - ├── k8s-proxy-httpproxy.yaml # Contour HTTPProxy (TLS passthrough) - └── your-other-apps/ # Your existing Flux manifests -``` From 860d1ec932c2093801835768a7fc8b813c811c6f Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Wed, 1 Apr 2026 20:41:26 +0530 Subject: [PATCH 16/30] docs: remove ArgoCD/Flux install instructions from GitOps guides - Not Keploy-specific. Users already have ArgoCD/Flux installed or can follow their own docs for setup. - Keep only the Keploy-specific manifests and steps. Signed-off-by: Asish Kumar Co-Authored-By: Claude Opus 4.6 Signed-off-by: Asish Kumar --- .../version-4.0.0/keploy-cloud/kubernetes.md | 52 +------------------ 1 file changed, 2 insertions(+), 50 deletions(-) diff --git a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md index b74d464b0..d46fe0639 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md @@ -342,32 +342,7 @@ kubectl apply -f k8s-proxy-httpproxy.yaml ## Deploy with ArgoCD -If you already use ArgoCD to manage your applications, adding Keploy requires just an ArgoCD Application YAML for the k8s-proxy Helm chart. No changes to your existing app code or manifests. - -### Install ArgoCD - -> Skip this if ArgoCD is already installed on your cluster. - -```bash -kubectl create namespace argocd -kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml -kubectl -n argocd rollout status deployment/argocd-server -``` - -Get the admin password: - -```bash -kubectl -n argocd get secret argocd-initial-admin-secret \ - -o jsonpath="{.data.password}" | base64 -d; echo -``` - -Access the ArgoCD UI: - -```bash -kubectl -n argocd port-forward svc/argocd-server 8443:443 & -``` - -Open `https://localhost:8443` in your browser. Login with username `admin` and the password from above. +Adding Keploy requires just an ArgoCD Application YAML for the k8s-proxy Helm chart. No changes to your existing app code or manifests. ### Create the ArgoCD Application for k8s-proxy @@ -482,30 +457,7 @@ Once deployed, your application appears in the Keploy UI under your cluster's ** ## Deploy with Flux CD -Flux watches your Git repository and automatically applies changes to the cluster. Adding Keploy requires a **HelmRelease** for the k8s-proxy Helm chart. - -### Bootstrap Flux - -> Skip this if Flux is already installed on your cluster. - -Bootstrap Flux with your GitHub repository: - -```bash -flux bootstrap github \ - --owner= \ - --repository= \ - --branch=main \ - --path=clusters/staging \ - --personal -``` - -This installs Flux on your cluster and creates the `clusters/staging` directory in your Git repo where you'll add Keploy manifests. - -Verify Flux is running: - -```bash -flux check -``` +Adding Keploy requires a **HelmRepository** source and a **HelmRelease** for the k8s-proxy Helm chart. ### Add the Keploy Helm Repository Source From 947132cebfeb434060967236b5841c9449857ab1 Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Wed, 1 Apr 2026 20:41:45 +0530 Subject: [PATCH 17/30] Revert "docs: remove ArgoCD/Flux install instructions from GitOps guides" This reverts commit beb5f1a6a1dd4a9049219d2e773f2a7316e8b236. Signed-off-by: Asish Kumar --- .../version-4.0.0/keploy-cloud/kubernetes.md | 52 ++++++++++++++++++- 1 file changed, 50 insertions(+), 2 deletions(-) diff --git a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md index d46fe0639..b74d464b0 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md @@ -342,7 +342,32 @@ kubectl apply -f k8s-proxy-httpproxy.yaml ## Deploy with ArgoCD -Adding Keploy requires just an ArgoCD Application YAML for the k8s-proxy Helm chart. No changes to your existing app code or manifests. +If you already use ArgoCD to manage your applications, adding Keploy requires just an ArgoCD Application YAML for the k8s-proxy Helm chart. No changes to your existing app code or manifests. + +### Install ArgoCD + +> Skip this if ArgoCD is already installed on your cluster. + +```bash +kubectl create namespace argocd +kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml +kubectl -n argocd rollout status deployment/argocd-server +``` + +Get the admin password: + +```bash +kubectl -n argocd get secret argocd-initial-admin-secret \ + -o jsonpath="{.data.password}" | base64 -d; echo +``` + +Access the ArgoCD UI: + +```bash +kubectl -n argocd port-forward svc/argocd-server 8443:443 & +``` + +Open `https://localhost:8443` in your browser. Login with username `admin` and the password from above. ### Create the ArgoCD Application for k8s-proxy @@ -457,7 +482,30 @@ Once deployed, your application appears in the Keploy UI under your cluster's ** ## Deploy with Flux CD -Adding Keploy requires a **HelmRepository** source and a **HelmRelease** for the k8s-proxy Helm chart. +Flux watches your Git repository and automatically applies changes to the cluster. Adding Keploy requires a **HelmRelease** for the k8s-proxy Helm chart. + +### Bootstrap Flux + +> Skip this if Flux is already installed on your cluster. + +Bootstrap Flux with your GitHub repository: + +```bash +flux bootstrap github \ + --owner= \ + --repository= \ + --branch=main \ + --path=clusters/staging \ + --personal +``` + +This installs Flux on your cluster and creates the `clusters/staging` directory in your Git repo where you'll add Keploy manifests. + +Verify Flux is running: + +```bash +flux check +``` ### Add the Keploy Helm Repository Source From dd0e4aa83bd2ac12ec40bedc43bd2670a158239e Mon Sep 17 00:00:00 2001 From: Neha Gupta Date: Wed, 1 Apr 2026 20:08:29 +0530 Subject: [PATCH 18/30] docs: fix MCP type to http, add recording tools and workflow (#817) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: fix MCP type to http, add recording tools and workflow - Fix Claude Code config: type "url" → type "http" (StreamableHTTP) - Add 4 new recording/schema tools to the tools table (43+ total) - Add "Using Recorded Traffic for Better Tests" section with agent workflow - Update tool count from 39+ to 43+ Co-Authored-By: Claude Opus 4.6 (1M context) Signed-off-by: slayerjain * fix: run prettier on agent-test-generation.md Co-Authored-By: Claude Opus 4.6 (1M context) Signed-off-by: slayerjain * fix: wrap k8s-proxy in backticks to fix Vale spelling lint Co-Authored-By: Claude Opus 4.6 (1M context) Signed-off-by: slayerjain --------- Signed-off-by: slayerjain Co-authored-by: slayerjain Co-authored-by: Claude Opus 4.6 (1M context) Signed-off-by: Asish Kumar --- .../running-keploy/agent-test-generation.md | 49 +++++++++++++------ 1 file changed, 35 insertions(+), 14 deletions(-) diff --git a/versioned_docs/version-4.0.0/running-keploy/agent-test-generation.md b/versioned_docs/version-4.0.0/running-keploy/agent-test-generation.md index 9f49a5ae7..247ca204c 100644 --- a/versioned_docs/version-4.0.0/running-keploy/agent-test-generation.md +++ b/versioned_docs/version-4.0.0/running-keploy/agent-test-generation.md @@ -74,18 +74,22 @@ The MCP endpoint is built into the Keploy API server at `/client/v1/mcp`. Tools ### Available Tools -| Tool | What it does | -| -------------------- | ------------------------------------------------------------------------ | -| `listApps` | List all applications | -| `createApp` | Create a new application | -| `generateTestSuites` | Trigger AI test generation from an OpenAPI spec | -| `runTestSuites` | Execute test suites against a target API | -| `listTestSuites` | List test suites for an app | -| `createTestSuite` | Create a test suite from steps JSON | -| `generate_and_wait` | Generate tests and wait for completion (composite) | -| `run_and_report` | Run tests and return results with failures and coverage gaps (composite) | -| `get_coverage_gaps` | Get uncovered endpoints with prioritized suggestions | -| _...39+ API tools_ | Every `/client/v1` endpoint is available as an MCP tool | +| Tool | What it does | +| ------------------------ | ------------------------------------------------------------------------ | +| `listApps` | List all applications | +| `createApp` | Create a new application | +| `generateTestSuites` | Trigger AI test generation from an OpenAPI spec | +| `runTestSuites` | Execute test suites against a target API | +| `listTestSuites` | List test suites for an app | +| `createTestSuite` | Create a test suite from steps JSON | +| `listAppsWithRecordings` | List apps that have integration test recordings from Keploy | +| `listRecordings` | List recording sessions (test sets) for an app | +| `getRecording` | Get recorded HTTP request/response pairs and dependency mocks | +| `getGeneratedSchema` | Get the auto-generated OpenAPI schema from captured traffic | +| `generate_and_wait` | Generate tests and wait for completion (composite) | +| `run_and_report` | Run tests and return results with failures and coverage gaps (composite) | +| `get_coverage_gaps` | Get uncovered endpoints with prioritized suggestions | +| _...43+ API tools_ | Every `/client/v1` endpoint is available as an MCP tool | :::caution API Key Security The examples below include an API key in configuration files. **Do not commit API keys to version control.** Use environment variables or add the config file to `.gitignore`. For CI/CD, use secret management. @@ -97,13 +101,13 @@ The examples below use the Keploy Cloud URL (`https://api.keploy.io`). If you're #### Claude Code -Add to your Claude Code MCP settings (`~/.claude/settings.json` or project-level). Note: Claude Code requires the `type: url` field (other clients do not). +Add to your Claude Code MCP settings (`~/.claude/settings.json` or project-level). Note: Claude Code requires the `type: http` field for StreamableHTTP transport (other clients do not need it). ```json { "mcpServers": { "keploy": { - "type": "url", + "type": "http", "url": "https://api.keploy.io/client/v1/mcp", "headers": { "Authorization": "Bearer kep_YOUR_API_KEY" @@ -184,6 +188,23 @@ Antigravity (formerly Windsurf) supports MCP servers. Add to your Antigravity MC 6. The agent reads the coverage gaps and generates additional test suites for uncovered endpoints 7. This loop continues until coverage targets are met +### Using Recorded Traffic for Better Tests + +If you use Keploy's integration testing (`k8s-proxy` or local agent), recorded HTTP traffic is available to AI agents via MCP. This produces higher-quality test suites because the AI can reference real request/response patterns instead of guessing from the OpenAPI spec alone. + +``` +Agent workflow: +1. listAppsWithRecordings → find apps with real traffic data +2. listRecordings → browse recording sessions +3. getRecording → get actual HTTP request/response pairs + dependency mocks +4. getGeneratedSchema → get the OpenAPI spec auto-generated from traffic +5. generate_and_wait (with examples from step 3) → produce realistic test suites +``` + +Ask your agent: + +> "Use the Keploy MCP tools to find apps with recorded traffic, fetch the recordings, and use them as examples to generate comprehensive API tests" + The MCP endpoint uses the same API key as the REST API and accepts the same two authentication methods. The examples above use `Authorization: Bearer kep_...`, but you can also use `X-API-Key: kep_...` as an alternative (replace the `Authorization` header with `"X-API-Key": "kep_YOUR_API_KEY"` in the config). See the [Public API docs](/docs/running-keploy/public-api/) for details. All tools proxy to `/client/v1` endpoints using the caller's credentials. ## Workflow From 9119325f7978ae63f4196ea1355e3c3a1c9f74ef Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Wed, 1 Apr 2026 22:57:48 +0530 Subject: [PATCH 19/30] docs: fix broken anchor link in Flux TLS passthrough note - Fixed broken `#how-tls-passthrough-works` link in Flux CD section to point to the correct `#ingress-with-tls-passthrough-optional` anchor. Signed-off-by: Asish Kumar Co-Authored-By: Claude Opus 4.6 Signed-off-by: Asish Kumar --- versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md index b74d464b0..2fc4a42da 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md @@ -595,7 +595,7 @@ spec: Replace `` with the same hostname used in `keploy.ingressUrl`. > [!NOTE] -> TLS passthrough is required because the k8s-proxy serves HTTPS natively. Envoy forwards the encrypted connection directly to the k8s-proxy without terminating TLS. See the [TLS passthrough explanation](#how-tls-passthrough-works) above. +> TLS passthrough is required because the k8s-proxy serves HTTPS natively. Envoy forwards the encrypted connection directly to the k8s-proxy without terminating TLS. See the [TLS passthrough explanation](#ingress-with-tls-passthrough-optional) above. ### Push and Let Flux Reconcile From 64a445fcc1baaec0600c20f03db0ee7dfde2f898 Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Wed, 1 Apr 2026 23:08:30 +0530 Subject: [PATCH 20/30] docs: fix Vale linter errors in Kubernetes and GitOps guides MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Added technical terms (kubectl, namespace, passthrough, HTTPProxy, Traefik, HAProxy, hostname, repo, etc.) to Vale vocabulary accept list. - Fixed em dash spacing (` — ` → `—`) to satisfy Google.EmDash rule. - Wrapped bare `k8s-proxy` references in backticks to avoid false Google.Units matches on `8s`. Signed-off-by: Asish Kumar Co-Authored-By: Claude Opus 4.6 Signed-off-by: Asish Kumar --- .../config/vocabularies/Base/accept.txt | 14 ++++++++ .../keploy-cloud/gitops-argocd.md | 34 +++++++++---------- .../version-4.0.0/keploy-cloud/gitops-flux.md | 30 ++++++++-------- .../version-4.0.0/keploy-cloud/kubernetes.md | 28 +++++++-------- 4 files changed, 60 insertions(+), 46 deletions(-) diff --git a/vale_styles/config/vocabularies/Base/accept.txt b/vale_styles/config/vocabularies/Base/accept.txt index cf432f4c1..304c6332a 100644 --- a/vale_styles/config/vocabularies/Base/accept.txt +++ b/vale_styles/config/vocabularies/Base/accept.txt @@ -4,6 +4,7 @@ APIs Appium Applitools Arkade +ArgoCD Asana Auditability borderRadius @@ -13,6 +14,7 @@ config containerName custom_functions DBs +declaratively Deduplication distros dockerfile @@ -23,13 +25,16 @@ GitHub gjson graphql Hacktoberfest +HAProxy Hasura header_contains header_equal header_exists header_matches +[Hh]ostname Hoppscotch html +HTTPProxy Idempotency Jacoco JBehave @@ -38,6 +43,8 @@ json_contains json_equal json_path JUnit +kubectl +kubernetes test-gen [Kk]eploy LLMs @@ -45,15 +52,18 @@ mabl middleware mock Mockaroo +[Nn]amespace[s]? Nhost npm NUnit Onboarding params +[Pp]assthrough Postgres Pytest realtime Redis +[Rr]epo Reqnroll SDK signin @@ -70,11 +80,15 @@ testmode Testrun testsets timeFreezing +Traefik Twilio Unittest url UTGen UUIDs +VM +VMs +VM's wiremessages Woohoo wsl diff --git a/versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md b/versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md index a798500ec..47a687067 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md @@ -24,9 +24,9 @@ import ProductTier from '@site/src/components/ProductTier'; -This guide walks you through deploying **Keploy's k8s-proxy** using **ArgoCD** (GitOps) on a Kubernetes cluster, with **Contour** as the ingress controller. +This guide walks you through deploying **Keploy's `k8s-proxy`** using **ArgoCD** (GitOps) on a Kubernetes cluster, with **Contour** as the ingress controller. -If you already use ArgoCD to manage your applications, adding Keploy requires **just two files** — an ArgoCD Application YAML and a Contour HTTPProxy YAML. No changes to your existing app code or manifests. +If you already use ArgoCD to manage your applications, adding Keploy requires **just two files**—an ArgoCD Application YAML and a Contour HTTPProxy YAML. No changes to your existing app code or manifests. > [!NOTE] > This guide assumes you have already completed the [Kubernetes Local Setup](/docs/keploy-cloud/kubernetes-local-setup) and have a running Kind cluster with Keploy connected. @@ -73,7 +73,7 @@ Open `https://localhost:8443` in your browser. Login with username `admin` and t ## 2) Deploy Contour ingress controller -Keploy's k8s-proxy serves **HTTPS natively** on its backend port. You need an ingress controller that supports **TLS passthrough** — forwarding the encrypted connection directly to the k8s-proxy without terminating it. +Keploy's `k8s-proxy` serves **HTTPS natively** on its backend port. You need an ingress controller that supports **TLS passthrough**—forwarding the encrypted connection directly to the `k8s-proxy` without terminating it. [Contour](https://projectcontour.io/) is a CNCF ingress controller powered by Envoy that supports this via its **HTTPProxy** CRD. @@ -105,7 +105,7 @@ kubectl patch svc envoy -n projectcontour --type='json' -p='[ This puts the **HTTPS listener on NodePort 30080** (mapped to the host) and the HTTP listener on 30081. > [!TIP] -> For cloud clusters (EKS/GKE/AKS), skip this patch. The default LoadBalancer type works — your cloud provider assigns an external IP automatically. +> For cloud clusters (EKS/GKE/AKS), skip this patch. The default LoadBalancer type works—your cloud provider assigns an external IP automatically. ### 2.3 Verify Contour @@ -141,7 +141,7 @@ kubectl -n keploy create secret generic keploy-credentials \ --- -## 4) Create the ArgoCD Application for k8s-proxy +## 4) Create the ArgoCD Application for `k8s-proxy` Create a file named `keploy-k8s-proxy.yaml`: @@ -192,8 +192,8 @@ spec: Replace: -- `` — the name you entered in the Keploy UI -- `` — the hostname that resolves to your cluster (e.g. your VM IP or a DNS name) +- ``—the name you entered in the Keploy UI +- ``—the hostname that resolves to your cluster (e.g. your VM IP or a DNS name) Apply it: @@ -205,7 +205,7 @@ kubectl apply -f keploy-k8s-proxy.yaml ## 5) Create the HTTPProxy for TLS passthrough -The k8s-proxy serves HTTPS on its backend. A standard Kubernetes `Ingress` only supports HTTP backends, so you need Contour's **HTTPProxy** CRD with TLS passthrough. +The `k8s-proxy` serves HTTPS on its backend. A standard Kubernetes `Ingress` only supports HTTP backends, so you need Contour's **HTTPProxy** CRD with TLS passthrough. Create a file named `k8s-proxy-httpproxy.yaml`: @@ -248,10 +248,10 @@ Envoy (port 30080) ← reads SNI hostname, does NOT decrypt k8s-proxy (port 8080) ← terminates TLS itself ``` -Envoy looks at the **SNI** (Server Name Indication) — the hostname in the TLS Client Hello — to decide where to route the connection. It then passes the encrypted bytes straight through to the k8s-proxy without inspecting them. This is why the `fqdn` in the HTTPProxy must match the hostname the client uses. +Envoy looks at the **SNI** (Server Name Indication)—the hostname in the TLS Client Hello—to decide where to route the connection. It then passes the encrypted bytes straight through to the `k8s-proxy` without inspecting them. This is why the `fqdn` in the HTTPProxy must match the hostname the client uses. > [!NOTE] -> SNI matching means you **must** access the k8s-proxy using the hostname (e.g. `https://your-host:30080`), not the raw IP address. Add an `/etc/hosts` entry if needed. +> SNI matching means you **must** access the `k8s-proxy` using the hostname (e.g. `https://your-host:30080`), not the raw IP address. Add an `/etc/hosts` entry if needed. --- @@ -279,7 +279,7 @@ curl -sk https://:30080/healthz ## 7) Deploy your application with ArgoCD -Your application needs **no changes** for Keploy. Deploy it as you normally would with ArgoCD — either from Helm charts or raw K8s manifests: +Your application needs **no changes** for Keploy. Deploy it as you normally would with ArgoCD—either from Helm charts or raw `K8s` manifests: ```yaml apiVersion: argoproj.io/v1alpha1 @@ -312,12 +312,12 @@ Once deployed, your application appears in the Keploy UI under your cluster's ** To add Keploy to an existing ArgoCD setup, you need: -| What | File | Purpose | -| ------------------ | -------------------------------- | ------------------------------------------ | -| ArgoCD Application | `keploy-k8s-proxy.yaml` | Deploy k8s-proxy from Keploy's Helm chart | -| Contour HTTPProxy | `k8s-proxy-httpproxy.yaml` | Route HTTPS traffic via TLS passthrough | -| Kubernetes Secret | `kubectl create secret` (manual) | Access key for Keploy cloud authentication | +| What | File | Purpose | +| ------------------ | -------------------------------- | ------------------------------------------- | +| ArgoCD Application | `keploy-k8s-proxy.yaml` | Deploy `k8s-proxy` from Keploy's Helm chart | +| Contour HTTPProxy | `k8s-proxy-httpproxy.yaml` | Route HTTPS traffic via TLS passthrough | +| Kubernetes Secret | `kubectl create secret` (manual) | Access key for Keploy cloud authentication | -Your existing application code, manifests, and ArgoCD Applications remain **completely untouched**. Keploy works alongside your app — not inside it. +Your existing application code, manifests, and ArgoCD Applications remain **completely untouched**. Keploy works alongside your app—not inside it. For a complete reference implementation, see the [keploy-argocd-demo](https://github.com/officialasishkumar/keploy-argocd-demo) repository. diff --git a/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md b/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md index 47ffdd980..3255f4e21 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md @@ -24,12 +24,12 @@ import ProductTier from '@site/src/components/ProductTier'; -This guide walks you through deploying **Keploy's k8s-proxy** using **Flux CD** (GitOps) on a Kubernetes cluster, with **Contour** as the ingress controller. +This guide walks you through deploying **Keploy's `k8s-proxy`** using **Flux CD** (GitOps) on a Kubernetes cluster, with **Contour** as the ingress controller. -Flux watches your Git repository and automatically applies changes to the cluster. Adding Keploy requires a **HelmRelease** for the k8s-proxy and an **HTTPProxy** for Contour routing. +Flux watches your Git repository and automatically applies changes to the cluster. Adding Keploy requires a **HelmRelease** for the `k8s-proxy` and an **HTTPProxy** for Contour routing. > [!NOTE] -> This guide assumes you have already completed the [Kubernetes Local Setup](/docs/keploy-cloud/kubernetes-local-setup) and have a running Kind cluster with Keploy connected. For Contour setup details, see the [ArgoCD guide](/docs/keploy-cloud/gitops-argocd#2-deploy-contour-ingress-controller) — the Contour steps are identical. +> This guide assumes you have already completed the [Kubernetes Local Setup](/docs/keploy-cloud/kubernetes-local-setup) and have a running Kind cluster with Keploy connected. For Contour setup details, see the [ArgoCD guide](/docs/keploy-cloud/gitops-argocd#2-deploy-contour-ingress-controller)—the Contour steps are identical. --- @@ -107,7 +107,7 @@ spec: --- -## 4) Create the HelmRelease for k8s-proxy +## 4) Create the HelmRelease for `k8s-proxy` Create `clusters/staging/keploy-k8s-proxy.yaml` in your Git repo: @@ -152,8 +152,8 @@ spec: Replace: -- `` — the name you entered in the Keploy UI -- `` — the hostname that resolves to your cluster +- ``—the name you entered in the Keploy UI +- ``—the hostname that resolves to your cluster --- @@ -181,7 +181,7 @@ spec: Replace `` with the same hostname used in `keploy.ingressUrl`. > [!NOTE] -> TLS passthrough is required because the k8s-proxy serves HTTPS natively. Envoy forwards the encrypted connection directly to the k8s-proxy without terminating TLS. See the [ArgoCD guide](/docs/keploy-cloud/gitops-argocd#5-create-the-httpproxy-for-tls-passthrough) for a detailed explanation. +> TLS passthrough is required because the `k8s-proxy` serves HTTPS natively. Envoy forwards the encrypted connection directly to the `k8s-proxy` without terminating TLS. See the [ArgoCD guide](/docs/keploy-cloud/gitops-argocd#5-create-the-httpproxy-for-tls-passthrough) for a detailed explanation. --- @@ -249,13 +249,13 @@ clusters/ To add Keploy to an existing Flux setup, you need: -| What | File | Purpose | -| ----------------- | -------------------------------- | ------------------------------------------ | -| Helm source | `keploy-source.yaml` | OCI Helm repository for Keploy charts | -| HelmRelease | `keploy-k8s-proxy.yaml` | Deploy k8s-proxy from Keploy's Helm chart | -| Contour HTTPProxy | `k8s-proxy-httpproxy.yaml` | Route HTTPS traffic via TLS passthrough | -| Kubernetes Secret | `kubectl create secret` (manual) | Access key for Keploy cloud authentication | +| What | File | Purpose | +| ----------------- | -------------------------------- | ------------------------------------------- | +| Helm source | `keploy-source.yaml` | OCI Helm repository for Keploy charts | +| HelmRelease | `keploy-k8s-proxy.yaml` | Deploy `k8s-proxy` from Keploy's Helm chart | +| Contour HTTPProxy | `k8s-proxy-httpproxy.yaml` | Route HTTPS traffic via TLS passthrough | +| Kubernetes Secret | `kubectl create secret` (manual) | Access key for Keploy cloud authentication | -Your existing application manifests and Flux configurations remain **completely untouched**. Keploy works alongside your app — not inside it. +Your existing application manifests and Flux configurations remain **completely untouched**. Keploy works alongside your app—not inside it. -For a reference implementation with both ArgoCD and Flux CD manifests, see the [keploy-argocd-demo](https://github.com/officialasishkumar/keploy-argocd-demo) repository — the `flux/` directory contains ready-to-use HelmRepository, HelmRelease, and HTTPProxy manifests for staging and production. +For a reference implementation with both ArgoCD and Flux CD manifests, see the [keploy-argocd-demo](https://github.com/officialasishkumar/keploy-argocd-demo) repository—the `flux/` directory contains ready-to-use HelmRepository, HelmRelease, and HTTPProxy manifests for staging and production. diff --git a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md index 2fc4a42da..7cb364007 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md @@ -251,13 +251,13 @@ kube-system coredns-7d764666f9-r82lr 1/1 R ## GitOps Deployment -If you use a GitOps tool to manage your Kubernetes cluster, you can deploy Keploy's k8s-proxy declaratively instead of using `helm upgrade` manually. The sections below cover **ArgoCD** and **Flux CD**. +If you use a GitOps tool to manage your Kubernetes cluster, you can deploy Keploy's `k8s-proxy` declaratively instead of using `helm upgrade` manually. The sections below cover **ArgoCD** and **Flux CD**. --- ## Ingress with TLS Passthrough (Optional) -Keploy's k8s-proxy serves **HTTPS natively** on its backend port. If you want to route external traffic through an ingress controller instead of a direct NodePort, you need one that supports **TLS passthrough** — forwarding the encrypted connection directly to the k8s-proxy without terminating it. +Keploy's `k8s-proxy` serves **HTTPS natively** on its backend port. If you want to route external traffic through an ingress controller instead of a direct NodePort, you need one that supports **TLS passthrough**—forwarding the encrypted connection directly to the `k8s-proxy` without terminating it. This section uses [Contour](https://projectcontour.io/) as an example. You can use any ingress controller that supports TLS passthrough (e.g. NGINX Ingress with `ssl-passthrough`, Traefik, HAProxy). If you're using a direct NodePort or LoadBalancer service, skip this section. @@ -289,7 +289,7 @@ kubectl patch svc envoy -n projectcontour --type='json' -p='[ This puts the **HTTPS listener on NodePort 30080** (mapped to the host) and the HTTP listener on 30081. > [!TIP] -> For cloud clusters (EKS/GKE/AKS), skip this patch. The default LoadBalancer type works — your cloud provider assigns an external IP automatically. +> For cloud clusters (EKS/GKE/AKS), skip this patch. The default LoadBalancer type works—your cloud provider assigns an external IP automatically. ### Verify Contour @@ -309,7 +309,7 @@ envoy NodePort 10.96.65.35 80:30081/TCP,443:30080/TCP 2m ## Create the HTTPProxy for TLS Passthrough -If you're using Contour as your ingress controller, create an HTTPProxy resource to route traffic to the k8s-proxy via TLS passthrough. +If you're using Contour as your ingress controller, create an HTTPProxy resource to route traffic to the `k8s-proxy` via TLS passthrough. Create a file named `k8s-proxy-httpproxy.yaml`: @@ -342,7 +342,7 @@ kubectl apply -f k8s-proxy-httpproxy.yaml ## Deploy with ArgoCD -If you already use ArgoCD to manage your applications, adding Keploy requires just an ArgoCD Application YAML for the k8s-proxy Helm chart. No changes to your existing app code or manifests. +If you already use ArgoCD to manage your applications, adding Keploy requires just an ArgoCD Application YAML for the `k8s-proxy` Helm chart. No changes to your existing app code or manifests. ### Install ArgoCD @@ -369,7 +369,7 @@ kubectl -n argocd port-forward svc/argocd-server 8443:443 & Open `https://localhost:8443` in your browser. Login with username `admin` and the password from above. -### Create the ArgoCD Application for k8s-proxy +### Create the ArgoCD Application for `k8s-proxy` Create a file named `keploy-k8s-proxy.yaml`: @@ -420,8 +420,8 @@ spec: Replace: -- `` — the name you entered in the Keploy UI -- `` — the hostname that resolves to your cluster (e.g. your VM IP or a DNS name) +- ``—the name you entered in the Keploy UI +- ``—the hostname that resolves to your cluster (e.g. your VM IP or a DNS name) Apply it: @@ -451,7 +451,7 @@ curl -sk https://:30080/healthz ### Deploy Your Application with ArgoCD -Your application needs **no changes** for Keploy. Deploy it as you normally would with ArgoCD — either from Helm charts or raw K8s manifests: +Your application needs **no changes** for Keploy. Deploy it as you normally would with ArgoCD—either from Helm charts or raw `K8s` manifests: ```yaml apiVersion: argoproj.io/v1alpha1 @@ -482,7 +482,7 @@ Once deployed, your application appears in the Keploy UI under your cluster's ** ## Deploy with Flux CD -Flux watches your Git repository and automatically applies changes to the cluster. Adding Keploy requires a **HelmRelease** for the k8s-proxy Helm chart. +Flux watches your Git repository and automatically applies changes to the cluster. Adding Keploy requires a **HelmRelease** for the `k8s-proxy` Helm chart. ### Bootstrap Flux @@ -523,7 +523,7 @@ spec: url: oci://docker.io/keploy ``` -### Create the HelmRelease for k8s-proxy +### Create the HelmRelease for `k8s-proxy` Create `clusters/staging/keploy-k8s-proxy.yaml` in your Git repo: @@ -568,8 +568,8 @@ spec: Replace: -- `` — the name you entered in the Keploy UI -- `` — the hostname that resolves to your cluster +- ``—the name you entered in the Keploy UI +- ``—the hostname that resolves to your cluster ### Create the HTTPProxy for TLS Passthrough @@ -595,7 +595,7 @@ spec: Replace `` with the same hostname used in `keploy.ingressUrl`. > [!NOTE] -> TLS passthrough is required because the k8s-proxy serves HTTPS natively. Envoy forwards the encrypted connection directly to the k8s-proxy without terminating TLS. See the [TLS passthrough explanation](#ingress-with-tls-passthrough-optional) above. +> TLS passthrough is required because the `k8s-proxy` serves HTTPS natively. Envoy forwards the encrypted connection directly to the `k8s-proxy` without terminating TLS. See the [TLS passthrough explanation](#ingress-with-tls-passthrough-optional) above. ### Push and Let Flux Reconcile From 529d925e360bad9a15d263f8ebd99b8b445468de Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Wed, 1 Apr 2026 23:43:57 +0530 Subject: [PATCH 21/30] docs: fix helm values schema and update stale links - Updated Helm CLI example in section 2.2 to use canonical nested `keploy.accessKey`, `keploy.clusterName`, etc. instead of top-level keys, matching the chart's values.yaml schema and the GitOps sections. - Updated prerequisite links in gitops-argocd.md and gitops-flux.md from orphaned `/docs/keploy-cloud/kubernetes-local-setup` to the canonical `/docs/keploy-cloud/kubernetes` page. Signed-off-by: Asish Kumar Co-Authored-By: Claude Opus 4.6 Signed-off-by: Asish Kumar --- .../version-4.0.0/keploy-cloud/gitops-argocd.md | 2 +- versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md | 2 +- versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md | 8 ++++---- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md b/versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md index 47a687067..0ca9eea96 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md @@ -29,7 +29,7 @@ This guide walks you through deploying **Keploy's `k8s-proxy`** using **ArgoCD** If you already use ArgoCD to manage your applications, adding Keploy requires **just two files**—an ArgoCD Application YAML and a Contour HTTPProxy YAML. No changes to your existing app code or manifests. > [!NOTE] -> This guide assumes you have already completed the [Kubernetes Local Setup](/docs/keploy-cloud/kubernetes-local-setup) and have a running Kind cluster with Keploy connected. +> This guide assumes you have already completed the [Kubernetes Setup](/docs/keploy-cloud/kubernetes) and have a running Kind cluster with Keploy connected. --- diff --git a/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md b/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md index 3255f4e21..a26cc3da7 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md @@ -29,7 +29,7 @@ This guide walks you through deploying **Keploy's `k8s-proxy`** using **Flux CD* Flux watches your Git repository and automatically applies changes to the cluster. Adding Keploy requires a **HelmRelease** for the `k8s-proxy` and an **HTTPProxy** for Contour routing. > [!NOTE] -> This guide assumes you have already completed the [Kubernetes Local Setup](/docs/keploy-cloud/kubernetes-local-setup) and have a running Kind cluster with Keploy connected. For Contour setup details, see the [ArgoCD guide](/docs/keploy-cloud/gitops-argocd#2-deploy-contour-ingress-controller)—the Contour steps are identical. +> This guide assumes you have already completed the [Kubernetes Setup](/docs/keploy-cloud/kubernetes) and have a running Kind cluster with Keploy connected. For Contour setup details, see the [ArgoCD guide](/docs/keploy-cloud/gitops-argocd#2-deploy-contour-ingress-controller)—the Contour steps are identical. --- diff --git a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md index 7cb364007..e0d20386c 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md @@ -138,11 +138,11 @@ Example command: helm upgrade --install k8s-proxy oci://docker.io/keploy/k8s-proxy-chart --version \ --namespace keploy \ --create-namespace \ - --set accessKey="" \ - --set clusterName="doc-test-2" \ - --set apiServerUrl="https://api.keploy.io" \ + --set keploy.accessKey="" \ + --set keploy.clusterName="doc-test-2" \ + --set keploy.apiServerUrl="https://api.keploy.io" \ --set service.type=NodePort \ - --set ingressUrl="http://localhost:30080" \ + --set keploy.ingressUrl="http://localhost:30080" \ --set service.nodePort=30080 \ --set environment="prod" \ --set proxy.insecure.enabled=true From 95c313a47bfee2bba7cff711cf02e57e63f203e6 Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Wed, 1 Apr 2026 23:47:25 +0530 Subject: [PATCH 22/30] docs: revert helm CLI values to top-level keys - Reverted section 2.2 Helm CLI example back to top-level accessKey, clusterName, etc. Both schemas work due to template fallback logic. Signed-off-by: Asish Kumar Co-Authored-By: Claude Opus 4.6 Signed-off-by: Asish Kumar --- versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md index e0d20386c..7cb364007 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md @@ -138,11 +138,11 @@ Example command: helm upgrade --install k8s-proxy oci://docker.io/keploy/k8s-proxy-chart --version \ --namespace keploy \ --create-namespace \ - --set keploy.accessKey="" \ - --set keploy.clusterName="doc-test-2" \ - --set keploy.apiServerUrl="https://api.keploy.io" \ + --set accessKey="" \ + --set clusterName="doc-test-2" \ + --set apiServerUrl="https://api.keploy.io" \ --set service.type=NodePort \ - --set keploy.ingressUrl="http://localhost:30080" \ + --set ingressUrl="http://localhost:30080" \ --set service.nodePort=30080 \ --set environment="prod" \ --set proxy.insecure.enabled=true From 9743ee9c1267e20cdb2c72746ab8ed9b402323e9 Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Wed, 1 Apr 2026 23:59:35 +0530 Subject: [PATCH 23/30] docs(gitops): clarify ingressUrl port for cloud clusters - Added note that cloud clusters (EKS/GKE/AKS) should use :443 instead of :30080 in the ingressUrl, since :30080 is specific to NodePort/Kind setups. Signed-off-by: Asish Kumar Co-Authored-By: Claude Opus 4.6 Signed-off-by: Asish Kumar --- versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md | 1 + versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md | 1 + 2 files changed, 2 insertions(+) diff --git a/versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md b/versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md index 0ca9eea96..4f9c66fff 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md @@ -194,6 +194,7 @@ Replace: - ``—the name you entered in the Keploy UI - ``—the hostname that resolves to your cluster (e.g. your VM IP or a DNS name) +- `:30080`—the NodePort from the Contour patch above. For cloud clusters (EKS/GKE/AKS) using a LoadBalancer, use `:443` instead Apply it: diff --git a/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md b/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md index a26cc3da7..57e3fc49a 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md @@ -154,6 +154,7 @@ Replace: - ``—the name you entered in the Keploy UI - ``—the hostname that resolves to your cluster +- `:30080`—the NodePort from the Contour patch. For cloud clusters (EKS/GKE/AKS) using a LoadBalancer, use `:443` instead --- From f9d854a441afd55fa7ffe70aa5f8695a2e5ce618 Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Thu, 2 Apr 2026 01:37:17 +0530 Subject: [PATCH 24/30] fix(gitops): add fullnameOverride and fix stale links - Added fullnameOverride: "k8s-proxy" to all GitOps Helm values. Without this, the chart generates a service name like k8s-proxy-k8s-proxy-chart which breaks HTTPProxy routing to service k8s-proxy on port 8080. - Fixed stale kubernetes-local-setup links in standalone GitOps docs. Signed-off-by: Asish Kumar Co-Authored-By: Claude Opus 4.6 Signed-off-by: Asish Kumar --- versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md | 3 ++- versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md | 3 ++- versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md | 2 ++ 3 files changed, 6 insertions(+), 2 deletions(-) diff --git a/versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md b/versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md index 4f9c66fff..59d72ffc8 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md @@ -125,7 +125,7 @@ envoy NodePort 10.96.65.35 80:30081/TCP,443:30080/TCP 2m ## 3) Create the Keploy access key secret -> Skip if you already created this during the [Kubernetes Local Setup](/docs/keploy-cloud/kubernetes-local-setup). +> Skip if you already created this during the [Kubernetes Setup](/docs/keploy-cloud/kubernetes). Go to the Keploy UI → **Clusters** → **Connect New Cluster**. Enter your cluster name and ingress URL (e.g. `https://your-host:30080`). Click **Connect** to get your access key. @@ -164,6 +164,7 @@ spec: replicaCount: 1 environment: "staging" selfHosted: false + fullnameOverride: "k8s-proxy" keploy: existingSecret: "keploy-credentials" diff --git a/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md b/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md index 57e3fc49a..35aaa67db 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md @@ -73,7 +73,7 @@ flux check ## 2) Create the Keploy access key secret -> Skip if you already created this during the [Kubernetes Local Setup](/docs/keploy-cloud/kubernetes-local-setup). +> Skip if you already created this during the [Kubernetes Setup](/docs/keploy-cloud/kubernetes). Go to the Keploy UI → **Clusters** → **Connect New Cluster**. Enter your cluster name and ingress URL (e.g. `https://your-host:30080`). Click **Connect** to get your access key. @@ -133,6 +133,7 @@ spec: replicaCount: 1 environment: "staging" selfHosted: false + fullnameOverride: "k8s-proxy" keploy: existingSecret: "keploy-credentials" diff --git a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md index 7cb364007..7ca082b2b 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md @@ -392,6 +392,7 @@ spec: replicaCount: 1 environment: "staging" selfHosted: false + fullnameOverride: "k8s-proxy" keploy: existingSecret: "keploy-credentials" @@ -549,6 +550,7 @@ spec: replicaCount: 1 environment: "staging" selfHosted: false + fullnameOverride: "k8s-proxy" keploy: existingSecret: "keploy-credentials" From 415244fb6a33e855df31d99251bd405f33335ff9 Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Thu, 2 Apr 2026 01:40:30 +0530 Subject: [PATCH 25/30] fix(gitops): add mutual exclusivity warning and secret creation step - Added warning that manual Helm install and GitOps are mutually exclusive to prevent users from installing k8s-proxy twice. - Added secret creation step before GitOps sections since they use existingSecret instead of inline --set accessKey. Signed-off-by: Asish Kumar Co-Authored-By: Claude Opus 4.6 Signed-off-by: Asish Kumar --- .../version-4.0.0/keploy-cloud/kubernetes.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md index 7ca082b2b..45aeb554a 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md @@ -253,6 +253,16 @@ kube-system coredns-7d764666f9-r82lr 1/1 R If you use a GitOps tool to manage your Kubernetes cluster, you can deploy Keploy's `k8s-proxy` declaratively instead of using `helm upgrade` manually. The sections below cover **ArgoCD** and **Flux CD**. +> [!WARNING] +> Choose **either** the manual Helm install (section 2.2) **or** a GitOps-based install below—not both. If you already installed `k8s-proxy` with Helm, uninstall it first (`helm uninstall k8s-proxy -n keploy`) before applying GitOps manifests. + +The GitOps examples use a Kubernetes Secret for the access key. Create it before proceeding: + +```bash +kubectl -n keploy create secret generic keploy-credentials \ + --from-literal=access-key="" +``` + --- ## Ingress with TLS Passthrough (Optional) From e7dfdca4bd2d1b14b33cda613bc959fd41c13906 Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Thu, 2 Apr 2026 02:25:43 +0530 Subject: [PATCH 26/30] fix(gitops): add namespace creation and port clarification - Added kubectl create namespace before secret creation so GitOps-only users don't hit a missing namespace error. - Added :30080 vs :443 note to ArgoCD and Flux Replace sections in kubernetes.md, matching the standalone GitOps docs. Signed-off-by: Asish Kumar Co-Authored-By: Claude Opus 4.6 Signed-off-by: Asish Kumar --- versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md index 45aeb554a..e0acfa5c7 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md @@ -259,6 +259,8 @@ If you use a GitOps tool to manage your Kubernetes cluster, you can deploy Keplo The GitOps examples use a Kubernetes Secret for the access key. Create it before proceeding: ```bash +kubectl create namespace keploy + kubectl -n keploy create secret generic keploy-credentials \ --from-literal=access-key="" ``` @@ -433,6 +435,7 @@ Replace: - ``—the name you entered in the Keploy UI - ``—the hostname that resolves to your cluster (e.g. your VM IP or a DNS name) +- `:30080`—the NodePort from the Contour patch. For cloud clusters (EKS/GKE/AKS) using a LoadBalancer, use `:443` instead Apply it: @@ -582,6 +585,7 @@ Replace: - ``—the name you entered in the Keploy UI - ``—the hostname that resolves to your cluster +- `:30080`—the NodePort from the Contour patch. For cloud clusters (EKS/GKE/AKS) using a LoadBalancer, use `:443` instead ### Create the HTTPProxy for TLS Passthrough From 3ae9d89fb694ce699df5e30debd2030d77bc5d5c Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Thu, 2 Apr 2026 02:27:59 +0530 Subject: [PATCH 27/30] fix(gitops): remove redundant namespace creation - Removed kubectl create namespace keploy since it's already created by the manual Helm install or by the GitOps syncPolicy createNamespace. Signed-off-by: Asish Kumar Co-Authored-By: Claude Opus 4.6 Signed-off-by: Asish Kumar --- versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md index e0acfa5c7..9337f92eb 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md @@ -259,8 +259,6 @@ If you use a GitOps tool to manage your Kubernetes cluster, you can deploy Keplo The GitOps examples use a Kubernetes Secret for the access key. Create it before proceeding: ```bash -kubectl create namespace keploy - kubectl -n keploy create secret generic keploy-credentials \ --from-literal=access-key="" ``` From 12283204162209fcaa8344cec1ebf6f953cc62b8 Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Thu, 2 Apr 2026 10:25:26 +0530 Subject: [PATCH 28/30] fix(gitops): demote HTTPProxy heading to nest under Ingress section - Changed ## to ### so Create the HTTPProxy stays grouped under the Ingress with TLS Passthrough section in the TOC. Signed-off-by: Asish Kumar Co-Authored-By: Claude Opus 4.6 Signed-off-by: Asish Kumar --- versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md index 9337f92eb..fc73518f3 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md @@ -317,7 +317,7 @@ envoy NodePort 10.96.65.35 80:30081/TCP,443:30080/TCP 2m --- -## Create the HTTPProxy for TLS Passthrough +### Create the HTTPProxy for TLS Passthrough If you're using Contour as your ingress controller, create an HTTPProxy resource to route traffic to the `k8s-proxy` via TLS passthrough. From 21db3b3b045bdfa41505808876a8d082143a5f25 Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Thu, 2 Apr 2026 10:41:42 +0530 Subject: [PATCH 29/30] docs(gitops): remove redundant mutual exclusivity warning - Removed the WARNING admonition about choosing Helm vs GitOps since it's obvious to anyone using GitOps tooling. Signed-off-by: Asish Kumar Co-Authored-By: Claude Opus 4.6 Signed-off-by: Asish Kumar --- versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md index fc73518f3..a426aff70 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md @@ -253,9 +253,6 @@ kube-system coredns-7d764666f9-r82lr 1/1 R If you use a GitOps tool to manage your Kubernetes cluster, you can deploy Keploy's `k8s-proxy` declaratively instead of using `helm upgrade` manually. The sections below cover **ArgoCD** and **Flux CD**. -> [!WARNING] -> Choose **either** the manual Helm install (section 2.2) **or** a GitOps-based install below—not both. If you already installed `k8s-proxy` with Helm, uninstall it first (`helm uninstall k8s-proxy -n keploy`) before applying GitOps manifests. - The GitOps examples use a Kubernetes Secret for the access key. Create it before proceeding: ```bash From 1194c99d6e247b20ce724bf3447a652cda6a7cf9 Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Thu, 2 Apr 2026 11:37:23 +0530 Subject: [PATCH 30/30] docs(gitops): remove demo repo links - Removed links to personal keploy-argocd-demo repo from both standalone GitOps docs since demo repos shouldn't be in official docs. Signed-off-by: Asish Kumar Co-Authored-By: Claude Opus 4.6 Signed-off-by: Asish Kumar --- versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md | 2 -- versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md | 2 -- 2 files changed, 4 deletions(-) diff --git a/versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md b/versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md index 59d72ffc8..9db347a8a 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md @@ -321,5 +321,3 @@ To add Keploy to an existing ArgoCD setup, you need: | Kubernetes Secret | `kubectl create secret` (manual) | Access key for Keploy cloud authentication | Your existing application code, manifests, and ArgoCD Applications remain **completely untouched**. Keploy works alongside your app—not inside it. - -For a complete reference implementation, see the [keploy-argocd-demo](https://github.com/officialasishkumar/keploy-argocd-demo) repository. diff --git a/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md b/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md index 35aaa67db..eb5d945bd 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md @@ -259,5 +259,3 @@ To add Keploy to an existing Flux setup, you need: | Kubernetes Secret | `kubectl create secret` (manual) | Access key for Keploy cloud authentication | Your existing application manifests and Flux configurations remain **completely untouched**. Keploy works alongside your app—not inside it. - -For a reference implementation with both ArgoCD and Flux CD manifests, see the [keploy-argocd-demo](https://github.com/officialasishkumar/keploy-argocd-demo) repository—the `flux/` directory contains ready-to-use HelmRepository, HelmRelease, and HTTPProxy manifests for staging and production.