Contour Configuration Reference

• Serve Flags
• Configuration File
• Environment Variables
• Bootstrap Config File

Overview

There are various ways to configure Contour, flags, the configuration file, as well as environment variables. Contour has a precedence of configuration for contour serve, meaning anything configured in the config file is overridden by environment vars which are overridden by cli flags.

Serve Flags

The contour serve command is the main command which is used to watch for Kubernetes resource and process them into Envoy configuration which is then streamed to any Envoy via its xDS gRPC connection. There are a number of flags that can be passed to this command which further configures how Contour operates. Many of these flags are mirrored in the Contour Configuration File.

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.

TLS Configuration

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

Fallback Certificate

Envoy Client Certificate

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.

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.

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

Network Configuration

The network configuration block can be used to configure various parameters network connections.

Listener Configuration

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

Server Configuration

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

Gateway Configuration

The gateway configuration block is used to configure which gateway-api Gateway Contour should configure:

Rate Limit Service Configuration

The rate limit service configuration block is used to configure an optional global rate limit service:

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
    #
    # specify the gateway-api Gateway Contour should configure
    # gateway:
    #   name: contour
    #   namespace: projectcontour
    #
    # 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 RFC-compliant behavior to strip "Content-Length" header if
    # "Tranfer-Encoding: chunked" is also set.
    # disableAllowChunkedLength: false
    # Disable HTTPProxy permitInsecure field
    disablePermitInsecure: false
    tls:
    # minimum TLS version that Contour will negotiate
    # minimum-protocol-version: "1.2"
    # TLS ciphers to be supported by Envoy TLS listeners when negotiating
    # TLS 1.2.
    # cipher-suites:
    # - '[ECDHE-ECDSA-AES128-GCM-SHA256|ECDHE-ECDSA-CHACHA20-POLY1305]'
    # - '[ECDHE-RSA-AES128-GCM-SHA256|ECDHE-RSA-CHACHA20-POLY1305]'
    # - 'ECDHE-ECDSA-AES256-GCM-SHA384'
    # - 'ECDHE-RSA-AES256-GCM-SHA384'
    # Defines the Kubernetes name/namespace matching a secret to use
    # as the fallback certificate when requests which don't match the
    # SNI defined for a vhost.
      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
    ### Logging options
    # Default setting
    accesslog-format: envoy
    # To enable JSON logging in Envoy
    # accesslog-format: json
    # The default fields that will be logged are specified below.
    # To customise this list, just add or remove entries.
    # The canonical list is available at
    # https://godoc.org/github.com/projectcontour/contour/internal/envoy#JSONFields
    # json-fields:
    #   - "@timestamp"
    #   - "authority"
    #   - "bytes_received"
    #   - "bytes_sent"
    #   - "downstream_local_address"
    #   - "downstream_remote_address"
    #   - "duration"
    #   - "method"
    #   - "path"
    #   - "protocol"
    #   - "request_id"
    #   - "requested_server_name"
    #   - "response_code"
    #   - "response_flags"
    #   - "uber_trace_id"
    #   - "upstream_cluster"
    #   - "upstream_host"
    #   - "upstream_local_address"
    #   - "upstream_service_time"
    #   - "user_agent"
    #   - "x_forwarded_for"
    #
    # default-http-versions:
    # - "HTTP/2"
    # - "HTTP/1.1"
    #
    # 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   
    #
    # network:
    #   Configure the number of additional ingress proxy hops from the
    #   right side of the x-forwarded-for HTTP header to trust.
    #   num-trusted-hops: 0
    #
    # rateLimitService:
    #   extensionService: projectcontour/ratelimit
    #   domain: contour
    #   failOpen: false    

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: