.. _envoy_v3_api_file_envoy/extensions/upstreams/http/v3/http_protocol_options.proto:
HTTP Protocol Options
=====================
.. _extension_envoy.upstreams.http.http_protocol_options:
This extension may be referenced by 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:
- :ref:`envoy.upstreams <extension_category_envoy.upstreams>`
.. _envoy_v3_api_msg_extensions.upstreams.http.v3.HttpProtocolOptions:
extensions.upstreams.http.v3.HttpProtocolOptions
------------------------------------------------
:repo:`[extensions.upstreams.http.v3.HttpProtocolOptions proto] <api/envoy/extensions/upstreams/http/v3/http_protocol_options.proto#L60>`
HttpProtocolOptions specifies Http upstream protocol options. This object
is used in
:ref:`typed_extension_protocol_options<envoy_v3_api_field_config.cluster.v3.Cluster.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:
.. code::
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:
.. code::
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]
.. code-block:: json
{
"common_http_protocol_options": "{...}",
"upstream_http_protocol_options": "{...}",
"explicit_http_config": "{...}",
"use_downstream_protocol_config": "{...}",
"auto_config": "{...}"
}
.. _envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.common_http_protocol_options:
common_http_protocol_options
(:ref:`config.core.v3.HttpProtocolOptions <envoy_v3_api_msg_config.core.v3.HttpProtocolOptions>`) This contains options common across HTTP/1 and HTTP/2
.. _envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.upstream_http_protocol_options:
upstream_http_protocol_options
(:ref:`config.core.v3.UpstreamHttpProtocolOptions <envoy_v3_api_msg_config.core.v3.UpstreamHttpProtocolOptions>`) This contains common protocol options which are only applied upstream.
.. _envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.explicit_http_config:
explicit_http_config
(:ref:`extensions.upstreams.http.v3.HttpProtocolOptions.ExplicitHttpConfig <envoy_v3_api_msg_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 :ref:`explicit_http_config <envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.explicit_http_config>`, :ref:`use_downstream_protocol_config <envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.use_downstream_protocol_config>`, :ref:`auto_config <envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.auto_config>` must be set.
.. _envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.use_downstream_protocol_config:
use_downstream_protocol_config
(:ref:`extensions.upstreams.http.v3.HttpProtocolOptions.UseDownstreamHttpConfig <envoy_v3_api_msg_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 :ref:`explicit_http_config <envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.explicit_http_config>`, :ref:`use_downstream_protocol_config <envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.use_downstream_protocol_config>`, :ref:`auto_config <envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.auto_config>` must be set.
.. _envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.auto_config:
auto_config
(:ref:`extensions.upstreams.http.v3.HttpProtocolOptions.AutoHttpConfig <envoy_v3_api_msg_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 :ref:`explicit_http_config <envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.explicit_http_config>`, :ref:`use_downstream_protocol_config <envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.use_downstream_protocol_config>`, :ref:`auto_config <envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.auto_config>` must be set.
.. _envoy_v3_api_msg_extensions.upstreams.http.v3.HttpProtocolOptions.ExplicitHttpConfig:
extensions.upstreams.http.v3.HttpProtocolOptions.ExplicitHttpConfig
-------------------------------------------------------------------
:repo:`[extensions.upstreams.http.v3.HttpProtocolOptions.ExplicitHttpConfig proto] <api/envoy/extensions/upstreams/http/v3/http_protocol_options.proto#L63>`
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.
.. code-block:: json
{
"http_protocol_options": "{...}",
"http2_protocol_options": "{...}",
"http3_protocol_options": "{...}"
}
.. _envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.ExplicitHttpConfig.http_protocol_options:
http_protocol_options
(:ref:`config.core.v3.Http1ProtocolOptions <envoy_v3_api_msg_config.core.v3.Http1ProtocolOptions>`)
Precisely one of :ref:`http_protocol_options <envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.ExplicitHttpConfig.http_protocol_options>`, :ref:`http2_protocol_options <envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.ExplicitHttpConfig.http2_protocol_options>`, :ref:`http3_protocol_options <envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.ExplicitHttpConfig.http3_protocol_options>` must be set.
.. _envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.ExplicitHttpConfig.http2_protocol_options:
http2_protocol_options
(:ref:`config.core.v3.Http2ProtocolOptions <envoy_v3_api_msg_config.core.v3.Http2ProtocolOptions>`)
Precisely one of :ref:`http_protocol_options <envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.ExplicitHttpConfig.http_protocol_options>`, :ref:`http2_protocol_options <envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.ExplicitHttpConfig.http2_protocol_options>`, :ref:`http3_protocol_options <envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.ExplicitHttpConfig.http3_protocol_options>` must be set.
.. _envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.ExplicitHttpConfig.http3_protocol_options:
http3_protocol_options
(:ref:`config.core.v3.Http3ProtocolOptions <envoy_v3_api_msg_config.core.v3.Http3ProtocolOptions>`) .. warning::
QUIC support is currently alpha and should be used with caution. Please
see :ref:`here <arch_overview_http3>` for details.
Precisely one of :ref:`http_protocol_options <envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.ExplicitHttpConfig.http_protocol_options>`, :ref:`http2_protocol_options <envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.ExplicitHttpConfig.http2_protocol_options>`, :ref:`http3_protocol_options <envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.ExplicitHttpConfig.http3_protocol_options>` must be set.
.. _envoy_v3_api_msg_extensions.upstreams.http.v3.HttpProtocolOptions.UseDownstreamHttpConfig:
extensions.upstreams.http.v3.HttpProtocolOptions.UseDownstreamHttpConfig
------------------------------------------------------------------------
:repo:`[extensions.upstreams.http.v3.HttpProtocolOptions.UseDownstreamHttpConfig proto] <api/envoy/extensions/upstreams/http/v3/http_protocol_options.proto#L83>`
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.
.. code-block:: json
{
"http_protocol_options": "{...}",
"http2_protocol_options": "{...}",
"http3_protocol_options": "{...}"
}
.. _envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.UseDownstreamHttpConfig.http_protocol_options:
http_protocol_options
(:ref:`config.core.v3.Http1ProtocolOptions <envoy_v3_api_msg_config.core.v3.Http1ProtocolOptions>`)
.. _envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.UseDownstreamHttpConfig.http2_protocol_options:
http2_protocol_options
(:ref:`config.core.v3.Http2ProtocolOptions <envoy_v3_api_msg_config.core.v3.Http2ProtocolOptions>`)
.. _envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.UseDownstreamHttpConfig.http3_protocol_options:
http3_protocol_options
(:ref:`config.core.v3.Http3ProtocolOptions <envoy_v3_api_msg_config.core.v3.Http3ProtocolOptions>`) .. warning::
QUIC support is currently alpha and should be used with caution. Please
see :ref:`here <arch_overview_http3>` for details.
.. _envoy_v3_api_msg_extensions.upstreams.http.v3.HttpProtocolOptions.AutoHttpConfig:
extensions.upstreams.http.v3.HttpProtocolOptions.AutoHttpConfig
---------------------------------------------------------------
:repo:`[extensions.upstreams.http.v3.HttpProtocolOptions.AutoHttpConfig proto] <api/envoy/extensions/upstreams/http/v3/http_protocol_options.proto#L103>`
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".
.. code-block:: json
{
"http_protocol_options": "{...}",
"http2_protocol_options": "{...}",
"http3_protocol_options": "{...}",
"alternate_protocols_cache_options": "{...}"
}
.. _envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.AutoHttpConfig.http_protocol_options:
http_protocol_options
(:ref:`config.core.v3.Http1ProtocolOptions <envoy_v3_api_msg_config.core.v3.Http1ProtocolOptions>`)
.. _envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.AutoHttpConfig.http2_protocol_options:
http2_protocol_options
(:ref:`config.core.v3.Http2ProtocolOptions <envoy_v3_api_msg_config.core.v3.Http2ProtocolOptions>`)
.. _envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.AutoHttpConfig.http3_protocol_options:
http3_protocol_options
(:ref:`config.core.v3.Http3ProtocolOptions <envoy_v3_api_msg_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 :ref:`here <arch_overview_http3_upstream>` for more information on
when HTTP/3 will be used, and when Envoy will fail over to TCP.
.. warning::
QUIC support is currently alpha and should be used with caution. Please
see :ref:`here <arch_overview_http3>` for details.
AutoHttpConfig config is undergoing especially rapid change and as it
is alpha is not guaranteed to be API-stable.
.. _envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.AutoHttpConfig.alternate_protocols_cache_options:
alternate_protocols_cache_options
(:ref:`config.core.v3.AlternateProtocolsCacheOptions <envoy_v3_api_msg_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.