enable child channel plugins

api/src/main/java/io/grpc/ChannelConfigurator.java

@@ -0,0 +1,63 @@
+/*
+ * Copyright 2026 The gRPC Authors
+ *
+ * Licensed 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.
+ */
+
+package io.grpc;
+
+
+
+/**
+ * A configurator for child channels created by gRPC's internal infrastructure.
+ *
+ * <p>This interface allows users to inject configuration (such as credentials, interceptors,
+ * or flow control settings) into channels created automatically by gRPC for control plane
+ * operations. Common use cases include:
+ * <ul>
+ * <li>xDS control plane connections</li>
+ * <li>Load Balancing helper channels (OOB channels)</li>
+ * </ul>
+ *
+ * <p><strong>Usage Example:</strong>
+ * <pre>{@code
+ * // 1. Define the configurator
+ * ChannelConfigurator configurator = builder -> {
+ *   builder.maxInboundMessageSize(4 * 1024 * 1024);
+ * };
+ *
+ * // 2. Apply to parent channel - automatically used for ALL child channels
+ * ManagedChannel channel = ManagedChannelBuilder
+ *     .forTarget("xds:///my-service")
+ *     .childChannelConfigurator(configurator)
+ *     .build();
+ * }</pre>
+ *
+ * <p>Implementations must be thread-safe as the configure methods may be invoked concurrently
+ * by multiple internal components.
+ *
+ * @since 1.81.0
+ */
+@ExperimentalApi("https://github.com/grpc/grpc-java/issues/12574")
+public interface ChannelConfigurator {
+
+  /**
+   * Configures a builder for a new child channel.
+   *
+   * <p>This method is invoked synchronously during the creation of the child channel,
+   * before {@link ManagedChannelBuilder#build()} is called.
+   *
+   * @param builder the mutable channel builder for the new child channel
+   */
+  default void configureChannelBuilder(ManagedChannelBuilder<?> builder) {}
+}

api/src/main/java/io/grpc/ForwardingChannelBuilder.java

@@ -242,6 +242,13 @@ public T disableServiceConfigLookUp() {
     return thisT();
   }
 
+
+  @Override
+  public T childChannelConfigurator(ChannelConfigurator channelConfigurator) {
+    delegate().childChannelConfigurator(channelConfigurator);
+    return thisT();
+  }
+
   /**
    * Returns the correctly typed version of the builder.
    */

api/src/main/java/io/grpc/ForwardingChannelBuilder2.java

@@ -258,7 +258,7 @@ public T disableServiceConfigLookUp() {
   }
 
   @Override
