HTTP Protocol Options (proto)

This extension has the qualified name envoy.upstreams.http.http_protocol_options

Note

This extension is intended to be robust against untrusted downstream traffic. It assumes that the upstream is trusted.

Tip

This extension extends and can be used with the following extension category:

envoy.upstreams

extensions.upstreams.http.v3.HttpProtocolOptions

[extensions.upstreams.http.v3.HttpProtocolOptions proto]

HttpProtocolOptions specifies Http upstream protocol options. This object is used in typed_extension_protocol_options, keyed by the name envoy.extensions.upstreams.http.v3.HttpProtocolOptions.

This controls what protocol(s) should be used for upstream and how said protocol(s) are configured.

This replaces the prior pattern of explicit protocol configuration directly in the cluster. So a configuration like this, explicitly configuring the use of HTTP/2 upstream:

clusters:
  - name: some_service
    connect_timeout: 5s
    upstream_http_protocol_options:
      auto_sni: true
    common_http_protocol_options:
      idle_timeout: 1s
    http2_protocol_options:
      max_concurrent_streams: 100
     .... [further cluster config]

Would now look like this:

clusters:
  - name: some_service
    connect_timeout: 5s
    typed_extension_protocol_options:
      envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
        "@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions
        upstream_http_protocol_options:
          auto_sni: true
        common_http_protocol_options:
          idle_timeout: 1s
        explicit_http_config:
          http2_protocol_options:
            max_concurrent_streams: 100
     .... [further cluster config]

{
  "common_http_protocol_options": {...},
  "upstream_http_protocol_options": {...},
  "explicit_http_config": {...},
  "use_downstream_protocol_config": {...},
  "auto_config": {...},
  "http_filters": []
}

common_http_protocol_options: (config.core.v3.HttpProtocolOptions) This contains options common across HTTP/1 and HTTP/2

upstream_http_protocol_options: (config.core.v3.UpstreamHttpProtocolOptions) This contains common protocol options which are only applied upstream.

explicit_http_config

(extensions.upstreams.http.v3.HttpProtocolOptions.ExplicitHttpConfig) To explicitly configure either HTTP/1 or HTTP/2 (but not both!) use explicit_http_config. If the explicit_http_config is empty, HTTP/1.1 is used.

This controls the actual protocol to be used upstream.

Precisely one of explicit_http_config, use_downstream_protocol_config, auto_config must be set.

use_downstream_protocol_config

(extensions.upstreams.http.v3.HttpProtocolOptions.UseDownstreamHttpConfig) This allows switching on protocol based on what protocol the downstream connection used.

This controls the actual protocol to be used upstream.

Precisely one of explicit_http_config, use_downstream_protocol_config, auto_config must be set.

auto_config

(extensions.upstreams.http.v3.HttpProtocolOptions.AutoHttpConfig) This allows switching on protocol based on ALPN

This controls the actual protocol to be used upstream.

Precisely one of explicit_http_config, use_downstream_protocol_config, auto_config must be set.

http_filters

(repeated extensions.filters.network.http_connection_manager.v3.HttpFilter) .. note::: Upstream HTTP filters are currently in alpha.

Optional HTTP filters for the upstream HTTP filter chain.

These filters will be applied for all HTTP streams which flow through this cluster. Unlike downstream HTTP filters, they will not be applied to terminated CONNECT requests.

If using upstream HTTP filters, please be aware that local errors sent by upstream HTTP filters will not trigger retries, and local errors sent by upstream HTTP filters will count as a final response if hedging is configured.

Tip

This extension category has the following known extensions:

extensions.upstreams.http.v3.HttpProtocolOptions.ExplicitHttpConfig

[extensions.upstreams.http.v3.HttpProtocolOptions.ExplicitHttpConfig proto]

If this is used, the cluster will only operate on one of the possible upstream protocols. Note that HTTP/2 or above should generally be used for upstream gRPC clusters.

{
  "http_protocol_options": {...},
  "http2_protocol_options": {...},
  "http3_protocol_options": {...}
}

http_protocol_options

(config.core.v3.Http1ProtocolOptions)

Precisely one of http_protocol_options, http2_protocol_options, http3_protocol_options must be set.

http2_protocol_options

(config.core.v3.Http2ProtocolOptions)

Precisely one of http_protocol_options, http2_protocol_options, http3_protocol_options must be set.

http3_protocol_options

(config.core.v3.Http3ProtocolOptions) .. warning::: QUIC upstream support is currently not ready for internet use. Please see here for details.

Precisely one of http_protocol_options, http2_protocol_options, http3_protocol_options must be set.

extensions.upstreams.http.v3.HttpProtocolOptions.UseDownstreamHttpConfig

[extensions.upstreams.http.v3.HttpProtocolOptions.UseDownstreamHttpConfig proto]

If this is used, the cluster can use either of the configured protocols, and will use whichever protocol was used by the downstream connection.

If HTTP/3 is configured for downstream and not configured for upstream, HTTP/3 requests will fail over to HTTP/2.

{
  "http_protocol_options": {...},
  "http2_protocol_options": {...},
  "http3_protocol_options": {...}
}

http_protocol_options: (config.core.v3.Http1ProtocolOptions)

http2_protocol_options: (config.core.v3.Http2ProtocolOptions)

http3_protocol_options

(config.core.v3.Http3ProtocolOptions) .. warning::: QUIC upstream support is currently not ready for internet use. Please see here for details.

extensions.upstreams.http.v3.HttpProtocolOptions.AutoHttpConfig

[extensions.upstreams.http.v3.HttpProtocolOptions.AutoHttpConfig proto]

If this is used, the cluster can use either HTTP/1 or HTTP/2, and will use whichever protocol is negotiated by ALPN with the upstream. Clusters configured with AutoHttpConfig will use the highest available protocol; HTTP/2 if supported, otherwise HTTP/1. If the upstream does not support ALPN, AutoHttpConfig will fail over to HTTP/1. This can only be used with transport sockets which support ALPN. Using a transport socket which does not support ALPN will result in configuration failure. The transport layer may be configured with custom ALPN, but the default ALPN for the cluster (or if custom ALPN fails) will be “h2,http/1.1”.

{
  "http_protocol_options": {...},
  "http2_protocol_options": {...},
  "http3_protocol_options": {...},
  "alternate_protocols_cache_options": {...}
}

http_protocol_options: (config.core.v3.Http1ProtocolOptions)

http2_protocol_options: (config.core.v3.Http2ProtocolOptions)

http3_protocol_options: (config.core.v3.Http3ProtocolOptions) Unlike HTTP/1 and HTTP/2, HTTP/3 will not be configured unless it is present, and (soon) only if there is an indication of server side support. See here for more information on when HTTP/3 will be used, and when Envoy will fail over to TCP.

Warning

QUIC upstream support is currently not ready for internet use. Please see here for details.

alternate_protocols_cache_options: (config.core.v3.AlternateProtocolsCacheOptions) The presence of alternate protocols cache options causes the use of the alternate protocols cache, which is responsible for parsing and caching HTTP Alt-Svc headers. This enables the use of HTTP/3 for origins that advertise supporting it.

Note

This is required when HTTP/3 is enabled.