Contour Logo

Documentation

Contour Configuration Reference

Configuration File

A configuration file can be passed to the --config-path argument of the contour serve command to specify additional configuration to Contour. In most deployments, this file is passed to Contour via a ConfigMap which is mounted as a volume to the Contour pod.

The Contour configuration file is optional. In its absence, Contour will operate with reasonable defaults. Where Contour settings can also be specified with command-line flags, the command-line value takes precedence over the configuration file.

Field NameTypeDefaultDescription
accesslog-formatstringenvoyThis key sets the global access log format for Envoy. Valid options are envoy or json.
debugbooleanfalseEnables debug logging.
default-http-versionsstring arrayHTTP/1.1
HTTP/2
This array specifies the HTTP versions that Contour should program Envoy to serve. HTTP versions are specified as strings of the form “HTTP/x”, where “x” represents the version number.
disablePermitInsecurebooleanfalseIf this field is true, Contour will ignore PermitInsecure field in HTTPProxy documents.
envoy-service-namestringenvoyThis sets the service name that will be inspected for address details to be applied to Ingress objects.
envoy-service-namespacestringprojectcontourThis sets the namespace of the service that will be inspected for address details to be applied to Ingress objects. If the CONTOUR_NAMESPACE environment variable is present, Contour will populate this field with its value.
ingress-status-addressstringNoneIf present, this specifies the address that will be copied into the Ingress status for each Ingress that Contour manages. It is exclusive with envoy-service-name and envoy-service-namespace.
inclusterbooleanfalseThis field specifies that Contour is running in a Kubernetes cluster and should use the in-cluster client access configuration.
json-fieldsstring arrayfieldsThis is the list the field names to include in the JSON access log format.
kubeconfigstring$HOME/.kube/configPath to a Kubernetes kubeconfig file for when Contour is executed outside a cluster.
leaderelectionleaderelectionThe leader election configuration.
tlsTLSThe default TLS configuration.
timeoutsTimeoutConfigThe timeout configuration.
clusterClusterConfigThe cluster configuration.
serverServerConfigThe server configuration for contour serve command.

TLS Configuration

The TLS configuration block can be used to configure default values for how Contour should provision TLS hosts.

Field NameTypeDefaultDescription
minimum-protocol-versionstring""This field specifies the minimum TLS protocol version that is allowed. Valid options are 1.2 and 1.3. Any other value defaults to TLS 1.1.
fallback-certificateFallback certificate configuration.
envoy-client-certificateClient certificate configuration for Envoy.

Fallback Certificate

Field NameTypeDefaultDescription
namestring""This field specifies the name of the Kubernetes secret to use as the fallback certificate.
namespacestring""This field specifies the namespace of the Kubernetes secret to use as the fallback certificate.

Envoy Client Certificate

Field NameTypeDefaultDescription
namestring""This field specifies the name of the Kubernetes secret to use as the client certificate and private key when establishing TLS connections to the backend service.
namespacestring""This field specifies the namespace of the Kubernetes secret to use as the client certificate and private key when establishing TLS connections to the backend service.

Leader Election Configuration

The leader election configuration block configures how a deployment with more than one Contour pod elects a leader. The Contour leader is responsible for updating the status field on Ingress and HTTPProxy documents. In the vast majority of deployments, only the configmap-name and configmap-namespace fields should require any configuration.

Field NameTypeDefaultDescription
configmap-namestringleader-electThe name of the ConfigMap that Contour leader election will lease.
configmap-namespacestringprojectcontourThe namespace of the ConfigMap that Contour leader election will lease. If the CONTOUR_NAMESPACE environment variable is present, Contour will populate this field with its value.
lease-durationduration15sThe duration of the leadership lease.
renew-deadlineduration10sThe length of time that the leader will retry refreshing leadership before giving up.
retry-periodduration2sThe interval at which Contour will attempt to the acquire leadership lease.

Timeout Configuration

The timeout configuration block can be used to configure various timeouts for the proxies. All fields are optional; Contour/Envoy defaults apply if a field is not specified.

Field NameTypeDefaultDescription
request-timeoutstringnone*This field specifies the default request timeout. Note that this is a timeout for the entire request, not an idle timeout. Must be a valid Go duration string, or omitted or set to infinity to disable the timeout entirely. See the Envoy documentation for more information.

