github.com/projectcontour/contour@v1.28.2/site/content/docs/v1.6.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` | 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  
    32  
    33  ### TLS Configuration
    34  
    35  The TLS configuration block can be used to configure default values for how
    36  Contour should provision TLS hosts.
    37  
    38  | Field Name | Type| Default  | Description |
    39  |------------|-----|----------|-------------|
    40  | 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. |
    41  | fallback-certificate | | | [Fallback certificate configuration](#fallback-certificate). |
    42  
    43  
    44  ### Fallback Certificate
    45  
    46  | Field Name | Type| Default  | Description |
    47  |------------|-----|----------|-------------|
    48  | name       | string | `""` | This field specifies the name of the Kubernetes secret to use as the fallback certificate.      |
    49  | namespace  | string | `""` | This field specifies the namespace of the Kubernetes secret to use as the fallback certificate. |
    50  
    51  
    52  ### Leader Election Configuration
    53  
    54  The leader election configuration block configures how a deployment with more than one Contour pod elects a leader.
    55  The Contour leader is responsible for updating the status field on Ingress and HTTPProxy documents.
    56  In the vast majority of deployments, only the `configmap-name` and `configmap-namespace` fields should require any configuration.
    57  
    58  | Field Name | Type | Default | Description |
    59  |------------|------|---------|-------------|
    60  | configmap-name | string | `leader-elect` | The name of the ConfigMap that Contour leader election will lease. |
    61  | 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. |
    62  | lease-duration | [duration][4] | `15s` | The duration of the leadership lease. |
    63  | renew-deadline | [duration][4] | `10s` | The length of time that the leader will retry refreshing leadership before giving up. |
    64  | retry-period | [duration][4] | `2s` | The interval at which Contour will attempt to the acquire leadership lease. |
    65  
    66  
    67  ### Configuration Example
    68  
    69  The following is an example ConfigMap with configuration file included:
    70  
    71  ```yaml
    72  apiVersion: v1
    73  kind: ConfigMap
    74  metadata:
    75    name: contour
    76    namespace: projectcontour
    77  data:
    78    contour.yaml: |
    79      # should contour expect to be running inside a k8s cluster
    80      # incluster: true
    81      #
    82      # path to kubeconfig (if not running inside a k8s cluster)
    83      # kubeconfig: /path/to/.kube/config
    84      #
    85      # disable ingressroute permitInsecure field
    86      # disablePermitInsecure: false
    87      tls:
    88        # minimum TLS version that Contour will negotiate
    89        # minimumProtocolVersion: "1.1"
    90        fallback-certificate:
    91        # name: fallback-secret-name
    92        # namespace: projectcontour
    93      # The following config shows the defaults for the leader election.
    94      # leaderelection:
    95        # configmap-name: leader-elect
    96        # configmap-namespace: projectcontour
    97      # Default HTTP versions.
    98      # default-http-versions:
    99      # - "HTTP/1.1"
   100      # - "HTTP/2"
   101  ```
   102  
   103  _Note:_ The default example `contour` includes this [file][1] for easy deployment of Contour.
   104  
   105  ## Environment Variables
   106  
   107  ### CONTOUR_NAMESPACE
   108  
   109  If present, the value of the `CONTOUR_NAMESPACE` environment variable is used as:
   110  
   111  1. The value for the `contour bootstrap --namespace` flag unless otherwise specified.
   112  1. The value for the `contour certgen --namespace` flag unless otherwise specified.
   113  1. The value for the `contour serve --envoy-service-namespace` flag unless otherwise specified.
   114  1. The value for the `leaderelection.configmap-namespace` config file setting for `contour serve` unless otherwise specified.
   115  
   116  The `CONTOUR_NAMESPACE` environment variable is set via the [Downward API][6] in the Contour [example manifests][7].
   117  
   118  
   119  [1]: {{< param github_url >}}/tree/{{page.version}}/examples/contour/01-contour-config.yaml
   120  [2]: /guides/structured-logs
   121  [3]: https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/
   122  [4]: https://golang.org/pkg/time/#ParseDuration
   123  [5]: https://godoc.org/github.com/projectcontour/contour/internal/envoy#DefaultFields
   124  [6]: https://kubernetes.io/docs/tasks/inject-data-application/environment-variable-expose-pod-information/
   125  [7]: {{< param github_url >}}/tree/{{page.version}}/examples/contour