moonchen commented on code in PR #13693: URL: https://github.com/apache/trafficserver/pull/13693#discussion_r4078366720
########## doc/admin-guide/configuration/http2-to-origin.en.rst: ########## @@ -0,0 +1,202 @@ +.. 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 + +To advertise these protocols globally, merge this setting into +:file:`records.yaml`: + +.. 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 +==================== + +Review :ts:cv:`proxy.config.http.server_session_sharing.pool` together with +:ts:cv:`proxy.config.http.server_session_sharing.match`. HTTP/2 origin sessions +are associated with their network thread. ``thread`` or ``hybrid`` pooling is +a useful starting point; global HTTP/1 pooling behavior is not a guarantee +that HTTP/2 connections will be reused across threads. For example: Review Comment: I think this paragraph should also explain what `global` pooling actually does when used with H/2 to origin. -- 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]