-  protected T addMetricSink(MetricSink metricSink) {
+  public T addMetricSink(MetricSink metricSink) {
     delegate().addMetricSink(metricSink);
     return thisT();
   }
@@ -269,6 +269,13 @@ public <X> T setNameResolverArg(NameResolver.Args.Key<X> key, X value) {
     return thisT();
   }
 
+
+  @Override
+  public T childChannelConfigurator(ChannelConfigurator channelConfigurator) {
+    delegate().childChannelConfigurator(channelConfigurator);
+    return thisT();
+  }
+
   /**
    * Returns the {@link ManagedChannel} built by the delegate by default. Overriding method can
    * return different value.

api/src/main/java/io/grpc/ForwardingServerBuilder.java

@@ -192,6 +192,12 @@ public T setBinaryLog(BinaryLog binaryLog) {
     return thisT();
   }
 
+  @Override
+  public T childChannelConfigurator(ChannelConfigurator channelConfigurator) {
+    delegate().childChannelConfigurator(channelConfigurator);
+    return thisT();
+  }
+
   /**
    * Returns the {@link Server} built by the delegate by default. Overriding method can return
    * different value.

api/src/main/java/io/grpc/ManagedChannelBuilder.java

@@ -168,8 +168,6 @@ protected T interceptWithTarget(InterceptorFactory factory) {
     throw new UnsupportedOperationException();
   }
 
-  /** Internal-only. */
-  @Internal
   protected interface InterceptorFactory {
     ClientInterceptor newInterceptor(String target);
   }
@@ -638,8 +636,7 @@ public T disableServiceConfigLookUp() {
    * @return this
    * @since 1.64.0
    */
-  @Internal
-  protected T addMetricSink(MetricSink metricSink) {
+  public T addMetricSink(MetricSink metricSink) {
     throw new UnsupportedOperationException();
   }
 
@@ -661,6 +658,23 @@ public <X> T setNameResolverArg(NameResolver.Args.Key<X> key, X value) {
     throw new UnsupportedOperationException();
   }
 
+
+  /**
+   * Sets a configurator that will be applied to all internal child channels created by this
+   * channel.
+   *
+   * <p>This allows injecting configuration (like credentials, interceptors, or flow control)
+   * into auxiliary channels created by gRPC infrastructure, such as xDS control plane connections.
+   *
+   * @param channelConfigurator the configurator to apply.
+   * @return this
+   * @since 1.81.0
+   */
+  @ExperimentalApi("https://github.com/grpc/grpc-java/issues/12574")
+  public T childChannelConfigurator(ChannelConfigurator channelConfigurator) {
+    throw new UnsupportedOperationException("Not implemented");
+  }
+
   /**
    * Builds a channel using the given parameters.
    *

api/src/main/java/io/grpc/NameResolver.java

@@ -358,6 +358,7 @@ public static final class Args {
     private final MetricRecorder metricRecorder;
     @Nullable private final NameResolverRegistry nameResolverRegistry;
     @Nullable private final IdentityHashMap<Key<?>, Object> customArgs;
+    @Nullable private final ChannelConfigurator channelConfigurator;
 
     private Args(Builder builder) {
       this.defaultPort = checkNotNull(builder.defaultPort, "defaultPort not set");
@@ -373,6 +374,7 @@ private Args(Builder builder) {
           : new MetricRecorder() {};
       this.nameResolverRegistry = builder.nameResolverRegistry;
       this.customArgs = cloneCustomArgs(builder.customArgs);
+      this.channelConfigurator = builder.channelConfigurator;
     }
 
     /**
@@ -471,6 +473,17 @@ public ChannelLogger getChannelLogger() {
       return channelLogger;
     }
 
+    /**
+     * Returns the configurator for child channels.
+     *
+     * @since 1.81.0
+     */
+    @Nullable
+    @Internal
+    public ChannelConfigurator getChildChannelConfigurator() {
+      return channelConfigurator;
+    }
+
     /**
      * Returns the Executor on which this resolver should execute long-running or I/O bound work.
      * Null if no Executor was set.
@@ -579,6 +592,7 @@ public static final class Builder {
       private MetricRecorder metricRecorder;
       private NameResolverRegistry nameResolverRegistry;
       private IdentityHashMap<Key<?>, Object> customArgs;
+      private ChannelConfigurator channelConfigurator = new ChannelConfigurator() {};
 
       Builder() {
       }
@@ -694,6 +708,16 @@ public Builder setNameResolverRegistry(NameResolverRegistry registry) {
         return this;
       }
 
+      /**
+       * See {@link Args#getChildChannelConfigurator()}. This is an optional field.
+       *
+       * @since 1.81.0
+       */
+      public Builder setChildChannelConfigurator(ChannelConfigurator channelConfigurator) {
+        this.channelConfigurator = channelConfigurator;
+        return this;
+      }
+
       /**
        * Builds an {@link Args}.
        *

api/src/main/java/io/grpc/ServerBuilder.java

@@ -424,6 +424,24 @@ public T setBinaryLog(BinaryLog binaryLog) {
     throw new UnsupportedOperationException();
   }
 
+
+  /**
+   * Sets a configurator that will be applied to all internal child channels created by this server.
+   *
+   * <p>This allows injecting configuration (like credentials, interceptors, or flow control)
+   * into auxiliary channels created by gRPC infrastructure, such as xDS control plane connections
+   * or OOB load balancing channels.
+   *
+   * @param channelConfigurator the configurator to apply.
+   * @return this
+   * @since 1.81.0
+   */
+  @ExperimentalApi("https://github.com/grpc/grpc-java/issues/12574")
+  public T childChannelConfigurator(ChannelConfigurator channelConfigurator) {
+    throw new UnsupportedOperationException("Not implemented");
+  }
+
+
   /**
    * Builds a server using the given parameters.
    *

api/src/test/java/io/grpc/ChannelConfiguratorTest.java

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2026 The gRPC Authors
+ *
+ * Licensed 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.
+ */
+
+package io.grpc;
+
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verifyNoInteractions;
+
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+@RunWith(JUnit4.class)
+public class ChannelConfiguratorTest {
+
+  @Test
+  public void defaultMethods_doNothing() {
+    ChannelConfigurator configurator = new ChannelConfigurator() {};
+
+    ManagedChannelBuilder<?> mockChannelBuilder = mock(ManagedChannelBuilder.class);
+    configurator.configureChannelBuilder(mockChannelBuilder);
+    verifyNoInteractions(mockChannelBuilder);
+  }
+}

api/src/test/java/io/grpc/NameResolverTest.java

@@ -105,6 +105,7 @@ public void args() {
   }
 
   private NameResolver.Args createArgs() {
+    ChannelConfigurator channelConfigurator = new ChannelConfigurator() {};
     return NameResolver.Args.newBuilder()
         .setDefaultPort(defaultPort)
         .setProxyDetector(proxyDetector)
@@ -116,9 +117,46 @@ private NameResolver.Args createArgs() {
         .setOverrideAuthority(overrideAuthority)
         .setMetricRecorder(metricRecorder)
         .setArg(FOO_ARG_KEY, customArgValue)
+        .setChildChannelConfigurator(channelConfigurator)
         .build();
   }
 
+  @Test
+  public void args_childChannelConfigurator() {
+    final ManagedChannelBuilder<?>[] capturedBuilder = new ManagedChannelBuilder<?>[1];
+    ChannelConfigurator channelConfigurator = new ChannelConfigurator() {
+      @Override
+      public void configureChannelBuilder(ManagedChannelBuilder<?> builder) {
+        capturedBuilder[0] = builder;
+      }
+    };
+
+    SynchronizationContext realSyncContext = new SynchronizationContext(
+        new Thread.UncaughtExceptionHandler() {
+          @Override
+          public void uncaughtException(Thread t, Throwable e) {
+            throw new AssertionError(e);
+          }
+        });
+
+    NameResolver.Args args = NameResolver.Args.newBuilder()
+        .setDefaultPort(8080)
+        .setProxyDetector(mock(ProxyDetector.class))
+        .setSynchronizationContext(realSyncContext)
+        .setServiceConfigParser(mock(NameResolver.ServiceConfigParser.class))
+        .setChannelLogger(mock(ChannelLogger.class))
+        .setChildChannelConfigurator(channelConfigurator)
+        .build();
+
+    ChannelConfigurator configurator = args.getChildChannelConfigurator();
+    assertThat(configurator).isSameInstanceAs(channelConfigurator);
+
+    // Validate configurator accepts builders
+    ManagedChannelBuilder<?> mockBuilder = mock(ManagedChannelBuilder.class);
+    configurator.configureChannelBuilder(mockBuilder);
+    assertThat(capturedBuilder[0]).isSameInstanceAs(mockBuilder);
+  }
+
   @Test
   @SuppressWarnings("deprecation")
   public void startOnOldListener_wrapperListener2UsedToStart() {

core/src/main/java/io/grpc/internal/ManagedChannelImpl.java

@@ -37,6 +37,7 @@
 import io.grpc.CallCredentials;
 import io.grpc.CallOptions;
 import io.grpc.Channel;
+import io.grpc.ChannelConfigurator;
 import io.grpc.ChannelCredentials;
 import io.grpc.ChannelLogger;
 import io.grpc.ChannelLogger.ChannelLogLevel;
@@ -155,6 +156,14 @@ public Result selectConfig(PickSubchannelArgs args) {
   private static final LoadBalancer.PickDetailsConsumer NOOP_PICK_DETAILS_CONSUMER =
       new LoadBalancer.PickDetailsConsumer() {};
 
+  /**
+   * Retrieves the user-provided configuration function for internal child channels.
+   *
+   * <p>This is intended for use by gRPC internal components
+   * that are responsible for creating auxiliary {@code ManagedChannel} instances.
+   */
+  private ChannelConfigurator channelConfigurator = new ChannelConfigurator() {};
+
   private final InternalLogId logId;
   private final String target;
   @Nullable
@@ -545,6 +554,9 @@ ClientStream newSubstream(
       Supplier<Stopwatch> stopwatchSupplier,
       List<ClientInterceptor> interceptors,
       final TimeProvider timeProvider) {
+    if (builder.channelConfigurator != null) {
+      this.channelConfigurator = builder.channelConfigurator;
+    }
     this.target = checkNotNull(builder.target, "target");
     this.logId = InternalLogId.allocate("Channel", target);
     this.timeProvider = checkNotNull(timeProvider, "timeProvider");
@@ -589,7 +601,8 @@ ClientStream newSubstream(
             .setOffloadExecutor(this.offloadExecutorHolder)
             .setOverrideAuthority(this.authorityOverride)
             .setMetricRecorder(this.metricRecorder)
-            .setNameResolverRegistry(builder.nameResolverRegistry);
+            .setNameResolverRegistry(builder.nameResolverRegistry)
+            .setChildChannelConfigurator(this.channelConfigurator);
     builder.copyAllNameResolverCustomArgsTo(nameResolverArgsBuilder);
     this.nameResolverArgs = nameResolverArgsBuilder.build();
     this.nameResolver = getNameResolver(
@@ -1486,6 +1499,12 @@ protected ManagedChannelBuilder<?> delegate() {
 
       ResolvingOobChannelBuilder builder = new ResolvingOobChannelBuilder();
 
+      // Note that we follow the global configurator pattern and try to fuse the configurations as
+      // soon as the builder gets created
+      if (channelConfigurator != null) {
+        channelConfigurator.configureChannelBuilder(builder);
+      }
+
       return builder
           // TODO(zdapeng): executors should not outlive the parent channel.
           .executor(executor)