Install Contour for Ingress Control

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.

Installation: Install the Contour package in one of the following ways, based on its deployment option:

Supervisor Service: Install and Configure Contour as a Supervisor Service
TKG on Supervisor:
- Install Contour Using the Tanzu CLI
- Install Contour Using Kubectl
Standalone management cluster: 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.

Container	Resource Type	Replicas	Description
Envoy	DaemonSet	one per node	High performance reverse proxy
Contour	Deployment	2	Management and configuration server for Envoy

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.

Parameter	Description	Type	Default
`infrastructure_provider`	The underlying infrastructure provider. Valid values are `vsphere`, `aws`, and `azure`.	string	`vsphere`
`kubernetes_distribution`	The distribution of Kubernetes, used to determine if distribution-specific configurations need to be applied. Options are empty and openshift. If running on an Openshift cluster, this must be set to openshift. When set to openshift, a Role and RoleBinding are created to associate Contour’s controllers with the appropriate Openshift Security Context Constraint resource.	string	none
`kubernetes_version`	The version of Kubernetes being used, for enabling version-specific behaviors. Accept any valid major.minor.patch version of Kubernetes. This field is optional. Currently only has effect when kubernetes_distribution is set to openshift.	semantic version string	none
`namespace`	The namespace where Contour and Envoy pods run, distinct from where the packages are deployed.	string	`tanzu-system-ingress`
`registry_secret_names`	The names of the placeholder secrets that will contain registry credentials to pull the Contour and Envoy images.	array of strings	`["contour-reg-creds"]`
`contour.configFileContents`	The YAML contents of the Contour config file. For more information, see the Contour Config File Contents section below.	YAML	none
`contour.replicas`	How many Contour pod replicas to have.	integer	`2`
`contour.useProxyProtocol`	Whether to enable `PROXY` protocol for all Envoy listeners.	boolean	`false`
`contour.logLevel`	The Contour log level. Valid values are `info` and `debug`.	string	`info`
`contour.pspNames`	A comma-separated list of pod security policies (PSPs) to apply to the Contour pods.	comma-separated string	`vmware-system-restricted`
`contour.resources.contour.limits.cpu`	CPU limit to apply to the contour container in the contour deployment.	string	none
`contour.resources.contour.limits.memory`	Memory limit to apply to the contour container in the contour deployment.	string	none
`contour.resources.contour.requests.cpu`	CPU request to apply to the contour container in the contour deployment.	string	none
`contour.resources.contour.requests.memory`	Memory request to apply to the contour container in the contour deployment.	string	none
`envoy.workload.type`	The type of Kubernetes workload Envoy is deployed as. Options are `Deployment` or `DaemonSet`.	string	`DaemonSet`
`envoy.workload.replicas`	The number of Envoy replicas to deploy when `envoy.workload.type` is set to `Deployment`.	integer	`2`
`envoy.workload.resources.envoy.limits.cpu`	CPU limit to apply to the envoy container in the envoy workload.	string	none
`envoy.workload.resources.envoy.limits.memory`	Memory limit to apply to the envoy container in the envoy workload.	string	none
`envoy.workload.resources.envoy.requests.cpu`	CPU request to apply to the envoy container in the envoy workload.	string	none
`envoy.workload.resources.envoy.requests.memory`	Memory request to apply to the envoy container in the envoy workload.	string	none
`envoy.workload.resources.shutdownManager.limits.cpu`	CPU limit to apply to the shutdown-manager container in the envoy workload.	string	none
`envoy.workload.resources.shutdownManager.limits.memory`	Memory limit to apply to the shutdown-manager container in the envoy workload.	string	none
`envoy.workload.resources.shutdownManager.requests.cpu`	CPU request to apply to the shutdown-manager container in the envoy workload.	string	none
`envoy.workload.resources.shutdownManager.limits.memory`	Memory request to apply to the shutdown-manager container in the envoy workload.	string	none
`envoy.service.type`	The type of Kubernetes service to provision for Envoy. Valid values are `LoadBalancer`, `NodePort`, and `ClusterIP`. If not specified, a `NodePort` service will be used for `vsphere` and a `LoadBalancer` for all other infrastructure providers.	string	none
`envoy.service.loadBalancerIP`	The desired load balancer IP for Envoy service. This setting is ignored if `envoy.service.type` is not set to `LoadBalancer`. This field configures the Service.Spec.LoadBalancerIP field which is deprecated as of Kubernetes 1.24. Users are encouraged to use cloud-provider specific Service annotations instead.	IP address string	none
`envoy.service.externalTrafficPolicy`	The external traffic policy for the Envoy service. Valid values are `Local` and `Cluster`.	string	`Local`
`envoy.service.annotations`	Annotations to set on the Envoy service.	map of string to string	none
`envoy.service.nodePorts.http`	If `envoy.service.type` == `NodePort`, the node port number to expose Envoy’s HTTP listener on. If not specified, a node port will be auto-assigned by Kubernetes. If loadBalancerTLSTermination is true, this value will be ignored, as the http port entry will be removed.	integer	none
`envoy.service.nodePorts.https`	If `envoy.service.type` == `NodePort`, the node port number to expose Envoy’s HTTPS listener on. If not specified, a node port will be auto-assigned by Kubernetes.	integer	none
`envoy.service.aws.LBType`	If `infrastructure_provider` == `aws`, the type of AWS load balancer to use. Valid values are `classic` and `nlb`. If not using `aws`, this value is ignored.	string	`classic`
`envoy.service.loadBalancerTLSTermination` *	When true, forwards traffic from 443 on the LoadBalancer to 8080 on the Envoy pod when terminating TLS at the LoadBalancer. Removes the http port entry on the Envoy Service.	boolean	`false`
`envoy.hostPorts.enable`	Whether to enable host ports for the Envoy pods. If `false`, `envoy.hostPorts.http` and `envoy.hostPorts.https` are ignored.	boolean	`true`
`envoy.hostPorts.http`	If `envoy.hostPorts.enable` == `true`, the host port number to expose Envoy’s HTTP listener on.	integer	`80`
`envoy.hostPorts.https`	If `envoy.hostPorts.enable` == `true`, the host port number to expose Envoy’s HTTPS listener on.	integer	`443`
`envoy.hostNetwork`	Whether to enable host networking for the Envoy pods.	boolean	`false`
`envoy.terminationGracePeriodSeconds`	The termination grace period, in seconds, for the Envoy pods.	integer	`300`
`envoy.logLevel`	The Envoy log level. Valid values are `trace`, `debug`, `info`, `warn`, `error`, `critical`, and `off`.	string	`info`
`envoy.pspNames`	A comma-separated list of pod security policies (PSPs) to apply to the Envoy pods.	comma-separated string	none
`certificates.duration`	How long the certificates should be valid for. Deprecated: Use `caDuration` and `leafDuration` instead. For backwards compatibility, `duration` takes precedence over `caDuration` and `leafDuration`.	time.Duration string	`8760h`
`certificates.renewBefore`	How long before expiration the certificates should be renewed. Deprecated: Use `caRenewBefore` and `leafRenewBefore` instead. For backwards compatibility , `renewBefore` takes precedence over `caRenewBefore` and `leafRenewBefore`.	time.Duration string	`360h`
`certificates.caDuration` **	How long the CA certificate for securing communication between Contour and Envoy should be valid for.	time.Duration string	`8760h`
`certificates.caRenewBefore` **	How long before expiration of the CA certificate for securing communication between Contour and Envoy should be renewed.	time.Duration string	`720h`
`certificates.leafDuration` **	How long the leaf certificates for securing communication between Contour and Envoy should be valid for. The leaf certificates are the certificates signed by the CA certificate.	time.Duration string	`720h`
`certificates.leafRenewBefore` **	How long before expiration of the leaf certificates for securing communication between Contour and Envoy should be renewed. The leaf certificates are the certificates signed by the CA certificate. It is recommended to set this to a value that is at least the leaf duration minus the ca certificate renew before, so the leaf certificates can be rotated every CA renew cycle.	time.Duration string	`360h`

