---
layout: docs
page_title: Configure Envoy proxy properties
description: Learn how to use the property-override extension for Envoy proxies to set and remove individual properties for the Envoy resources Consul generates.
---

# Configure Envoy proxy properties

This topic describes how to use the `property-override` extension to set and remove individual properties for the Envoy resources Consul generates. The extension uses [`protoreflect`](https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect), which enables Consul to dynamically manipulate messages.

The extension currently supports setting scalar and enum fields, removing individual fields addressable by `Path`, and initializing unset intermediate message fields indicated in `Path`.

It currently does _not_ support the following use cases:
- Adding, updating, or removing repeated field members
- Adding or updating [protobuf `map`](https://protobuf.dev/programming-guides/proto3/#maps) fields
- Adding or updating [protobuf `Any`](https://protobuf.dev/programming-guides/proto3/#any) fields

## Workflow

Complete the following steps to use the `property-override` extension:

1. Configure an `EnvoyExtensions` block in a service defaults or proxy defaults configuration entry. 
1. Apply the configuration entry.

<Warning title="Security warning">
  The property override extension is an advanced feature capable of introducing unintended consequences or reducing cluster security if used incorrectly. Consul does not enforce TLS retention, intentions, or other security-critical components of the Envoy configuration. Additionally, Consul does not verify that the configuration does not contain errors that affect service traffic.
</Warning>

## Add the `EnvoyExtensions`

Add Envoy extension configurations to a proxy defaults or service defaults configuration entry. Place the extension configuration in an `EnvoyExtensions` block in the configuration entry.

- When you configure Envoy extensions on proxy defaults, they apply to every service.
- When you configure Envoy extensions on service defaults, they apply to a specific service.

Consul applies Envoy extensions configured in proxy defaults before it applies extensions in service defaults. As a result, the Envoy extension configuration in service defaults may override configurations in proxy defaults.

The following example shows a service defaults configuration entry named `api` that sets the `/respect_dns_ttl` field for the `other-svc` upstream service:

<CodeTabs tabs={[ "HCL", "JSON", "YAML" ]}>
<CodeBlockConfig filename="property-override-extension-service-defaults.hcl">

```hcl
Kind     = "service-defaults"
Name     = "api"
Protocol = "http"
EnvoyExtensions = [ 
  {
    Name = "builtin/property-override"
    Arguments = {
      ProxyType = "connect-proxy"
      Patches = [
        {
          ResourceFilter  = {
            ResourceType     = "cluster"
            TrafficDirection = "outbound"
            Services = [{
               Name =  "other-svc"
            }]
          }
          Op    = "add"
          Path  = "/respect_dns_ttl"
          Value = true
        }
      ]
    }
  }
]
```
</CodeBlockConfig>
<CodeBlockConfig filename="property-override-extension-service-defaults.json">

```json
{
  "kind": "service-defaults",
  "name": "api",
  "protocol": "http",
  "envoyExtensions": [{
    "name": "builtin/property-override",
    "arguments": {
      "proxyType": "connect-proxy",
      "patches": [{
        "resourceFilter": {
          "resourceType": "cluster",
          "trafficDirection": "outbound",
          "services": [{ "name":  "other-svc" }]
        },
        "op": "add",
        "path": "/respect_dns_ttl",
        "value": true
      }]
    }
  }]
}
```
</CodeBlockConfig>
<CodeBlockConfig filename="property-override-extension-service-defaults.yaml">

```yaml
apiversion: consul.hashicorp.com/v1alpha1
kind: ServiceDefaults
metadata:
  name: api
spec:
  protocol: http
  envoyExtensions:
    name = "builtin/property-override"
    arguments: 
      proxyType: "connect-proxy",
      patches: 
      - resourceFilter: 
          resourceType: "cluster" 
          trafficDirection: "outbound"
          services: 
            - name:  "other-svc"
        op: "add"
        path: "/respect_dns_ttl",
        value: true
```

</CodeBlockConfig>
</CodeTabs>


Refer to the [property override configuration reference](/consul/docs/reference/proxy/extensions/property-override) for details on how to configure the extension. 

Refer to the [proxy defaults configuration entry reference](/consul/docs/reference/config-entry/proxy-defaults) and [service defaults configuration entry reference](/consul/docs/reference/config-entry/service-defaults) for details on how to define the configuration entries. 

<Warning>
  Adding Envoy extensions default proxy configurations may have unintended consequences. We recommend configuring `EnvoyExtensions` in service defaults configuration entries in most cases.
</Warning>

### Constructing paths

To target the properties for an Envoy resource type, you must specify the path where the properties exist in the [`Path` field](/consul/docs/reference/proxy/extensions/property-override#patches-path) of the property override extension configuration. 

To view a list of supported fields for the `Path` field, set the `Path` field to an empty or partially invalid string. Consul will return an error with a list of supported fields for the first unrecognized segment of the path. By default, Consul only returns the first ten fields, but you can set the [`Debug` field](/consul/docs/reference/proxy/extensions/property-override#debug) to `true`  to direct Consul to output all possible fields. 

The following examplem configure will trigger Consul to return an error with the top-level fields available for the Envoy cluster resource:

```hcl
Kind = "service-defaults"
Name = "api"
EnvoyExtensions = [
  {
    Name = "builtin/property-override"
    Arguments = {
      Debug = true
      ProxyType = "connect-proxy"
      Patches = [
        {
          ResourceFilter = {
            ResourceType = "cluster"
            TrafficDirection = "outbound"
          }
          Op = "add"
          Path =  ""
          Value =  5
        }
      ]
    }
  }
]
```

After applying the configuration entry, Consul prints a message that includes the possible fields for the resource:

```shell-session
$ consul config write api.hcl
non-empty, non-root Path is required;
available envoy.config.cluster.v3.Cluster fields:
transport_socket_matches
name
alt_stat_name
type
cluster_type
eds_cluster_config
connect_timeout
## ...
```

You can use the output to help you construct the appropriate value for the `Path` field. For example:

```shell-session
$ consul config write api.hcl 2>&1 | grep round_robin
round_robin_lb_config
```

## Apply the configuration entry

If your network is deployed to virtual machines, use the `consul config write` command and specify the proxy defaults or service defaults configuration entry to apply the configuration. For Kubernetes-orchestrated networks, use the `kubectl apply` command. The following example applies the extension in a proxy defaults configuration entry.

<CodeTabs tabs={[ "HCL", "JSON", "YAML" ]}>

```shell-session
$ consul config write property-override-extension-service-defaults.hcl
```

```shell-session
$ consul config write property-override-extension-service-defaults.json
```

```shell-session
$ kubectl apply property-override-extension-service-defaults.yaml
```

</CodeTabs>
