Proxy defaults configuration reference

This topic provides reference information for proxy defaults configuration entries. Refer to Service mesh proxy overview for information about using proxies in Consul.

Introduction

Proxy defaults configuration entries set global passthrough Envoy settings for proxies in the service mesh, including sidecars and gateways. Proxy defaults configuration entries do not control features for peered clusters, transparent proxy, or TLS behavior. For information about configuring Consul settings that affect service mesh behavior, refer to the mesh configuration entry reference.

Consul only supports one global proxy defaults configuration entry at a time. If multiple configuration entries are defined in Consul Enterprise, Consul implements the configuration entry in the default partition.

Configuration model

The following list outlines field hierarchy, language-specific data types, and requirements in proxy defaults configuration entries. Click on a property name to view additional details, including default values.

Kind: string | required | must be set to proxy-defaults
Name: string | must be set to global
Namespace: string | default | Enterprise
Partition: string | default | Enterprise
Meta: map
Config: map
EnvoyExtensions: list of maps
- Name: string
- Required: string
- Arguments: string
- ConsulVersion: string
- EnvoyVersion: string
Mode: string
TransparentProxy: map
- OutboundListenerPort: number | 15001
- DialedDirectly: boolean | false
MutualTLSMode: string
MeshGateway: map
- Mode: string
Expose: map
- Checks: boolean | false
- Paths: list of maps
  - Path: string | must begin with /
  - LocalPathPort: number | 0
  - ListenerPort: number | 0
  - Protocol: string | http
PrioritizeByLocality: map | Enterprise
- Mode: string | failover
AccessLogs: map
- Enabled: boolean | false
- DisableListenerLogs: boolean | false
- Type: string | stdout
- Path: string
- JSONFormat: string
- TextFormat: string

apiVersion: string | required | must be set to consul.hashicorp.com/v1alpha1
kind: string | required | must be set to ProxyDefaults
metadata: map | required
- name: string | required | must be set to global
- namespace: string | default | Enterprise
spec: map | required
- config: map
- EnvoyExtensions: list of maps
  - name: string
  - required: string
  - arguments: string
  - consulVersion: string
  - envoyVersion: string
- mode: string
- transparentProxy: map
  - outboundListenerPort: number | 15001
  - dialedDirectly: boolean | false
- mutualTLSMode: string
- meshGateway: map
  - mode: string
- expose: map
  - checks: boolean | false
  - paths: list
    - path: string | must begin with /
    - localPathPort: number | 0
    - listenerPort: number | 0
    - protocol: string | http
- prioritizeByLocality: map | Enterprise
  - mode: string | failover
- accessLogs: map
  - enabled: boolean | false
  - disableListenerLogs: boolean | false
  - type: string | stdout
  - path: string
  - jsonFormat: string
  - textFormat: string

Complete configuration

When every field is defined, a proxy defaults configuration entry has the following form:

Kind      = "proxy-defaults"
Name      = "global"
Namespace = "default"
Meta {
  <arbitrary string key> = "<arbitrary string value>"
}
Config {
  <arbitrary string key> = <arbitrary value>
}
EnvoyExtensions = [
  {
    Name= "<name of the extension>"
    Required = "required"
    Arguments = "<arguments to pass to the extension>"
    ConsulVersion = "<Consul version required by the extension>"
    EnvoyVersion = "<Envoy version required by the extension>"
  }
]
Mode = "<name of proxy mode>"
TransparentProxy {
  OutboundListenerPort = <port the proxy should listen on for outbound traffic>
  DialedDirectly       = <true if proxy instances should be dialed directly>
}
MutualTLSMode = "<mutual TLS mode for all proxies>"
MeshGateway {
  Mode = "<name of mesh gateway configuration for all proxies>"
}
Expose {
  Checks = <true to expose all HTTP and gRPC checks through Envoy>

  Paths = [
    {
      Path          = "<the HTTP path to expose>"
      LocalPathPort = <port where the local service is listening for connections to the path>
      ListenerPort  = <port where the proxy will listen for connections>
      Protocol      = "<protocol of the listener>"
    }
  ]
}
PrioritizeByLocality = {
   Mode = "failover"
}
AccessLogs {
  Enabled              = < true | false >
  DisableListenerLogs  = < true | false , disables listener access logs for unrecognized traffic>
  Type                 = "< file | stdout | stdout, the destination for access logs >"
  Path                 = "< set the output path for 'file' based access logs >"
  JSONFormat           = "< json representation of access log format >"
  TextFormat           = "< text representation of access log format >"
}

