async-service-supervisor-envoy 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8cc76c3df4e361de12ad49143c31e5faca1228296ae3e0ca3eb698e5b7b97d16
-  data.tar.gz: 941d1d35f6780ec586f57ee50c31228d12c325c9675a5a2d75c5bc6d455652f5
+  metadata.gz: e8bbbdeea238ea31ad9ff156f47a43d168b52965e1cc0e54f972ccb2a994cfaa
+  data.tar.gz: e07f1e1ba197e0c7b4a629072dc8177a371d9f31189f4f6c8e03bf4899fd93c5
 SHA512:
-  metadata.gz: e45791d7ab2c2e3dbfd3ca22adf5f1df7dbd4bcc25a2e4a9c9cd9ec923e4bcc5d0817c7753d3ed756b175beb6e014be279e9663ffef75bc53b608e6908adfba8
-  data.tar.gz: 0b2dd096da3c2535f7de470b2d1f2bcb4674f33f05035936ce878a76137bc4a9872e95617bc57e2ea3793de19c55e1a966067bcef78fb251766dc27dc17f4c4b
+  metadata.gz: de6300d313bc18e8002defade3348a29216571401b6aba6effa3d4a9c2389704765014f395a3e0f4121fa8ae7e2e254dd0049b93fecd779838601444bd2f0d60
+  data.tar.gz: 4d36bd1ceb4d691e15b02042a3c0d214a656a170fd518585d5a266338011381a8eef97956a0bc9caecc9a6e3d02595e92411381294934628f835bbad256a5d6f

data/context/getting-started.md

@@ -1,6 +1,6 @@
 # Getting Started
 
-This guide explains how to use `async-service-supervisor-envoy` to publish supervised worker endpoints to Envoy using xDS.
+This guide explains how to use `async-service-supervisor-envoy` to publish supervised worker clusters and endpoints to Envoy using xDS.
 
 ## Installation
 
@@ -16,10 +16,12 @@ The gem depends on `async-service-supervisor` and `async-grpc-xds`.
 
 `async-service-supervisor-envoy` provides:
 
-  - {ruby Async::Service::Supervisor::Envoy::Monitor} - A supervisor monitor that publishes worker endpoints through xDS.
+  - {ruby Async::Service::Supervisor::Envoy::Monitor} - A supervisor monitor that publishes worker clusters through CDS and their endpoints through EDS.
   - {ruby Async::Service::Supervisor::Envoy::Endpoint} - A small value object for endpoint state.
 
-The monitor runs an xDS control plane endpoint. Envoy connects to it using ADS and receives CDS/EDS updates derived from supervisor worker state.
+The monitor always serves a dedicated Endpoint Discovery Service stream. By default it also serves Cluster Discovery Service. It does not claim Envoy's Aggregated Discovery Service, so another control plane can use ADS for listeners, routes, and other configuration.
+
+CDS describes the logical services exposed by supervised workers, including their supported protocol, active health checks, and load-balancing policy. EDS supplies the concrete workers currently available for each service.
 
 ## Endpoint State
 
