Skip to main content

Deploy Keploy with Flux CD​

EnterpriseSelf-HostedDedicated

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 Setup and have a running Kind cluster with Keploy connected. For Contour setup details, see the ArgoCD guide—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)
  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)

1) Bootstrap Flux​

Skip this if Flux is already installed on your cluster.

Bootstrap Flux with your GitHub repository:

flux bootstrap github \
  --owner=<YOUR_GITHUB_USERNAME> \
  --repository=<YOUR_REPO_NAME> \
  --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:

flux check

2) Create the Keploy access key secret​

Skip if you already created this during the Kubernetes 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.

kubectl create namespace keploy

kubectl -n keploy create secret generic keploy-credentials \
  --from-literal=access-key="<YOUR_ACCESS_KEY>"

[!WARNING] Never commit access keys to Git. For production, use Flux SOPS or 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:

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:

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
    fullnameOverride: "k8s-proxy"

    keploy:
      existingSecret: "keploy-credentials"
      existingSecretKey: "access-key"
      clusterName: "<YOUR_CLUSTER_NAME>"
      apiServerUrl: "https://api.keploy.io"
      ingressUrl: "https://<YOUR_INGRESS_HOST>:30080"

    service:
      type: ClusterIP

    mongodb:
      enabled: false
    minio:
      enabled: false

Replace:

  • <YOUR_CLUSTER_NAME>—the name you entered in the Keploy UI
  • <YOUR_INGRESS_HOST>—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

5) Create the HTTPProxy for TLS passthrough​

Create clusters/staging/k8s-proxy-httpproxy.yaml in your Git repo:

apiVersion: projectcontour.io/v1
kind: HTTPProxy
metadata:
  name: k8s-proxy-ingress
  namespace: keploy
spec:
  virtualhost:
    fqdn: <YOUR_INGRESS_HOST>
    tls:
      passthrough: true
  tcpproxy:
    services:
      - name: k8s-proxy
        port: 8080

Replace <YOUR_INGRESS_HOST> 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 for a detailed explanation.

6) Push and let Flux reconcile​

Commit and push all three files:

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:

# 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​

# 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://<YOUR_INGRESS_HOST>: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:

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:

WhatFilePurpose
Helm sourcekeploy-source.yamlOCI Helm repository for Keploy charts
HelmReleasekeploy-k8s-proxy.yamlDeploy k8s-proxy from Keploy's Helm chart
Contour HTTPProxyk8s-proxy-httpproxy.yamlRoute HTTPS traffic via TLS passthrough
Kubernetes Secretkubectl 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.