# leandroyyy/kind-system-test-envoy architecture

> Architecture diagram of the GitHub repository leandroyyy/kind-system-test-envoy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/leandroyyy/kind-system-test-envoy
- Repository: https://github.com/leandroyyy/kind-system-test-envoy

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% VIEW A: Provisioning / Control-plane workflow
  %% =========================
  subgraph "View A — Provisioning / Orchestration (control-plane)"
    direction TB

    Dev["Developer / CI Runner"]:::external

    subgraph "Host machine"
      direction TB
      Docker["Docker Engine"]:::external

      subgraph "Go control tooling"
        direction TB
        Manager["Cluster Manager (cmd/manager)"]:::control
        BuildCLI["Image Builder CLI (cmd/build-image)"]:::control

        subgraph "Infra abstraction libs (pkg/...)"
          direction TB
          KindOps["Kind Cluster Ops (pkg/kind)"]:::control
          K8sClient["K8s Client (pkg/k8s)"]:::control
          Applier["Manifest Applier (pkg/k8s)"]:::control
        end
      end

      subgraph "Build context"
        direction TB
        AppCode["HTTP App source (app/)"]:::artifact
        Dockerfile["Dockerfile (kind-app:latest)"]:::artifact
        Image["Docker image: kind-app:latest"]:::artifact
      end

      subgraph "Declarative manifests (source of truth)"
        direction TB
        KindCfg["kind-cluster.yaml"]:::config
        App1Man["app1 Deployment YAML"]:::config
        App2Man["app2 Deployment YAML"]:::config
        EnvoyDepMan["Envoy Deployment YAML"]:::config
        EnvoyCfgMan["Envoy Config YAML (ConfigMap)"]:::config
      end
    end

    subgraph "Kind cluster (Kubernetes-in-Docker)"
      direction TB
      Kind["Kind (cluster + node containers)"]:::external

      subgraph "Kubernetes control plane"
        direction TB
        APIServer["Kubernetes API Server"]:::k8s
      end
    end

    Dev -->|"invoke go run"| Manager

    Manager -->|"uses"| KindOps
    Manager -->|"uses"| K8sClient
    Manager -->|"uses"| Applier
    Manager -.->|"optionally invokes"| BuildCLI

    %% Numbered control-plane interactions
    Manager -->|"1)Create_cluster (from kind-cluster.yaml)"| Kind
    KindCfg -->|"input_to_create"| Kind

    Manager -->|"2)Build_image (docker build)"| Docker
    Dockerfile -->|"build_context"| Docker
    AppCode -->|"build_context"| Docker
    Docker -->|"produces"| Image

    Manager -->|"3)kind_load_docker-image (image_not_auto_visible_in_Kind)"| Kind
    Image -->|"load_into_node_cache"| Kind

    Manager -->|"4)Apply_manifests (YAML)"| APIServer
    Applier -->|"apply"| APIServer
    K8sClient -->|"client-go"| APIServer
    App1Man -->|"apply"| APIServer
    App2Man -->|"apply"| APIServer
    EnvoyDepMan -->|"apply"| APIServer
    EnvoyCfgMan -->|"apply"| APIServer

    Manager -->|"5)Wait_watch_ready (deployments)"| APIServer

    %% Transition to runtime view
    APIServer -->|"After_apply+ready:workloads_running"| RuntimeBridge["Runtime starts (data plane active)"]:::note
  end

  %% =========================
  %% VIEW B: Runtime / Data-plane routing
  %% =========================
  subgraph "View B — Runtime Request Routing (data-plane)"
    direction TB

    Client["Client (curl)"]:::external
    TestRunner["E2E Test Runner (go test)"]:::test

    subgraph "Host networking"
      direction TB
      Local8080["localhost:8080"]:::external
      PortMap["Docker/Kind port mapping\n(NodePort/hostPort/port-forward)"]:::external
    end

    subgraph "Kind cluster (runtime workloads)"
      direction TB

      subgraph "Envoy edge proxy"
        direction TB
        Envoy["Envoy Pod/Deployment"]:::k8s
        EnvoyCfg["Envoy config (ConfigMap)"]:::config
        Routes["Routing rules:\n- '/' => LB(app1,app2)\n- '/app1' => app1\n- '/app2' => app2"]:::note
      end

      subgraph "Application workloads (same image deployed twice)"
        direction TB
        App1["app1 Deployment/Pods\n(image: kind-app:latest)"]:::k8s
        App2["app2 Deployment/Pods\n(image: kind-app:latest)"]:::k8s
      end

      SvcEnvoy["Service: Envoy (exposed)"]:::k8s
      SvcApp1["Service: app1"]:::k8s
      SvcApp2["Service: app2"]:::k8s
    end

    Client -->|"HTTP_request"| Local8080
    TestRunner -->|"HTTP_requests+assertions"| Local8080

    Local8080 -->|"forward_to_cluster"| PortMap
    PortMap -->|"to_Envoy_listener:8080"| SvcEnvoy
    SvcEnvoy -->|"routes"| Envoy

    Envoy -->|"mounts/reads"| EnvoyCfg
    Routes --- Envoy

    Envoy -->|"HTTP_route '/app1'"| SvcApp1
    Envoy -->|"HTTP_route '/app2'"| SvcApp2
    Envoy -->|"HTTP_route '/' (round_robin)"| SvcApp1
    Envoy -->|"HTTP_route '/' (round_robin)"| SvcApp2

    SvcApp1 -->|"to_pods"| App1
    SvcApp2 -->|"to_pods"| App2

    App1 -->|"HTTP_response"| Envoy
    App2 -->|"HTTP_response"| Envoy
    Envoy -->|"HTTP_response"| SvcEnvoy
    SvcEnvoy -->|"back_to_localhost"| PortMap
    PortMap -->|"return"| Local8080
  end

  %% Bridge between views
  RuntimeBridge -->|"Validated via localhost endpoint"| Local8080

  %% =========================
  %% Click Events (component_mapping)
  %% =========================
  click Manager "https://github.com/leandroyyy/kind-system-test-envoy/blob/main/cmd/manager/main.go"
  click BuildCLI "https://github.com/leandroyyy/kind-system-test-envoy/blob/main/cmd/build-image/main.go"
  click AppCode "https://github.com/leandroyyy/kind-system-test-envoy/blob/main/app/main.go"
  click Dockerfile "https://github.com/leandroyyy/kind-system-test-envoy/tree/main/app/Dockerfile"
  click KindOps "https://github.com/leandroyyy/kind-system-test-envoy/blob/main/pkg/kind/cluster.go"
  click K8sClient "https://github.com/leandroyyy/kind-system-test-envoy/blob/main/pkg/k8s/client.go"
  click Applier "https://github.com/leandroyyy/kind-system-test-envoy/blob/main/pkg/k8s/applier.go"
  click KindCfg "https://github.com/leandroyyy/kind-system-test-envoy/blob/main/manifests/kind-cluster.yaml"
  click App1Man "https://github.com/leandroyyy/kind-system-test-envoy/blob/main/manifests/app1-deployment.yaml"
  click App2Man "https://github.com/leandroyyy/kind-system-test-envoy/blob/main/manifests/app2-deployment.yaml"
  click EnvoyDepMan "https://github.com/leandroyyy/kind-system-test-envoy/blob/main/manifests/envoy-deployment.yaml"
  click EnvoyCfgMan "https://github.com/leandroyyy/kind-system-test-envoy/blob/main/manifests/envoy-config.yaml"
  click TestRunner "https://github.com/leandroyyy/kind-system-test-envoy/blob/main/tests/routing_test.go"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#e5e7eb,stroke:#6b7280,color:#111827,stroke-width:1px
  classDef control fill:#bfdbfe,stroke:#1d4ed8,color:#0b1b3a,stroke-width:1px
  classDef k8s fill:#bbf7d0,stroke:#15803d,color:#052e16,stroke-width:1px
  classDef config fill:#fde68a,stroke:#b45309,color:#3b2f0b,stroke-width:1px
  classDef artifact fill:#c7d2fe,stroke:#3730a3,color:#111827,stroke-width:1px
  classDef test fill:#fecaca,stroke:#b91c1c,color:#3b0a0a,stroke-width:1px
  classDef note fill:#fff7ed,stroke:#c2410c,color:#7c2d12,stroke-width:1px,stroke-dasharray: 4 3
```