@@ -62,11 +64,59 @@ Add the monitor to your supervisor environment:
 require "async/service/supervisor/envoy"
 
 Async::Service::Supervisor::Envoy::Monitor.new(
-	bind: "http://127.0.0.1:18000"
+	bind: "http://127.0.0.1:18000",
+	management_cluster: "xds_cluster"
 )
 ```
 
-By default, workers are grouped into clusters by `state[:name]`.
+By default, workers are grouped into clusters by `state[:name]`. When cluster publication is enabled, `management_cluster` must match the static Envoy cluster used to reach the monitor.
+
+If another control plane owns cluster configuration, disable CDS publication while retaining supervisor-owned endpoint discovery:
+
+``` ruby
+Async::Service::Supervisor::Envoy::Monitor.new(
+	bind: "http://127.0.0.1:18000",
+	publish_clusters: false
+)
+```
+
+In this mode, the external control plane or bootstrap configuration must define each cluster, configure it to use the monitor's dedicated EDS service, and supply its protocol, health checks, and load-balancing policy. The cluster's EDS service name must match the worker cluster name published by the monitor.
+
+## Envoy Configuration
+
+Configure Envoy to obtain clusters from the monitor's dedicated CDS service. The monitor configures each discovered cluster to obtain its endpoints from the dedicated EDS service on the same management server:
+
+``` yaml
+dynamic_resources:
+  cds_config:
+    resource_api_version: V3
+    api_config_source:
+      api_type: GRPC
+      transport_api_version: V3
+      grpc_services:
+        - envoy_grpc:
+            cluster_name: xds_cluster
+
+static_resources:
+  clusters:
+    - name: xds_cluster
+      connect_timeout: 1s
+      type: STRICT_DNS
+      http2_protocol_options: {}
+      load_assignment:
+        cluster_name: xds_cluster
+        endpoints:
+          - lb_endpoints:
+              - endpoint:
+                  address:
+                    socket_address:
+                      address: 127.0.0.1
+                      port_value: 18000
+```
+
+The bootstrap cluster name must match the monitor's `management_cluster`. Envoy uses it for independent CDS and EDS gRPC streams; no `ads_config` is required.
+
+If a static route refers to a cluster delivered by CDS, set `validate_clusters: false` on that route configuration. Envoy can then load the route before the cluster arrives and will begin routing once CDS and EDS have warmed it.
 
 ## Custom Mapping
 
@@ -113,10 +163,14 @@ utilization_monitor = Async::Service::Supervisor::UtilizationMonitor.new(interva
 ]
 ```
 
-The supervisor utilization monitor manages each worker's shared-memory allocation and registration. The Envoy monitor samples it through `sample_by_worker`, combines each worker's `requests_total` counter with processor usage from `process-metrics`, and serves the resulting ORCA reports from the same HTTP/2 endpoint as ADS. It also configures each discovered cluster to use Envoy's client-side weighted-round-robin policy.
+The supervisor utilization monitor manages each worker's shared-memory allocation and registration. The Envoy monitor samples it through `sample_by_worker`, combines each worker's `requests_total` counter with processor usage from `process-metrics`, and serves the resulting ORCA reports from the same HTTP/2 endpoint as CDS and EDS. It also configures each discovered cluster to use Envoy's client-side weighted-round-robin policy.
 
 The first sample establishes a baseline. Subsequent reports contain normalized `cpu_utilization` and `rps_fractional` values for each worker. Reports are removed immediately when a worker disconnects.
 
+Workers are identified by the `hostname` published with each endpoint, which Envoy sends as the request authority when it opens an out-of-band reporting stream. Enabling ORCA therefore publishes one endpoint per worker rather than one per shared listener.
+
+The generated load-balancing policy uses the monitor's bind port and reporting interval. Envoy dials that port on each endpoint's own address, which reaches the monitor because it shares a network namespace with the workers.
+
 Out-of-band ORCA requires:
 
   - Envoy 1.39 or later.

data/context/index.yaml

@@ -9,4 +9,4 @@ files:
 - path: getting-started.md
   title: Getting Started
   description: This guide explains how to use `async-service-supervisor-envoy` to
-    publish supervised worker endpoints to Envoy using xDS.
+    publish supervised worker clusters and endpoints to Envoy using xDS.

data/lib/async/service/supervisor/envoy/monitor.rb

@@ -3,12 +3,15 @@
 # Released under the MIT License.
 # Copyright, 2026, by Samuel Williams.
 
-require "async/http/endpoint"
-require "async/service/supervisor/monitor"
-require "async/service/supervisor/utilization_monitor"
 require "async/grpc/xds/client_side_weighted_round_robin"
