Skip to content

docs: add Kubernetes deployment guide with ArgoCD and Flux CD#816

Merged
officialasishkumar merged 31 commits intomainfrom
feat/enterprise-k8s-gitops-guides
Apr 2, 2026
Merged

docs: add Kubernetes deployment guide with ArgoCD and Flux CD#816
officialasishkumar merged 31 commits intomainfrom
feat/enterprise-k8s-gitops-guides

Conversation

@officialasishkumar
Copy link
Copy Markdown
Member

@officialasishkumar officialasishkumar commented Apr 1, 2026

Summary

  • Added a unified Kubernetes page under Installation covering local Kind cluster setup, ArgoCD deployment, and Flux CD deployment of Keploy k8s-proxy
  • Restructured the Installation sidebar: Local (was "Keploy OSS"), Enterprise (was "Enterprise Installation"), Kubernetes (single combined page)
  • The Kubernetes page includes:
    • Local Kind cluster creation with NodePort mapping
    • Connecting the cluster to Keploy via Helm
    • Contour ingress controller setup with TLS passthrough
    • ArgoCD deployment guide (Application YAML, verification, self-healing demo)
    • Flux CD deployment guide (HelmRepository, HelmRelease, reconciliation)
    • TLS passthrough explanation (SNI routing, why HTTPProxy is needed over standard Ingress)
  • All content validated against k8s-proxy Helm chart source code
  • Tested end-to-end on a local Kind cluster with both ArgoCD and Flux CD
  • Reference implementation: keploy-k8s-demo

New sidebar structure

Installation
├── Local
├── Enterprise
└── Kubernetes  (single page with all K8s content)

Files changed

  • versioned_sidebars/version-4.0.0-sidebars.json — sidebar restructure, label fixes, doc ID correction
  • versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md — new combined Kubernetes page (local setup + ArgoCD + Flux CD)
  • versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md — original ArgoCD guide (content merged into kubernetes.md)
  • versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md — original Flux CD guide (content merged into kubernetes.md)
  • versioned_docs/version-4.0.0/server/installation.md — sidebar label changed to "Local"
  • versioned_docs/version-4.0.0/keploy-cloud/installation.md — sidebar label changed to "Enterprise"

Test plan

  • npm run build passes without errors
  • Sidebar renders "Local", "Enterprise", "Kubernetes" under Installation
  • TOC shows ArgoCD and Flux CD as top-level entries (h2 headings)
  • All internal anchor links resolve correctly
  • ArgoCD deployment tested end-to-end on Kind cluster
  • Flux CD manifests validated against Helm chart source
  • Reference repo (keploy-k8s-demo) tested with ArgoCD — self-healing and Git sync verified

@kilo-code-bot
Copy link
Copy Markdown

kilo-code-bot bot commented Apr 1, 2026

Code Review Summary

Status: 1 Critical Issue Remains | Recommendation: Address before merge

Overview

Severity Count
CRITICAL 1
WARNING 0
SUGGESTION 0

Incremental Review

Reviewed changes since commit 12283204162209fcaa8344cec1ebf6f953cc62b8:

Changes in This Commit

  1. Warning Admonition Removed ⚠️
    • kubernetes.md (line ~256): The mutual exclusivity warning about choosing either manual Helm install OR GitOps was removed. While the section text still implies this ("instead of using helm upgrade manually"), the explicit warning helped prevent user confusion. This is a minor documentation concern.

Outstanding Issues

CRITICAL: Missing Namespace Creation (from previous review)

File Line Issue
versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md 259 Missing kubectl create namespace keploy before secret creation in GitOps section

Details: In the "GitOps Deployment" section, the secret creation command (kubectl -n keploy create secret generic keploy-credentials) requires the keploy namespace to exist. Users following the GitOps path would skip section 2.2 (which uses --create-namespace), so this command will fail with "namespace not found".

Fix: Add kubectl create namespace keploy before line 259, similar to what's done in gitops-argocd.md (lines 132-136) and gitops-flux.md (lines 76-80).

Previous Issues - Resolved

All inline comments from previous reviews have been addressed:

Issue Status
Broken intro note links (ArgoCD guide) ✅ Fixed
Broken intro note links (Flux guide) ✅ Fixed
Broken anchor link (kubernetes.md) ✅ Fixed
ArgoCD repoURL format ✅ Author clarified as correct
Helm values structure ✅ Fixed
Files Reviewed (1 file in incremental diff)
  • versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md — Warning admonition removed
Full PR Files (8 files)
  • versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md — ArgoCD deployment guide
  • versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md — Flux CD deployment guide
  • versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md — Combined Kubernetes setup guide
  • versioned_docs/version-4.0.0/keploy-cloud/installation.md — Sidebar label change
  • versioned_docs/version-4.0.0/server/installation.md — Sidebar label change
  • versioned_sidebars/version-4.0.0-sidebars.json — Sidebar structure reorganization
  • versioned_docs/version-4.0.0/running-keploy/agent-test-generation.md — Merge from main
  • vale_styles/config/vocabularies/Base/accept.txt — Vocabulary additions

