ext_proc: document session affinity configuration

configs/ext-proc-session-affinity-cookie.yaml

@@ -0,0 +1,76 @@
+# Passive-cookie ext_proc session affinity.
+static_resources:
+  listeners:
+  - name: listener_0
+    address:
+      socket_address:
+        address: 0.0.0.0
+        port_value: 10000
+    filter_chains:
+    - filters:
+      - name: envoy.filters.network.http_connection_manager
+        typed_config:
+          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
+          stat_prefix: ingress_http
+          route_config:
+            name: local_route
+            virtual_hosts:
+            - name: local_service
+              domains: ["*"]
+              routes:
+              - match:
+                  prefix: "/"
+                route:
+                  cluster: origin
+          http_filters:
+          # session-affinity-cookie-filter-start
+          - name: envoy.filters.http.ext_proc
+            typed_config:
+              "@type": type.googleapis.com/envoy.extensions.filters.http.ext_proc.v3.ExternalProcessor
+              grpc_service:
+                envoy_grpc:
+                  cluster_name: ext_proc_cluster
+                initial_metadata:
+                - key: cookie
+                  value: "%REQ(cookie)%"
+          # session-affinity-cookie-filter-end
+          - name: envoy.filters.http.router
+            typed_config:
+              "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
+  clusters:
+  - name: origin
+    load_assignment:
+      cluster_name: origin
+      endpoints:
+      - lb_endpoints:
+        - endpoint:
+            address:
+              socket_address:
+                address: 127.0.0.1
+                port_value: 8080
+  # session-affinity-cookie-cluster-start
+  - name: ext_proc_cluster
+    lb_policy: RING_HASH
+    typed_extension_protocol_options:
+      envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
+        "@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions
+        explicit_http_config:
+          http2_protocol_options: {}
+        hash_policy:
+        - cookie:
+            name: session_id
+    load_assignment:
+      cluster_name: ext_proc_cluster
+      endpoints:
+      - lb_endpoints:
+        - endpoint:
+            address:
+              socket_address:
+                address: 127.0.0.1
+                port_value: 50051
+        - endpoint:
+            address:
+              socket_address:
+                address: 127.0.0.1
+                port_value: 50052
+# session-affinity-cookie-cluster-end

configs/ext-proc-session-affinity-header.yaml

@@ -0,0 +1,76 @@
+# Header-based ext_proc session affinity.
+static_resources:
+  listeners:
+  - name: listener_0
+    address:
+      socket_address:
+        address: 0.0.0.0
+        port_value: 10000
+    filter_chains:
+    - filters:
+      - name: envoy.filters.network.http_connection_manager
+        typed_config:
+          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
+          stat_prefix: ingress_http
+          route_config:
+            name: local_route
+            virtual_hosts:
+            - name: local_service
+              domains: ["*"]
+              routes:
+              - match:
+                  prefix: "/"
+                route:
+                  cluster: origin
+          http_filters:
+          # session-affinity-header-filter-start
+          - name: envoy.filters.http.ext_proc
+            typed_config:
+              "@type": type.googleapis.com/envoy.extensions.filters.http.ext_proc.v3.ExternalProcessor
+              grpc_service:
+                envoy_grpc:
+                  cluster_name: ext_proc_cluster
+                initial_metadata:
+                - key: x-session-id
+                  value: "%REQ(x-session-id)%"
+          # session-affinity-header-filter-end
+          - name: envoy.filters.http.router
+            typed_config:
+              "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
+  clusters:
+  - name: origin
+    load_assignment:
+      cluster_name: origin
+      endpoints:
+      - lb_endpoints:
+        - endpoint:
+            address:
+              socket_address:
+                address: 127.0.0.1
+                port_value: 8080
+  # session-affinity-header-cluster-start
+  - name: ext_proc_cluster
+    lb_policy: RING_HASH
+    typed_extension_protocol_options:
+      envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
+        "@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions
+        explicit_http_config:
+          http2_protocol_options: {}
+        hash_policy:
+        - header:
+            header_name: x-session-id
+    load_assignment:
+      cluster_name: ext_proc_cluster
+      endpoints:
+      - lb_endpoints:
+        - endpoint:
+            address:
+              socket_address:
+                address: 127.0.0.1
+                port_value: 50051
+        - endpoint:
+            address:
+              socket_address:
+                address: 127.0.0.1
+                port_value: 50052
+# session-affinity-header-cluster-end