+require "async/grpc/xds/cluster_discovery_service"
+require "async/grpc/xds/config_source"
 require "async/grpc/xds/control_plane"
+require "async/grpc/xds/endpoint_discovery_service"
 require "async/grpc/xds/server"
+require "async/http/endpoint"
+require "async/service/supervisor/monitor"
+require "async/service/supervisor/utilization_monitor"
 require "process/metrics"
 require "xds/data/orca/v3/orca_load_report_pb"
 
@@ -22,12 +25,18 @@ module Async
 		module Supervisor
 			# Provides Envoy integration for supervisor-managed services.
 			module Envoy
-				# Represents a supervisor monitor that publishes worker endpoints to Envoy using xDS.
+				# Represents a supervisor monitor that publishes worker endpoints and optionally clusters to Envoy using xDS.
+				#
+				# The monitor always serves a dedicated EDS stream and can additionally serve
+				# CDS, leaving ADS available to another control plane.
 				class Monitor < Async::Service::Supervisor::Monitor
 					# Initialize the monitor.
-					# @parameter bind [String | Nil] The optional address for the xDS control plane server.
+					# @parameter bind [String | Nil] The optional address for the discovery server.
 					# @parameter delegate [Delegate] The delegate used to map supervisor state into Envoy endpoints.
 					# @parameter control_plane [Async::GRPC::XDS::ControlPlane] The xDS control plane to update.
+					# @parameter management_cluster [String] The static Envoy cluster used to reach this discovery server.
+					# @parameter publish_clusters [Boolean] Whether to publish derived cluster configuration through CDS.
+					# @parameter health_checks [Array(Envoy::Config::Core::V3::HealthCheck)] The active health checks applied to published clusters.
 					# @parameter orca [Boolean] Whether to collect and serve per-worker ORCA load reports.
 					# @parameter processor [Process::Metrics::Processor | Nil] The optional process CPU sampler.
 					# @parameter utilization_monitor [Async::Service::Supervisor::UtilizationMonitor | Nil] The per-worker utilization monitor used for ORCA reporting.
@@ -36,6 +45,9 @@ module Async
 						bind: nil,
 						delegate: Delegate.new,
 						control_plane: Async::GRPC::XDS::ControlPlane.new,
+						management_cluster: "xds_cluster",
+						publish_clusters: true,
+						health_checks: [],
 						orca: false,
 						processor: nil,
 						utilization_monitor: nil,
@@ -47,11 +59,14 @@ module Async
 						@bind = bind
 						@delegate = delegate
 						@control_plane = control_plane
+						@eds_config = Async::GRPC::XDS::ConfigSource.grpc(management_cluster)
+						@publish_clusters = publish_clusters
+						@health_checks = health_checks
 						@interval = interval
 						@orca = orca
 						@controllers = {}
 						@published_clusters = {}
-						@server_task = nil
+						@published_endpoints = {}
 						@mutex = Mutex.new
 						
 						if @orca
@@ -102,15 +117,21 @@ module Async
 						end
 					end
 					
-					# Run the monitor and optional xDS server task.
-					# @parameter parent [Async::Task] The parent task used for the xDS server.
+					# Run the monitor and optional discovery server task.
+					# @parameter parent [Async::Task] The parent task used for the server.
 					# @returns [Async::Task] The monitor task.
 					def run(parent: Async::Task.current)
 						task = super(parent: parent)
 						
 						if @bind
-							@server_task = parent.async do
-								server = Async::GRPC::XDS::Server.new(@control_plane)
+							parent.async do
+								services = [Async::GRPC::XDS::EndpointDiscoveryService]
+								services.unshift(Async::GRPC::XDS::ClusterDiscoveryService) if @publish_clusters
+								
+								server = Async::GRPC::XDS::Server.new(
+									@control_plane,
+									services: services
+								)
 								server.dispatcher.register(ORCAService.new(self, minimum_interval: @interval)) if @orca
 								server.run(server_endpoint)
 							end
