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:
-
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 for securing communication between Contour and Envoy should be valid for. | time.Duration | 8760h |
certificates.renewBefore |
How long before expiration the certificates for securing communication between Contour and Envoy should be renewed. | time.Duration | 360h |
* new parameter in Contour v1.25.2, not in v1.24.5.
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 |
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.
