Hms standalone rest server with Spring Boot by difin · Pull Request #6327 · apache/hive

difin · 2026-02-19T15:54:20Z

What changes were proposed in this pull request?

The Standalone REST Catalog Server is reimplemented to use Spring Boot instead of plain Java:

Server framework – Uses Spring Boot with an embedded Jetty server instead of raw servlet wiring.
Health checks – Adds Actuator liveness and readiness probes; readiness verifies HMS connectivity via Thrift.
Observability – Exposes Prometheus metrics for Kubernetes HPA and monitoring.
Configuration – Keeps port and other settings in MetastoreConf but bridges them into Spring (e.g., via system properties) so Spring Boot uses the configured port.
Graceful shutdown – Uses Spring Boot’s shutdown handling with a configurable timeout.
Standalone packaging – Adds a spring-boot-maven-plugin “exec” JAR for running the server as a standalone process.

Why are the changes needed?

Spring Boot improves how the Standalone REST Catalog Server is run and operated:

Kubernetes support – Liveness and readiness probes (/actuator/health/*) let Kubernetes reliably route traffic and restart unhealthy pods. Readiness includes an actual HMS connectivity check instead of a simple config check.
Observability – Prometheus metrics enable HPA, dashboards, and alerting, which is standard for production deployments.
Operational behavior – Graceful shutdown and a well-defined lifecycle reduce the chance of dropped requests during restarts.
Maintainability – Spring Boot replaces custom servlet wiring and configuration, and aligns with common patterns for cloud-native Java services.

Does this PR introduce any user-facing change?

If the standalone REST Catalog server is deployed in Kubernetes:

Liveness/readiness probes – Configure HTTP probes to use the new actuator endpoints:
-- Liveness: httpGet: /actuator/health/liveness
-- Readiness: httpGet: /actuator/health/readiness
Metrics/HPA – Prometheus scraping or custom metrics use /actuator/prometheus.

How was this patch tested?

Integration tests in TestStandaloneRESTCatalogServer and TestStandaloneRESTCatalogServerJwtAuth run the Spring Boot standalone HMS REST catalog server and verify liveness/readiness probes, Prometheus metrics, REST catalog operations, and JWT auth with Keycloak (Testcontainers).

deniskuzZ · 2026-02-20T14:29:22Z

	Suppressed: java.lang.NullPointerException: Cannot invoke "org.keycloak.admin.client.Keycloak.close()" because "this.keycloak" is null
		at org.apache.iceberg.rest.extension.OAuth2AuthorizationServer.stop(OAuth2AuthorizationServer.java:181)
		at org.apache.iceberg.rest.extension.HiveRESTCatalogServerExtension.afterAll(HiveRESTCatalogServerExtension.java:124)
		... 1 more
Caused by: java.lang.ClassNotFoundException: jakarta.annotation.Priority

.../qtest-iceberg/src/test/java/org/apache/hadoop/hive/cli/TestStandaloneRESTCatalogServer.java

deniskuzZ · 2026-02-20T14:39:22Z

.../qtest-iceberg/src/test/java/org/apache/hadoop/hive/cli/TestStandaloneRESTCatalogServer.java

-    LOG.info("=== Test: Health Check ===");
-    
-    String healthUrl = "http://localhost:" + restCatalogServer.getPort() + "/health";
+  public void testPrometheusMetrics() throws Exception {


do we use spring actuator? nice :)

.../qtest-iceberg/src/test/java/org/apache/hadoop/hive/cli/TestStandaloneRESTCatalogServer.java

deniskuzZ · 2026-02-20T14:48:53Z

to support OAuth / JWT Authentication don't we need SecurityConfig?

@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.oauth2ResourceServer()
            .jwt(); // validate JWT tokens
    }
}

cc @okumin

standalone-metastore/metastore-rest-catalog/pom.xml

itests/qtest-iceberg/pom.xml

...log/src/main/java/org/apache/iceberg/rest/standalone/health/HMSReadinessHealthIndicator.java

...st-catalog/src/main/java/org/apache/iceberg/rest/standalone/StandaloneRESTCatalogServer.java

standalone-metastore/metastore-rest-catalog/src/main/resources/application.properties

standalone-metastore/metastore-rest-catalog/pom.xml

okumin · 2026-03-07T06:25:17Z

to support OAuth / JWT Authentication don't we need SecurityConfig?

DISCLAIMER: I might not be understanding Spring with Servlet correctly.
We may finally be able to use the Spring's tool if all are migrated to Spring. As of today, if Spring can leverage ServletSecurity, we don't immediately move to there.

.../qtest-iceberg/src/test/java/org/apache/hadoop/hive/cli/TestStandaloneRESTCatalogServer.java

...iceberg/src/test/java/org/apache/hadoop/hive/cli/TestStandaloneRESTCatalogServerJwtAuth.java

...st-catalog/src/main/java/org/apache/iceberg/rest/standalone/IcebergCatalogConfiguration.java

...st-catalog/src/main/java/org/apache/iceberg/rest/standalone/StandaloneRESTCatalogServer.java

deniskuzZ · 2026-03-10T11:44:17Z

...st-catalog/src/main/java/org/apache/iceberg/rest/standalone/StandaloneRESTCatalogServer.java

+      System.setProperty(ConfVars.CATALOG_SERVLET_PORT.getVarname(), String.valueOf(port));
+    }
+
    StandaloneRESTCatalogServer server = new StandaloneRESTCatalogServer(conf);


Spring Boot should manage the lifecycle of your application class. Typically you don't manually instantiate your @SpringBootApplication class. see above snippet

deniskuzZ

added few comments, rest LGTM

deniskuzZ

LGTM +1

deniskuzZ · 2026-03-12T17:48:54Z

...-rest-catalog/src/main/java/org/apache/iceberg/rest/standalone/RestCatalogServerRuntime.java

+        servletPath = IcebergCatalogConfiguration.DEFAULT_SERVLET_PATH;
+      }
+
+      String scheme = isSslEnabled() ? "https" : "http";


minor: should we inline?

sonarqubecloud · 2026-03-13T04:23:32Z

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

difin requested a review from deniskuzZ February 19, 2026 15:54

asf-ci-hive added the tests pending label Feb 19, 2026

difin mentioned this pull request Feb 19, 2026

HIVE-29468: Standalone HMS REST Catalog Server: Migrate to Spring Boot #6324

Closed

asf-ci-hive added tests unstable and removed tests pending labels Feb 19, 2026

difin force-pushed the hms-standalone-r 8000 est-server-with-spring-boot branch from 2e24788 to 196fd31 Compare February 19, 2026 20:19

asf-ci-hive added tests pending tests unstable and removed tests unstable tests pending labels Feb 19, 2026