Note: A value of 0s previously disabled this timeout entirely. This is no longer the case. Use infinity or omit this field to disable the timeout.
connection-idle-timeoutstring60sThis field defines how long the proxy should wait while there are no active requests (for HTTP/1.1) or streams (for HTTP/2) before terminating an HTTP connection. Must be a valid Go duration string, or infinity to disable the timeout entirely. See the Envoy documentation for more information.
stream-idle-timeoutstring5m*This field defines how long the proxy should wait while there is no request activity (for HTTP/1.1) or stream activity (for HTTP/2) before terminating the HTTP request or stream. Must be a valid Go duration string, or infinity to disable the timeout entirely. See the Envoy documentation for more information.
max-connection-durationstringnone*This field defines the maximum period of time after an HTTP connection has been established from the client to the proxy before it is closed by the proxy, regardless of whether there has been activity or not. Must be a valid Go duration string, or omitted or set to infinity for no max duration. See the Envoy documentation for more information.
connection-shutdown-grace-periodstring5s*This field defines how long the proxy will wait between sending an initial GOAWAY frame and a second, final GOAWAY frame when terminating an HTTP/2 connection. During this grace period, the proxy will continue to respond to new streams. After the final GOAWAY frame has been sent, the proxy will refuse new streams. Must be a valid Go duration string. See the Envoy documentation for more information.

* This is Envoy’s default setting value and is not explicitly configured by Contour.

Cluster Configuration

The cluster configuration block can be used to configure various parameters for Envoy clusters.

Field NameTypeDefaultDescription
dns-lookup-familystringautoThis field specifies the dns-lookup-family to use for upstream requests to externalName type Kubernetes services from an HTTPProxy route. Values are: auto, v4, v6`

Server Configuration

The server configuration block can be used to configure various settings for the contour serve command.

Field NameTypeDefaultDescription
xds-server-typestringcontourThis field specifies the xDS Server to use. Options are contour or envoy.

Configuration Example

The following is an example ConfigMap with configuration file included:

apiVersion: v1
kind: ConfigMap
metadata:
  name: contour
  namespace: projectcontour
data:
  contour.yaml: |
    # server:
    #   determine which XDS Server implementation to utilize in Contour.
    #   xds-server-type: contour
    #
    # should contour expect to be running inside a k8s cluster
    # incluster: true
    #
    # path to kubeconfig (if not running inside a k8s cluster)
    # kubeconfig: /path/to/.kube/config
    #
    # disable httpproxy permitInsecure field
    # disablePermitInsecure: false
    tls:
      # minimum TLS version that Contour will negotiate
      # minimumProtocolVersion: "1.1"
      fallback-certificate:
      # name: fallback-secret-name
      # namespace: projectcontour
      envoy-client-certificate:
      # name: envoy-client-cert-secret-name
      # namespace: projectcontour
    # The following config shows the defaults for the leader election.
    # leaderelection:
      # configmap-name: leader-elect
      # configmap-namespace: projectcontour
    # Default HTTP versions.
    # default-http-versions:
    # - "HTTP/1.1"
    # - "HTTP/2"
    # The following shows the default proxy timeout settings.
    # timeouts:
    #  request-timeout: infinity
    #  connection-idle-timeout: 60s
    #  stream-idle-timeout: 5m
    #  max-connection-duration: infinity
    #  connection-shutdown-grace-period: 5s
    #
    # Envoy cluster settings.
    # cluster:
    #   configure the cluster dns lookup family
    #   valid options are: auto (default), v4, v6
    #   dns-lookup-family: auto    

Note: The default example contour includes this file for easy deployment of Contour.

Environment Variables

CONTOUR_NAMESPACE

If present, the value of the CONTOUR_NAMESPACE environment variable is used as:

  1. The value for the contour bootstrap --namespace flag unless otherwise specified.
  2. The value for the contour certgen --namespace flag unless otherwise specified.
  3. The value for the contour serve --envoy-service-namespace flag unless otherwise specified.
  4. The value for the leaderelection.configmap-namespace config file setting for contour serve unless otherwise specified.

The CONTOUR_NAMESPACE environment variable is set via the Downward API in the Contour example manifests.

Bootstrap Config File

The bootstrap configuration file is generated by an initContainer in the Envoy daemonset which runs the contour bootstrap command to generate the file. This configuration file configures the Envoy container to connect to Contour and receive configuration via xDS.

The next section outlines all the available flags that can be passed to the contour bootstrap command which are used to customize the configuration file to match the environment in which Envoy is deployed.

Flags

There are flags that can be passed to contour bootstrap that help configure how Envoy connects to Contour:

FlagDefaultDescription
–resources-dir""Directory where resource files will be written.
–admin-address127.0.0.1Address the Envoy admin webpage will listen on.
–admin-port9001Port the Envoy admin webpage will listen on.
–xds-address127.0.0.1Address to connect to Contour xDS server on.
–xds-port8001Port to connect to Contour xDS server on.
–envoy-cafile""CA filename for Envoy secure xDS gRPC communication.
–envoy-cert-file""Client certificate filename for Envoy secure xDS gRPC communication.
–envoy-key-file""Client key filename for Envoy secure xDS gRPC communication.
–namespaceprojectcontourNamespace the Envoy container will run, also configured via ENV variable “CONTOUR_NAMESPACE”. Namespace is used as part of the metric names on static resources defined in the bootstrap configuration file.
–xds-resource-versionv2Specify the xDS API resource version to use. Options are v2 or v3.

Ready to try Contour?

Read our getting started documentation.