Contour Ingress Controller

Contour is a Kubernetes ingress controller that uses Envoy proxy as a reverse proxy and load balancer. It supports dynamic configuration updates and provides three primary configuration APIs:

• Ingress: The standard Kubernetes API for basic ingress use cases.
• HTTPProxy: A Contour-specific Custom Resource Definition (CRD) that provides advanced functionality beyond the standard Ingress API.
• Gateway API: A vendor-neutral, CRD-based API managed by the Kubernetes SIG-Network community.

Contour is an Ingress controller for Kubernetes that utilizes the Envoy proxy as a reverse proxy and load balancer. It is designed to support dynamic configuration updates out of the box while maintaining a lightweight profile. It bridges solution gaps by providing minimal dropped connections during configuration updates and supporting multiple ingress configuration types in multi-team clusters, including:

• Ingress/v1
• HTTPProxy (Contour custom resource)
• Gateway API

When external authorization is configured, the request flow is as follows:

1. Client Request: The HTTP Client sends a request to the Envoy instance.
2. Authorization Check: Envoy intercepts the request and sends an authorization check request to the Authorization server (the service defined by the ExtensionService).
3. Verification: The Authorization server verifies the request. It may optionally communicate with an external Authorization Provider to validate tokens or permissions.
4. Response:
   • Success: The Authorization server returns a response containing the authorization status and optional HTTP header modifications. Envoy applies these modifications and forwards the request to the application.
   • Failure: Envoy immediately responds to the client with an HTTP error, and the request never reaches the application.

Contour and Envoy expose metrics compatible with Prometheus.

• Envoy Metrics: Envoy exposes metrics via a Prometheus-compatible /stats/prometheus endpoint on port 8002. Contour configures a static listener to route traffic specifically to this endpoint to avoid exposing the full Envoy admin interface.
• Contour Metrics: Contour exposes a Prometheus-compatible /metrics endpoint. By default, this listens on port 8000.

Configuration: You can change the Contour metrics port using the --http-address and --http-port flags for the serve command. If you change these flags, you must also update the Contour Service deployment manifest to match the new port.

Contour is an opinionated project that prioritizes sensible defaults over infinite configurability.

• Sensible Defaults: Contour applies recommended values for Envoy configuration parameters (e.g., compressing HTTP response bodies, enforcing specific TLS versions/ciphers) unconditionally to reduce the complexity of the configuration space.
• Manual Overrides: Administrators can provide custom values as a last resort if the defaults do not meet their specific requirements.
• Debuggability: Contour is designed so that users can debug failures without contacting maintainers. This includes:
  • Using Kubernetes CRD validation to provide immediate feedback via the API server.
  • Exposing error information via status conditions on Kubernetes objects (like HTTPProxy) rather than relying solely on internal logs.

Contour distinguishes between two ways of deploying and managing Contour + Envoy instances:

• Static provisioning: A manual process where a user deploys a Contour + Envoy instance and a Gateway custom resource. The user is responsible for ensuring the Gateway specification matches the deployed Contour + Envoy configuration.
• Dynamic provisioning: An automated process where a Gateway provisioner (a controller in the cluster) detects the creation of a Gateway custom resource and automatically deploys a matching Contour + Envoy instance. The provisioner handles the reconciliation loop and deletion processes.

This tutorial provides a workflow for deploying secure HTTPS web applications on Kubernetes using Contour as the Ingress controller and cert-manager to automate TLS certificate provisioning from Let's Encrypt.

Prerequisites

• A Kubernetes cluster (tested on GKE 1.22).
• RBAC enabled.
• A cloud provider capable of provisioning a LoadBalancer service type.
• A DNS domain under your control.
• Administrator permissions.

Contour (v1.9+) supports routing client requests to an external authorization server that implements the Envoy external authorization gRPC protocol. This allows for centralized client authorization across multiple applications.

To implement this, you use two primary resources:

1. ExtensionService: Binds an external server to Contour and instructs Envoy to create an upstream cluster for it.
2. HTTPProxy: Binds the ExtensionService to a specific application by referencing the service name in the virtualhost.authorization field.

When configured, Envoy intercepts the HTTP request and sends an authorization check to the external server before routing the request to the upstream application. The authorization response can include HTTP header modifications which Envoy applies to the request before forwarding it.

Contour supports configuration via CLI flags, environment variables, and a configuration file. When multiple configuration methods are used, the following precedence applies (from highest to lowest priority):

1. CLI Flags (highest priority)
2. Environment Variables
3. Configuration File (lowest priority)

Contour is designed around two primary user personas with distinct responsibilities:

Cluster Administrator

Responsible for the health and operation of the Kubernetes cluster. Tasks include:

• Installing Contour and Envoy.
• Managing the software lifecycle of these applications.
• Managing connectivity to the outside world, TLS secrets, and DNS.
• Configuring Contour applications.

Application Developer

Responsible for deploying web applications or microservices. Tasks include:

• Interacting with Contour by creating Kubernetes objects (e.g., HTTPProxy, Ingress, or Gateway API resources).
• Developers do not interact with Contour directly, only through the Kubernetes objects they manage.