apiVersion: consul.hashicorp.com/v1alpha1
kind: ProxyDefaults
metadata:
  name: global
  namespace: default
spec:
  meta:
    <arbitrary string key>: <arbitrary string value>
  config:
    <arbitrary string key>: <arbitrary value>
  EnvoyExtensions:
  - name: <name of the extension>
    required: required
    arguments: <arguments to pass to the extension>
    consulVersion: <Consul version required by the extension>
    envoyVersion: <Envoy version required by the extension>
  mode: <name of proxy mode>
  transparentProxy:
    outboundListenerPort: <port the proxy should listen on for outbound traffic>
    dialedDirectly: <true if proxy instances should be dialed directly>
  mutualTLSMode: <mutual TLS mode for all proxies>
  meshGateway:
    mode: <name of mesh gateway configuration for all proxies>
  expose:
    checks: <true to expose all HTTP and gRPC checks through Envoy>
    paths:
      - path: <the HTTP path to expose>
        localPathPort: <port where the local service is listening for connections to the path>
        listenerPort: <port where the proxy will listen for connections>
        protocol:= <protocol of the listener>
  accessLogs:
    enabled: < true | false >
    disableListenerLogs:  < true | false , disables listener access logs for unrecognized traffic>
    type: < file | stdout | stdout, the destination for access logs >
    path: < set the output path for 'file' based access logs >
    jsonFormat: < json representation of access log format >
    textFormat: < text representation of access log format >

{
  "Kind": "proxy-defaults",
  "Name": "global",
  "Namespace": "default",
  "Meta": {
    "<arbitrary string key>": "<arbitrary string value>"
  },
  "Config": {
    "<arbitrary string key>": <arbitrary value>
  },
  "EnvoyExtensions": [
    {
      "Name": "<name of the extension>",
      "Required": "required",
      "Arguments": "<arguments to pass to the extension>",
      "ConsulVersion": "<Consul version required by the extension>",
      "EnvoyVersion": "<Envoy version required by the extension>"
    }
  ],
  "Mode": "<name of proxy mode>",
  "TransparentProxy": {
    "OutboundListenerPort": <port the proxy should listen on for outbound traffic>,
    "DialedDirectly": <true if proxy instances should be dialed directly>
  },
  "MutualTLSMode": "<mutual TLS mode for all proxies>",
  "MeshGateway": {
    "Mode": = "<name of mesh gateway configuration for all proxies>"
  },
  "Expose": {
    "Checks": <true to expose all HTTP and gRPC checks through Envoy>,
    "Paths": [
      {
        "Path": "<the HTTP path to expose>",
        "LocalPathPort": <port where the local service is listening for connections to the path>,
        "ListenerPort": <port where the proxy will listen for connections>,
        "Protocol": "<protocol of the listener>"
      }
    ]
  },
  "AccessLogs": {
    "Enabled": < true | false >,
    "DisableListenerLogs": < true | false , disables listener access logs for unrecognized traffic>,
    "Type": "< file | stdout | stdout, the destination for access logs >",
    "Path": "< set the output path for 'file' based access logs >",
    "JSONFormat": "< json representation of access log format >",
    "TextFormat": "< text representation of access log format >"
  }
}

Specification

This section provides details about the fields you can configure in the proxy defaults configuration entry.

`Kind`

Specifies the type of configuration entry to implement. Must be set to proxy-defaults.

Values

Default: None
This field is required.
Data type: String value that must be set to proxy-defaults.

`Name`

Specifies a name for the configuration entry that is used to identify the configuration entry. Must be set to global.

Values

Default: None
This field is required.
Data type: String that must be set to global.

`Namespace`

Specifies the namespace that the proxy defaults apply to. You can only specify the default namespace.

Values

Default: default
Data type: String

