# projectcontour/contour architecture

> Architecture diagram of the GitHub repository projectcontour/contour, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/projectcontour/contour
- Repository: https://github.com/projectcontour/contour

## Overview

##### And outline the core components
- Kubernetes Cluster: This is the environment where Contour runs. It provides the API server, kube-controller-manager, and other Kubernetes primitives.
- Envoy Proxy: Represent the Envoy proxy as an external data plane component which receives configuration updates from Contour via the xDS API (see the internal/xds and internal/xdscache directories for details).
- Configuration APIs:
– Ingress API (standard Kubernetes Ingress objects)
– HTTPProxy (Contour’s own CRD with enhanced features)
– Gateway API (newer, evolving Kubernetes API)
- Supporting Components: Include ancillary components like the certificate generator (cmd/contour/certgen and internal/certgen), logging, metrics collection modules (internal/metrics), and health checks (internal/health) within Contour.
- Testing and CI/CD Pipelines: While not part of runtime architecture, note that robust unit and e2e tests, along with CI pipelines (see .github/workflows, test/e2e) are used to ensure system correctness.

##### Relationships and system interactions
- Contour continuously monitors the Kubernetes API for changes in Ingress, HTTPProxy, and Gateway API resources.
- When a change is detected, Contour’s reconciliation loop (using internal/k8s and internal/dag) rebuilds its internal Directed Acyclic Graph (DAG), reflecting desired routing, TLS, and load balancing policies.
- This new state is then converted into configuration resources (using xDS protocols, as found in internal/xds and internal/xdscache) which are then pushed to one or more Envoy proxy instances.
- The Envoy proxy, running as a separate container or deployment, receives configuration updates dynamically and serves as the actual reverse proxy and load balancer for incoming traffic.
– From Kubernetes API to Contour Controller (watching for resource changes)
– From Contour Controller to Envoy (pushing xDS configuration updates)
– Backward or bidirectional communication for health checks and metrics (e.g., Prometheus scraping, as noted in examples and test/e2e/prometheus)

##### Architectural patterns and design principles
- Event-driven reconciliation: The control loop is based on watching API events and re-building the routing DAG.
- Separation of concerns: There is a clear distinction between the control plane (Contour) and the data plane (Envoy) with well-defined API contracts (xDS).
- Modular design: By splitting functionality across packages (e.g., certgen, dag building, envoy configuration, CRD management), the project makes it easier to extend and test.
- Extensibility: Multiple APIs (Ingress, HTTPProxy, Gateway API) are supported to give users flexibility in how they define routing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Kubernetes Cluster
    subgraph "Kubernetes Cluster"
        K8s_API["Kubernetes API Server"]:::control
        subgraph "Contour Controller"
            API_Support["APIs: Ingress,HTTPProxy,Gateway_API"]:::control
            CT_main["Main Binary (cmd/contour)"]:::control
            DAG["DAG Builder (internal/dag)"]:::control
            API_Def["API Definitions (apis/projectcontour)"]:::control
            CRD_Proc["CRD Processor (internal/provisioner)"]:::control
            XDS["xDS Configurator (internal/xds)"]:::control
            XDS_Cache["xDS Cache (internal/xdscache)"]:::control
            Envoy_Int["Envoy Integration (internal/envoy)"]:::control
            Cert_CLI["Certificate Generator CLI (cmd/contour/certgen.go)"]:::control
            Cert_Lib["Certificate Generator Lib (internal/certgen)"]:::control
            Log_Metrics["Logging & Metrics (internal/contour/metrics,internal/metrics)"]:::control
            Health["Health Checks (internal/health/health.go)"]:::control

            API_Support --> CT_main
            CT_main --> DAG
            CT_main --> API_Def
            CT_main --> CRD_Proc
            CT_main --> XDS
            CT_main --> XDS_Cache
            CT_main --> Envoy_Int
            CT_main --> Cert_CLI
            CT_main --> Cert_Lib
            CT_main --> Log_Metrics
            CT_main --> Health
        end
    end

    %% Envoy Data Plane
    Envoy_Proxy["Envoy Proxy"]:::data

    %% Testing and CI
    subgraph "Testing & CI"
        CI["CI/CD Pipelines (.github/workflows)"]:::test
        E2E["E2E Tests (test/)"]:::test
        CI --- E2E
    end

    %% Interactions
    K8s_API -->|"ResourceEvent"| API_Support
    CT_main -->|"PushxDSConfig"| Envoy_Proxy
    Envoy_Proxy <-->|"Health/Metrics"| Log_Metrics

    %% Click Events
    click CT_main "https://github.com/projectcontour/contour/tree/main/cmd/contour"
    click DAG "https://github.com/projectcontour/contour/tree/main/internal/dag"
    click API_Def "https://github.com/projectcontour/contour/tree/main/apis/projectcontour"
    click CRD_Proc "https://github.com/projectcontour/contour/tree/main/internal/provisioner"
    click XDS "https://github.com/projectcontour/contour/tree/main/internal/xds"
    click XDS_Cache "https://github.com/projectcontour/contour/tree/main/internal/xdscache"
    click Envoy_Int "https://github.com/projectcontour/contour/tree/main/internal/envoy"
    click Cert_CLI "https://github.com/projectcontour/contour/blob/main/cmd/contour/certgen.go"
    click Cert_Lib "https://github.com/projectcontour/contour/tree/main/internal/certgen"
    click Log_Metrics "https://github.com/projectcontour/contour/tree/main/internal/metrics"
    click Health "https://github.com/projectcontour/contour/blob/main/internal/health/health.go"
    click CI "https://github.com/projectcontour/contour/tree/main/.github/workflows"
    click E2E "https://github.com/projectcontour/contour/tree/main/test/"

    %% Styles
    classDef control fill:#AEDFF7,stroke:#333,stroke-width:1px;
    classDef data fill:#F7D6AE,stroke:#333,stroke-width:1px;
    classDef test fill:#D6F7AE,stroke:#333,stroke-width:1px;
```
