From 2bc6a36857a83610f091892960483fd597c2ddb2 Mon Sep 17 00:00:00 2001 From: AgraVator Date: Tue, 23 Dec 2025 14:07:36 +0530 Subject: [PATCH 1/5] propose child channel plugins --- A110-child-channel-plugins.md | 235 ++++++++++++++++++++++++++++++++++ 1 file changed, 235 insertions(+) create mode 100644 A110-child-channel-plugins.md diff --git a/A110-child-channel-plugins.md b/A110-child-channel-plugins.md new file mode 100644 index 000000000..d8152c61f --- /dev/null +++ b/A110-child-channel-plugins.md @@ -0,0 +1,235 @@ +# **gRFC AXX: Child Channel Configuration Plugins** + +* **Author(s)**: [Abhishek Agrawal](mailto:agrawalabhi@google.com) +* **Status**: Draft +* **To be implemented in**: Core, Java, Go +* **Last updated**: 2025-12-22 + +## **Abstract** + +This proposal introduces a mechanism to configure "child channels"—channels created internally by gRPC components (such as xDS control plane channel). Currently, these internal channels cannot easily inherit configuration (like metric sinks and interceptors) from the user application without relying on global state. This design proposes a language-specific approach to injecting configuration: using `functional interfaces` in Java, `DialOptions` in Go, and `ChannelArgs` in Core. + +## **Background** + +Complex gRPC ecosystems often require the creation of auxiliary channels that are not directly instantiated by the user application. Two primary examples are: + +1. **xDS (Extensible Discovery Service)**: When a user creates a channel with an xDS target, the gRPC library internally creates a separate channel to communicate with the xDS control plane. Currently, users have limited ability to configure this internal control plane channel. +2. **Advanced Load Balancing (RLS, GrpcLB):** Policies like RLS (Route Lookup Service) and GrpcLB, as well as other high-level libraries built on top of gRPC, frequently create internal channels to communicate with look-aside load balancers or backends. + +### **The Problem** + +There is currently no standardized way to configure behavior for these child channels. + +* **Metrics**: Users need to configure metric sinks so that telemetry from internal channels can be read and exported. +* **Interceptors**: Users may need to apply specific interceptors (e.g., for authentication, logging, or tracing) to internal traffic. +* **No Global State**: These configurations cannot be set globally (e.g., using static singletons) because different parts of an application may require different configurations, such as different metric backends or security credentials. + +## **Proposal** + +The proposal creates a "plugin" or configuration injection style for internal channels. The implementation varies by language to match existing idioms, but the goal remains consistent: allow the user to pass a configuration object or function that the internal channel factory applies during creation. + +### **Java** + +In Java, the configuration will be achieved by accepting functions (callbacks). The API allows users to pass a `Consumer>` (or a similar functional interface). When an internal library (e.g., xDS, RLS, gRPCLB) creates a child channel, it applies this user-provided function to the builder before building the channel. + + + * #### 1\. Configuration Interface + + Use the standard `java.util.function.Consumer` and define a new public API interface, `ChildChannelConfigurer`, to encapsulate the configuration logic for auxiliary channels. + + ```java + import java.util.function.Consumer; + import io.grpc.ManagedChannelBuilder; + + // Captures the intent of the plugin. + // Consumes a builder to modify it before the channel is built + public interface ChildChannelConfigurer extends Consumer> { + // Inherits accept(T t) from Consumer + } + ``` + + * #### 2\. API Changes + + Add `ManagedChannelBuilder#childChannelConfigurer()` to allow users to register this configurer, and `ManagedChannelBuilder#configureChannel(ManagedChannel parent)` to allow a new builder to inherit configuration (including the `ChildChannelConfigurer` and `MetricRecorder`) from an existing parent channel. + + * #### 3\. Internal Implementation + + The implementation propagates these configurations when creating internal channels. It leverages `configureChannel()` to act as a fusion point, automatically applying the `ChildChannelConfigurer` and other parent properties to the new builder. The implementation follows the pattern for global configurators and calls `.accept()` as soon as the builder is available. + + * #### 4\. Usage Example + + ```java + // 1. Define the configurer for internal child channels + ChildChannelConfigurer myInternalConfig = (builder) -> { + // Apply interceptors or configuration to the child channel builder + builder.intercept(new MyAuthInterceptor()); + builder.maxInboundMessageSize(1024 * 1024); + }; + + // 2. Apply it to the parent channel + ManagedChannel channel = ManagedChannelBuilder.forTarget("xds:///my-service") + .childChannelConfigurer(myInternalConfig) // <--- Configuration injected here + .build(); + ``` + + * #### 5. Out-of-Band (OOB) Channels + + We do not propose applying child channel configurations to Out-of-Band (OOB) channels at this time. To maintain architectural flexibility and avoid breaking changes in the future, we will modify the implementation to use a `noOp()` MetricSink for OOB channels rather than inheriting the parent channel's sink. + +Furthermore, we acknowledge that certain configurations will not function out-of-the-box for `resolvingOobChannel` due to its specific initialization requirements. + + + +### **Go** + +In Go, configuration for child channels will be achieved by passing a specific `DialOption` to the parent channel. This option will encapsulate a slice of *other* `DialOption`s that should be applied exclusively to any internal child channels (like xDS control plane connections) created by the parent. + +* #### 1\. Define a new API for configuring the childChannelOptions + + * **New Public API** We will introduce a new function in the `grpc` package that returns a `DialOption` specifically for child channels. + +```go +// WithChildChannelOptions returns a DialOption that specifies a list of options +// to be applied to any internal child channels (e.g., xDS control plane channels) +// created by this ClientConn. +// +// These options are NOT applied to the ClientConn returned by NewClient. +func WithChildChannelOptions(opts ...DialOption) DialOption { + return newFuncDialOption(func(o *dialOptions) { + o.childChannelOptions = opts + }) +} +``` + +### + +* #### 2\. Internal Mechanics + + * We need to add a field to the internal `dialOptions` struct to hold these options, and then ensure internal components (like the xDS client) read them. + + * ##### A. Update `dialOptions` struct + +```go +● type dialOptions struct { +● // ... existing fields ... +● // childChannelOptions holds options intended for internal child channels. +● childChannelOptions []DialOption +● } +``` + + * ##### B. Update Internal Channel Creation (e.g., in `xds/client`) + + * When the xDS client (or any internal component) needs to dial the control plane, it must merge its own required options with the user-provided child options. + +* #### 3\. Usage Example (User-Side Code) + + * This design gives the user complete flexibility. They can configure the parent channel one way (e.g., mTLS) and the child channel another way (e.g., OAuth token \+ Metrics), all in one `NewClient` call. + +```go +import ( + "google.golang.org/grpc" + "google.golang.org/grpc/credentials/insecure" +) + +func main() { + // 1. Define configuration specifically for the internal control plane + // (e.g., a specific metrics interceptor or custom authority) + internalOpts := []grpc.DialOption{ + grpc.WithUnaryInterceptor(MyMonitoringInterceptor), + grpc.WithAuthority("xds-authority.example.com"), + } + + // 2. Create the Parent Channel + // Pass the internal options using the new wrapper. + conn, err := grpc.NewClient("xds:///my-service", + // Parent configuration + grpc.WithTransportCredentials(insecure.NewCredentials()), + + // Child configuration (injected here) + grpc.WithChildChannelOptions(internalOpts...), + ) + + if err != nil { + panic(err) + } + // ... use conn ... +} +``` + +### **Core (C/C++)** + +In gRPC Core, we utilize the existing `ChannelArgs` mechanism recursively to pass configuration to internal channels. Instead of introducing a new configuration class or interface, we define a standard argument key whose value is a pointer to another `grpc_channel_args` structure. This "Nested Arguments" pattern allows the parent channel to carry a specific subset of arguments intended solely for its children (e.g., xDS control plane connections). + +* #### 1\. Define the Configuration Mechanism + + * We define a new channel argument key. The value associated with this key is a pointer to a `grpc_channel_args` struct (or the C++ `ChannelArgs` wrapper), managed via a pointer vtable to ensure correct ownership and copying. + +```c +// A pointer argument key that internal components (like xDS) look for. +// The value is a pointer to a grpc_channel_args struct containing the subset +// of options (e.g., specific socket mutators, user agents) for child channels. +#define GRPC_ARG_CHILD_CHANNEL_ARGS "grpc.internal.child_channel_args" +``` + +#### + +* #### 2\. Internal Implementation + + * Internal components that create channels (specifically `XdsClient`) are updated to look for this argument. If present, these arguments are merged with the default arguments required by the component. + * **Extraction:** The component queries the parent's args for `GRPC_ARG_CHILD_CHANNEL_ARGS`. + * **Merge:** The extracted args are layered on top of the default internal args (e.g., bootstrap configuration). + * **Creation:** The combined arguments are passed to `grpc_channel_create`. + +* #### **3\. Usage Example (User-Side Code)** + + * A user configures the parent channel by creating a subset of arguments for the child, packing them into a standard `grpc_arg`, and passing them to the parent. + +```c +// 1. Prepare the Child Config (The Subset) +// Example: We want the internal control plane to use a specific Socket Mutator +grpc_socket_mutator* my_mutator = CreateMySocketMutator(); +grpc_arg child_arg = grpc_channel_arg_socket_mutator_create(my_mutator); +grpc_channel_args child_args_struct = {1, &child_arg}; + +// 2. Pack the Subset into the Parent's Arguments +// We use a helper (conceptually similar to grpc_channel_arg_pointer_create) +// to wrap the child_args_struct safely with a VTable for ownership. +grpc_arg parent_arg = grpc_channel_arg_pointer_create( + GRPC_ARG_CHILD_CHANNEL_ARGS, + &child_args_struct, + &grpc_channel_args_pointer_vtable // VTable handles copy/destroy of the struct +); + +// 3. Create the Parent Channel +grpc_channel_args parent_args = {1, &parent_arg}; +auto channel = grpc::CreateCustomChannel( + "xds:///my-service", + grpc::InsecureChannelCredentials(), + grpc::ChannelArguments::FromC(parent_args) +); + +// Result: The 'channel' (parent) does NOT use 'my_mutator'. +// However, when it creates the internal xDS channel, it extracts 'child_args_struct' +// and applies 'my_mutator' to that connection. +``` + +## **Rationale** + +### **Why not Global Configuration?** + +Global configuration (static variables) was rejected because it prevents multi-tenant applications from isolating configurations. For example, one GCS client might need to export metrics to Prometheus, while another in the same process exports to Cloud Monitoring. + +### **Why Language-Specific Approaches?** + +While the concept (configuring child channels) is cross-language, the mechanism for channel creation differs significantly: + +* **Java** relies heavily on the `Builder` pattern, making functional callbacks the most natural fit. +* **Go** uses functional options (`DialOption`), so passing a slice of options is idiomatic. +* **Core** uses a generic key-value map (`ChannelArgs`) for almost all configurations, maintaining consistency with the core C-core design. + +## **Open Issues** + +* Should there be distinct configurations for different(i.e. different target strings) child channels ? +* For xDS client pool the first since it only depends on the target string, any subsequent usage within the same process having the same target string will end up using the previously created client with possibly different configuration. + +[image1]: \ No newline at end of file From bec26c95148360a99f9d5f07bbcd29e4fb9fa331 Mon Sep 17 00:00:00 2001 From: AgraVator Date: Tue, 23 Dec 2025 14:24:35 +0530 Subject: [PATCH 2/5] correct formatting --- A110-child-channel-plugins.md | 306 ++++++++++++++++------------------ 1 file changed, 143 insertions(+), 163 deletions(-) diff --git a/A110-child-channel-plugins.md b/A110-child-channel-plugins.md index d8152c61f..2d934e6df 100644 --- a/A110-child-channel-plugins.md +++ b/A110-child-channel-plugins.md @@ -1,9 +1,9 @@ # **gRFC AXX: Child Channel Configuration Plugins** -* **Author(s)**: [Abhishek Agrawal](mailto:agrawalabhi@google.com) -* **Status**: Draft -* **To be implemented in**: Core, Java, Go -* **Last updated**: 2025-12-22 +* **Author(s)**: [Abhishek Agrawal](mailto:agrawalabhi@google.com) +* **Status**: Draft +* **To be implemented in**: Core, Java, Go +* **Last updated**: 2025-12-23 ## **Abstract** @@ -13,15 +13,15 @@ This proposal introduces a mechanism to configure "child channels"—channels cr Complex gRPC ecosystems often require the creation of auxiliary channels that are not directly instantiated by the user application. Two primary examples are: -1. **xDS (Extensible Discovery Service)**: When a user creates a channel with an xDS target, the gRPC library internally creates a separate channel to communicate with the xDS control plane. Currently, users have limited ability to configure this internal control plane channel. +1. **xDS (Extensible Discovery Service)**: When a user creates a channel with an xDS target, the gRPC library internally creates a separate channel to communicate with the xDS control plane. Currently, users have limited ability to configure this internal control plane channel. 2. **Advanced Load Balancing (RLS, GrpcLB):** Policies like RLS (Route Lookup Service) and GrpcLB, as well as other high-level libraries built on top of gRPC, frequently create internal channels to communicate with look-aside load balancers or backends. ### **The Problem** There is currently no standardized way to configure behavior for these child channels. -* **Metrics**: Users need to configure metric sinks so that telemetry from internal channels can be read and exported. -* **Interceptors**: Users may need to apply specific interceptors (e.g., for authentication, logging, or tracing) to internal traffic. +* **Metrics**: Users need to configure metric sinks so that telemetry from internal channels can be read and exported. +* **Interceptors**: Users may need to apply specific interceptors (e.g., for authentication, logging, or tracing) to internal traffic. * **No Global State**: These configurations cannot be set globally (e.g., using static singletons) because different parts of an application may require different configurations, such as different metric backends or security credentials. ## **Proposal** @@ -33,203 +33,183 @@ The proposal creates a "plugin" or configuration injection style for internal ch In Java, the configuration will be achieved by accepting functions (callbacks). The API allows users to pass a `Consumer>` (or a similar functional interface). When an internal library (e.g., xDS, RLS, gRPCLB) creates a child channel, it applies this user-provided function to the builder before building the channel. - * #### 1\. Configuration Interface +* #### 1\. Configuration Interface - Use the standard `java.util.function.Consumer` and define a new public API interface, `ChildChannelConfigurer`, to encapsulate the configuration logic for auxiliary channels. + Use the standard `java.util.function.Consumer` and define a new public API interface, `ChildChannelConfigurer`, to encapsulate the configuration logic for auxiliary channels. - ```java - import java.util.function.Consumer; - import io.grpc.ManagedChannelBuilder; + ```java + import java.util.function.Consumer; + import io.grpc.ManagedChannelBuilder; - // Captures the intent of the plugin. - // Consumes a builder to modify it before the channel is built - public interface ChildChannelConfigurer extends Consumer> { - // Inherits accept(T t) from Consumer - } - ``` + // Captures the intent of the plugin. + // Consumes a builder to modify it before the channel is built + public interface ChildChannelConfigurer extends Consumer> { + // Inherits accept(T t) from Consumer + } + ``` - * #### 2\. API Changes +* #### 2\. API Changes - Add `ManagedChannelBuilder#childChannelConfigurer()` to allow users to register this configurer, and `ManagedChannelBuilder#configureChannel(ManagedChannel parent)` to allow a new builder to inherit configuration (including the `ChildChannelConfigurer` and `MetricRecorder`) from an existing parent channel. + Add `ManagedChannelBuilder#childChannelConfigurer()` to allow users to register this configurer, and `ManagedChannelBuilder#configureChannel(ManagedChannel parent)` to allow a new builder to inherit configuration (including the `ChildChannelConfigurer` and `MetricRecorder`) from an existing parent channel. - * #### 3\. Internal Implementation +* #### 3\. Internal Implementation - The implementation propagates these configurations when creating internal channels. It leverages `configureChannel()` to act as a fusion point, automatically applying the `ChildChannelConfigurer` and other parent properties to the new builder. The implementation follows the pattern for global configurators and calls `.accept()` as soon as the builder is available. + The implementation propagates these configurations when creating internal channels. It leverages `configureChannel()` to act as a fusion point, automatically applying the `ChildChannelConfigurer` and other parent properties to the new builder. The implementation follows the pattern for global configurators and calls `.accept()` as soon as the builder is available. - * #### 4\. Usage Example +* #### 4\. Usage Example - ```java - // 1. Define the configurer for internal child channels - ChildChannelConfigurer myInternalConfig = (builder) -> { - // Apply interceptors or configuration to the child channel builder - builder.intercept(new MyAuthInterceptor()); - builder.maxInboundMessageSize(1024 * 1024); - }; + ```java + // 1. Define the configurer for internal child channels + ChildChannelConfigurer myInternalConfig = (builder) -> { + // Apply interceptors or configuration to the child channel builder + builder.intercept(new MyAuthInterceptor()); + builder.maxInboundMessageSize(1024 * 1024); + }; - // 2. Apply it to the parent channel - ManagedChannel channel = ManagedChannelBuilder.forTarget("xds:///my-service") - .childChannelConfigurer(myInternalConfig) // <--- Configuration injected here - .build(); - ``` + // 2. Apply it to the parent channel + ManagedChannel channel = ManagedChannelBuilder.forTarget("xds:///my-service") + .childChannelConfigurer(myInternalConfig) // <--- Configuration injected here + .build(); + ``` - * #### 5. Out-of-Band (OOB) Channels +* #### 5\. Out-of-Band (OOB) Channels - We do not propose applying child channel configurations to Out-of-Band (OOB) channels at this time. To maintain architectural flexibility and avoid breaking changes in the future, we will modify the implementation to use a `noOp()` MetricSink for OOB channels rather than inheriting the parent channel's sink. + We do not propose applying child channel configurations to Out-of-Band (OOB) channels at this time. To maintain architectural flexibility and avoid breaking changes in the future, we will modify the implementation to use a `noOp()` MetricSink for OOB channels rather than inheriting the parent channel's sink. -Furthermore, we acknowledge that certain configurations will not function out-of-the-box for `resolvingOobChannel` due to its specific initialization requirements. - - + Furthermore, we acknowledge that certain configurations will not function out-of-the-box for `resolvingOobChannel` due to its specific initialization requirements. ### **Go** -In Go, configuration for child channels will be achieved by passing a specific `DialOption` to the parent channel. This option will encapsulate a slice of *other* `DialOption`s that should be applied exclusively to any internal child channels (like xDS control plane connections) created by the parent. - -* #### 1\. Define a new API for configuring the childChannelOptions - - * **New Public API** We will introduce a new function in the `grpc` package that returns a `DialOption` specifically for child channels. +In Go, configuration for child channels is be achieved by passing a specific `DialOption` to the parent channel. This option encapsulates a slice of other a slice of *other* `DialOption`s that are applied exclusively to any internal child channels created by the parent. -```go -// WithChildChannelOptions returns a DialOption that specifies a list of options -// to be applied to any internal child channels (e.g., xDS control plane channels) -// created by this ClientConn. -// -// These options are NOT applied to the ClientConn returned by NewClient. -func WithChildChannelOptions(opts ...DialOption) DialOption { - return newFuncDialOption(func(o *dialOptions) { - o.childChannelOptions = opts - }) -} -``` +* #### 1\. New API for Child Channel Options -### + We introduce a new function in the grpc package that returns a `DialOption` specifically for child channels. -* #### 2\. Internal Mechanics + ```go + // WithChildChannelOptions returns a DialOption that specifies a list of options + // to be applied to any internal child channels (e.g., xDS control plane channels) + // created by this ClientConn. + // + // These options are NOT applied to the ClientConn returned by NewClient. + func WithChildChannelOptions(opts ...DialOption) DialOption { + return newFuncDialOption(func(o *dialOptions) { + o.childChannelOptions = opts + }) + } + ``` - * We need to add a field to the internal `dialOptions` struct to hold these options, and then ensure internal components (like the xDS client) read them. +* #### 2\. Internal Mechanics - * ##### A. Update `dialOptions` struct + A new field is added to the internal `dialOptions` struct to hold these options. When the xDS client (or any internal component) dials the control plane, it merges its own required options with the user-provided child options. -```go -● type dialOptions struct { -● // ... existing fields ... -● // childChannelOptions holds options intended for internal child channels. -● childChannelOptions []DialOption -● } -``` - - * ##### B. Update Internal Channel Creation (e.g., in `xds/client`) - - * When the xDS client (or any internal component) needs to dial the control plane, it must merge its own required options with the user-provided child options. + ```go + type dialOptions struct { + // ... existing fields ... + // childChannelOptions holds options intended for internal child channels. + childChannelOptions []DialOption + } + ``` * #### 3\. Usage Example (User-Side Code) - * This design gives the user complete flexibility. They can configure the parent channel one way (e.g., mTLS) and the child channel another way (e.g., OAuth token \+ Metrics), all in one `NewClient` call. - -```go -import ( - "google.golang.org/grpc" - "google.golang.org/grpc/credentials/insecure" -) - -func main() { - // 1. Define configuration specifically for the internal control plane - // (e.g., a specific metrics interceptor or custom authority) - internalOpts := []grpc.DialOption{ - grpc.WithUnaryInterceptor(MyMonitoringInterceptor), - grpc.WithAuthority("xds-authority.example.com"), - } - - // 2. Create the Parent Channel - // Pass the internal options using the new wrapper. - conn, err := grpc.NewClient("xds:///my-service", - // Parent configuration - grpc.WithTransportCredentials(insecure.NewCredentials()), - - // Child configuration (injected here) - grpc.WithChildChannelOptions(internalOpts...), - ) + This design provides users with the flexibility to define independent configurations for parent and child channels within a single NewClient call. For example, a parent channel can be configured with transport security (mTLS) while the internal child channels (such as the xDS control plane connection) are configured with specific interceptors or a custom authority. + + ```go + import ( + "google.golang.org/grpc" + "google.golang.org/grpc/credentials/insecure" + ) + + func main() { + // 1. Define configuration specifically for the internal control plane + // (e.g., a specific metrics interceptor or custom authority) + internalOpts := []grpc.DialOption{ + grpc.WithUnaryInterceptor(MyMonitoringInterceptor), + grpc.WithAuthority("xds-authority.example.com"), + } + + // 2. Create the Parent Channel + // Pass the internal options using the WithChildChannelOptions wrapper. + conn, err := grpc.NewClient("xds:///my-service", + // Parent channel configuration + grpc.WithTransportCredentials(insecure.NewCredentials()), + + // Child channel configuration (injected here) + grpc.WithChildChannelOptions(internalOpts...), + ) + + if err != nil { + log.Fatalf("failed to create client: %v", err) + } + defer conn.Close() - if err != nil { - panic(err) - } - // ... use conn ... -} -``` + // ... use conn ... + } + ``` ### **Core (C/C++)** -In gRPC Core, we utilize the existing `ChannelArgs` mechanism recursively to pass configuration to internal channels. Instead of introducing a new configuration class or interface, we define a standard argument key whose value is a pointer to another `grpc_channel_args` structure. This "Nested Arguments" pattern allows the parent channel to carry a specific subset of arguments intended solely for its children (e.g., xDS control plane connections). - -* #### 1\. Define the Configuration Mechanism +In gRPC Core, we utilize the existing `ChannelArgs` mechanism recursively to pass configuration to internal channels. We define a standard argument key whose value is a pointer to another `grpc_channel_args` structure. This "Nested Arguments" pattern allows the parent channel to carry a specific subset of arguments intended solely for its children. - * We define a new channel argument key. The value associated with this key is a pointer to a `grpc_channel_args` struct (or the C++ `ChannelArgs` wrapper), managed via a pointer vtable to ensure correct ownership and copying. +* #### 1\. Configuration Mechanism -```c -// A pointer argument key that internal components (like xDS) look for. -// The value is a pointer to a grpc_channel_args struct containing the subset -// of options (e.g., specific socket mutators, user agents) for child channels. -#define GRPC_ARG_CHILD_CHANNEL_ARGS "grpc.internal.child_channel_args" -``` + We define a new channel argument key. The value associated with this key is a pointer to a `grpc_channel_args` struct, managed via a pointer vtable to ensure correct ownership and copying. -#### + ```c + // A pointer argument key that internal components (like xDS) look for. + // The value is a pointer to a grpc_channel_args struct containing the subset + // of options (e.g., specific socket mutators, user agents) for child channels. + #define GRPC_ARG_CHILD_CHANNEL_ARGS "grpc.internal.child_channel_args" + ``` * #### 2\. Internal Implementation - * Internal components that create channels (specifically `XdsClient`) are updated to look for this argument. If present, these arguments are merged with the default arguments required by the component. - * **Extraction:** The component queries the parent's args for `GRPC_ARG_CHILD_CHANNEL_ARGS`. - * **Merge:** The extracted args are layered on top of the default internal args (e.g., bootstrap configuration). - * **Creation:** The combined arguments are passed to `grpc_channel_create`. - -* #### **3\. Usage Example (User-Side Code)** - - * A user configures the parent channel by creating a subset of arguments for the child, packing them into a standard `grpc_arg`, and passing them to the parent. - -```c -// 1. Prepare the Child Config (The Subset) -// Example: We want the internal control plane to use a specific Socket Mutator -grpc_socket_mutator* my_mutator = CreateMySocketMutator(); -grpc_arg child_arg = grpc_channel_arg_socket_mutator_create(my_mutator); -grpc_channel_args child_args_struct = {1, &child_arg}; - -// 2. Pack the Subset into the Parent's Arguments -// We use a helper (conceptually similar to grpc_channel_arg_pointer_create) -// to wrap the child_args_struct safely with a VTable for ownership. -grpc_arg parent_arg = grpc_channel_arg_pointer_create( - GRPC_ARG_CHILD_CHANNEL_ARGS, - &child_args_struct, - &grpc_channel_args_pointer_vtable // VTable handles copy/destroy of the struct -); - -// 3. Create the Parent Channel -grpc_channel_args parent_args = {1, &parent_arg}; -auto channel = grpc::CreateCustomChannel( - "xds:///my-service", - grpc::InsecureChannelCredentials(), - grpc::ChannelArguments::FromC(parent_args) -); - -// Result: The 'channel' (parent) does NOT use 'my_mutator'. -// However, when it creates the internal xDS channel, it extracts 'child_args_struct' -// and applies 'my_mutator' to that connection. -``` + Internal components that create channels (specifically `XdsClient`) are updated to look for this argument. When present, these arguments are merged with the default internal arguments required by the component. + +* #### 3\. Usage Example (User-Side Code) + + In this design, a user configures the parent channel by defining a subset of arguments intended for child channels, packing them into a standard `grpc_arg`, and passing them to the parent. This allows for granular control over internal components, such as the xDS control plane connection, without affecting the parent channel stack. + + ```c + // 1. Prepare the Child Config (The Subset) + // In this example, we configure a specific Socket Mutator for the child channel. + grpc_socket_mutator* my_mutator = CreateMySocketMutator(); + grpc_arg child_arg = grpc_channel_arg_socket_mutator_create(my_mutator); + grpc_channel_args child_args_struct = {1, &child_arg}; + + // 2. Pack the Subset into the Parent's Arguments + // The child_args_struct is wrapped as a pointer argument. + // We use a VTable to ensure the nested struct is safely copied or + // destroyed during the parent channel's lifetime. + grpc_arg parent_arg = grpc_channel_arg_pointer_create( + GRPC_ARG_CHILD_CHANNEL_ARGS, + &child_args_struct, + &grpc_channel_args_pointer_vtable + ); + + // 3. Create the Parent Channel + // The parent channel receives the nested argument but does not apply + // the socket mutator to itself. + grpc_channel_args parent_args = {1, &parent_arg}; + auto channel = grpc::CreateCustomChannel( + "xds:///my-service", + grpc::InsecureChannelCredentials(), + grpc::ChannelArguments::FromC(parent_args) + ); + + ``` ## **Rationale** ### **Why not Global Configuration?** -Global configuration (static variables) was rejected because it prevents multi-tenant applications from isolating configurations. For example, one GCS client might need to export metrics to Prometheus, while another in the same process exports to Cloud Monitoring. +We reject global configuration (static variables) because it prevents multi-tenant applications from isolating configurations. For example, one client may need to export metrics to Prometheus, while another in the same process exports to Cloud Monitoring. ### **Why Language-Specific Approaches?** -While the concept (configuring child channels) is cross-language, the mechanism for channel creation differs significantly: - -* **Java** relies heavily on the `Builder` pattern, making functional callbacks the most natural fit. -* **Go** uses functional options (`DialOption`), so passing a slice of options is idiomatic. -* **Core** uses a generic key-value map (`ChannelArgs`) for almost all configurations, maintaining consistency with the core C-core design. - -## **Open Issues** - -* Should there be distinct configurations for different(i.e. different target strings) child channels ? -* For xDS client pool the first since it only depends on the target string, any subsequent usage within the same process having the same target string will end up using the previously created client with possibly different configuration. +While the concept is cross-language, the mechanisms for channel creation differs significantly: -[image1]: \ No newline at end of file +* **Java** relies heavily on the `Builder` pattern, making functional callbacks the most natural fit. +* **Go** uses functional options (`DialOption`), so passing a slice of options is idiomatic. +* **Core** uses a generic key-value map (`ChannelArgs`), maintaining consistency with the core C-core design. \ No newline at end of file From 29bcc2a5726cb0b7d8bf4c1a9a17673b4a3c0638 Mon Sep 17 00:00:00 2001 From: AgraVator Date: Tue, 23 Dec 2025 14:26:45 +0530 Subject: [PATCH 3/5] use actual gRFC number --- A110-child-channel-plugins.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/A110-child-channel-plugins.md b/A110-child-channel-plugins.md index 2d934e6df..106cdf905 100644 --- a/A110-child-channel-plugins.md +++ b/A110-child-channel-plugins.md @@ -1,4 +1,4 @@ -# **gRFC AXX: Child Channel Configuration Plugins** +# **A110: Child Channel Configuration Plugins** * **Author(s)**: [Abhishek Agrawal](mailto:agrawalabhi@google.com) * **Status**: Draft From 82a4b0b7040af038645080ec95a38537fba43aac Mon Sep 17 00:00:00 2001 From: AgraVator Date: Mon, 29 Dec 2025 21:24:29 +0530 Subject: [PATCH 4/5] suggested changes --- A110-child-channel-plugins.md | 134 ++++++++++++++++++++++------------ 1 file changed, 86 insertions(+), 48 deletions(-) diff --git a/A110-child-channel-plugins.md b/A110-child-channel-plugins.md index 106cdf905..b54186b18 100644 --- a/A110-child-channel-plugins.md +++ b/A110-child-channel-plugins.md @@ -1,39 +1,75 @@ -# **A110: Child Channel Configuration Plugins** +# A110: Child Channel Options -* **Author(s)**: [Abhishek Agrawal](mailto:agrawalabhi@google.com) -* **Status**: Draft -* **To be implemented in**: Core, Java, Go -* **Last updated**: 2025-12-23 +* Author(s): [Abhishek Agrawal](mailto:agrawalabhi@google.com) +* Approver: a11r +* Status: In Review +* Implemented in: Core, Java, Go +* Last updated: 2025-12-24 +* Discussion at: [Mailing List Link TBD] -## **Abstract** +## Abstract -This proposal introduces a mechanism to configure "child channels"—channels created internally by gRPC components (such as xDS control plane channel). Currently, these internal channels cannot easily inherit configuration (like metric sinks and interceptors) from the user application without relying on global state. This design proposes a language-specific approach to injecting configuration: using `functional interfaces` in Java, `DialOptions` in Go, and `ChannelArgs` in Core. +This proposal introduces a mechanism to configure "child channels"—channels created internally by gRPC components (such as xDS control plane channel). Currently, these channels are often opaque to the user, making it difficult to inject necessary configurations for metrics, tracing etc from the user application without relying on global state. This design proposes an approach for users to pass configuration options to these internal channels. -## **Background** +## Background Complex gRPC ecosystems often require the creation of auxiliary channels that are not directly instantiated by the user application. Two primary examples are: -1. **xDS (Extensible Discovery Service)**: When a user creates a channel with an xDS target, the gRPC library internally creates a separate channel to communicate with the xDS control plane. Currently, users have limited ability to configure this internal control plane channel. -2. **Advanced Load Balancing (RLS, GrpcLB):** Policies like RLS (Route Lookup Service) and GrpcLB, as well as other high-level libraries built on top of gRPC, frequently create internal channels to communicate with look-aside load balancers or backends. +1. xDS (Extensible Discovery Service): When a user creates a channel with an xDS target, the gRPC library internally creates a separate channel to communicate with the xDS control plane. +2. External Authorization (ext_authz): As described in [gRFC A92](https://github.com/grpc/proposal/pull/481), the gRPC server or client may create an internal channel to contact an external authorization service. +3. External Processing (ext_proc): As described in [gRFC A93](https://github.com/grpc/proposal/pull/484), filters may create internal channels to call external processing servers. -### **The Problem** +### Related Proposals -There is currently no standardized way to configure behavior for these child channels. +* [A27: xDS-Based Global Load Balancing](https://github.com/grpc/proposal/blob/master/A27-xds-global-load-balancing.md) +* [A66: Otel Stats](https://github.com/grpc/proposal/blob/master/A66-otel-stats.md) +* [A72: OpenTelemetry Tracing](https://github.com/grpc/proposal/blob/master/A72-open-telemetry-tracing.md) +* [A92: xDS ExtAuthz Support](https://github.com/grpc/proposal/pull/481) +* [A93: xDS ExtProc Support](https://github.com/grpc/proposal/pull/484) -* **Metrics**: Users need to configure metric sinks so that telemetry from internal channels can be read and exported. -* **Interceptors**: Users may need to apply specific interceptors (e.g., for authentication, logging, or tracing) to internal traffic. -* **No Global State**: These configurations cannot be set globally (e.g., using static singletons) because different parts of an application may require different configurations, such as different metric backends or security credentials. +### The Problem -## **Proposal** +The primary motivation for this feature is the need to configure observability on a per-channel basis and propagate them to child channels. -The proposal creates a "plugin" or configuration injection style for internal channels. The implementation varies by language to match existing idioms, but the goal remains consistent: allow the user to pass a configuration object or function that the internal channel factory applies during creation. +* StatsPlugins & Tracing: Users need to configure metric sinks (as described in gRFC A66 and A72) so that telemetry from internal channels is correctly tagged and exported. +* Interceptors: Users may need to apply specific interceptors (e.g., for authentication, logging, or tracing) to internal traffic. -### **Java** +These configurations cannot be set globally because different parts of an application may require different configurations, such as different metric backends or security credentials. -In Java, the configuration will be achieved by accepting functions (callbacks). The API allows users to pass a `Consumer>` (or a similar functional interface). When an internal library (e.g., xDS, RLS, gRPCLB) creates a child channel, it applies this user-provided function to the builder before building the channel. +## Proposal +We introduce the concept of **Child Channel Options**. This is a configuration container attached to a parent channel that is strictly designated for use by its children. -* #### 1\. Configuration Interface +### Encapsulation +The user API must allow "nesting" of channel options. A user creating a Parent Channel `P` can provide a set of options `O_child`. +* `O_child` is opaque to `P`. `P` does not apply these options to itself. +* `O_child` is carried in `P`'s state, available for extraction by internal components. + +### Propagation +When an internal component (e.g., an xDS client factory or an auth filter) attached to `P` needs to create a Child Channel `C`: +1. It retrieves `O_child` from `P`. +2. It applies `O_child` to the configuration of `C`. + +### Precedence and Merging +The Child Channel `C` typically requires some internal configuration `O_internal` (e.g., specific target URIs, bootstrap credentials, or internal User-Agent strings). +* Merge Rule: `O_child` and `O_internal` are merged. +* Conflict Resolution: Mandatory internal settings (`O_internal`) generally take precedence over user-provided child options (`O_child`) to ensure correctness. However, additive options (like Interceptors, StatsPlugins, or Metric Sinks) are combined. + +### Shared Resources +Certain internal channels, specifically the **xDS Control Plane Client**, are often pooled and shared across multiple parent channels within a process based on the target URI (see [gRFC A27](https://github.com/grpc/proposal/blob/master/A27-xds-global-load-balancing.md)). + +If multiple Parent Channels (`P1`, `P2`) point to the same xDS target but provide *different* Child Channel Options (`O_child1`, `O_child2`): +* Behavior: The shared client is created using the options from the first parent channel that triggers its creation (e.g., `O_child1`). +* Subsequent Usage: When `P2` requests the client, it receives the existing shared client. `O_child2` is effectively ignored for that specific shared resource. + +### Language Implementations + +#### Java + +In Java, the configuration will be achieved by accepting functions (callbacks). The API allows users to pass a `Consumer>` (or a similar functional interface). When an internal library (e.g., xDS, gRPCLB) creates a child channel, it applies this user-provided function to the builder before building the channel. + + +* ##### Configuration Interface Use the standard `java.util.function.Consumer` and define a new public API interface, `ChildChannelConfigurer`, to encapsulate the configuration logic for auxiliary channels. @@ -48,41 +84,43 @@ In Java, the configuration will be achieved by accepting functions (callbacks). } ``` -* #### 2\. API Changes +* ##### API Changes + + * ManagedChannelBuilder: Add `ManagedChannelBuilder#childChannelConfigurer(ChildChannelConfigurer childChannelConfigurer)` to allow users to register this configurer, and `ManagedChannelBuilder#configureChannel(ManagedChannel parent)` to allow a new builder to inherit configuration from an existing parent channel. + * ServerBuilder: Add `ServerBuilder#childChannelConfigurer(ChildChannelConfigurer configurer)` to allow users to provide configuration for any internal channels created by the server (e.g., connections to external authorization or processing services). - Add `ManagedChannelBuilder#childChannelConfigurer()` to allow users to register this configurer, and `ManagedChannelBuilder#configureChannel(ManagedChannel parent)` to allow a new builder to inherit configuration (including the `ChildChannelConfigurer` and `MetricRecorder`) from an existing parent channel. -* #### 3\. Internal Implementation +* ##### Internal Implementation The implementation propagates these configurations when creating internal channels. It leverages `configureChannel()` to act as a fusion point, automatically applying the `ChildChannelConfigurer` and other parent properties to the new builder. The implementation follows the pattern for global configurators and calls `.accept()` as soon as the builder is available. -* #### 4\. Usage Example +* ##### Usage Example ```java - // 1. Define the configurer for internal child channels + // Define the configurer for internal child channels ChildChannelConfigurer myInternalConfig = (builder) -> { - // Apply interceptors or configuration to the child channel builder - builder.intercept(new MyAuthInterceptor()); - builder.maxInboundMessageSize(1024 * 1024); + InternalManagedChannelBuilder.addMetricSink(builder, sink); + InternalManagedChannelBuilder.interceptWithTarget( + builder, openTelemetryMetricsModule::getClientInterceptor); }; - // 2. Apply it to the parent channel + // Apply it to the parent channel ManagedChannel channel = ManagedChannelBuilder.forTarget("xds:///my-service") - .childChannelConfigurer(myInternalConfig) // <--- Configuration injected here - .build(); + .childChannelConfigurer(myInternalConfig) // <--- Configuration injected here + .build(); ``` -* #### 5\. Out-of-Band (OOB) Channels +* ##### Out-of-Band (OOB) Channels We do not propose applying child channel configurations to Out-of-Band (OOB) channels at this time. To maintain architectural flexibility and avoid breaking changes in the future, we will modify the implementation to use a `noOp()` MetricSink for OOB channels rather than inheriting the parent channel's sink. Furthermore, we acknowledge that certain configurations will not function out-of-the-box for `resolvingOobChannel` due to its specific initialization requirements. -### **Go** +#### Go -In Go, configuration for child channels is be achieved by passing a specific `DialOption` to the parent channel. This option encapsulates a slice of other a slice of *other* `DialOption`s that are applied exclusively to any internal child channels created by the parent. +In Go, configuration for child channels is be achieved by passing a specific `DialOption` to the parent channel. This option encapsulates a slice of *other* `DialOption`s that are applied exclusively to any internal child channels created by the parent. -* #### 1\. New API for Child Channel Options +* ##### New API for Child Channel Options We introduce a new function in the grpc package that returns a `DialOption` specifically for child channels. @@ -99,7 +137,7 @@ In Go, configuration for child channels is be achieved by passing a specific `Di } ``` -* #### 2\. Internal Mechanics +* ##### Internal Mechanics A new field is added to the internal `dialOptions` struct to hold these options. When the xDS client (or any internal component) dials the control plane, it merges its own required options with the user-provided child options. @@ -111,7 +149,7 @@ In Go, configuration for child channels is be achieved by passing a specific `Di } ``` -* #### 3\. Usage Example (User-Side Code) +* ##### Usage Example (User-Side Code) This design provides users with the flexibility to define independent configurations for parent and child channels within a single NewClient call. For example, a parent channel can be configured with transport security (mTLS) while the internal child channels (such as the xDS control plane connection) are configured with specific interceptors or a custom authority. @@ -148,11 +186,11 @@ In Go, configuration for child channels is be achieved by passing a specific `Di } ``` -### **Core (C/C++)** +##### Core (C/C++) In gRPC Core, we utilize the existing `ChannelArgs` mechanism recursively to pass configuration to internal channels. We define a standard argument key whose value is a pointer to another `grpc_channel_args` structure. This "Nested Arguments" pattern allows the parent channel to carry a specific subset of arguments intended solely for its children. -* #### 1\. Configuration Mechanism +* ##### Configuration Mechanism We define a new channel argument key. The value associated with this key is a pointer to a `grpc_channel_args` struct, managed via a pointer vtable to ensure correct ownership and copying. @@ -160,14 +198,14 @@ In gRPC Core, we utilize the existing `ChannelArgs` mechanism recursively to pas // A pointer argument key that internal components (like xDS) look for. // The value is a pointer to a grpc_channel_args struct containing the subset // of options (e.g., specific socket mutators, user agents) for child channels. - #define GRPC_ARG_CHILD_CHANNEL_ARGS "grpc.internal.child_channel_args" + #define GRPC_ARG_CHILD_CHANNEL_ARGS "grpc.child_channel_args" ``` -* #### 2\. Internal Implementation +* ##### Internal Implementation Internal components that create channels (specifically `XdsClient`) are updated to look for this argument. When present, these arguments are merged with the default internal arguments required by the component. -* #### 3\. Usage Example (User-Side Code) +* ##### Usage Example (User-Side Code) In this design, a user configures the parent channel by defining a subset of arguments intended for child channels, packing them into a standard `grpc_arg`, and passing them to the parent. This allows for granular control over internal components, such as the xDS control plane connection, without affecting the parent channel stack. @@ -200,16 +238,16 @@ In gRPC Core, we utilize the existing `ChannelArgs` mechanism recursively to pas ``` -## **Rationale** +## Rationale -### **Why not Global Configuration?** +### Why not Global Configuration? We reject global configuration (static variables) because it prevents multi-tenant applications from isolating configurations. For example, one client may need to export metrics to Prometheus, while another in the same process exports to Cloud Monitoring. -### **Why Language-Specific Approaches?** +### Why Language-Specific Approaches? While the concept is cross-language, the mechanisms for channel creation differs significantly: -* **Java** relies heavily on the `Builder` pattern, making functional callbacks the most natural fit. -* **Go** uses functional options (`DialOption`), so passing a slice of options is idiomatic. -* **Core** uses a generic key-value map (`ChannelArgs`), maintaining consistency with the core C-core design. \ No newline at end of file +* Java relies heavily on the `Builder` pattern, making functional callbacks the most natural fit. +* Go uses functional options (`DialOption`), so passing a slice of options is idiomatic. +* Core uses a generic key-value map (`ChannelArgs`), maintaining consistency with the core C-core design. \ No newline at end of file From 2038e4358580400ad041e6c43ffc327db8e6078e Mon Sep 17 00:00:00 2001 From: AgraVator Date: Mon, 29 Dec 2025 21:25:55 +0530 Subject: [PATCH 5/5] suggested changes --- A110-child-channel-plugins.md | 144 +++++++++++++--------------------- 1 file changed, 54 insertions(+), 90 deletions(-) diff --git a/A110-child-channel-plugins.md b/A110-child-channel-plugins.md index b54186b18..aad38634c 100644 --- a/A110-child-channel-plugins.md +++ b/A110-child-channel-plugins.md @@ -9,7 +9,7 @@ ## Abstract -This proposal introduces a mechanism to configure "child channels"—channels created internally by gRPC components (such as xDS control plane channel). Currently, these channels are often opaque to the user, making it difficult to inject necessary configurations for metrics, tracing etc from the user application without relying on global state. This design proposes an approach for users to pass configuration options to these internal channels. +This proposal introduces a mechanism to configure "child channels", channels created internally by gRPC components (such as xDS control plane channel). Currently, these channels are often opaque to the user, making it difficult to inject necessary configurations for metrics, tracing etc from the user application. This design proposes an approach for users to pass configuration options to these internal channels. ## Background @@ -29,9 +29,9 @@ Complex gRPC ecosystems often require the creation of auxiliary channels that ar ### The Problem -The primary motivation for this feature is the need to configure observability on a per-channel basis and propagate them to child channels. +The primary motivation for this feature is the need to configure observability on a per-child-channel basis. -* StatsPlugins & Tracing: Users need to configure metric sinks (as described in gRFC A66 and A72) so that telemetry from internal channels is correctly tagged and exported. +* StatsPlugins & Tracing: Users need to configure metric sinks (as described in gRFC [A66](https://github.com/grpc/proposal/blob/master/A66-otel-stats.md) and [A72](https://github.com/grpc/proposal/blob/master/A72-open-telemetry-tracing.md)) so that telemetry from internal channels is correctly tagged and exported. * Interceptors: Users may need to apply specific interceptors (e.g., for authentication, logging, or tracing) to internal traffic. These configurations cannot be set globally because different parts of an application may require different configurations, such as different metric backends or security credentials. @@ -53,7 +53,7 @@ When an internal component (e.g., an xDS client factory or an auth filter) attac ### Precedence and Merging The Child Channel `C` typically requires some internal configuration `O_internal` (e.g., specific target URIs, bootstrap credentials, or internal User-Agent strings). * Merge Rule: `O_child` and `O_internal` are merged. -* Conflict Resolution: Mandatory internal settings (`O_internal`) generally take precedence over user-provided child options (`O_child`) to ensure correctness. However, additive options (like Interceptors, StatsPlugins, or Metric Sinks) are combined. +* Conflict Resolution: Mandatory internal settings (`O_internal`) generally take precedence over user-provided child options (`O_child`) to ensure correctness. ### Shared Resources Certain internal channels, specifically the **xDS Control Plane Client**, are often pooled and shared across multiple parent channels within a process based on the target URI (see [gRFC A27](https://github.com/grpc/proposal/blob/master/A27-xds-global-load-balancing.md)). @@ -68,7 +68,6 @@ If multiple Parent Channels (`P1`, `P2`) point to the same xDS target but provid In Java, the configuration will be achieved by accepting functions (callbacks). The API allows users to pass a `Consumer>` (or a similar functional interface). When an internal library (e.g., xDS, gRPCLB) creates a child channel, it applies this user-provided function to the builder before building the channel. - * ##### Configuration Interface Use the standard `java.util.function.Consumer` and define a new public API interface, `ChildChannelConfigurer`, to encapsulate the configuration logic for auxiliary channels. @@ -86,22 +85,15 @@ In Java, the configuration will be achieved by accepting functions (callbacks). * ##### API Changes - * ManagedChannelBuilder: Add `ManagedChannelBuilder#childChannelConfigurer(ChildChannelConfigurer childChannelConfigurer)` to allow users to register this configurer, and `ManagedChannelBuilder#configureChannel(ManagedChannel parent)` to allow a new builder to inherit configuration from an existing parent channel. + * ManagedChannelBuilder: Add `ManagedChannelBuilder#childChannelConfigurer(ChildChannelConfigurer childChannelConfigurer)` to allow users to register this configurer. * ServerBuilder: Add `ServerBuilder#childChannelConfigurer(ChildChannelConfigurer configurer)` to allow users to provide configuration for any internal channels created by the server (e.g., connections to external authorization or processing services). - -* ##### Internal Implementation - - The implementation propagates these configurations when creating internal channels. It leverages `configureChannel()` to act as a fusion point, automatically applying the `ChildChannelConfigurer` and other parent properties to the new builder. The implementation follows the pattern for global configurators and calls `.accept()` as soon as the builder is available. - * ##### Usage Example ```java // Define the configurer for internal child channels ChildChannelConfigurer myInternalConfig = (builder) -> { - InternalManagedChannelBuilder.addMetricSink(builder, sink); - InternalManagedChannelBuilder.interceptWithTarget( - builder, openTelemetryMetricsModule::getClientInterceptor); + builder.addMetricSink(sink); }; // Apply it to the parent channel @@ -118,62 +110,59 @@ In Java, the configuration will be achieved by accepting functions (callbacks). #### Go -In Go, configuration for child channels is be achieved by passing a specific `DialOption` to the parent channel. This option encapsulates a slice of *other* `DialOption`s that are applied exclusively to any internal child channels created by the parent. +In Go, both the Client (`grpc.NewClient`) and the Server (`NewGRPCServer`) create internal child channels. We introduce mechanisms to pass `DialOption`s into these internal channels from both entry points. * ##### New API for Child Channel Options - We introduce a new function in the grpc package that returns a `DialOption` specifically for child channels. +* Client-Side: `WithChildChannelOptions` - ```go - // WithChildChannelOptions returns a DialOption that specifies a list of options - // to be applied to any internal child channels (e.g., xDS control plane channels) - // created by this ClientConn. - // - // These options are NOT applied to the ClientConn returned by NewClient. - func WithChildChannelOptions(opts ...DialOption) DialOption { - return newFuncDialOption(func(o *dialOptions) { - o.childChannelOptions = opts - }) - } - ``` + For standard clients, we introduce a `DialOption` wrapper. -* ##### Internal Mechanics + ```go + // WithChildChannelOptions returns a DialOption that specifies a list of + // DialOptions to be applied to any internal child channels. + func WithChildChannelOptions(opts ...DialOption) DialOption { + return newFuncDialOption(func(o *dialOptions) { + o.childChannelOptions = opts + }) + } + ``` - A new field is added to the internal `dialOptions` struct to hold these options. When the xDS client (or any internal component) dials the control plane, it merges its own required options with the user-provided child options. +* Server-Side: `WithChildDialOptions` - ```go - type dialOptions struct { - // ... existing fields ... - // childChannelOptions holds options intended for internal child channels. - childChannelOptions []DialOption - } - ``` + For xDS-enabled servers, we introduce a `ServerOption` wrapper. Since `xds.NewGRPCServer` creates an internal xDS client to fetch listener configurations, it requires a way to apply `DialOptions` (such as **Socket Options** or **Stats Handlers**) to that internal connection. + + ```go + // WithChildDialOptions returns a ServerOption that specifies a list of + // DialOptions to be applied to the server's internal child channels + // (e.g., the xDS control plane connection). + func WithChildDialOptions(opts ...DialOption) ServerOption { + return newFuncServerOption(func(o *serverOptions) { + o.childDialOptions = opts + }) + } + ``` * ##### Usage Example (User-Side Code) This design provides users with the flexibility to define independent configurations for parent and child channels within a single NewClient call. For example, a parent channel can be configured with transport security (mTLS) while the internal child channels (such as the xDS control plane connection) are configured with specific interceptors or a custom authority. ```go - import ( - "google.golang.org/grpc" - "google.golang.org/grpc/credentials/insecure" - ) - func main() { - // 1. Define configuration specifically for the internal control plane - // (e.g., a specific metrics interceptor or custom authority) + // Define configuration specifically for the internal control plane internalOpts := []grpc.DialOption{ - grpc.WithUnaryInterceptor(MyMonitoringInterceptor), - grpc.WithAuthority("xds-authority.example.com"), + // Inject the OTel handler here. It will only measure traffic on the + // internal child channels (e.g., to the xDS server). + grpc.WithStatsHandler(otelHandler) } - // 2. Create the Parent Channel - // Pass the internal options using the WithChildChannelOptions wrapper. + // Create the Parent Channel conn, err := grpc.NewClient("xds:///my-service", - // Parent channel configuration + // Parent channel configuration (Data Plane) grpc.WithTransportCredentials(insecure.NewCredentials()), - // Child channel configuration (injected here) + // Child channel configuration (Control Plane) + // The OTel handler inside here applies ONLY to the child channels. grpc.WithChildChannelOptions(internalOpts...), ) @@ -195,47 +184,24 @@ In gRPC Core, we utilize the existing `ChannelArgs` mechanism recursively to pas We define a new channel argument key. The value associated with this key is a pointer to a `grpc_channel_args` struct, managed via a pointer vtable to ensure correct ownership and copying. ```c - // A pointer argument key that internal components (like xDS) look for. - // The value is a pointer to a grpc_channel_args struct containing the subset - // of options (e.g., specific socket mutators, user agents) for child channels. - #define GRPC_ARG_CHILD_CHANNEL_ARGS "grpc.child_channel_args" + // A pointer argument key. The value is a pointer to a grpc_channel_args + // struct containing the subset of options for child channels. + #define GRPC_ARG_CHILD_CHANNEL_ARGS "grpc.child_channel.args" ``` -* ##### Internal Implementation +* **API Changes** - Internal components that create channels (specifically `XdsClient`) are updated to look for this argument. When present, these arguments are merged with the default internal arguments required by the component. + We add a helper method to the C++ `ChannelArguments` class to simplify packing the nested arguments safely. -* ##### Usage Example (User-Side Code) + ```cpp + // Sets the channel arguments to be used for child channels. + void SetChildChannelArgs(const ChannelArguments& args); + ``` - In this design, a user configures the parent channel by defining a subset of arguments intended for child channels, packing them into a standard `grpc_arg`, and passing them to the parent. This allows for granular control over internal components, such as the xDS control plane connection, without affecting the parent channel stack. +* ##### Usage Example (User-Side Code) ```c - // 1. Prepare the Child Config (The Subset) - // In this example, we configure a specific Socket Mutator for the child channel. - grpc_socket_mutator* my_mutator = CreateMySocketMutator(); - grpc_arg child_arg = grpc_channel_arg_socket_mutator_create(my_mutator); - grpc_channel_args child_args_struct = {1, &child_arg}; - - // 2. Pack the Subset into the Parent's Arguments - // The child_args_struct is wrapped as a pointer argument. - // We use a VTable to ensure the nested struct is safely copied or - // destroyed during the parent channel's lifetime. - grpc_arg parent_arg = grpc_channel_arg_pointer_create( - GRPC_ARG_CHILD_CHANNEL_ARGS, - &child_args_struct, - &grpc_channel_args_pointer_vtable - ); - - // 3. Create the Parent Channel - // The parent channel receives the nested argument but does not apply - // the socket mutator to itself. - grpc_channel_args parent_args = {1, &parent_arg}; - auto channel = grpc::CreateCustomChannel( - "xds:///my-service", - grpc::InsecureChannelCredentials(), - grpc::ChannelArguments::FromC(parent_args) - ); - + // TODO(AgraVator): add example for configuring child channel observability ``` ## Rationale @@ -244,10 +210,8 @@ In gRPC Core, we utilize the existing `ChannelArgs` mechanism recursively to pas We reject global configuration (static variables) because it prevents multi-tenant applications from isolating configurations. For example, one client may need to export metrics to Prometheus, while another in the same process exports to Cloud Monitoring. -### Why Language-Specific Approaches? - -While the concept is cross-language, the mechanisms for channel creation differs significantly: +## Implementation -* Java relies heavily on the `Builder` pattern, making functional callbacks the most natural fit. -* Go uses functional options (`DialOption`), so passing a slice of options is idiomatic. -* Core uses a generic key-value map (`ChannelArgs`), maintaining consistency with the core C-core design. \ No newline at end of file +@AgraVator will be implementing immediately in grpc-java. A draft is available in +[PR 12578](https://github.com/grpc/grpc-java/pull/12578). Other languages will +follow, with work starting potentially in a few weeks.