The proxy defaults configuration entry kind defines default behaviors for proxies in the service mesh. Use the reference guide to learn about `""proxy-defaults""` config entry parameters.
This topic provides reference information for proxy defaults configuration entries. Refer to [Service mesh proxy overview](/consul/docs/connect/proxies) for information about using proxies in Consul.
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/docs/connect/config-entries/mesh).
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.
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.
This section provides details about the fields you can configure in the proxy defaults configuration entry.
<Tabs>
<Tab heading="HCL and JSON" group="hcl">
### `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](/consul/docs/enterprise/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](#/consul/docs/dynamic-app-config/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:
Specifies a list of extensions that modify Envoy proxy configurations. Refer to [Envoy extensions](/consul/docs/connect/proxies/envoy-extensions) for additional information.
#### Values
- Default: None
- Data type: List of maps containing the following fields:
- `Name`
- `Required`
- `Arguments`
- `ConsulVersion`
- `EnvoyVersion`
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. <p>Use this parameter to ensure that extensions required for secure communication are not unintentionally bypassed.</p><p>Consul returns an error when `Required` is set to `true` and the extension does not update Envoy resources. </p> | 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. <p>The `ConsulVersion` and `EnvoyVersion` must both validate for Consul to implement the extension.</p> | 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. <p>The `ConsulVersion` and `EnvoyVersion` must both validate for Consul to implement the extension.</p> | 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](/consul/docs/k8s/connect/transparent-proxy) 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](/consul/docs/services/configuration/services-configuration-reference#tagged_addresses-virtual), 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](/consul/docs/connect/proxy-config-reference#expose-paths-configuration-reference) for additional information.
#### Values
- Default: None
- Data type: Map containing the following parameters:
- [`Checks`](#expose-checks)
- [`Paths`](#expose-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`](/consul/docs/agent/config/config-files#advertise). The ports for the listeners are dynamically allocated from the [agent's `expose_min_port`](/consul/docs/agent/config/config-files#expose_min_port) and [`expose_max_port`](/consul/docs/agent/config/config-files#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: <li>`http`</li><li>`http2`: Use with gRPC traffic</li> | String | `http` |
### `FailoverPolicy`
Sets the failover policy `mode` field for all proxies. The failover policy mode defines how Consul directs traffic to failover service instances if the primary instance becomes unreachable. For example, you can direct Consul to send failover traffic to local service instances. Refer to [Failover overview](/consul/docs/connect/failover) for additional information.
You can specify the following string values for the `mode` field:
- `default`: Envoy sends failover traffic to the first failover target with healthy instances.
- `order-by-locality`: Envoy prioritizes failover targets that are closer to the downstream service. Envoy deterministically orders failover targets that are the same distance from the local proxy.
#### Values
- Default: None
- Data type: Map containing the `mode` field
### `AccessLogs`
Specifies [Envoy access logger](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/access_logging.html?highlight=access%20logs) configurations for all proxies in the service mesh, including gateways. This field also configures access logs on [Envoy's administration interface](https://www.envoyproxy.io/docs/envoy/latest/operations/admin.html?highlight=administration%20logs).
#### 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: <li>`stdout`</li><li>`stderr`</li><li>`file`</li> | 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](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#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](/consul/docs/connect/observability/access-logs#default-log-format) |
| `TextFormat` | Specifies a text-formatted string that represents the format for each emitted access log. You can use [Envoy command operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) to customize the emitted data. You can also nest data. You cannot set this field and the `JSONFormat` field concurrently. | String | None |
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](/consul/docs/k8s/crds#consul-oss) for additional information. If you are on Consul Enterprise, refer to [Kubernetes namespaces in Consul Enterprise](/consul/docs/k8s/crds#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 `metadata` fields are siblings of the `spec` field. All other configurations are children.
### `spec.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:
Specifies a list of extensions that modify Envoy proxy configurations. Refer to [Envoy extensions](/consul/docs/connect/proxies/envoy-extensions) for additional information.
#### Values
- Default: None
- Data type: List of maps of containing the following fields:
- `name`
- `required`
- `arguments`
- `consulVersion`
- `envoyVersion`
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. <p>Use this parameter to ensure that extensions required for secure communication are not unintentionally bypassed.</p><p>Consul returns an error when `Required` is set to `true` and the extension does not update Envoy resources. </p> | 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. <p>The `consulVersion` and `envoyVersion` must both validate for Consul to implement the extension.</p> | 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. <p>The `consulVersion` and `envoyVersion` must both validate for Consul to implement the extension.</p> | 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`
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](/consul/docs/k8s/connect/transparent-proxy) 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](/consul/docs/services/configuration/services-configuration-reference#tagged_addresses-virtual), 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:
`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`
### `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`
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](/consul/docs/connect/proxy-config-reference#expose-paths-configuration-reference) for additional information.
#### Values
- Default: None
- Data type: Map containing the following parameters:
- [`checks`](#expose-checks)
- [`aths`](#expose-paths)
### `spec.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`](/consul/docs/agent/config/config-files#advertise). The ports for the listeners are dynamically allocated from the [agent's `expose_min_port`](/consul/docs/agent/config/config-files#expose_min_port) and [`expose_max_port`](/consul/docs/agent/config/config-files#expose_max_port) configurations.
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: <li>`http`</li><li>`http2`: Use with gRPC traffic</li> | String | `http` |
### `spec.failoverPolicy`
Sets the failover policy `mode` field for all proxies. The failover policy mode defines how Consul directs traffic to failover service instances if the primary instance becomes unreachable. For example, you can direct Consul to send failover traffic to local service instances. Refer to [Failover overview](/consul/docs/connect/failover) for additional information.
You can specify the following string values for the `mode` field:
- `default`: Envoy sends failover traffic to the first failover target with healthy instances.
- `order-by-locality`: Envoy prioritizes failover targets that are closer to the downstream service. Envoy deterministically orders failover targets that are the same distance from the local proxy.
#### Values
- Default: None
- Data type: Map containing the `mode` field
### `spec.accessLogs`
Specifies [Envoy access logger](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/access_logging.html?highlight=access%20logs) configurations for all proxies in the service mesh, including gateways. This field also configures access logs on [Envoy's administration interface](https://www.envoyproxy.io/docs/envoy/latest/operations/admin.html?highlight=administration%20logs).
#### 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: <li>`stdout`</li><li>`stderr`</li><li>`file`</li> | 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](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#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](/consul/docs/connect/observability/access-logs#default-log-format) |
| `textFormat` | Specifies a text-formatted string that represents the format for each emitted access log. You can use [Envoy command operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) to customize the emitted data. You can also nest data. You cannot set this field and the `jsonFormat` field concurrently. | String | None |
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.
```hcl
Kind = "proxy-defaults"
Name = "global"
Namespace = "default" # Can only be set to "default".
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.
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.
The following example enables access logs for all proxies. Refer to [access logs](/consul/docs/connect/observability/access-logs) for more detailed examples.
