.. _envoy_v3_api_file_envoy/extensions/http/stateful_session/header/v3/header.proto:

Header based stateful session extension (proto)
===============================================






.. _envoy_v3_api_msg_extensions.http.stateful_session.header.v3.HeaderBasedSessionState:

extensions.http.stateful_session.header.v3.HeaderBasedSessionState
------------------------------------------------------------------


:repo:`[extensions.http.stateful_session.header.v3.HeaderBasedSessionState proto] <api/envoy/extensions/http/stateful_session/header/v3/header.proto#L37>`

This extension allows the session state to be tracked via request headers.

This extension encodes the address of the upstream host selected by the load balancer
into a response header with the :ref:`header configuration
<envoy_v3_api_msg_extensions.http.stateful_session.header.v3.HeaderBasedSessionState>`.
When new requests are incoming, this extension will try to parse the specific upstream host
address by header name. If the address parsed from the header corresponds to a valid
upstream host, this upstream host will be selected first. See :ref:`stateful session filter
<envoy_v3_api_msg_extensions.filters.http.stateful_session.v3.StatefulSession>`.

For example, if the header name is set to ``session-header``, Envoy will prefer ``1.2.3.4:80``
as the upstream host when the request contains the following header:

.. code-block:: none

    session-header: "MS4yLjMuNDo4MA=="

When processing the upstream response, if ``1.2.3.4:80`` is indeed the final choice the extension
does nothing. If ``1.2.3.4:80`` is not the final choice, the new selected host will be set to
response headers (via the ``session-header`` response header).


.. _extension_envoy.http.stateful_session.header:

This extension has the qualified name ``envoy.http.stateful_session.header``


.. note::
  This extension is functional but has not had substantial production burn time,
  use only with this caveat.

  This extension has an unknown security posture and should only be
  used in deployments where both the downstream and upstream are
  trusted.

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


  - :ref:`envoy.http.stateful_session <extension_category_envoy.http.stateful_session>`



  This extension must be configured with one of the following type URLs:



  - :ref:`type.googleapis.com/envoy.extensions.http.stateful_session.header.v3.HeaderBasedSessionState <envoy_v3_api_msg_extensions.http.stateful_session.header.v3.HeaderBasedSessionState>`




.. code-block:: json
  :force:

  {
    "name": ...
  }

.. _envoy_v3_api_field_extensions.http.stateful_session.header.v3.HeaderBasedSessionState.name:


name
  (`string <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_, *REQUIRED*) The name that will be used to obtain header value from downstream HTTP request or generate
  new header for downstream.