Edge Proxy Configuration

3 minute read

When an Istio gateway is deployed as an edge proxy, directly exposed to untrusted client traffic, Envoy recommends specific settings for buffer limits, timeouts, HTTP/2 tuning, header sanitization, and connection limits.

Istio’s ProxyConfig.ConnectionSettings API lets you apply these recommendations in one step using the EDGE profile, or configure individual settings for any proxy.

For the complete field reference, see ProxyConfig.ConnectionSettings.

Applying the `EDGE` profile

Set profile: EDGE within connectionSettings to apply Envoy’s recommended edge proxy defaults to a gateway. The profile can be set globally via MeshConfig or per gateway using a pod annotation.

Global configuration

apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  meshConfig:
    defaultConfig:
      connectionSettings:
        profile: EDGE

Per-gateway annotation

metadata:
  annotations:
    "proxy.istio.io/config": '{"connectionSettings": {"profile": "EDGE"}}'

`EDGE` profile defaults

The EDGE profile applies the following defaults. Explicitly setting any field always takes precedence over profile defaults.

Setting	Default value
`listenerPerConnectionBufferLimitBytes`	`32768 (32 KiB)`
`clusterPerConnectionBufferLimitBytes`	`32768 (32 KiB)`
`httpIdleTimeout`	`3600s` (1 hour)
`httpRequestTimeout`	`300s` (5 minutes)
`httpStreamIdleTimeout`	`300s` (5 minutes)
`httpMaxConcurrentStreams`	100
`http2InitialStreamWindowSize`	`65536 (64 KiB)`
`http2InitialConnectionWindowSize`	1048576 (1 MiB)
`httpRequestHeadersTimeout`	`60s` (1 minute)
`httpHeadersWithUnderscoresAction`	`REJECT_REQUEST`
`httpMergeSlashes`	true
`httpPathWithEscapedSlashesAction`	`UNESCAPE_AND_REDIRECT`

Overriding profile defaults

You can set profile: EDGE and override specific settings. For example, to raise the maximum concurrent streams limit:

apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  meshConfig:
    defaultConfig:
      connectionSettings:
        profile: EDGE
        httpMaxConcurrentStreams: 200

Or via pod annotation:

metadata:
  annotations:
    "proxy.istio.io/config": '{"connectionSettings": {"profile": "EDGE", "httpMaxConcurrentStreams": 200}}'

Configuring individual settings without a profile

You can set individual connectionSettings fields without using a profile. This is useful when you want specific connection tuning without the full set of edge defaults.

apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  meshConfig:
    defaultConfig:
      connectionSettings:
        httpIdleTimeout: 600s
        httpMaxConcurrentStreams: 50

When no profile is set, no additional defaults are applied. Only explicitly set fields take effect.

Global downstream connection limit

The globalDownstreamConnectionLimit field configures the maximum number of downstream connections the proxy will accept. This uses Envoy’s overload manager in the bootstrap configuration.

apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  meshConfig:
    defaultConfig:
      connectionSettings:
        profile: EDGE
        globalDownstreamConnectionLimit: 10000

This field takes precedence over the ISTIO_META_GLOBAL_DOWNSTREAM_MAX_CONNECTIONS proxy metadata value, which in turn takes precedence over the deprecated overload.global_downstream_max_connections runtime flag.

Relationship with other APIs

DestinationRule: ConnectionSettings configures the downstream side of the proxy (listeners and the HTTP Connection Manager), while DestinationRule’s connectionPoolSettings configures the upstream cluster side. Both apply independently at different hops and do not override each other.

Path normalization: The httpMergeSlashes and httpPathWithEscapedSlashesAction fields in ConnectionSettings take precedence over the equivalent MeshConfig pathNormalization settings when set. For guidance on choosing path normalization options, see the security best practices.