add service discovery for REST frontend with ZK/ETCD support

[ychris78]

Why are the changes needed?

Currently, the Kyuubi REST frontend service does not register itself with the HA discovery service (ZK/ETCD). This means REST clients must use static host URLs and cannot benefit from dynamic service discovery, automatic failover, or load balancing that the Thrift frontend already
supports.

This patch adds full service discovery support for the REST frontend, covering both the server-side (registering REST endpoints in ZK/ETCD under a dedicated namespace) and the client-side (discovering and dynamically refreshing REST endpoints).

Server-side changes:

• KyuubiRestFrontendService now creates a KyuubiRestServiceDiscovery when HA is configured, registering the REST service under {namespace}/rest (e.g. /kyuubi/rest) to distinguish it from Thrift endpoints.
• KyuubiRestServiceDiscovery extends ServiceDiscovery with custom namespace logic and graceful shutdown.
• ServiceDiscovery._namespace and _discoveryClient visibility changed from private to protected to allow subclass customization.

Client-side changes:

• New RestDiscoveryConf configuration class for ZK/ETCD discovery settings (addresses, namespace, client class, refresh interval).
• New RestServiceDiscoverer utility to discover REST host URLs from ZK/ETCD service nodes.
• KyuubiRestClient.discoveryBuilder() API to create a client with automatic background endpoint refresh.
• RetryableRestClient refactored to track the current URI by value instead of index, with a new updateUris() method for dynamic URI list updates.

How was this patch tested?

• Unit tests added:

  • RetryableRestClientTest — tests updateUris() behavior: keeping current server, switching when removed, URI rotation.
  • RestDiscoveryConfTest — tests default values, setters, and validation logic.
  • RestServiceDiscovererTest — tests namespace construction and validation.

• Integration tests added:

  • KyuubiRestServiceDiscoverySuite — tests with embedded ZooKeeper:
    • REST discovery is conditional on HA configuration.
    • REST instance publishes under namespace/rest and can be discovered.
    • Graceful shutdown when the REST service node is deleted.

• Compiled and tested kyuubi-ha, kyuubi-rest-client, and kyuubi-server modules (mvn compile and mvn test all passed).

Was this patch authored or co-authored using generative AI tooling?

co-authored

[pan3793]

In practice, it's usually to use a gateway like nginx for HA of HTTP services.

[ychris78]

In practice, it's usually to use a gateway like nginx for HA of HTTP services.

Thanks for the suggestion. I agree that a reverse proxy like nginx is a common approach for HTTP HA, but I think client-side service discovery via ZK/ETCD offers several unique advantages in Kyuubi's context:

1. No additional infrastructure required
   Kyuubi already relies on ZK/ETCD for Thrift frontend HA. Reusing the same service discovery infrastructure for REST means users don't need to deploy, configure, and maintain an extra nginx layer.

2. No single point of failure
   With nginx, the gateway itself becomes a SPOF (unless you additionally set up nginx HA with keepalived, etc., which adds even more complexity). Client-side discovery eliminates this — each client independently discovers available endpoints.

3. Dynamic topology without config changes
   When REST instances are added or removed, clients automatically pick up the change via the background refresher. With nginx, you'd need to update upstream configs and reload.

4. Consistency with existing architecture
   Kyuubi's Thrift frontend already uses ZK-based service discovery (ServiceDiscovery). This PR follows the same pattern for REST, providing a consistent user experience, just like jdbc:hive2://zk1:2181,zk2:2181/;serviceDiscoveryMode=zooKeeper.

5. Better suited for programmatic clients
   The kyuubi-rest-client is a Java library embedded in applications. Requiring those applications to go through nginx adds operational coupling. With this PR, they can self-discover endpoints with just ZK/ETCD addresses.

6. The two approaches are not mutually exclusive
   This PR doesn't prevent users from using nginx. Users who prefer a gateway can still point the REST client at nginx. This simply provides a zero-extra-infrastructure option for the many users already running ZK/ETCD.