@@ -189,17 +210,26 @@ module Async
 						records_by_cluster = build_records_by_cluster
 						clusters = build_clusters(records_by_cluster)
 						
-						records_by_cluster.each do |cluster, records|
-							configuration = cluster_configuration(records)
-							
-							unless @published_clusters[cluster] == configuration
-								@control_plane.update_cluster(cluster, **configuration)
-								@published_clusters[cluster] = configuration
+						if @publish_clusters
+							records_by_cluster.each do |cluster, records|
+								configuration = cluster_configuration(records)
+								
+								unless @published_clusters[cluster] == configuration
+									@control_plane.update_cluster(cluster, **configuration)
+									@published_clusters[cluster] = configuration
+								end
 							end
+						elsif @orca
+							records_by_cluster.each_value{|records| validate_orca_records(records)}
 						end
 						
-						(@published_clusters.keys | clusters.keys).each do |cluster|
-							@control_plane.update_endpoints(cluster, clusters.fetch(cluster, []))
+						# Skipping an identical assignment only avoids a redundant version bump:
+						(@published_endpoints.keys | clusters.keys).each do |cluster|
+							endpoints = clusters.fetch(cluster, [])
+							next if @published_endpoints[cluster] == endpoints
+							
+							@control_plane.update_endpoints(cluster, endpoints)
+							@published_endpoints[cluster] = endpoints
 						end
 					end
 					
@@ -215,6 +245,9 @@ module Async
 						records_by_cluster.transform_values do |records|
 							if @orca
 								records.map do |record|