`Partition`

Specifies the local admin partition that the proxy defaults apply to. Refer to admin partitions for more information.

Values

Default: default
Data type: String

`Meta`

Specifies a set of custom key-value pairs to add the Consul KV store.

Values

Default: None
Data type: Map of one or more key-value pairs.
- Keys: String
- Values: String, integer, or float

`Config`

Specifies an arbitrary map of configuration values used by service mesh proxies. The available configurations depend on the mesh proxy you use. You can configure any global values that your proxy allows in this field. Refer to the following topics for additional information:

Values

Default: None
Data type: Map

`EnvoyExtensions`

Specifies a list of extensions that modify Envoy proxy configurations. Refer to Envoy extensions for additional information.

Values

Default: None
Data type: List of maps containing the following fields:

The following table describes how to configure values in the EnvoyExtensions map:

Parameter	Description	Data type	Default
`Name`	Specifies the name of the extension.	String	None
`Required`	Specify `true` to require Consul to implement the extension. Use this parameter to ensure that extensions required for secure communication are not unintentionally bypassed. Consul returns an error when `Required` is set to `true` and the extension does not update Envoy resources.	String	None
`Arguments`	Specifies the arguments to pass to the extension executable. Refer to the documentation for the extension you want to implement for additional information.	Map	None
`ConsulVersion`	Specifies the version of Consul that the extension is allowed to work with. Consul validates the version during xDS updates. If a different version is in use, Consul skips the extension and writes the event to the log. The `ConsulVersion` and `EnvoyVersion` must both validate for Consul to implement the extension.	String	None
`EnvoyVersion`	Specifies the version of Envoy that the extension is allowed to work with. Consul validates the version during xDS updates. If a different version is in use, Consul skips the extension and writes the event to the log. The `ConsulVersion` and `EnvoyVersion` must both validate for Consul to implement the extension.	String	None

`Mode`

Specifies a mode for how proxies direct inbound and outbound traffic. You can specify one of the following values:

transparent: In transparent mode, proxies capture and redirect inbound and outbound traffic. The mode does not enable traffic redirection, but directs Consul to configure Envoy as if traffic is already being redirected.
direct: In this mode, the local application and other proxies must directly dial proxy listeners.

Values

Default: None
Data type: String

`TransparentProxy`

Contains configurations for proxies that are running in transparent proxy mode. This mode enables permissive mTLS for Consul so that you can use your Kubernetes cluster's DNS service instead of Consul DNS. Refer to Transparent proxy mode for additional information.

Values

Default: None
Data type: Map of containing the following fields:
- OutboundListenerPort
- DialedDirectly

The following table describes how to configure values in the TransparentProxy map:

Parameter	Description	Data type	Default
`OutboundListenerPort`	Specifies the port that the proxy listens on for outbound traffic. Outbound application traffic must be captured and redirected to this port.	Integer	`15001`
`DialedDirectly`	Determines whether other proxies in transparent mode can directly dial this proxy instance's IP address. Proxies in transparent mode commonly dial upstreams at the `virtual` tagged address, which load balances across instances. Dialing individual instances can be helpful when sending requests to stateful services, such as database clusters with a leader.	Boolean	`false`

`MutualTLSMode`

Controls the default mutual TLS (mTLS) mode for all proxies. You can only set mutual TLS mode for services in transparent proxy mode.

You can specify one of the following modes:

strict: The sidecar proxy requires mTLS for incoming traffic. permissive: The sidecar proxy accepts mTLS traffic on the sidecar proxy service port and accepts any traffic on the destination service port. We recommend only using permissive mode if necessary while onboarding services to the service mesh.

Values

Default: strict
Data type: One of the following string values:
- strict
- permissive

`MeshGateway`

Sets the default mesh gateway mode field for all proxies. You can specify the following string values for the mode field:

none: The proxy does not make outbound connections through a mesh gateway. Instead, it makes outbound connections directly to the destination services.
local: The proxy makes an outbound connection to a gateway running in the same datacenter.
remote: The proxy makes an outbound connection to a gateway running in the destination datacenter.

Values

Default: None
Data type: Map containing the mode field

`Expose`