Fix these issues in Kilo Cloud


Reviewed by claude-opus-4.5 · 341,335 tokens

@officialasishkumar officialasishkumar changed the title docs: add GitOps deployment guides (ArgoCD, Flux) for Keploy k8s-proxy docs: add Kubernetes deployment guide with ArgoCD and Flux CD Apr 1, 2026
@slayerjain slayerjain requested a review from Copilot April 1, 2026 16:50
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR updates the v4.0.0 documentation to provide a unified Kubernetes deployment guide (including Kind + GitOps flows) and restructures the Installation section in the sidebar into Local / Enterprise / Kubernetes entries.

Changes:

  • Restructures the v4.0.0 sidebar “Installation” entry into a collapsible category with “Local”, “Enterprise”, and “Kubernetes”.
  • Adds a new combined Kubernetes setup page covering Kind, Helm connect, TLS passthrough with Contour, and GitOps deployment via ArgoCD + Flux CD.
  • Renames installation doc sidebar labels to match the new Installation grouping (“Local”, “Enterprise”).

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file
File Description
versioned_sidebars/version-4.0.0-sidebars.json Converts Installation into a category and points to Local/Enterprise/Kubernetes docs.
versioned_docs/version-4.0.0/server/installation.md Updates sidebar label to “Local”.
versioned_docs/version-4.0.0/keploy-cloud/installation.md Updates sidebar label to “Enterprise”.
versioned_docs/version-4.0.0/keploy-cloud/kubernetes.md Adds the unified Kubernetes guide (Kind + Contour TLS passthrough + ArgoCD + Flux).
versioned_docs/version-4.0.0/keploy-cloud/gitops-argocd.md Adds an ArgoCD-focused GitOps guide for k8s-proxy.
versioned_docs/version-4.0.0/keploy-cloud/gitops-flux.md Adds a Flux-focused GitOps guide for k8s-proxy.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

officialasishkumar and others added 19 commits April 1, 2026 23:08
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 <officialasishkumar@gmail.com>
Covers Contour ingress with TLS passthrough, ArgoCD Application
template, HTTPProxy setup, and step-by-step verification.

Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
Covers Flux bootstrap, HelmRepository source, HelmRelease config,
Contour HTTPProxy with TLS passthrough, and verification steps.

Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
…llation

Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
- 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 <officialasishkumar@gmail.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
…n 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 <officialasishkumar@gmail.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
- 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 <officialasishkumar@gmail.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
- 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 <officialasishkumar@gmail.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
- 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 <officialasishkumar@gmail.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
- 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 <officialasishkumar@gmail.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
- Already covered in the local setup section (step 2).

Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
- The tables just repeated what the guide already covered.

Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
- Not Keploy-specific, just Envoy/Contour internals.

Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
- Developers know where they put their files.

Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
- 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 <officialasishkumar@gmail.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
…des"

This reverts commit beb5f1a.

Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
* 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) <noreply@anthropic.com>
Signed-off-by: slayerjain <shubhamkjain@outlook.com>

* fix: run prettier on agent-test-generation.md

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: slayerjain <shubhamkjain@outlook.com>

* fix: wrap k8s-proxy in backticks to fix Vale spelling lint

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: slayerjain <shubhamkjain@outlook.com>

---------

Signed-off-by: slayerjain <shubhamkjain@outlook.com>
Co-authored-by: slayerjain <shubhamkjain@outlook.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
- 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 <officialasishkumar@gmail.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
@officialasishkumar officialasishkumar force-pushed the feat/enterprise-k8s-gitops-guides branch from b7913af to 119251b Compare April 1, 2026 17:39
- 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 <officialasishkumar@gmail.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
@officialasishkumar officialasishkumar force-pushed the feat/enterprise-k8s-gitops-guides branch from 119251b to 64a445f Compare April 1, 2026 17:40
- 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 <officialasishkumar@gmail.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

officialasishkumar and others added 2 commits April 2, 2026 01:37
- 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 <officialasishkumar@gmail.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
- 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 <officialasishkumar@gmail.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

officialasishkumar and others added 2 commits April 2, 2026 02:25
- 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 <officialasishkumar@gmail.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
- 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 <officialasishkumar@gmail.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

- Changed ## to ### so Create the HTTPProxy stays grouped under the
  Ingress with TLS Passthrough section in the TOC.

Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

- Removed the WARNING admonition about choosing Helm vs GitOps since
  it's obvious to anyone using GitOps tooling.

Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

- 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 <officialasishkumar@gmail.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Asish Kumar <officialasishkumar@gmail.com>
@officialasishkumar officialasishkumar merged commit b390338 into main Apr 2, 2026
7 of 8 checks passed
@officialasishkumar officialasishkumar deleted the feat/enterprise-k8s-gitops-guides branch April 2, 2026 08:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants