How leandroyyy/kind-system-test-envoy works
What this project is (type + purpose)
This is an infrastructure+runtime demo project: a Go-based “cluster manager” provisions a local Kind Kubernetes cluster, builds a single Docker image for a simple HTTP app, loads that image into the Kind node, applies Kubernetes manifests (apps + Envoy), and then validates Envoy routing via Go tests.
1) Provisioning / control-plane workflow (what cmd/manager does to create the environment)
2) Runtime request routing architecture (how traffic flows through Envoy to app1/app2 in Kubernetes)
Repository structure to architectural modules (for accurate boundaries)
Use the file tree to define “implementation components” and tie them to runtime components:
Go entrypoints (control tools)
• cmd/manager/main.go
Primary orchestrator: creates Kind cluster, builds image, loads image, applies manifests, waits readiness.
• cmd/build-image/main.go
A supporting CLI: encapsulates building Docker image (likely used by manager or usable standalone).
Runtime workload
• app/main.go + app/Dockerfile
The HTTP application packaged as kind-app:latest. Deployed twice as app1 and app2.
Infra abstraction libraries (used by manager)
• pkg/kind/cluster.go
Kind cluster lifecycle operations (create/delete, load image, etc.).
• pkg/k8s/client.go
Kubernetes API client setup (client-go configuration).
• pkg/k8s/applier.go
Manifest application logic (apply YAMLs to the cluster).
Declarative deployment config
• manifests/kind-cluster.yaml (Kind cluster config)
• manifests/app1-deployment.yaml, manifests/app2-deployment.yaml
• manifests/envoy-config.yaml, manifests/envoy-deployment.yaml
Verification
• tests/routing_test.go
End-to-end routing tests (HTTP requests against Envoy endpoint).
View A: Provisioning / orchestration (control flow)
Actors / external dependencies
• Developer / CI runner (invokes go run cmd/manager/main.go)
• Docker Engine (build image; Kind runs as Docker containers)
• Kind CLI/API (creates the Kubernetes-in-Docker cluster; loads images)
• Kubernetes API server (inside the Kind control plane; receives manifests)
Manager internal modules (from pkg/)
• Manager (cmd/manager)
• Kind Cluster Ops (pkg/kind/cluster.go)
• K8s Client (pkg/k8s/client.go)
• Manifest Applier (pkg/k8s/applier.go)
• (Optional) Image Builder CLI (cmd/build-image) or its invoked logic
Manager → Kind: Load docker image into cluster node(s) (kind load docker-image)
4. Manager → Kubernetes API: Apply manifests (app1/app2 Deployments, Envoy Deployment, Envoy ConfigMap)
View B: Runtime request/data plane (traffic routing)
Runtime components inside the Kind cluster
• Namespace (if manifests define one; if not, assume default)
• Envoy Deployment/Pod(s)
• Envoy Config (from envoy-config.yaml, typically a ConfigMap)
• app1 Deployment → app1 Pod(s) (containers running kind-app:latest)
• app2 Deployment → app2 Pod(s) (same image)
• Kubernetes Services (very likely present even if not called out in README; if your manifests define Services, include them explicitly)
• Ingress exposure mechanism (based on manifests; often NodePort or hostPort for Envoy on localhost:8080)
External to cluster
• Client (curl / tests)
• Host network / port mapping from Docker/Kind to localhost:8080
• Client → localhost:8080 → (Kind node port mapping) → Envoy listener (port 8080) → route:
• / → load-balance cluster → app1 or app2 (round-robin)
• /app1 → upstream app1 only
• /app2 → upstream app2 only
• Response returns back along the same path.
• go test ./tests/... runner
• Tests sending HTTP requests to http://localhost:8080/...
• Assertions about:
• round-robin behavior for /
• deterministic routing for /app1 and /app2
Control-plane edges
• Manager → Docker Engine: docker build (image artifact produced)
• Manager → Kind: create cluster + load image
• Manager → Kubernetes API: apply YAML + readiness checks/watch
• Manager → Manifests directory: show that manifests are the source of truth for deployments/config
Runtime edges
• Client/Test Runner → Envoy: HTTP requests
• Envoy → app1/app2: upstream HTTP forwarding
• Envoy → Envoy Config: config mount/reference (ConfigMap volume or similar)
• app1/app2 → (optional): any logs/metrics aren’t in repo; don’t invent observability components unless manifests show them.
These boundaries explain why “build locally” ≠ “available in cluster” until loaded.
Architectural patterns/design principles apparent from the repo
• Controller/Orchestrator pattern (imperative provisioning): cmd/manager is an orchestrator coordinating Kind + Docker + K8s APIs.
• Declarative desired state (YAML manifests): runtime is described by manifests; Go code applies them.
• Edge proxy routing with Envoy as the L7 entrypoint.
• Environment parity for local dev: Kind provides a reproducible local cluster.
Final checklist for correctness against this repo
• Includes Kind cluster creation from manifests/kind-cluster.yaml
• Includes Docker image build from app/Dockerfile
• Includes explicit “kind load docker-image” step (highlighted)
• Includes K8s manifest application of app1/app2 + Envoy
• Includes Envoy routing rules /, /app1, /app2
• Includes tests hitting localhost:8080 and asserting routing
• Avoids adding components not present (databases, service mesh, ingress controller) unless manifests explicitly define them