github.com/projectcontour/contour@v1.28.2/site/content/docs/main/configuration.md (about) 1 # Contour Configuration Reference 2 3 - [Serve Flags](#serve-flags) 4 - [Configuration File](#configuration-file) 5 - [Environment Variables](#environment-variables) 6 - [Bootstrap Config File](#bootstrap-config-file) 7 8 ## Overview 9 10 There are various ways to configure Contour, flags, the configuration file, as well as environment variables. 11 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. 12 13 ## Serve Flags 14 15 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. 16 There are a number of flags that can be passed to this command which further configures how Contour operates. 17 Many of these flags are mirrored in the [Contour Configuration File](#configuration-file). 18 19 | Flag Name | Description | 20 | --------------------------------------------------------------- | --------------------------------------------------------------------------------------- | 21 | `--config-path` | Path to base configuration | 22 | `--contour-config-name` | Name of the ContourConfiguration resource to use | 23 | `--incluster` | Use in cluster configuration | 24 | `--kubeconfig=</path/to/file>` | Path to kubeconfig (if not in running inside a cluster) | 25 | `--xds-address=<ipaddr>` | xDS gRPC API address | 26 | `--xds-port=<port>` | xDS gRPC API port | 27 | `--stats-address=<ipaddr>` | Envoy /stats interface address | 28 | `--stats-port=<port>` | Envoy /stats interface port | 29 | `--debug-http-address=<address>` | Address the debug http endpoint will bind to. | 30 | `--debug-http-port=<port>` | Port the debug http endpoint will bind to | 31 | `--http-address=<ipaddr>` | Address the metrics HTTP endpoint will bind to | 32 | `--http-port=<port>` | Port the metrics HTTP endpoint will bind to. | 33 | `--health-address=<ipaddr>` | Address the health HTTP endpoint will bind to | 34 | `--health-port=<port>` | Port the health HTTP endpoint will bind to | 35 | `--contour-cafile=</path/to/file\|CONTOUR_CERT_FILE>` | CA bundle file name for serving gRPC with TLS | 36 | `--contour-cert-file=</path/to/file\|CONTOUR_CERT_FILE>` | Contour certificate file name for serving gRPC over TLS | 37 | `--contour-key-file=</path/to/file\|CONTOUR_KEY_FILE>` | Contour key file name for serving gRPC over TLS | 38 | `--insecure` | Allow serving without TLS secured gRPC | 39 | `--root-namespaces=<ns,ns>` | Restrict contour to searching these namespaces for root ingress routes | 40 | `--watch-namespaces=<ns,ns>` | Restrict contour to searching these namespaces for all resources | 41 | `--ingress-class-name=<name>` | Contour IngressClass name (comma-separated list allowed) | 42 | `--ingress-status-address=<address>` | Address to set in Ingress object status | 43 | `--envoy-http-access-log=</path/to/file>` | Envoy HTTP access log | 44 | `--envoy-https-access-log=</path/to/file>` | Envoy HTTPS access log | 45 | `--envoy-service-http-address=<ipaddr>` | Kubernetes Service address for HTTP requests | 46 | `--envoy-service-https-address=<ipaddr>` | Kubernetes Service address for HTTPS requests | 47 | `--envoy-service-http-port=<port>` | Kubernetes Service port for HTTP requests | 48 | `--envoy-service-https-port=<port>` | Kubernetes Service port for HTTPS requests | 49 | `--envoy-service-name=<name>` | Name of the Envoy service to inspect for Ingress status details. | 50 | `--envoy-service-namespace=<namespace>` | Envoy Service Namespace | 51 | `--use-proxy-protocol` | Use PROXY protocol for all listeners | 52 | `--accesslog-format=<envoy\|json>` | Format for Envoy access logs | 53 | `--disable-leader-election` | Disable leader election mechanism | 54 | `--disable-feature=<extensionservices\|tlsroutes\|grpcroutes>` | Do not start an informer for the specified resources. Flag can be given multiple times. | 55 | `--leader-election-lease-duration` | The duration of the leadership lease. | 56 | `--leader-election-renew-deadline` | The duration leader will retry refreshing leadership before giving up. | 57 | `--leader-election-retry-period` | The interval which Contour will attempt to acquire leadership lease. | 58 | `--leader-election-resource-name` | The name of the resource (Lease) leader election will lease. | 59 | `--leader-election-resource-namespace` | The namespace of the resource (Lease) leader election will lease. | 60 | `-d, --debug` | Enable debug logging | 61 | `--kubernetes-debug=<log level>` | Enable Kubernetes client debug logging | 62 | `--log-format=<text\|json>` | Log output format for Contour. Either text (default) or json. | 63 | `--kubernetes-client-qps=<qps>` | QPS allowed for the Kubernetes client. | 64 | `--kubernetes-client-burst=<burst>` | Burst allowed for the Kubernetes client. | 65 66 ## Configuration File 67 68 A configuration file can be passed to the `--config-path` argument of the `contour serve` command to specify additional configuration to Contour. 69 In most deployments, this file is passed to Contour via a ConfigMap which is mounted as a volume to the Contour pod. 70 71 The Contour configuration file is optional. 72 In its absence, Contour will operate with reasonable defaults. 73 Where Contour settings can also be specified with command-line flags, the command-line value takes precedence over the configuration file. 74 75 | Field Name | Type | Default | Description | 76 |---------------------------| ---------------------- |------------------------------------------------------------------------------------------------------| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 77 | accesslog-format | string | `envoy` | This key sets the global [access log format][2] for Envoy. Valid options are `envoy` or `json`. | 78 | accesslog-format-string | string | None | If present, this specifies custom access log format for Envoy. See [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage) for more information about the syntax. This field only has effect if `accesslog-format` is `envoy` | 79 | accesslog-level | string | `info` | This field specifies the verbosity level of the access log. Valid options are `info` (default, all requests are logged), `error` (all non-success, i.e. 300+ response code, requests are logged), `critical` (all server error, i.e. 500+ response code, requests are logged) and `disabled`. | 80 | debug | boolean | `false` | Enables debug logging. | 81 | default-http-versions | string array | <code style="white-space:nowrap">HTTP/1.1</code> <br> <code style="white-space:nowrap">HTTP/2</code> | 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. | 82 | disableAllowChunkedLength | boolean | `false` | If this field is true, Contour will disable the RFC-compliant Envoy behavior to strip the `Content-Length` header if `Transfer-Encoding: chunked` is also set. This is an emergency off-switch to revert back to Envoy's default behavior in case of failures. 83 | disableMergeSlashes | boolean | `false` | This field disables Envoy's non-standard merge_slashes path transformation behavior that strips duplicate slashes from request URL paths. 84 | serverHeaderTransformation | string | `overwrite` | This field defines the action to be applied to the Server header on the response path. Values: `overwrite` (default), `append_if_absent`, `pass_through` 85 | disablePermitInsecure | boolean | `false` | If this field is true, Contour will ignore `PermitInsecure` field in HTTPProxy documents. | 86 | envoy-service-name | string | `envoy` | This sets the service name that will be inspected for address details to be applied to Ingress objects. | 87 | envoy-service-namespace | string | `projectcontour` | This 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. | 88 | ingress-status-address | string | None | If 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`. | 89 | incluster | boolean | `false` | This field specifies that Contour is running in a Kubernetes cluster and should use the in-cluster client access configuration. | 90 | json-fields | string array | [fields][5] | This is the list the field names to include in the JSON [access log format][2]. This field only has effect if `accesslog-format` is `json`. | 91 | kubeconfig | string | `$HOME/.kube/config` | Path to a Kubernetes [kubeconfig file][3] for when Contour is executed outside a cluster. | 92 | kubernetesClientQPS | float32 | | QPS allowed for the Kubernetes client. | 93 | kubernetesClientBurst | int | | Burst allowed for the Kubernetes client. | 94 | policy | PolicyConfig | | The default [policy configuration](#policy-configuration). | 95 | tls | TLS | | The default [TLS configuration](#tls-configuration). | 96 | timeouts | TimeoutConfig | | The [timeout configuration](#timeout-configuration). | 97 | cluster | ClusterConfig | | The [cluster configuration](#cluster-configuration). | 98 | network | NetworkConfig | | The [network configuration](#network-configuration). | 99 | listener | ListenerConfig | | The [listener configuration](#listener-configuration). | 100 | server | ServerConfig | | The [server configuration](#server-configuration) for `contour serve` command. | 101 | gateway | GatewayConfig | | The [gateway-api Gateway configuration](#gateway-configuration). | 102 | rateLimitService | RateLimitServiceConfig | | The [rate limit service configuration](#rate-limit-service-configuration). | 103 | enableExternalNameService | boolean | `false` | Enable ExternalName Service processing. Enabling this has security implications. Please see the [advisory](https://github.com/projectcontour/contour/security/advisories/GHSA-5ph6-qq5x-7jwc) for more details. | 104 | metrics | MetricsParameters | | The [metrics configuration](#metrics-configuration) | 105 | featureFlags | string array | `[]` | Defines the toggle to enable new contour features. Available toggles are: <br/> 1. `useEndpointSlices` - configures contour to fetch endpoint data from k8s endpoint slices. | 106 107 ### TLS Configuration 108 109 The TLS configuration block can be used to configure default values for how 110 Contour should provision TLS hosts. 111 112 | Field Name | Type | Default | Description | 113 | ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 114 | minimum-protocol-version | string | `1.2` | This field specifies the minimum TLS protocol version that is allowed. Valid options are `1.2` (default) and `1.3`. Any other value defaults to TLS 1.2. 115 | maximum-protocol-version | string | `1.3` | This field specifies the maximum TLS protocol version that is allowed. Valid options are `1.2` and `1.3`. Any other value defaults to TLS 1.3. | 116 | fallback-certificate | | | [Fallback certificate configuration](#fallback-certificate). | 117 | envoy-client-certificate | | | [Client certificate configuration for Envoy](#envoy-client-certificate). | 118 | cipher-suites | []string | See [config package documentation](https://pkg.go.dev/github.com/projectcontour/contour/pkg/config#pkg-variables) | This field specifies the TLS ciphers to be supported by TLS listeners when negotiating TLS 1.2. This parameter should only be used by advanced users. Note that this is ignored when TLS 1.3 is in use. The set of ciphers that are allowed is a superset of those supported by default in stock, non-FIPS Envoy builds and FIPS builds as specified [here](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#envoy-v3-api-field-extensions-transport-sockets-tls-v3-tlsparameters-cipher-suites). Custom ciphers not accepted by Envoy in a standard build are not supported. | 119 120 ### Upstream TLS Configuration 121 122 The Upstream TLS configuration block can be used to configure default values for how Contour establishes TLS for upstream connections. 123 124 | Field Name | Type | Default | Description | 125 | ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 126 | minimum-protocol-version | string | `1.2` | This field specifies the minimum TLS protocol version that is allowed. Valid options are `1.2` (default) and `1.3`. Any other value defaults to TLS 1.2. | 127 | maximum-protocol-version | string | `1.3` | This field specifies the maximum TLS protocol version that is allowed. Valid options are `1.2` and `1.3`. Any other value defaults to TLS 1.3. | 128 | cipher-suites | []string | See [config package documentation](https://pkg.go.dev/github.com/projectcontour/contour/pkg/config#pkg-variables) | This field specifies the TLS ciphers to be supported by TLS listeners when negotiating TLS 1.2. This parameter should only be used by advanced users. Note that this is ignored when TLS 1.3 is in use. The set of ciphers that are allowed is a superset of those supported by default in stock, non-FIPS Envoy builds and FIPS builds as specified [here](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#envoy-v3-api-field-extensions-transport-sockets-tls-v3-tlsparameters-cipher-suites). Custom ciphers not accepted by Envoy in a standard build are not supported. | 129 130 ### Fallback Certificate 131 132 | Field Name | Type | Default | Description | 133 | ---------- | ------ | ------- | ----------------------------------------------------------------------------------------------- | 134 | name | string | `""` | This field specifies the name of the Kubernetes secret to use as the fallback certificate. | 135 | namespace | string | `""` | This field specifies the namespace of the Kubernetes secret to use as the fallback certificate. | 136 137 138 ### Envoy Client Certificate 139 140 | Field Name | Type | Default | Description | 141 | ---------- | ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 142 | name | string | `""` | 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. | 143 | namespace | string | `""` | 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. | 144 145 146 ### Timeout Configuration 147 148 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. 149 150 | Field Name | Type | Default | Description | 151 | -------------------------------- | ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 152 | request-timeout | string | none* | 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][4], or omitted or set to `infinity` to disable the timeout entirely. See [the Envoy documentation][12] for more information.<br /><br />_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._ | 153 | connection-idle-timeout | string | `60s` | This 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. The timeout applies to downstream connections only. Must be a [valid Go duration string][4], or `infinity` to disable the timeout entirely. See [the Envoy documentation][8] for more information. | 154 | stream-idle-timeout | string | `5m`* | This field defines how long the proxy should wait while there is no activity during single request/response (for HTTP/1.1) or stream (for HTTP/2). Timeout will not trigger while HTTP/1.1 connection is idle between two consecutive requests. Must be a [valid Go duration string][4], or `infinity` to disable the timeout entirely. See [the Envoy documentation][9] for more information. | 155 | max-connection-duration | string | none* | 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][4], or omitted or set to `infinity` for no max duration. See [the Envoy documentation][10] for more information. | 156 | delayed-close-timeout | string | `1s`* | *Note: this is an advanced setting that should not normally need to be tuned.* <br /><br /> This field defines how long envoy will wait, once connection close processing has been initiated, for the downstream peer to close the connection before Envoy closes the socket associated with the connection. Setting this timeout to 'infinity' will disable it. See [the Envoy documentation][13] for more information. | 157 | connection-shutdown-grace-period | string | `5s`* | 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][4]. See [the Envoy documentation][11] for more information. | 158 | connect-timeout | string | `2s` | This field defines how long the proxy will wait for the upstream connection to be established. 159 160 _This is Envoy's default setting value and is not explicitly configured by Contour._ 161 162 ### Cluster Configuration 163 164 The cluster configuration block can be used to configure various parameters for Envoy clusters. 165 166 | Field Name | Type | Default | Description | 167 |-----------------------------------|--------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 168 | dns-lookup-family | string | auto | This 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`, `all` | 169 | max-requests-per-connection | int | none | This field specifies the maximum requests for upstream connections. If not specified, there is no limit | 170 | circuit-breakers | [CircuitBreakers](#circuit-breakers) | none | This field specifies the default value for [circuit-breaker-annotations](https://projectcontour.io/docs/main/config/annotations/) for services that don't specify them. | 171 | per-connection-buffer-limit-bytes | int | 1MiB* | This field specifies the soft limit on size of the cluster’s new connection read and write buffer. If not specified, Envoy defaults of 1MiB apply | 172 | upstream-tls | UpstreamTLS | | [Upstream TLS configuration](#upstream-tls) | 173 174 _This is Envoy's default setting value and is not explicitly configured by Contour._ 175 176 177 178 179 ### Network Configuration 180 181 The network configuration block can be used to configure various parameters network connections. 182 183 | Field Name | Type | Default | Description | 184 | ---------------- | ---- | ------- | ----------------------------------------------------------------------------------------------------------------------- | 185 | num-trusted-hops | int | 0 | Configures the number of additional ingress proxy hops from the right side of the x-forwarded-for HTTP header to trust. | 186 | admin-port | int | 9001 | Configures the Envoy Admin read-only listener on Envoy. Set to `0` to disable. | 187 188 ### Listener Configuration 189 190 The listener configuration block can be used to configure various parameters for Envoy listener. 191 192 | Field Name | Type | Default | Description | 193 |-----------------------------------|--------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 194 | connection-balancer | string | `""` | This field specifies the listener connection balancer. If the value is `exact`, the listener will use the exact connection balancer to balance connections between threads in a single Envoy process. See [the Envoy documentation][14] for more information. | 195 | max-requests-per-connection | int | none | This field specifies the maximum requests for downstream connections. If not specified, there is no limit | 196 | per-connection-buffer-limit-bytes | int | 1MiB* | This field specifies the soft limit on size of the listener’s new connection read and write buffer. If not specified, Envoy defaults of 1MiB apply | 197 | socket-options | SocketOptions | | The [Socket Options](#socket-options) for Envoy listeners. | 198 | max-requests-per-io-cycle | int | none | Defines the limit on number of HTTP requests that Envoy will process from a single connection in a single I/O cycle. Requests over this limit are processed in subsequent I/O cycles. Can be used as a mitigation for CVE-2023-44487 when abusive traffic is detected. Configures the `http.max_requests_per_io_cycle` Envoy runtime setting. The default value when this is not set is no limit. | 199 | http2-max-concurrent-streams | int | none | Defines the value for SETTINGS_MAX_CONCURRENT_STREAMS Envoy will advertise in the SETTINGS frame in HTTP/2 connections and the limit for concurrent streams allowed for a peer on a single HTTP/2 connection. It is recommended to not set this lower than 100 but this field can be used to bound resource usage by HTTP/2 connections and mitigate attacks like CVE-2023-44487. The default value when this is not set is unlimited. | 200 201 _This is Envoy's default setting value and is not explicitly configured by Contour._ 202 203 ### Server Configuration 204 205 The server configuration block can be used to configure various settings for the `contour serve` command. 206 207 | Field Name | Type | Default | Description | 208 | --------------- | ------ | ------- | ----------------------------------------------------------------------------- | 209 | xds-server-type | string | contour | This field specifies the xDS Server to use. Options are `contour` or `envoy`. | 210 211 ### Gateway Configuration 212 213 The gateway configuration block is used to configure which gateway-api Gateway Contour should configure: 214 215 | Field Name | Type | Default | Description | 216 | -------------- | -------------- | ------- | ------------------------------------------------------------------------------ | 217 | controllerName | string | | **DEPRECATED**: Use `gatewayRef` or the Gateway provisioner instead. This field will be removed in a future release. Gateway Class controller name (i.e. projectcontour.io/gateway-controller). If set, Contour will reconcile the oldest GatewayClass, and its oldest Gateway, with this controller string. Only one of `controllerName` or `gatewayRef` must be set. | 218 | gatewayRef | NamespacedName | | [Gateway namespace and name](#gateway-ref). If set, Contour will reconcile this specific Gateway. Only one of `controllerName` or `gatewayRef` must be set. | 219 220 ### Gateway Ref 221 222 | Field Name | Type | Default | Description | 223 | ---------- | ------ | ------- | ----------------------------------------------------------------------------------------------- | 224 | name | string | `""` | This field specifies the name of the specific Gateway to reconcile. | 225 | namespace | string | `""` | This field specifies the namespace of the specific Gateway to reconcile. | 226 227 ### Policy Configuration 228 229 The Policy configuration block can be used to configure default policy values 230 that are set if not overridden by the user. 231 232 The `request-headers` field is used to rewrite headers on a HTTP request, and 233 the `response-headers` field is used to rewrite headers on a HTTP response. 234 235 | Field Name | Type | Default | Description | 236 | ---------------- | ------------ | ------- | ------------------------------------------------------------------------------------------------- | 237 | request-headers | HeaderPolicy | none | The default request headers set or removed on all service routes if not overridden in the object | 238 | response-headers | HeaderPolicy | none | The default response headers set or removed on all service routes if not overridden in the object | 239 | applyToIngress | Boolean | false | Whether the global policy should apply to Ingress objects | 240 241 #### HeaderPolicy 242 243 The `set` field sets an HTTP header value, creating it if it doesn't already exist but not overwriting it if it does. 244 The `remove` field removes an HTTP header. 245 246 | Field Name | Type | Default | Description | 247 | ---------- | ----------------- | ------- | ------------------------------------------------------------------------------- | 248 | set | map[string]string | none | Map of headers to set on all service routes if not overridden in the object | 249 | remove | []string | none | List of headers to remove on all service routes if not overridden in the object | 250 251 Note: the values of entries in the `set` and `remove` fields can be overridden in HTTPProxy objects but it it not possible to remove these entries. 252 253 ### Rate Limit Service Configuration 254 255 The rate limit service configuration block is used to configure an optional global rate limit service: 256 257 | Field Name | Type | Default | Description | 258 |-----------------------------| ------ | ------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 259 | extensionService | string | <none> | This field identifies the extension service defining the rate limit service, formatted as <namespace>/<name>. | 260 | domain | string | contour | This field defines the rate limit domain value to pass to the rate limit service. Acts as a container for a set of rate limit definitions within the RLS. | 261 | failOpen | bool | false | This field defines whether to allow requests to proceed when the rate limit service fails to respond with a valid rate limit decision within the timeout defined on the extension service. | 262 | enableXRateLimitHeaders | bool | false | This field defines whether to include the X-RateLimit headers X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (as defined by the IETF Internet-Draft https://tools.ietf.org/id/draft-polli-ratelimit-headers-03.html), on responses to clients when the Rate Limit Service is consulted for a request. | 263 | enableResourceExhaustedCode | bool | false | This field defines whether to translate status code 429 to gRPC RESOURCE_EXHAUSTED instead of UNAVAILABLE. | 264 265 ### Metrics Configuration 266 267 MetricsParameters holds configurable parameters for Contour and Envoy metrics. 268 269 | Field Name | Type | Default | Description | 270 | ----------- | ----------------------- | ------- | -------------------------------------------------------------------- | 271 | contour | MetricsServerParameters | | [Metrics Server Parameters](#metrics-server-parameters) for Contour. | 272 | envoy | MetricsServerParameters | | [Metrics Server Parameters](#metrics-server-parameters) for Envoy. | 273 274 ### Metrics Server Parameters 275 276 MetricsServerParameters holds configurable parameters for Contour and Envoy metrics. 277 Metrics are served over HTTPS if `server-certificate-path` and `server-key-path` are set. 278 Metrics and health endpoints cannot have the same port number when metrics are served over HTTPS. 279 280 | Field Name | Type | Default | Description | 281 | ----------------------- | ------ | ---------------------------- | -----------------------------------------------------------------------------| 282 | address | string | 0.0.0.0 | Address that metrics server will bind to. | 283 | port | int | 8000 (Contour), 8002 (Envoy) | Port that metrics server will bind to. | 284 | server-certificate-path | string | none | Optional path to the server certificate file. | 285 | server-key-path | string | none | Optional path to the server private key file. | 286 | ca-certificate-path | string | none | Optional path to the CA certificate file used to verify client certificates. | 287 288 ### Socket Options 289 290 | Field Name | Type | Default | Description | 291 | --------------- | ------ | ------- | ----------------------------------------------------------------------------- | 292 | tos | int | 0 | Defines the value for IPv4 TOS field (including 6 bit DSCP field) for IP packets originating from Envoy listeners. Single value is applied to all listeners. The value must be in the range 0-255, 0 means socket option is not set. If listeners are bound to IPv6-only addresses, setting this option will cause an error. | 293 | traffic-class | int | 0 | Defines the value for IPv6 Traffic Class field (including 6 bit DSCP field) for IP packets originating from the Envoy listeners. Single value is applied to all listeners. The value must be in the range 0-255, 0 means socket option is not set. If listeners are bound to IPv4-only addresses, setting this option will cause an error. | 294 295 296 ### Circuit Breakers 297 298 | Field Name | Type | Default | Description | 299 | --------------- | ------ | ------- | ----------------------------------------------------------------------------- | 300 | max-connections | int | 0 | The maximum number of connections that a single Envoy instance allows to the Kubernetes Service; defaults to 1024. | 301 | max-pending-requests | int | 0 | The maximum number of pending requests that a single Envoy instance allows to the Kubernetes Service; defaults to 1024. | 302 | max-requests | int | 0 | The maximum parallel requests a single Envoy instance allows to the Kubernetes Service; defaults to 1024 | 303 | max-retries | int | 0 | The maximum number of parallel retries a single Envoy instance allows to the Kubernetes Service; defaults to 3. This setting only makes sense if the cluster is configured to do retries.| 304 305 ### Configuration Example 306 307 The following is an example ConfigMap with configuration file included: 308 309 ```yaml 310 apiVersion: v1 311 kind: ConfigMap 312 metadata: 313 name: contour 314 namespace: projectcontour 315 data: 316 contour.yaml: | 317 # 318 # server: 319 # determine which XDS Server implementation to utilize in Contour. 320 # xds-server-type: contour 321 # 322 # specify the gateway-api Gateway Contour should configure 323 # gateway: 324 # controllerName: projectcontour.io/gateway-controller 325 # 326 # should contour expect to be running inside a k8s cluster 327 # incluster: true 328 # 329 # path to kubeconfig (if not running inside a k8s cluster) 330 # kubeconfig: /path/to/.kube/config 331 # 332 # Disable RFC-compliant behavior to strip "Content-Length" header if 333 # "Tranfer-Encoding: chunked" is also set. 334 # disableAllowChunkedLength: false 335 # Disable HTTPProxy permitInsecure field 336 disablePermitInsecure: false 337 tls: 338 # minimum TLS version that Contour will negotiate 339 # minimum-protocol-version: "1.2" 340 # TLS ciphers to be supported by Envoy TLS listeners when negotiating 341 # TLS 1.2. 342 # cipher-suites: 343 # - '[ECDHE-ECDSA-AES128-GCM-SHA256|ECDHE-ECDSA-CHACHA20-POLY1305]' 344 # - '[ECDHE-RSA-AES128-GCM-SHA256|ECDHE-RSA-CHACHA20-POLY1305]' 345 # - 'ECDHE-ECDSA-AES256-GCM-SHA384' 346 # - 'ECDHE-RSA-AES256-GCM-SHA384' 347 # Defines the Kubernetes name/namespace matching a secret to use 348 # as the fallback certificate when requests which don't match the 349 # SNI defined for a vhost. 350 fallback-certificate: 351 # name: fallback-secret-name 352 # namespace: projectcontour 353 envoy-client-certificate: 354 # name: envoy-client-cert-secret-name 355 # namespace: projectcontour 356 ### Logging options 357 # Default setting 358 accesslog-format: envoy 359 # The default access log format is defined by Envoy but it can be customized by setting following variable. 360 # accesslog-format-string: "...\n" 361 # To enable JSON logging in Envoy 362 # accesslog-format: json 363 # accesslog-level: info 364 # The default fields that will be logged are specified below. 365 # To customise this list, just add or remove entries. 366 # The canonical list is available at 367 # https://godoc.org/github.com/projectcontour/contour/internal/envoy#JSONFields 368 # json-fields: 369 # - "@timestamp" 370 # - "authority" 371 # - "bytes_received" 372 # - "bytes_sent" 373 # - "downstream_local_address" 374 # - "downstream_remote_address" 375 # - "duration" 376 # - "method" 377 # - "path" 378 # - "protocol" 379 # - "request_id" 380 # - "requested_server_name" 381 # - "response_code" 382 # - "response_flags" 383 # - "uber_trace_id" 384 # - "upstream_cluster" 385 # - "upstream_host" 386 # - "upstream_local_address" 387 # - "upstream_service_time" 388 # - "user_agent" 389 # - "x_forwarded_for" 390 # 391 # default-http-versions: 392 # - "HTTP/2" 393 # - "HTTP/1.1" 394 # 395 # The following shows the default proxy timeout settings. 396 # timeouts: 397 # request-timeout: infinity 398 # connection-idle-timeout: 60s 399 # stream-idle-timeout: 5m 400 # max-connection-duration: infinity 401 # connection-shutdown-grace-period: 5s 402 # 403 # Envoy cluster settings. 404 # cluster: 405 # configure the cluster dns lookup family 406 # valid options are: auto (default), v4, v6, all 407 # dns-lookup-family: auto 408 # the maximum requests for upstream connections. 409 # If not specified, there is no limit. 410 # Setting this parameter to 1 will effectively disable keep alive 411 # max-requests-per-connection: 0 412 # the soft limit on size of the cluster’s new connection read and write buffers 413 # per-connection-buffer-limit-bytes: 32768 414 # 415 # network: 416 # Configure the number of additional ingress proxy hops from the 417 # right side of the x-forwarded-for HTTP header to trust. 418 # num-trusted-hops: 0 419 # Configure the port used to access the Envoy Admin interface. 420 # admin-port: 9001 421 # 422 # Configure an optional global rate limit service. 423 # rateLimitService: 424 # Identifies the extension service defining the rate limit service, 425 # formatted as <namespace>/<name>. 426 # extensionService: projectcontour/ratelimit 427 # Defines the rate limit domain to pass to the rate limit service. 428 # Acts as a container for a set of rate limit definitions within 429 # the RLS. 430 # domain: contour 431 # Defines whether to allow requests to proceed when the rate limit 432 # service fails to respond with a valid rate limit decision within 433 # the timeout defined on the extension service. 434 # failOpen: false 435 # Defines whether to include the X-RateLimit headers X-RateLimit-Limit, 436 # X-RateLimit-Remaining, and X-RateLimit-Reset (as defined by the IETF 437 # Internet-Draft linked below), on responses to clients when the Rate 438 # Limit Service is consulted for a request. 439 # ref. https://tools.ietf.org/id/draft-polli-ratelimit-headers-03.html 440 # enableXRateLimitHeaders: false 441 # Defines whether to translate status code 429 to grpc code RESOURCE_EXHAUSTED 442 # instead of the default UNAVAILABLE 443 # enableResourceExhaustedCode: false 444 # 445 # Global Policy settings. 446 # policy: 447 # # Default headers to set on all requests (unless set/removed on the HTTPProxy object itself) 448 # request-headers: 449 # set: 450 # # example: the hostname of the Envoy instance that proxied the request 451 # X-Envoy-Hostname: %HOSTNAME% 452 # # example: add a l5d-dst-override header to instruct Linkerd what service the request is destined for 453 # l5d-dst-override: %CONTOUR_SERVICE_NAME%.%CONTOUR_NAMESPACE%.svc.cluster.local:%CONTOUR_SERVICE_PORT% 454 # # default headers to set on all responses (unless set/removed on the HTTPProxy object itself) 455 # response-headers: 456 # set: 457 # # example: Envoy flags that provide additional details about the response or connection 458 # X-Envoy-Response-Flags: %RESPONSE_FLAGS% 459 # Whether or not the policy settings should apply to ingress objects 460 # applyToIngress: true 461 # 462 # metrics: 463 # contour: 464 # address: 0.0.0.0 465 # port: 8000 466 # server-certificate-path: /path/to/server-cert.pem 467 # server-key-path: /path/to/server-private-key.pem 468 # ca-certificate-path: /path/to/root-ca-for-client-validation.pem 469 # envoy: 470 # address: 0.0.0.0 471 # port: 8002 472 # server-certificate-path: /path/to/server-cert.pem 473 # server-key-path: /path/to/server-private-key.pem 474 # ca-certificate-path: /path/to/root-ca-for-client-validation.pem 475 # 476 # listener: 477 # connection-balancer: exact 478 # socket-options: 479 # tos: 64 480 # traffic-class: 64 481 ``` 482 483 _Note:_ The default example `contour` includes this [file][1] for easy deployment of Contour. 484 485 ## Environment Variables 486 487 ### CONTOUR_NAMESPACE 488 489 If present, the value of the `CONTOUR_NAMESPACE` environment variable is used as: 490 491 1. The value for the `contour bootstrap --namespace` flag unless otherwise specified. 492 1. The value for the `contour certgen --namespace` flag unless otherwise specified. 493 1. The value for the `contour serve --envoy-service-namespace` flag unless otherwise specified. 494 1. The value for the `contour serve --leader-election-resource-namespace` flag unless otherwise specified. 495 496 The `CONTOUR_NAMESPACE` environment variable is set via the [Downward API][6] in the Contour [example manifests][7]. 497 498 ## Bootstrap Config File 499 500 The bootstrap configuration file is generated by an initContainer in the Envoy daemonset which runs the `contour bootstrap` command to generate the file. 501 This configuration file configures the Envoy container to connect to Contour and receive configuration via xDS. 502 503 The next section outlines all the available flags that can be passed to the `contour bootstrap` command which are used to customize 504 the configuration file to match the environment in which Envoy is deployed. 505 506 ### Bootstrap Flags 507 508 There are flags that can be passed to `contour bootstrap` that help configure how Envoy 509 connects to Contour: 510 511 | Flag | Default | Description | 512 | -------------------------------------- |-------------------| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | 513 | <nobr>--resources-dir</nobr> | "" | Directory where resource files will be written. | 514 | <nobr>--admin-address</nobr> | /admin/admin.sock | Path to Envoy admin unix domain socket. | 515 | <nobr>--admin-port (Deprecated)</nobr> | 9001 | Deprecated: Port is now configured as a Contour flag. | 516 | <nobr>--xds-address</nobr> | 127.0.0.1 | Address to connect to Contour xDS server on. | 517 | <nobr>--xds-port</nobr> | 8001 | Port to connect to Contour xDS server on. | 518 | <nobr>--envoy-cafile</nobr> | "" | CA filename for Envoy secure xDS gRPC communication. | 519 | <nobr>--envoy-cert-file</nobr> | "" | Client certificate filename for Envoy secure xDS gRPC communication. | 520 | <nobr>--envoy-key-file</nobr> | "" | Client key filename for Envoy secure xDS gRPC communication. | 521 | <nobr>--namespace</nobr> | projectcontour | Namespace 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. | 522 | <nobr>--xds-resource-version</nobr> | v3 | Currently, the only valid xDS API resource version is `v3`. | 523 | <nobr>--dns-lookup-family</nobr> | auto | Defines what DNS Resolution Policy to use for Envoy -> Contour cluster name lookup. Either v4, v6, auto or all. | 524 | <nobr>--log-format | text | Log output format for Contour. Either text or json. | 525 | <nobr>--overload-max-heap | 0 | Defines the maximum heap memory of the envoy controlled by the overload manager. When the value is greater than 0, the overload manager is enabled, and when envoy reaches 95% of the maximum heap size, it performs a shrink heap operation. When it reaches 98% of the maximum heap size, Envoy Will stop accepting requests. | 526 527 528 [1]: {{< param github_url>}}/tree/{{< param branch >}}/examples/contour/01-contour-config.yaml 529 [2]: config/access-logging 530 [3]: https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/ 531 [4]: https://golang.org/pkg/time/#ParseDuration 532 [5]: https://godoc.org/github.com/projectcontour/contour/internal/envoy#DefaultFields 533 [6]: https://kubernetes.io/docs/tasks/inject-data-application/environment-variable-expose-pod-information/ 534 [7]: {{< param github_url>}}/tree/{{< param branch >}}/examples/contour 535 [8]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#envoy-v3-api-field-config-core-v3-httpprotocoloptions-idle-timeout 536 [9]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-stream-idle-timeout 537 [10]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#envoy-v3-api-field-config-core-v3-httpprotocoloptions-max-connection-duration 538 [11]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-drain-timeout 539 [12]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-request-timeout 540 [13]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-delayed-close-timeout 541 [14]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/listener/v3/listener.proto#config-listener-v3-listener-connectionbalanceconfig