docs/root/configuration/http/http_filters/ext_proc_filter.rst

@@ -27,6 +27,50 @@ stream requests from the proxy.
 The updated list of supported features can be found on the
 :ref:`reference page <envoy_v3_api_msg_extensions.filters.http.ext_proc.v3.ExternalProcessor>`.
 
+Session affinity
+----------------
+
+When the filter uses the Envoy gRPC client, requests to the external processor can use
+consistent hashing to keep sessions on the same processor endpoint. Configure the gRPC
+:ref:`initial metadata <envoy_v3_api_field_config.core.v3.GrpcService.initial_metadata>` to
+copy an affinity key from the downstream request, and configure the external processor cluster
+with a matching
+:ref:`cluster-level hash policy <envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.hash_policy>`.
+
+For example, the filter can copy a session header into the gRPC request:
+
+.. literalinclude:: /_configs/repo/ext-proc-session-affinity-header.yaml
+   :language: yaml
+   :start-after: session-affinity-header-filter-start
+   :end-before: session-affinity-header-filter-end
+   :caption: :download:`ext-proc-session-affinity-header.yaml </_configs/repo/ext-proc-session-affinity-header.yaml>`
+
+The external processor cluster can then hash the copied header:
+
+.. literalinclude:: /_configs/repo/ext-proc-session-affinity-header.yaml
+   :language: yaml
+   :start-after: session-affinity-header-cluster-start
+   :end-before: session-affinity-header-cluster-end
+
+Passive cookie affinity can be configured in the same way by copying the downstream ``cookie``
+header into the gRPC initial metadata and selecting the cookie by name in the cluster hash policy:
+
+.. literalinclude:: /_configs/repo/ext-proc-session-affinity-cookie.yaml
+   :language: yaml
+   :start-after: session-affinity-cookie-filter-start
+   :end-before: session-affinity-cookie-filter-end
+   :caption: :download:`ext-proc-session-affinity-cookie.yaml </_configs/repo/ext-proc-session-affinity-cookie.yaml>`
+
+.. literalinclude:: /_configs/repo/ext-proc-session-affinity-cookie.yaml
+   :language: yaml
+   :start-after: session-affinity-cookie-cluster-start
+   :end-before: session-affinity-cookie-cluster-end
+
+The cluster must use a hash-based load balancer such as ``RING_HASH`` or ``MAGLEV``. Cookie
+affinity must be passive: generated cookies cannot be propagated from the external processor
+side stream to the original downstream client. This configuration does not apply to the native
+Google gRPC client. Cluster-level hash policies take precedence over request-level policies.
+
 Statistics
 ----------
 This filter outputs statistics in the

test/extensions/filters/http/ext_proc/BUILD

@@ -461,6 +461,7 @@ envoy_extension_cc_test(
         "//source/extensions/filters/http/match_delegate:config",
         "//source/extensions/filters/http/set_metadata:config",
         "//source/extensions/http/ext_proc/processing_request_modifiers/mapped_attribute_builder:mapped_attribute_builder_lib",
+        "//source/extensions/load_balancing_policies/ring_hash:config",
         "//source/extensions/retry/host/previous_hosts:config",
         "//test/common/http:common_lib",
         "//test/integration:http_integration_lib",
@@ -480,6 +481,7 @@ envoy_extension_cc_test(
         "@envoy_api//envoy/extensions/filters/http/upstream_codec/v3:pkg_cc_proto",
         "@envoy_api//envoy/extensions/http/ext_proc/processing_request_modifiers/mapped_attribute_builder/v3:pkg_cc_proto",
         "@envoy_api//envoy/extensions/retry/host/previous_hosts/v3:pkg_cc_proto",
+        "@envoy_api//envoy/extensions/upstreams/http/v3:pkg_cc_proto",
         "@envoy_api//envoy/service/ext_proc/v3:pkg_cc_proto",
         "@envoy_api//envoy/type/v3:pkg_cc_proto",
         "@ocp-diag-core//ocpdiag/core/testing:status_matchers",