Specifies default configurations for exposing HTTP paths through Envoy. Exposing paths through Envoy enables services to protect themselves by only listening on localhost. Applications that are not Consul service mesh-enabled are still able to contact an HTTP endpoint.

Example use-cases include exposing the /metrics endpoint to a monitoring system, such as Prometheus, and exposing the /healthz endpoint to the kubelet for liveness checks. Refer to Expose Paths Configuration Reference for additional information.

Values

Default: None
Data type: Map containing the following parameters:
- Checks
- Paths

`Expose{}.Checks`

Exposes all HTTP and gRPC checks registered with the agent when set to true. Envoy exposes listeners for the checks and only accepts connections originating from localhost or the Consul agent's advertise_addr. The ports for the listeners are dynamically allocated from the agent's expose_min_port and expose_max_port configurations.

We recommend enabling the Checks configuration when a Consul client cannot reach registered services over localhost.

Values

Default: false
Data type: Boolean

`Expose{}.Paths[]`

Specifies a list of configuration maps that define paths to expose through Envoy when Expose.Checks is set to true.

Values

Default: None
Data type: List of maps

The following table describes the parameters for each map you can define in the list:

Parameter	Description	Data type	Default
`Path`	Specifies the HTTP path to expose. You must prepend the path with a forward slash (`/`).	String	None
`LocalPathPort`	Specifies the port where the local service listens for connections to the path.	Integer	`0`
`ListenPort`	Specifies the port where the proxy listens for connections. The port must be available. If the port is unavailable, Envoy does not expose a listener for the path and the proxy registration still succeeds.	Integer	`0`
`Protocol`	Specifies the protocol of the listener. You can configure one of the following values: `http` `http2`: Use with gRPC traffic	String	`http`

`PrioritizeByLocality`

Sets a mode for the service that allows instances to prioritize upstream targets that are in the same network region and zone. You can specify the following string values for the mode field:

failover: If the upstream targets that a service is connected to become unreachable, the service prioritizes healthy upstream instances with matching Locality configuration. Refer to Route traffic to local upstreams for additional information.

Values

Default: None
Data type: Map

`AccessLogs`

Specifies Envoy access logger configurations for all proxies in the service mesh, including gateways. This field also configures access logs on Envoy's administration interface.

Values

Default: None
Data type: Map

The following table describes the parameters you can define in the AccessLogs map:

Parameter	Description	Data type	Default
`Enabled`	Enables Envoy to emit access logs for all proxies in the service mesh.	Boolean	`false`
`DisabledListenerLogs`	Disables access logs for traffic rejected at the listener level. Rejected traffic includes connections that do not match any of Envoy's configured filters, such as Consul upstream services. Set this option to `true` if you do not want to log unknown requests that Envoy is not forwarding.	Boolean	`false`
`Type`	Specifies the destination for access logs. You can specify one of the following types: `stdout` `stderr` `file`	String	None
`Path`	Specifies the destination for writing access logs to file when `Type` is set to `file`.	String	None
`JSONFormat`	Specifies a JSON-formatted string that represents the format for each emitted access log. You can use Envoy command operators to customize the emitted data. You can also nest data. You cannot set this field and the `TextFormat` field concurrently.	String	Default log format
`TextFormat`	Specifies a text-formatted string that represents the format for each emitted access log. You can use Envoy command operators to customize the emitted data. You can also nest data. You cannot set this field and the `JSONFormat` field concurrently.	String	None

apiVersion

Specifies the version of the Consul API to use to apply the configuration entry. This must be set to consul.hashicorp.com/v1alpha1.

Values

Default: None
This field is required.
Data type: String value that must be set to consul.hashicorp.com/v1alpha1.

`kind`

Specifies the type of configuration entry to implement. Must be set to ProxyDefaults.

Values

Default: None
This field is required.
Data type: String value that must be set to ProxyDefaults.

`metadata`

Map that contains the service name, namespace, and admin partition that the configuration entry applies to.

Values

Default: none
Map containing the following strings:
- name
- namespace

`metadata.name`

Specifies a name for the configuration entry that is used to identify the configuration entry. Must be set to global.

Values

