github.com/projectcontour/contour@v1.28.2/site/content/docs/v1.7.0/configuration.md (about) 1 # Contour Configuration Reference 2 3 - [Configuration File](#configuration-file) 4 - [Environment Variables](#environment-variables) 5 6 ## Configuration File 7 8 A configuration file can be passed to the `--config-path` argument of the `contour serve` command to specify additional configuration to Contour. 9 In most deployments, this file is passed to Contour via a ConfigMap which is mounted as a volume to the Contour pod. 10 11 The Contour configuration file is optional. 12 In its absence, Contour will operate with reasonable defaults. 13 Where Contour settings can also be specified with command-line flags, the command-line value takes precedence over the configuration file. 14 15 | Field Name | Type | Default | Description | 16 |------------|------|---------|-------------| 17 | accesslog-format | string | `envoy` | This key sets the global [access log format][2] for Envoy. Valid options are `envoy` or `json`. | 18 | debug | boolean | `false` | Enables debug logging. | 19 | 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". | 20 , where "x" represents the version number. | 21 | disablePermitInsecure | boolean | `false` | If this field is true, Contour will ignore `PermitInsecure` field in HTTPProxy documents. | 22 | envoy-service-name | string | `envoy` | This sets the service name that will be inspected for address details to be applied to Ingress objects. | 23 | 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. | 24 | 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`.| 25 | incluster | boolean | `false` | This field specifies that Contour is running in a Kubernetes cluster and should use the in-cluster client access configuration. | 26 | json-fields | string array | [fields][5]| This is the list the field names to include in the JSON [access log format][2]. | 27 | kubeconfig | string | `$HOME/.kube/config` | Path to a Kubernetes [kubeconfig file][3] for when Contour is executed outside a cluster. | 28 | leaderelection | leaderelection | | The [leader election configuration](#leader-election-configuration). | 29 | request-timeout | [duration][4] | `0s` | **Deprecated and will be removed in a future release. Use [timeouts.request-timeout](#timeout-configuration) instead.**<br /><br /> This field specifies the default request timeout as a Go duration string. Zero means there is no timeout. | 30 | tls | TLS | | The default [TLS configuration](#tls-configuration). | 31 | timeouts | TimeoutConfig | | The [timeout configuration](#timeout-configuration). | 32 33 34 ### TLS Configuration 35 36 The TLS configuration block can be used to configure default values for how 37 Contour should provision TLS hosts. 38 39 | Field Name | Type| Default | Description | 40 |------------|-----|----------|-------------| 41 | minimum-protocol-version| string | `""` | 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. | 42 | fallback-certificate | | | [Fallback certificate configuration](#fallback-certificate). | 43 44 45 ### Fallback Certificate 46 47 | Field Name | Type| Default | Description | 48 |------------|-----|----------|-------------| 49 | name | string | `""` | This field specifies the name of the Kubernetes secret to use as the fallback certificate. | 50 | namespace | string | `""` | This field specifies the namespace of the Kubernetes secret to use as the fallback certificate. | 51 52 53 ### Leader Election Configuration 54 55 The leader election configuration block configures how a deployment with more than one Contour pod elects a leader. 56 The Contour leader is responsible for updating the status field on Ingress and HTTPProxy documents. 57 In the vast majority of deployments, only the `configmap-name` and `configmap-namespace` fields should require any configuration. 58 59 | Field Name | Type | Default | Description | 60 |------------|------|---------|-------------| 61 | configmap-name | string | `leader-elect` | The name of the ConfigMap that Contour leader election will lease. | 62 | configmap-namespace | string | `projectcontour` | The 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. | 63 | lease-duration | [duration][4] | `15s` | The duration of the leadership lease. | 64 | renew-deadline | [duration][4] | `10s` | The length of time that the leader will retry refreshing leadership before giving up. | 65 | retry-period | [duration][4] | `2s` | The interval at which Contour will attempt to the acquire leadership lease. | 66 67 68 ### Timeout Configuration 69 70 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. 71 72 | Field Name | Type| Default | Description | 73 |------------|-----|----------|-------------| 74 | 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._ | 75 | 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. Must be a [valid Go duration string][4], or `infinity` to disable the timeout entirely. See [the Envoy documentation][8] for more information. | 76 | stream-idle-timeout| string | `5m`* |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][4], or `infinity` to disable the timeout entirely. See [the Envoy documentation][9] for more information. | 77 | 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. | 78 | 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. | 79 80 81 _* This is Envoy's default setting value and is not explicitly configured by Contour._ 82 83 ### Configuration Example 84 85 The following is an example ConfigMap with configuration file included: 86 87 ```yaml 88 apiVersion: v1 89 kind: ConfigMap 90 metadata: 91 name: contour 92 namespace: projectcontour 93 data: 94 contour.yaml: | 95 # should contour expect to be running inside a k8s cluster 96 # incluster: true 97 # 98 # path to kubeconfig (if not running inside a k8s cluster) 99 # kubeconfig: /path/to/.kube/config 100 # 101 # disable httpproxy permitInsecure field 102 # disablePermitInsecure: false 103 tls: 104 # minimum TLS version that Contour will negotiate 105 # minimumProtocolVersion: "1.1" 106 fallback-certificate: 107 # name: fallback-secret-name 108 # namespace: projectcontour 109 # The following config shows the defaults for the leader election. 110 # leaderelection: 111 # configmap-name: leader-elect 112 # configmap-namespace: projectcontour 113 # Default HTTP versions. 114 # default-http-versions: 115 # - "HTTP/1.1" 116 # - "HTTP/2" 117 # The following shows the default proxy timeout settings. 118 # timeouts: 119 # request-timeout: infinity 120 # connection-idle-timeout: 60s 121 # stream-idle-timeout: 5m 122 # max-connection-duration: infinity 123 # connection-shutdown-grace-period: 5s 124 ``` 125 126 _Note:_ The default example `contour` includes this [file][1] for easy deployment of Contour. 127 128 ## Environment Variables 129 130 ### CONTOUR_NAMESPACE 131 132 If present, the value of the `CONTOUR_NAMESPACE` environment variable is used as: 133 134 1. The value for the `contour bootstrap --namespace` flag unless otherwise specified. 135 1. The value for the `contour certgen --namespace` flag unless otherwise specified. 136 1. The value for the `contour serve --envoy-service-namespace` flag unless otherwise specified. 137 1. The value for the `leaderelection.configmap-namespace` config file setting for `contour serve` unless otherwise specified. 138 139 The `CONTOUR_NAMESPACE` environment variable is set via the [Downward API][6] in the Contour [example manifests][7]. 140 141 142 [1]: {{< param github_url >}}/tree/{{page.version}}/examples/contour/01-contour-config.yaml 143 [2]: /guides/structured-logs 144 [3]: https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/ 145 [4]: https://golang.org/pkg/time/#ParseDuration 146 [5]: https://godoc.org/github.com/projectcontour/contour/internal/envoy#DefaultFields 147 [6]: https://kubernetes.io/docs/tasks/inject-data-application/environment-variable-expose-pod-information/ 148 [7]: {{< param github_url >}}/tree/{{page.version}}/examples/contour 149 [8]: https://www.envoyproxy.io/docs/envoy/latest/api-v2/api/v2/core/protocol.proto#envoy-api-field-core-httpprotocoloptions-idle-timeout 150 [9]: https://www.envoyproxy.io/docs/envoy/latest/api-v2/config/filter/network/http_connection_manager/v2/http_connection_manager.proto#envoy-api-field-config-filter-network-http-connection-manager-v2-httpconnectionmanager-stream-idle-timeout 151 [10]: https://www.envoyproxy.io/docs/envoy/latest/api-v2/api/v2/core/protocol.proto#envoy-api-field-core-httpprotocoloptions-max-connection-duration 152 [11]: https://www.envoyproxy.io/docs/envoy/latest/api-v2/config/filter/network/http_connection_manager/v2/http_connection_manager.proto#envoy-api-field-config-filter-network-http-connection-manager-v2-httpconnectionmanager-drain-timeout 153 [12]: https://www.envoyproxy.io/docs/envoy/latest/api-v2/config/filter/network/http_connection_manager/v2/http_connection_manager.proto#envoy-api-field-config-filter-network-http-connection-manager-v2-httpconnectionmanager-request-timeout