^* 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:

Parameter	Description	Type	Default
`server.xds-server-type`	XDS Server type to use: Supported Values: contour or envoy	string	none
`tls.minimum-protocol-version`	Minimum TLS version that Contour will negotiate	string	`1.2`
`tls.fallback-certificate.name`	Name of secret containing fallback certificate for requests that don’t match SNI defined for a vhost	string	none
`tls.fallback-certificate.namespace`	Namespace of secret containing fallback certificate	string	none
`tls.envoy-client-certificate.name`	Name of the secret to use as client certificate, private key for TLS connection to backend service	string	none
`tls.envoy-client-certificate.namespace`	Namespace of the secret to use as client certificate, private key for TLS connection to backend service	string	none
`leaderelection.configmap-name`	Name of configmap to be used for contour leaderelection	string	`leader-elect`
`leaderelection.configmap-namespace`	Namespace of contour leaderelection configmap	string	`tanzu-system-ingress`
`disablePermitInsecure`	Disables HTTPProxy permitInsecure field	boolean	`false`
`accesslog-format`	Access log format	string	`envoy`
`json-fields`	Fields that will be logged	array of strings	envoy package doc	none
`default-http-versions`	HTTP versions that Contour should program Envoy to serve	array of strings	`["HTTP/1.1", "HTTP/2"]`
`timeouts.request-timeout`	The timeout for an entire request to be received from a client	time.Duration	none (timeout is disabled)
`timeouts.connection-idle-timeout`	The time to wait before terminating an idle connection	time.Duration	`60s`
`timeouts.stream-idle-timeout`	The time to wait before terminating an request or stream with no activity	time.Duration	`5m`
`timeouts.max-connection-duration`	The time to wait before terminating an connection irrespective of activity or not	time.Duration	none (timeout is disabled)
`timeouts.connection-shutdown-grace-period`	The time to wait between sending an initial and final GOAWAY	time.Duration	`5s`
`cluster.dns-lookup-family`	dns-lookup-family to use for upstream requests to externalName type services from an HTTPProxy route. Supported Values: `auto`, `v4`, `v6`	string	none
`debug`	Turn on contour debugging	boolean	`false`
`ingress-status-address`	The address to set on status of every Ingress resource	string	none

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:

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

Note
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.

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

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

Run kubectl describe on the HTTPRoute object until you confirm that its status is Accepted: True.
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.