From 980a623c26f80d93ad28b95f9865b3bb08865e4c Mon Sep 17 00:00:00 2001 From: Zhiyan Foo Date: Tue, 27 May 2025 12:25:13 -0400 Subject: [PATCH 1/6] XDS authority literal rewrite --- A91-xds-authority-literal-rewrite.md | 94 ++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 A91-xds-authority-literal-rewrite.md diff --git a/A91-xds-authority-literal-rewrite.md b/A91-xds-authority-literal-rewrite.md new file mode 100644 index 000000000..86015353a --- /dev/null +++ b/A91-xds-authority-literal-rewrite.md @@ -0,0 +1,94 @@ +Title +---- +* Author(s): Zhiyan Foo +* Approver: a11r +* Status: Draft +* Implemented in: TBD +* Last updated: 2025-04-23 +* Discussion at: TBD (filled after thread exists) + +## Abstract + +Implement the +[`host_rewrite_literal`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#envoy-v3-api-field-config-route-v3-routeaction-host-rewrite-literal) +route_action feature in gRPC xDS client, enabling explicit authority header rewrites. This will +be conditioned on `trusted_xds_server` as described in [gRFC A81][A81]. + + +## Background + +gRPC xDS currently supports `auto_host_rewrite` as per [gRFC A81][A81] but lacks `host_rewrite_literal` +support, useful when a single cluster targets a reverse proxy routing based on the authority +header. +``` + +------------------+ + | gRPC xDS Client | <- (RDS configuration sets `host_rewrite_literal` to + +------------------+ target one of Svc A/B/C) + | + | <- (gRPC xDS client reuses the same CDS target for all connections to + | the proxy) + +---------+ + | Proxy | + +---------+ + | <- (Proxy routing logic based on Authority header) + .---------------+--------------. + / | \ ++--------+ +--------+ +--------+ +| Svc A | | Svc B | | Svc C | ++--------+ +--------+ +--------+ +``` + +### Related Proposals: +* [gRFC A29: xDS-Based Security for gRPC Clients and Servers][A29] +* [gRFC A81: xDS Authority Rewriting][A81] +* [gRFC A86: xDS-Based HTTP CONNECT][A86] + + +## Proposal + +This proposal has the following parts: +- xDS resource unmarshalling: We will retrieve the `host_rewrite_literal` value from rds. The + protobuf option for authority rewriting is already set as a one-of, so there's no issue of + deciding precedence of the different authority writing options. + + If the `xds_trusted_server` attribute is set to false, the `host_rewrite_literal` field will + be ignored. + +- xDS ConfigSelector: We will propagate the `host_rewrite_literal` configuration to the + configSeletor where it would be stored in the rpc context. + +- During the stream creation, and the RPC call attributes are being set, if there is a non-empty + value for the `host_rewrite_literal`, it will take precedence over other options for the RPC + Call Host attribute. An exception would if a host override is specified either per-client or + per-RPC. In either case the per-client or per-RPC configuration would take precedence. + + +### Temporary environment variable protection + +Feature guarded by `GRPC_XDS_EXPERIMENTAL_AUTHORIY_LITERAL_REWRITE`, disabled by default. + +## Rationale + +Alternative approaches considered. +- Exclusively use the existing [`auto_host_rewrite`][route_action] feature. This would require a + CDS cluster per upstream target, which means that there would be one connection per service + behind the proxy between each gRPC clients and the proxy. +- Using the HTTP CONNECT protocol has the same drawback in that connections to the proxy that + target different upstream services won't reuse the same connection. + - in the case where instead of a single proxy in between the client and target upstream + service there are two proxies (e.g. client -> egress proxy -> ingress proxy -> svc), this + would not only prevent connection reuse between the initial client to the proxy, but also + between the intermediary proxies (e.g. between the egress and ingress proxy). + +Even if connection pooling was not a major concern, this addition will bring gRPC xDS client +functionality closer to parity with Envoy's capabilities, simplifying configurations for users +migrating to or using both systems concurrently. + +## Implementation + +[Go implementation](https://github.com/zhiyanfoo/grpc-go/pull/2/files). + +[A29]: A29-xds-tls-security.md +[A81]: A81-xds-authority-rewriting.md +[A86]: https://github.com/grpc/proposal/pull/455 +[route_action]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto From fd0458c60a3606d6d070fb025c9fcf31c377a7e4 Mon Sep 17 00:00:00 2001 From: zhiyanfoo Date: Mon, 2 Jun 2025 15:57:17 -0400 Subject: [PATCH 2/6] Update A91-xds-authority-literal-rewrite.md Co-authored-by: Antoine Tollenaere --- A91-xds-authority-literal-rewrite.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/A91-xds-authority-literal-rewrite.md b/A91-xds-authority-literal-rewrite.md index 86015353a..ffbc80703 100644 --- a/A91-xds-authority-literal-rewrite.md +++ b/A91-xds-authority-literal-rewrite.md @@ -57,7 +57,7 @@ This proposal has the following parts: - xDS ConfigSelector: We will propagate the `host_rewrite_literal` configuration to the configSeletor where it would be stored in the rpc context. -- During the stream creation, and the RPC call attributes are being set, if there is a non-empty +- During the stream creation, when the RPC call attributes are being set, if there is a non-empty value for the `host_rewrite_literal`, it will take precedence over other options for the RPC Call Host attribute. An exception would if a host override is specified either per-client or per-RPC. In either case the per-client or per-RPC configuration would take precedence. From e8f98104c6b6124b05eddd1abfc8086b227c9bf4 Mon Sep 17 00:00:00 2001 From: zhiyanfoo Date: Mon, 2 Jun 2025 15:57:58 -0400 Subject: [PATCH 3/6] Update A91-xds-authority-literal-rewrite.md --- A91-xds-authority-literal-rewrite.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/A91-xds-authority-literal-rewrite.md b/A91-xds-authority-literal-rewrite.md index ffbc80703..a1332e29e 100644 --- a/A91-xds-authority-literal-rewrite.md +++ b/A91-xds-authority-literal-rewrite.md @@ -1,7 +1,7 @@ Title ---- * Author(s): Zhiyan Foo -* Approver: a11r +* Approver: TBD * Status: Draft * Implemented in: TBD * Last updated: 2025-04-23 From 115406df7f20584d306f58b3bb17440af7e90c1b Mon Sep 17 00:00:00 2001 From: Zhiyan Foo Date: Mon, 2 Jun 2025 16:55:11 -0400 Subject: [PATCH 4/6] address comments --- A91-xds-authority-literal-rewrite.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/A91-xds-authority-literal-rewrite.md b/A91-xds-authority-literal-rewrite.md index a1332e29e..76fce8b3a 100644 --- a/A91-xds-authority-literal-rewrite.md +++ b/A91-xds-authority-literal-rewrite.md @@ -10,7 +10,7 @@ Title ## Abstract Implement the -[`host_rewrite_literal`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#envoy-v3-api-field-config-route-v3-routeaction-host-rewrite-literal) +[`host_rewrite_literal`][envoy-host_rewrite_literal] route_action feature in gRPC xDS client, enabling explicit authority header rewrites. This will be conditioned on `trusted_xds_server` as described in [gRFC A81][A81]. @@ -54,8 +54,8 @@ This proposal has the following parts: If the `xds_trusted_server` attribute is set to false, the `host_rewrite_literal` field will be ignored. -- xDS ConfigSelector: We will propagate the `host_rewrite_literal` configuration to the - configSeletor where it would be stored in the rpc context. +- xDS ConfigSelector: gRPC will pass down the `host_rewrite_literal`literal to use to the child + policies via channel arguments, or a similar mechanism depending on the language. - During the stream creation, when the RPC call attributes are being set, if there is a non-empty value for the `host_rewrite_literal`, it will take precedence over other options for the RPC @@ -86,9 +86,10 @@ migrating to or using both systems concurrently. ## Implementation -[Go implementation](https://github.com/zhiyanfoo/grpc-go/pull/2/files). +[Go implementation](https://github.com/zhiyanfoo/grpc-go/pull/2). [A29]: A29-xds-tls-security.md [A81]: A81-xds-authority-rewriting.md [A86]: https://github.com/grpc/proposal/pull/455 +[envoy-host_rewrite_literal]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#envoy-v3-api-field-config-route-v3-routeaction-host-rewrite-literal [route_action]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto From 2abc884fb9eba082500b08b521830c72d9f89ed4 Mon Sep 17 00:00:00 2001 From: Antoine Tollenaere Date: Wed, 14 Jan 2026 14:33:12 +0100 Subject: [PATCH 5/6] align with A81 --- ...d => A111-xds-authority-literal-rewrite.md | 80 +++++++++++++------ 1 file changed, 54 insertions(+), 26 deletions(-) rename A91-xds-authority-literal-rewrite.md => A111-xds-authority-literal-rewrite.md (51%) diff --git a/A91-xds-authority-literal-rewrite.md b/A111-xds-authority-literal-rewrite.md similarity index 51% rename from A91-xds-authority-literal-rewrite.md rename to A111-xds-authority-literal-rewrite.md index 76fce8b3a..2c58fed13 100644 --- a/A91-xds-authority-literal-rewrite.md +++ b/A111-xds-authority-literal-rewrite.md @@ -1,25 +1,24 @@ Title ---- -* Author(s): Zhiyan Foo +* Author(s): Zhiyan Foo, Antoine Tollenaere * Approver: TBD * Status: Draft -* Implemented in: TBD -* Last updated: 2025-04-23 +* Implemented in: Go +* Last updated: 2026-01-14 * Discussion at: TBD (filled after thread exists) ## Abstract -Implement the -[`host_rewrite_literal`][envoy-host_rewrite_literal] -route_action feature in gRPC xDS client, enabling explicit authority header rewrites. This will -be conditioned on `trusted_xds_server` as described in [gRFC A81][A81]. - +Implement the [`host_rewrite_literal`][envoy-host_rewrite_literal] route_action +feature in gRPC xDS client, enabling explicit authority header rewrites. This +will be conditioned on `trusted_xds_server` as described in [gRFC A81][A81]. ## Background -gRPC xDS currently supports `auto_host_rewrite` as per [gRFC A81][A81] but lacks `host_rewrite_literal` -support, useful when a single cluster targets a reverse proxy routing based on the authority -header. +gRPC xDS currently supports `auto_host_rewrite` as per [gRFC A81][A81] but lacks +`host_rewrite_literal` support, useful when a single cluster targets a reverse +proxy routing based on the authority header. + ``` +------------------+ | gRPC xDS Client | <- (RDS configuration sets `host_rewrite_literal` to @@ -43,29 +42,58 @@ header. * [gRFC A81: xDS Authority Rewriting][A81] * [gRFC A86: xDS-Based HTTP CONNECT][A86] - ## Proposal This proposal has the following parts: -- xDS resource unmarshalling: We will retrieve the `host_rewrite_literal` value from rds. The - protobuf option for authority rewriting is already set as a one-of, so there's no issue of - deciding precedence of the different authority writing options. - If the `xds_trusted_server` attribute is set to false, the `host_rewrite_literal` field will - be ignored. +- xDS resource unmarshalling: We will retrieve the `host_rewrite_literal` value + from RDS and return that information to the XdsClient watchers as part of the + parsed resources. + +- xDS ConfigSelector: the xDS ConfigSelector will enable authority rewriting + based on the chosen route. + +- xds_cluster_impl LB policy: The LB policy will perform the authority + rewriting if it was enabled by the ConfigSelector using the mechanism + introduced in [A81] for authority rewriting. + +### xDS Resource Validation + +When validating an RDS resource, if the `trusted_xds_server` server option is +present for this xDS server in the bootstrap config, we will look at the +[envoy-host_rewrite_literal] field. The string value of this field will be +included in the parsed resource struct that is passed to the XdsClient watcher. +If `trusted_xds_server` is unset, the field will be set to the empty string. + +### xDS ConfigSelector Changes + +When the xDS ConfigSelector performs routing, it will need to pass the values of +the route's `host_rewrite_literal` field to the LB picker. This data will be +passed using the mechanism used to handle `auto_host_rewrite` in [A81]. + +### xds_cluster_impl LB Policy Changes + +In the xds_cluster_impl picker, if the `host_rewrite_literal` field is not empty +in the route, the picker will set the `:authority` header to the value of the +field attribute, as described in [A81]. + +The `:authority` header is subject to the same secure naming checks defined in +[A81]. -- xDS ConfigSelector: gRPC will pass down the `host_rewrite_literal`literal to use to the child - policies via channel arguments, or a similar mechanism depending on the language. +### Precedence rules -- During the stream creation, when the RPC call attributes are being set, if there is a non-empty - value for the `host_rewrite_literal`, it will take precedence over other options for the RPC - Call Host attribute. An exception would if a host override is specified either per-client or - per-RPC. In either case the per-client or per-RPC configuration would take precedence. +Because `host_rewrite_literal` and `auto_host_rewrite` are part of the same +`host_rewrite_specifier` oneof, those fields cannot collide and there is no +precedence rule to define. If users set a per-call `:authority` explicitly, it +will take precedence over the value in `host_rewrite_literal`. This matches the +behavior implemented for `auto_host_rewrite`. +## Temporary environment variable protection -### Temporary environment variable protection +Feature guarded by `GRPC_EXPERIMENTAL_XDS_LITERAL_AUTHORITY_REWRITE` env var, +disabled by default. The env var guard will be removed once the feature passes +interop tests. -Feature guarded by `GRPC_XDS_EXPERIMENTAL_AUTHORIY_LITERAL_REWRITE`, disabled by default. ## Rationale @@ -86,7 +114,7 @@ migrating to or using both systems concurrently. ## Implementation -[Go implementation](https://github.com/zhiyanfoo/grpc-go/pull/2). +[Go implementation](https://github.com/grppc/grpc-go/pull/XXX). [A29]: A29-xds-tls-security.md [A81]: A81-xds-authority-rewriting.md From b28e837ba2ebf94b3a40d3ac5b279fbd377d694e Mon Sep 17 00:00:00 2001 From: Zhiyan Foo Date: Thu, 15 Jan 2026 09:57:07 -0500 Subject: [PATCH 6/6] Add link to grpc-go PR --- A111-xds-authority-literal-rewrite.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/A111-xds-authority-literal-rewrite.md b/A111-xds-authority-literal-rewrite.md index 2c58fed13..29ad2ba8e 100644 --- a/A111-xds-authority-literal-rewrite.md +++ b/A111-xds-authority-literal-rewrite.md @@ -4,7 +4,7 @@ Title * Approver: TBD * Status: Draft * Implemented in: Go -* Last updated: 2026-01-14 +* Last updated: 2026-01-15 * Discussion at: TBD (filled after thread exists) ## Abstract @@ -114,7 +114,7 @@ migrating to or using both systems concurrently. ## Implementation -[Go implementation](https://github.com/grppc/grpc-go/pull/XXX). +[Go implementation](https://github.com/grpc/grpc-go/pull/8838). [A29]: A29-xds-tls-security.md [A81]: A81-xds-authority-rewriting.md