Default: None
This field is required.
Data type: String that must be set to global.

`metadata.namespace`

Specifies the namespace that the proxy defaults apply to. If you are on the community version, Consul ignores the namespace field. Refer to Kubernetes namespaces in Consul for additional information. If you are on Consul Enterprise, refer to Kubernetes namespaces in Consul Enterprise for additional information.

Values

Default: default
Data type: String

`spec`

Map that contains the details about the ProxyDefaults configuration entry. The apiVersion, kind``, and metadatafields are siblings of thespec` field. All other configurations are children.

`spec.config`

Values

Default: None
Data type: Map

`spec.envoyExtensions`

Specifies a list of extensions that modify Envoy proxy configurations. Refer to Envoy extensions for additional information.

Values

Default: None
Data type: List of maps of containing the following fields:

The following table describes how to configure values in the EnvoyExtensions map:

Parameter	Description	Data type	Default
`name`	Specifies the name of the extension.	String	None
`required`	Specify `true` to require Consul to implement the extension. Use this parameter to ensure that extensions required for secure communication are not unintentionally bypassed. Consul returns an error when `Required` is set to `true` and the extension does not update Envoy resources.	String	None
`arguments`	Specifies the arguments to pass to the extension executable. Refer to the documentation for the extension you want to implement for additional information.	Map	None
`consulVersion`	Specifies the version of Consul that the extension is allowed to work with. Consul validates the version during xDS updates. If a different version is in use, Consul skips the extension and writes the event to the log. The `consulVersion` and `envoyVersion` must both validate for Consul to implement the extension.	String	None
`envoyVersion`	Specifies the version of Envoy that the extension is allowed to work with. Consul validates the version during xDS updates. If a different version is in use, Consul skips the extension and writes the event to the log. The `consulVersion` and `envoyVersion` must both validate for Consul to implement the extension.	String	None

`spec.mode`

Specifies a mode for how proxies direct inbound and outbound traffic. You can specify one of the following values:

transparent: In transparent mode, proxies capture and redirect inbound and outbound traffic. The mode does not enable traffic redirection, but directs Consul to configure Envoy as if traffic is already being redirected.
direct: In this mode, the local application and other proxies must directly dial proxy listeners.

Values

Default: None
Data type: String

`spec.transparentProxy`

Values

Default: None
Data type: Map of containing the following fields:
- outboundListenerPort
- dialedDirectly

The following table describes how to configure values in the TransparentProxy map:

Parameter	Description	Data type	Default
`outboundListenerPort`	Specifies the port that the proxy listens on for outbound traffic. Outbound application traffic must be captured and redirected to this port.	Integer	`15001`
`dialedDirectly`	Determines whether other proxies in transparent mode can directly dial this proxy instance's IP address. Proxies in transparent mode commonly dial upstreams at the `virtual` tagged address, which load balances across instances. Dialing individual instances can be helpful when sending requests to stateful services, such as database clusters with a leader.	Boolean	`false`

`spec.mutualTLSMode`

Controls the default mutual TLS (mTLS) mode for all proxies. You can only set mutual TLS mode for services in transparent proxy mode.

You can specify one of the following modes:

Values

Default: strict
Data type: One of the following string values:
- strict
- permissive

`spec.meshGateway`

Sets the default mesh gateway mode field for all proxies. You can specify the following string values for the mode field:

none: The proxy does not make outbound connections through a mesh gateway. Instead, it makes outbound connections directly to the destination services.
local: The proxy makes an outbound connection to a gateway running in the same datacenter.
remote: The proxy makes an outbound connection to a gateway running in the destination datacenter.

Values

Default: None
Data type: Map containing the mode field

`spec.expose`

Values

Default: None
Data type: Map containing the following parameters:
- checks
- paths

`spec.expose{}.checks`

We recommend enabling the Checks configuration when a Consul client cannot reach registered services over localhost, such as when Consul agents run in their own pods in Kubernetes.

Values

Default: false
Data type: Boolean

`spec.expose{}.paths[]`

Specifies a list of configuration maps that define paths to expose through Envoy when spec.expose.checks is set to true.

Values

Default: None
Data type: List of maps.

The following table describes the parameters for each map you can define in the list:

Parameter	Description	Data type	Default
`path`	Specifies the HTTP path to expose. You must prepend the path with a forward slash (`/`).	String	None
`localPathPort`	Specifies the port where the local service listens for connections to the path.	Integer	`0`
`listenPort`	Specifies the port where the proxy listens for connections. The port must be available. If the port is unavailable, Envoy does not expose a listener for the path and the proxy registration still succeeds.	Integer	`0`
`protocol`	Specifies the protocol of the listener. You can configure one of the following values: `http` `http2`: Use with gRPC traffic	String	`http`

`spec.prioritizeByLocality`

Sets a mode for the service that allows instances to prioritize upstream targets that are in the same network region and zone. You can specify the following string values for the mode field:

failover: If the upstream targets that a service is connected to become unreachable, the service prioritizes healthy upstream instances with matching locality configuration. Refer to Route traffic to local upstreams for additional information.

Values

Default: None
Data type: Map

`spec.accessLogs`

Specifies Envoy access logger configurations for all proxies in the service mesh, including gateways. This field also configures access logs on Envoy's administration interface.

Values

Default: None
Data type: Map

The following table describes the parameters you can define in the accessLogs map:

Parameter	Description	Data type	Default
`enabled`	Enables Envoy to emit access logs for all proxies in the service mesh.	Boolean	`false`
`disabledListenerLogs`	Disables access logs for traffic rejected at the listener level. Rejected traffic includes connections that do not match any of Envoy's configured filters, such as Consul upstream services. Set this option to `true` if you do not want to log unknown requests that Envoy is not forwarding.	Boolean	`false`
`type`	Specifies the destination for access logs. You can specify one of the following types: `stdout` `stderr` `file`	String	None
`path`	Specifies the destination for writing access logs to file when `type` is set to `file`.	String	None
`jsonFormat`	Specifies a JSON-formatted string that represents the format for each emitted access log. You can use Envoy command operators to customize the emitted data. You can also nest data. You cannot set this field and the `textFormat` field concurrently.	String	Default log format
`textFormat`	Specifies a text-formatted string that represents the format for each emitted access log. You can use Envoy command operators to customize the emitted data. You can also nest data. You cannot set this field and the `jsonFormat` field concurrently.	String	None

Examples

The following examples demonstrate common patterns for configuring proxy defaults configuration entries.

Default protocol

The following example sets the default protocol for all proxies to http.

Community edition

Kind      = "proxy-defaults"
Name      = "global"
Config {
  protocol = "http"
}

Consul Enterprise

When using multiple namespaces with Consul Enterprise, the only configuration entry that affects proxy defaults is the one in the default namespace. This configuration applies to proxies in all namespaces.

Kind      = "proxy-defaults"
Name      = "global"
Namespace = "default" # Can only be set to "default".
Config {
  protocol = "http"
}

Community edition

apiVersion: consul.hashicorp.com/v1alpha1
kind: ProxyDefaults
metadata:
  name: global
spec:
  config:
    protocol: http

Consul Enterprise

apiVersion: consul.hashicorp.com/v1alpha1
kind: ProxyDefaults
metadata:
  name: global
  namespace: default
spec:
  config:
    protocol: http

Community edition

{
  "Kind": "proxy-defaults",
  "Name": "global",
  "Config": {
    "protocol": "http"
  }
}

Consul Enterprise

{
  "Kind": "proxy-defaults",
  "Name": "global",
  "Namespace": "default",
  "Config": {
    "protocol": "http"
  }
}

Prometheus

The following example configures all proxies to expose Prometheus metrics.

Kind      = "proxy-defaults"
Name      = "global"
Config {
  envoy_prometheus_bind_addr = "0.0.0.0:9102"
}

Access Logs

The following example enables access logs for all proxies. Refer to access logs for more detailed examples.

Kind      = "proxy-defaults"
Name      = "global"
AccessLogs {
  Enabled = true
}

Proxy-specific defaults

The following example configures custom default values for all proxies.

Kind      = "proxy-defaults"
Name      = "global"
Config {
  local_connect_timeout_ms = 1000
  handshake_timeout_ms     = 10000
}