bneradt commented on code in PR #13693: URL: https://github.com/apache/trafficserver/pull/13693#discussion_r4299482516
########## doc/admin-guide/configuration/http2-to-origin.en.rst: ########## @@ -0,0 +1,211 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. include:: ../../common.defs + +.. _http2-to-origin: + +HTTP/2 to Origin +**************** + +|TS| can negotiate HTTP/2 with TLS origin servers independently of the +protocol used by its clients. Several requests can share one origin +connection, reducing connection setup overhead. Origins that support only +HTTP/1.1 can continue to use it. + +This guide describes reverse proxy connections established by |TS|. A forward +proxy's CONNECT tunnel is different: the client negotiates TLS and HTTP inside +the tunnel, so configuring |TS|'s origin ALPN does not select that protocol. + +Enable protocol negotiation +=========================== + +Configure |TS| to advertise HTTP/2 support to origin peers via ALPN +negotiation. Set :ts:cv:`proxy.config.ssl.client.alpn_protocols` to offer +HTTP/2 with HTTP/1.1 as a fallback. To start with one remap rule, use +:ref:`admin-plugins-conf-remap` in :file:`remap.config`:: + + map https://www.example.com/ https://origin.example.com/ @plugin=conf_remap.so @pparam=proxy.config.ssl.client.alpn_protocols=h2,http/1.1 + +A remap rule takes effect when :file:`remap.config` is reloaded. To advertise +these protocols globally, merge this setting into :file:`records.yaml` and +restart |TS|; the global record is not reloadable: + +.. code-block:: yaml + + records: + ssl: + client: + alpn_protocols: h2,http/1.1 + +The destination must use TLS for this ALPN configuration to apply. The origin +selects a mutually supported protocol during the TLS handshake; offering +``h2`` does not force every origin connection to use HTTP/2. Existing +connections retain their negotiated protocol. Check for per-remap overrides +when a global change does not affect the expected origin. + +Start with a limited set of origins and representative traffic, including +uploads, large responses, conditional requests, and long-lived connections. +Check the fixes available in your |TS| release before expanding deployment. + +Flow control +============ + +HTTP/2 has both stream and connection receive windows. With policy ``0``, +several active streams share a connection window the size of a single stream +window. That can restrict throughput even when the individual streams have +room to receive more data. + +Policy ``1`` increases the connection receive window while keeping each +stream's receive window fixed. It is a useful starting point for concurrent +traffic: + +.. code-block:: yaml + + records: + http2: + flow_control: + policy_in: 1 + policy_out: 1 + +The directions describe the connections, not the direction of request data: + +* :ts:cv:`proxy.config.http2.flow_control.policy_in` controls what |TS| can + receive from HTTP/2 clients, such as concurrent request bodies. +* :ts:cv:`proxy.config.http2.flow_control.policy_out` controls what |TS| can + receive from HTTP/2 origins, such as concurrent response bodies. The origin's + receive windows control how much request-body data |TS| can send to it. + +Policy ``1`` sizes the connection window as the initial stream window +multiplied by the configured maximum concurrent streams for that direction. +Review :ts:cv:`proxy.config.http2.initial_window_size_out` and +:ts:cv:`proxy.config.http2.max_concurrent_streams_out` together when tuning +origin response throughput and buffering. + +Policy ``2`` also enlarges the connection window, but dynamically changes the +stream windows as concurrency changes. These adjustments can generate repeated +SETTINGS frames. Some origins limit SETTINGS frequency and can terminate the +connection with GOAWAY and ``ENHANCE_YOUR_CALM``. Policy ``1`` avoids these +concurrency-driven stream-window updates. Increasing |TS|'s inbound SETTINGS +limit does not change a limit imposed by the origin. + +Persist policy changes in :file:`records.yaml` and restart |TS| during a planned +maintenance window. The policies are copied into HTTP/2 state at startup; +seeing a new value in ``traffic_ctl config get`` after a reload alone does not +verify that HTTP/2 is using it. + +Pooling and timeouts +==================== + +|TS| places every HTTP/2 origin session in the session pool of the network +thread that drives its connection, whatever +:ts:cv:`proxy.config.http.server_session_sharing.pool` is set to. The +session's state is owned by that thread, so it cannot be shared with other +threads. When a transaction needs an origin connection, |TS| first searches +the current thread's pool and then the pool type configured by that record. +With ``global`` pooling, HTTP/1.1 origin connections are still shared by all +threads, while an HTTP/2 origin session serves only transactions on its own +thread. :ts:cv:`proxy.config.http.server_session_sharing.match` applies to +both protocols. Review Comment: That describes the code before #13447. On current master, `HttpSessionManager::acquire_session` always calls `_acquire_session(..., TS_SERVER_SESSION_SHARING_POOL_THREAD)` first, and only falls back to the global pool for `global`/`hybrid` (or `global_locked`) on a miss. See the "Always check the thread-local pool first" comment there. `h2_to_origin_pool_reuse.test.py` is the regression test for H2 origin reuse with `pool: global`; the other H2 tests that pick `thread`/`hybrid` predate it. So the section is accurate for this release. Older releases (10.1.x, for example) do behave as you describe, so I added a short note telling operators on those releases to use `thread` or `hybrid`. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
