Requires Docker to be available (Testcontainers starts Keycloak in a container). + * + *
Verifies:
+ * - Accepts valid JWT tokens from Keycloak
+ * - Rejects invalid/malformed tokens
+ * - Rejects requests without a Bearer token
+ */
+@RunWith(SpringRunner.class)
+@SpringBootTest(
+ classes = {
+ BaseStandaloneRESTCatalogServerTest.TestRestCatalogApplication.class,
+ TestStandaloneRESTCatalogServerJwtAuth.TestConfig.class
+ },
+ webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT,
+ properties = {
+ "spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration",
+ "spring.main.allow-bean-definition-overriding=true"
+ }
+)
+@TestExecutionListeners(
+ listeners = {
+ BaseStandaloneRESTCatalogServerTest.HmsStartupListener.class,
+ TestStandaloneRESTCatalogServerJwtAuth.KeycloakStartupListener.class
+ },
+ mergeMode = TestExecutionListeners.MergeMode.MERGE_WITH_DEFAULTS
+)
+public class TestStandaloneRESTCatalogServerJwtAuth extends BaseStandaloneRESTCatalogServerTest {
+ private static OAuth2AuthorizationServer authorizationServer;
+
+ @Override
+ protected String getBearerTokenForCatalogTests() {
+ return authorizationServer != null ? authorizationServer.getAccessToken() : null;
+ }
+
+ @Order(Ordered.HIGHEST_PRECEDENCE - 1)
+ public static class KeycloakStartupListener implements TestExecutionListener {
+ @Override
+ public void beforeTestClass(TestContext testContext) throws Exception {
+ if (authorizationServer != null) {
+ return;
+ }
+ // Use accessTokenHeaderTypeRfc9068=false so Keycloak emits "JWT" (not "at+jwt") in the token
+ // header - SimpleJWTAuthenticator accepts null and JWT but not "at+jwt" by default.
+ authorizationServer = new OAuth2AuthorizationServer(
+ org.testcontainers.containers.Network.newNetwork(), false);
+ authorizationServer.start();
+ LOG.info("Started Keycloak authorization server at {}", authorizationServer.getIssuer());
+ }
+ }
+
+ @TestConfiguration
+ static class TestConfig {
+ @Bean
+ @Primary
+ public Configuration hadoopConfiguration() {
+ Configuration conf = createBaseTestConfiguration();
+ MetastoreConf.setVar(conf, ConfVars.CATALOG_SERVLET_AUTH, "jwt");
+ MetastoreConf.setVar(conf, ConfVars.THRIFT_METASTORE_AUTHENTICATION_JWT_JWKS_URL,
+ authorizationServer.getIssuer() + "/protocol/openid-connect/certs");
+ return conf;
+ }
+
+ @Bean
+ @Primary
+ public RestCatalogServerRuntime restCatalogServerRuntime(ServerProperties serverProperties) {
+ Configuration conf = createBaseTestConfiguration();
+ MetastoreConf.setVar(conf, ConfVars.CATALOG_SERVLET_AUTH, "jwt");
+ MetastoreConf.setVar(conf, ConfVars.THRIFT_METASTORE_AUTHENTICATION_JWT_JWKS_URL,
+ authorizationServer.getIssuer() + "/protocol/openid-connect/certs");
+ return new RestCatalogServerRuntime(conf, serverProperties);
+ }
+ }
+
+ @AfterClass
+ public static void teardownClass() throws IOException {
+ if (authorizationServer != null) {
+ try {
+ authorizationServer.stop();
+ } catch (Exception e) {
+ LOG.warn("Failed to stop Keycloak (may not have started): {}", e.getMessage());
+ }
+ }
+ teardownBase();
+ }
+
+ @Test(timeout = 60000)
+ public void testRESTCatalogRejectsInvalidToken() throws Exception {
+ LOG.info("=== Test: REST Catalog Rejects Invalid JWT ===");
+
+ String invalidToken = "invalid-token-not-a-valid-jwt";
+ try (CloseableHttpClient httpClient = createHttpClient();
+ CloseableHttpResponse response = httpClient.execute(get("/iceberg/v1/config", invalidToken))) {
+ assertEquals("Config endpoint with invalid JWT should return 401", 401, response.getStatusLine().getStatusCode());
+ LOG.info("Invalid JWT correctly rejected");
+ }
+ }
+
+ @Test(timeout = 60000)
+ public void testRESTCatalogRejectsRequestWithoutToken() throws Exception {
+ LOG.info("=== Test: REST Catalog Rejects Request Without Token ===");
+
+ try (CloseableHttpClient httpClient = createHttpClient();
+ CloseableHttpResponse response = httpClient.execute(get("/iceberg/v1/config"))) {
+ assertEquals("Config endpoint without token should return 401", 401, response.getStatusLine().getStatusCode());
+ LOG.info("Request without token correctly rejected");
+ }
+ }
+}
diff --git a/packaging/pom.xml b/packaging/pom.xml
index 9b9ff3c8b499..46949bd66b7f 100644
--- a/packaging/pom.xml
+++ b/packaging/pom.xml
@@ -184,6 +184,9 @@
This server runs independently of HMS and provides a REST API for Iceberg catalog operations. * It connects to an external HMS instance via Thrift. - * + * *
Designed for Kubernetes deployment with load balancer/API gateway in front: *
* Client → Load Balancer/API Gateway → StandaloneRESTCatalogServer → HMS *- * + * *
Multiple instances can run behind a Kubernetes Service for load balancing.
*/
+@SpringBootApplication(exclude = DataSourceAutoConfiguration.class)
+@SuppressWarnings("java:S1118") // Not a utility class; Spring Boot requires instantiation
public class StandaloneRESTCatalogServer {
private static final Logger LOG = LoggerFactory.getLogger(StandaloneRESTCatalogServer.class);
-
- private final Configuration conf;
- private Server server;
- private int port;
-
- public StandaloneRESTCatalogServer(Configuration conf) {
- this.conf = conf;
- }
-
- /**
- * Starts the standalone REST Catalog server.
- */
- public void start() {
- // Validate required configuration
- String thriftUris = MetastoreConf.getVar(conf, ConfVars.THRIFT_URIS);
- if (thriftUris == null || thriftUris.isEmpty()) {
- throw new IllegalArgumentException("metastore.thrift.uris must be configured to connect to HMS");
- }
-
- int servletPort = MetastoreConf.getIntVar(conf, ConfVars.CATALOG_SERVLET_PORT);
- String servletPath = MetastoreConf.getVar(conf, ConfVars.ICEBERG_CATALOG_SERVLET_PATH);
-
- if (servletPath == null || servletPath.isEmpty()) {
- servletPath = "iceberg"; // Default path
- MetastoreConf.setVar(conf, ConfVars.ICEBERG_CATALOG_SERVLET_PATH, servletPath);
- }
-
- LOG.info("Starting Standalone REST Catalog Server");
- LOG.info(" HMS Thrift URIs: {}", thriftUris);
- LOG.info(" Servlet Port: {}", servletPort);
- LOG.info(" Servlet Path: /{}", servletPath);
-
- // Create servlet using factory
- ServletServerBuilder.Descriptor catalogDescriptor = HMSCatalogFactory.createServlet(conf);
- if (catalogDescriptor == null) {
- throw new IllegalStateException("Failed to create REST Catalog servlet. " +
- "Check that metastore.catalog.servlet.port and metastore.iceberg.catalog.servlet.path are configured.");
- }
-
- // Create health check servlet
- HealthCheckServlet healthServlet = new HealthCheckServlet();
-
- // Build and start server
- ServletServerBuilder builder = new ServletServerBuilder(conf);
- builder.addServlet(catalogDescriptor);
- builder.addServlet(servletPort, "health", healthServlet);
-
- server = builder.start(LOG);
- if (server == null || !server.isStarted()) {
- // Server failed to start - likely a port conflict
- throw new IllegalStateException(String.format(
- "Failed to start REST Catalog server on port %d. Port may already be in use. ", servletPort));
- }
-
- // Get actual port (may be auto-assigned)
- port = catalogDescriptor.getPort();
- LOG.info("Standalone REST Catalog Server started successfully on port {}", port);
- LOG.info(" REST Catalog endpoint: http://localhost:{}/{}", port, servletPath);
- LOG.info(" Health check endpoint: http://localhost:{}/health", port);
- }
-
- /**
- * Stops the server.
- */
- public void stop() {
- if (server != null && server.isStarted()) {
- try {
- LOG.info("Stopping Standalone REST Catalog Server");
- server.stop();
- server.join();
- LOG.info("Standalone REST Catalog Server stopped");
- } catch (InterruptedException e) {
- Thread.currentThread().interrupt();
- LOG.warn("Server stop interrupted", e);
- } catch (Exception e) {
- LOG.error("Error stopping server", e);
- }
- }
- }
-
- /**
- * Gets the port the server is listening on.
- * @return the port number
- */
- @VisibleForTesting
- public int getPort() {
- return port;
- }
- /**
- * Gets the REST Catalog endpoint URL.
- * @return the endpoint URL
- */
- public String getRestEndpoint() {
- String servletPath = MetastoreConf.getVar(conf, ConfVars.ICEBERG_CATALOG_SERVLET_PATH);
- if (servletPath == null || servletPath.isEmpty()) {
- servletPath = "iceberg";
- }
- return "http://localhost:" + port + "/" + servletPath;
- }
-
- /**
- * Simple health check servlet for Kubernetes readiness/liveness probes.
- */
- private static final class HealthCheckServlet extends HttpServlet {
- @Override
- protected void doGet(HttpServletRequest req, HttpServletResponse resp) {
- try {
- resp.setContentType("application/json");
- resp.setStatus(HttpServletResponse.SC_OK);
- resp.getWriter().println("{\"status\":\"healthy\"}");
- } catch (IOException e) {
- LOG.warn("Failed to write health check response", e);
- }
- }
- }
-
/**
* Main method for running as a standalone application.
- * @param args command line arguments
+ * @param args command line arguments (-Dkey=value for configuration)
*/
public static void main(String[] args) {
- Configuration conf = MetastoreConf.newMetastoreConf();
-
- // Load configuration from command line args or environment
- // Format: -Dkey=value or use system properties
+ // Apply -D args to system properties so application.yml and Configuration bean pick them up
for (String arg : args) {
if (arg.startsWith("-D")) {
String[] kv = arg.substring(2).split("=", 2);
if (kv.length == 2) {
- conf.set(kv[0], kv[1]);
+ System.setProperty(kv[0], kv[1]);
}
}
}
-
- StandaloneRESTCatalogServer server = new StandaloneRESTCatalogServer(conf);
-
- // Add shutdown hook
- Runtime.getRuntime().addShutdownHook(new Thread(() -> {
- LOG.info("Shutdown hook triggered");
- server.stop();
- }));
-
- try {
- server.start();
- LOG.info("Server running. Press Ctrl+C to stop.");
-
- // Keep server running
- server.server.join();
- } catch (InterruptedException e) {
- Thread.currentThread().interrupt();
- LOG.warn("Server stop interrupted", e);
- } catch (Exception e) {
- LOG.error("Failed to start server", e);
- System.exit(1);
+ // Sync port from MetastoreConf to Spring's server.port if not already set
+ if (System.getProperty(ConfVars.CATALOG_SERVLET_PORT.getVarname()) == null) {
+ int port = MetastoreConf.getIntVar(MetastoreConf.newMetastoreConf(), ConfVars.CATALOG_SERVLET_PORT);
+ if (port > 0) {
+ System.setProperty(ConfVars.CATALOG_SERVLET_PORT.getVarname(), String.valueOf(port));
+ }
}
+
+ SpringApplication.run(StandaloneRESTCatalogServer.class, args);
+
+ LOG.info("Standalone REST Catalog Server started successfully");
+ LOG.info("Server running. Press Ctrl+C to stop.");
}
}
diff --git a/standalone-metastore/metastore-rest-catalog/src/main/java/org/apache/iceberg/rest/standalone/health/HMSReadinessHealthIndicator.java b/standalone-metastore/metastore-rest-catalog/src/main/java/org/apache/iceberg/rest/standalone/health/HMSReadinessHealthIndicator.java
new file mode 100644
index 000000000000..252a3d298b2b
--- /dev/null
+++ b/standalone-metastore/metastore-rest-catalog/src/main/java/org/apache/iceberg/rest/standalone/health/HMSReadinessHealthIndicator.java
@@ -0,0 +1,69 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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 org.apache.iceberg.rest.standalone.health;
+
+import org.apache.hadoop.conf.Configuration;
+import org.apache.hadoop.hive.metastore.HiveMetaStoreClient;
+import org.apache.hadoop.hive.metastore.conf.MetastoreConf;
+import org.apache.hadoop.hive.metastore.conf.MetastoreConf.ConfVars;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.boot.actuate.health.Health;
+import org.springframework.boot.actuate.health.HealthIndicator;
+import org.springframework.stereotype.Component;
+
+/**
+ * Custom health indicator for HMS connectivity.
+ * Verifies that HMS is reachable via Thrift, not just that configuration is present.
+ * Used by Kubernetes readiness probes to determine if the server is ready to accept traffic.
+ */
+@Component
+public class HMSReadinessHealthIndicator implements HealthIndicator {
+ private static final Logger LOG = LoggerFactory.getLogger(HMSReadinessHealthIndicator.class);
+
+ private final Configuration conf;
+
+ public HMSReadinessHealthIndicator(Configuration conf) {
+ this.conf = conf;
+ }
+
+ @Override
+ public Health health() {
+ String hmsThriftUris = MetastoreConf.getVar(conf, ConfVars.THRIFT_URIS);
+ if (hmsThriftUris == null || hmsThriftUris.isEmpty()) {
+ return Health.down()
+ .withDetail("reason", "HMS Thrift URIs not configured")
+ .build();
+ }
+
+ try (HiveMetaStoreClient client = new HiveMetaStoreClient(conf)) {
+ // Lightweight call to verify HMS is reachable
+ client.getAllDatabases();
+ return Health.up()
+ .withDetail("hmsThriftUris", hmsThriftUris)
+ .withDetail("warehouse", MetastoreConf.getVar(conf, ConfVars.WAREHOUSE))
+ .build();
+ } catch (Exception e) {
+ LOG.warn("HMS connectivity check failed: {}", e.getMessage());
+ return Health.down()
+ .withDetail("hmsThriftUris", hmsThriftUris)
+ .withDetail("error", e.getMessage())
+ .build();
+ }
+ }
+}
diff --git a/standalone-metastore/metastore-rest-catalog/src/main/resources/application.yml b/standalone-metastore/metastore-rest-catalog/src/main/resources/application.yml
new file mode 100644
index 000000000000..d15c0701e800
--- /dev/null
+++ b/standalone-metastore/metastore-rest-catalog/src/main/resources/application.yml
@@ -0,0 +1,69 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you 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.
+
+# Spring Boot Configuration for Standalone HMS REST Catalog Server
+
+# Server configuration
+# Port is set via MetastoreConf.CATALOG_SERVLET_PORT or -Dmetastore.catalog.servlet.port
+# SSL is enabled by default with a bundled self-signed cert (dev). Override for production:
+# -Dserver.ssl.key-store=/path/to/keystore.p12 -Dserver.ssl.key-store-password=secret
+server:
+ port: ${metastore.catalog.servlet.port:8080}
+ shutdown: graceful
+ ssl:
+ enabled: true
+ key-store: classpath:keystore.p12
+ key-store-password: changeit
+ key-store-type: PKCS12
+ key-alias: iceberg
+spring:
+ lifecycle:
+ timeout-per-shutdown-phase: 30s
+
+# Actuator endpoints for Kubernetes
+management:
+ endpoints:
+ web:
+ exposure:
+ include: health,prometheus,info
+ endpoint:
+ health:
+ show-details: always
+ probes:
+ enabled: true
+ health:
+ livenessState:
+ enabled: true
+ readinessState:
+ enabled: true
+ metrics:
+ export:
+ prometheus:
+ enabled: true
+
+# Logging
+logging:
+ level:
+ org.apache.iceberg.rest.standalone: INFO
+ org.apache.hadoop.hive.metastore: INFO
+ org.springframework.boot: WARN
+
+# Application info
+info:
+ app:
+ name: Standalone HMS REST Catalog Server
+ description: Standalone REST Catalog Server for Apache Hive Metastore
+ version: "@project.version@"
diff --git a/standalone-metastore/metastore-rest-catalog/src/main/resources/keystore.p12 b/standalone-metastore/metastore-rest-catalog/src/main/resources/keystore.p12
new file mode 100644
index 000000000000..b5ba6825dad2
Binary files /dev/null and b/standalone-metastore/metastore-rest-catalog/src/main/resources/keystore.p12 differ
diff --git a/standalone-metastore/metastore-server/src/main/java/org/apache/hadoop/hive/metastore/auth/jwt/SimpleJWTAuthenticator.java b/standalone-metastore/metastore-server/src/main/java/org/apache/hadoop/hive/metastore/auth/jwt/SimpleJWTAuthenticator.java
index a6e85def82c3..45fc4d337a76 100644
--- a/standalone-metastore/metastore-server/src/main/java/org/apache/hadoop/hive/metastore/auth/jwt/SimpleJWTAuthenticator.java
+++ b/standalone-metastore/metastore-server/src/main/java/org/apache/hadoop/hive/metastore/auth/jwt/SimpleJWTAuthenticator.java
@@ -38,7 +38,10 @@
public class SimpleJWTAuthenticator {
private static final Logger LOG = LoggerFactory.getLogger(SimpleJWTAuthenticator.class.getName());
- private static final Set