How projectcontour/contour works
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.