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:

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:

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

  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.

check-circle-line exclamation-circle-line close-line
Scroll to top icon