+									# Envoy sends the endpoint hostname as the request authority when
+									# it opens an out-of-band reporting stream, which is how a single
+									# ORCA service identifies which worker a report is for:
 									{
 										addresses: record[:endpoint].addresses,
 										healthy: record[:healthy],
@@ -243,12 +276,14 @@ module Async
 						raise ArgumentError, "Envoy cluster contains no common protocols: #{protocols.inspect}" if common_protocols.empty?
 						raise ArgumentError, "HTTPS upstream endpoints are not yet supported!" if schemes.first == :https
 						
-						configuration = {protocol: envoy_protocol(common_protocols)}
+						configuration = {
+							protocol: envoy_protocol(common_protocols),
+							eds_config: @eds_config,
+							health_checks: @health_checks,
+						}
 						
 						if @orca
-							if records.any?{|record| record[:endpoint].addresses.any?{|address| address[:path]}}
-								raise ArgumentError, "Out-of-band ORCA reporting requires IP endpoints!"
-							end
+							validate_orca_records(records)
 							
 							configuration[:load_balancing_policy] = Async::GRPC::XDS::ClientSideWeightedRoundRobin.build(
 								@orca_port,
@@ -259,6 +294,12 @@ module Async
 						configuration
 					end
 					
+					def validate_orca_records(records)
+						if records.any?{|record| record[:endpoint].addresses.any?{|address| address[:path]}}
+							raise ArgumentError, "Out-of-band ORCA reporting requires IP endpoints!"
+						end
+					end
+					
 					def sample_load_reports
 						controllers = @mutex.synchronize{@controllers.dup}
 						workers = @utilization_monitor.sample_by_worker

data/lib/async/service/supervisor/envoy/version.rb

@@ -11,7 +11,7 @@ module Async
 		module Supervisor
 			# @namespace
 			module Envoy
-				VERSION = "0.3.1"
+				VERSION = "0.5.0"
 			end
 		end
 	end

data/readme.md

@@ -8,7 +8,7 @@ Provides an Envoy xDS monitor for `async-service-supervisor`.
 
 `async-service-supervisor-envoy` publishes supervised worker endpoints to Envoy:
 
-  - **xDS control plane** - Runs an ADS server backed by `async-grpc-xds`.
+  - **Cluster and endpoint discovery** - Runs dedicated CDS and EDS services backed by `async-grpc-xds`, leaving ADS free for listener, route, and other configuration.
   - **Supervisor integration** - Registers and removes endpoints from supervisor worker lifecycle events.
   - **Multiple clusters** - Groups workers by `state[:name]` by default.
   - **Endpoint contract** - Converts concrete post-bind worker listeners into Envoy upstream endpoints, including grouped IP or Unix socket addresses.
@@ -19,12 +19,24 @@ Provides an Envoy xDS monitor for `async-service-supervisor`.
 
 Please see the [project documentation](https://socketry.github.io/async-service-supervisor-envoy/) for more details.
 
-  - [Getting Started](https://socketry.github.io/async-service-supervisor-envoy/guides/getting-started/index) - This guide explains how to use `async-service-supervisor-envoy` to publish supervised worker endpoints to Envoy using xDS.
+  - [Getting Started](https://socketry.github.io/async-service-supervisor-envoy/guides/getting-started/index) - This guide explains how to use `async-service-supervisor-envoy` to publish supervised worker clusters and endpoints to Envoy using xDS.
 
 ## Releases
 
 Please see the [project releases](https://socketry.github.io/async-service-supervisor-envoy/releases/index) for all releases.
 
+### v0.5.0
+
+  - Serve clusters and endpoints through dedicated CDS and EDS services instead of the aggregated discovery service, leaving ADS available for listener, route, and other configuration.
+  - Allow cluster publication to be disabled when clusters are owned by another control plane.
+  - Configure generated clusters to obtain endpoint assignments from the dedicated EDS service.
+  - Publish endpoint assignments only when they change, instead of on every reconciliation.
+  - Use normalized processor utilization from `process-metrics` v0.13.
+
+### v0.4.0
+
+  - Publish configured active health checks with Envoy clusters.
+
 ### v0.3.1
 
   - Add Bake tasks for inspecting Envoy monitor status, clusters, and endpoints.
@@ -47,10 +59,6 @@ Please see the [project releases](https://socketry.github.io/async-service-super
   - Publish grouped IP and Unix-domain-socket endpoint addresses to Envoy.
   - Configure generated clusters from each endpoint's supported HTTP protocol names.
 
-### v0.1.0
-
-  - Deduplicate immutable endpoint values reported by multiple supervised workers and aggregate their health.
-
 ## See Also
 
   - [async-service-supervisor](https://github.com/socketry/async-service-supervisor) - Supervisor for managed Async service workers.

data/releases.md

@@ -1,5 +1,17 @@
 # Releases
 
+## v0.5.0
+
+  - Serve clusters and endpoints through dedicated CDS and EDS services instead of the aggregated discovery service, leaving ADS available for listener, route, and other configuration.
+  - Allow cluster publication to be disabled when clusters are owned by another control plane.
+  - Configure generated clusters to obtain endpoint assignments from the dedicated EDS service.
+  - Publish endpoint assignments only when they change, instead of on every reconciliation.
+  - Use normalized processor utilization from `process-metrics` v0.13.
+
+## v0.4.0
+
+  - Publish configured active health checks with Envoy clusters.
+
 ## v0.3.1
 
   - Add Bake tasks for inspecting Envoy monitor status, clusters, and endpoints.
@@ -21,7 +33,3 @@
   - Register concrete Falcon cluster listeners as Envoy upstream endpoint state after binding.
   - Publish grouped IP and Unix-domain-socket endpoint addresses to Envoy.
   - Configure generated clusters from each endpoint's supported HTTP protocol names.
-
-## v0.1.0
-
-  - Initial release.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-service-supervisor-envoy
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -58,14 +58,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.4'
 - !ruby/object:Gem::Dependency
   name: async-http
   requirement: !ruby/object:Gem::Requirement
@@ -100,14 +100,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.12'
+        version: '0.13'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.12'
+        version: '0.13'
 executables: []
 extensions: []
 extra_rdoc_files: []