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 the 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 fields
• Adding or updating protobuf Any fields

Workflow

• Complete the following steps to use the property-override extension:
• Configure an EnvoyExtensions block in a service defaults or proxy defaults configuration entry.
• Apply the configuration entry.

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.

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.

In the following proxy defaults configuration entry example, Consul sets the /respect_dns_ttl field on the api service proxy’s cluster configuration for the other-svc upstream service:

property-override-extension-service-defaults.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
        }
      ]
    }
  }
]

property-override-extension-service-defaults.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
    }]
  }
}]

property-override-extension-service-defaults.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

Refer to the property override configuration reference for details on how to configure the extension.

Refer to the proxy defaults configuration entry reference and service defaults configuration entry reference 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.

Constructing paths

To target the properties for an Envoy resource type, you must specify the path where the properties exist in the Path field of the property override extension configuration. Set the Path field to an empty or partially invalid string when saving the configuration entry and Consul returns 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 to true to direct Consul to output all possible fields.

In the following example, Consul outputs the top-level fields available for the Envoy cluster resource:

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:

$ 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:

$ 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.

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

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

$ kubectl apply property-override-extension-service-defaults.yaml