This topic gives an overview of the Contour package, which you can install in Tanzu Kubernetes Grid (TKG) workload clusters to provide ingress control services for the cluster.

Contour is a Kubernetes ingress controller that uses the Envoy reverse HTTP proxy. Contour with Envoy is commonly used with other packages, such as External DNS, Prometheus, and Harbor.

The Contour package includes the Contour ingress controller and the Envoy reverse HTTP proxy. See Install Contour in Workload Clusters Deployed by a Standalone Management Cluster.

Contour Components

The Contour package installs on the cluster the two containers listed in the table. For more information, see https://projectcontour.io/. The containers are pulled from the VMware public registry specified in the Package Repository.

Contour Data Values

Below is an example contour-data-values.yaml.

The only customization is that the Envoy service is of type LoadBalancer (the default is NodePort). This means that the Envoy service will be accessible from outside of the cluster for ingress.

infrastructure_provider: vsphere
namespace: tanzu-system-ingress
contour:
 configFileContents: {}
 useProxyProtocol: false
 replicas: 2
 pspNames: "vmware-system-restricted"
 logLevel: info
envoy:
 service:
   type: LoadBalancer
   annotations: {}
   externalTrafficPolicy: Cluster
   disableWait: false
 hostPorts:
   enable: true
   http: 80
   https: 443
 hostNetwork: false
 terminationGracePeriodSeconds: 300
 logLevel: info
certificates:
 duration: 8760h
 renewBefore: 360h

Contour Package Configuration Parameters

You can customize your configuration by editing the default values in the Contour package configuration file.

The table below contains information about the values that you can customize in the contour-data-values.yaml file and how they can be used to modify the default behavior of Contour when deployed into a workload cluster.

If you reconfigure your Contour settings after the initial deployment, you must follow the steps in Update a Running Contour Deployment to apply the new configuration to the cluster.

^* new parameter in Contour v1.25.2 and above

^** new parameter in Contour v1.28.2 and above

Contour Config File Contents

As described above, the package configuration field contour.configFileContents can be used to specify the desired content for the Contour config file. The Contour package will use the contents of the contour.configFileContents field to create a ConfigMap which is mounted into the Contour pods as a volume. The format and exhaustive list of options for this config file are provided in the open-source Contour documentation.

For example, to customize the Contour config file to require TLS 1.3, use a data values file like the following:

contour:
  configFileContents:
    tls:
      minimum-protocol-version: 1.3
      maximum-protocol-version: 1.3

Some of the commonly used Contour config file settings are described below for convenience:

Gateway API support

Gateway API is a project maintained by SIG-NETWORK that represents next-generation APIs for service networking in Kubernetes. The API is comprised of a set of CRDs, intended to be expressive and extensible, with role-oriented interfaces. For more information, see API Overview in the Kubernetes Gateway API documentation.

In TKG 2.5.1, the Standard release channel Gateway API CRDs from version v0.8.1 are available in management and workload clusters.

Contour package version v1.26.1 and later supports configuring Contour to reconcile Gateway API resources as follows:

1. Define and create GatewayClass and Gateway objects for Contour:

   kind: GatewayClass
   apiVersion: gateway.networking.k8s.io/v1beta1
   metadata:
     name: example
   spec:
     controllerName: projectcontour.io/gateway-controller
   

   kind: Gateway
   apiVersion: gateway.networking.k8s.io/v1beta1
   metadata:
     name: contour
     namespace: tanzu-system-ingress
   spec:
     gatewayClassName: example
     listeners:
     - name: http
       protocol: HTTP
       port: 80
       allowedRoutes:
         namespaces:
           from: All
   

   The Contour package sets up the Gateway API in static provisioning mode and does not support more than two listener ports, 80 for HTTP and 443 for HTTPS.

2. Update your Contour package data-values.yaml file as described in Update a Running Contour Deployment to add the new Gateway object and enable attaching routes to it. For example, with the Gateway object named contour as defined above:

   contour:
     configFileContents:
       gateway:
         gatewayRef:
           name: contour
           namespace: tanzu-system-ingress
   

3. Run kubectl describe on the Gateway object until you confirm that:

   • Its status is listed as Accepted: True and Programmed: True
   • It has an IP address

4. Define and create an HTTPRoute object with parentRefs set to attach to the Gateway object and backendRefs set to name the Gateway API:

   apiVersion: gateway.networking.k8s.io/v1beta1
   kind: HTTPRoute
   metadata:
     name: example
     namespace: tanzu-system-ingress
   spec:
     parentRefs:
     - name: contour
     rules:
     - matches:
       - path:
           type: PathPrefix
           value: /
       backendRefs:
       - name: backend
         port: 8080
   

5. Run kubectl describe on the HTTPRoute object until you confirm that its status is Accepted: True.

6. To test the API, run curl or point a browser to the Gateway address with the API name, for example curl http://10.186.139.192:8080/backend.

For how to use Gateway API for advanced routing and request/response modification, see HTTP routing in the Kubernetes Gateway API documentation.

Route Timeout for File Downloads

By default, Envoy has a 15-second timeout for backend services to return a response. If you are using Contour for file transfer, or for other services that are slow to respond, you may need to adjust this value.

To set a custom response timeout, configure your HTTPProxy like the following:

apiVersion: projectcontour.io/v1
kind: HTTPProxy
metadata:
  name: httpproxy-custom-response-timeout
spec:
  virtualhost:
    fqdn: timeout.bar.com
  routes:
  - conditions:
    - prefix: /
    services:
    - name: s1
      port: 80
    timeoutPolicy:
      response: 5m

If you are using an Ingress resource instead, you can add the projectcontour.io/response-timeout annotation like the following:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-custom-response-timeout
  annotations:
    projectcontour.io/response-timeout: 5m
spec:
  rules:
  - host: timeout.bar.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: s1
            port:
              number: 80

See the open-source Contour documentation for HTTPProxy response timeouts and Ingress annotations for more information.

xDS mTLS Certificate Rotation Settings

By default, the xDS communication between the Contour controller and Envoy instances is secured via mTLS. The Contour package generates cert-manager Certificate objects, and cert-manager creates and rotates Secret objects for each component.

Prior to Contour 1.28.2, the validity periods for the generated CA certificate and client certificates were configured by the Contour package fields certificates.duration and certificates.renewBefore. The default values set certificates as valid for 1 year and rotated 30 days before expiry.

As of Contour 1.28.2, these fields have been deprecated and replaced by individual configuration fields for CA certificate and client certificate validity: certificates.caDuration, certificates.caRenewBefore, certificates.leafDuration, and certificates.leafRenewBefore. By default the generated CA is valid for 1 year and rotated 30 days before expiration. Leaf certificates are valid for 30 days and rotated 15 days before expiration.

To configure these fields with different values from the defaults, it is recommended to set leafRenewBefore to a value that is at least the leaf.Duration minus the CA certificates.caRenewBefore. This means that Contour and Envoy client certificates will be rotated more frequently than the CA, and ensures that stale CA certificate data does not end up in Secrets supplied to Contour and Envoy, which can cause connection issues and dropped traffic when Envoy instances restart or attempt to connect to the Contour controller.

The deprecated fields take precedence, for backwards compatibility, but it is recommended to use the newer fields to provide more control over CA and leaf certificates.