This is an automated email from the ASF dual-hosted git repository.
okumin pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/hive-site.git
The following commit(s) were added to refs/heads/main by this push:
new 8a4187d HIVE-28059: Document Iceberg REST Catalog API of Hive 4.2.0
(#76)
8a4187d is described below
commit 8a4187d2f6fa1211f16694768d38a615c6b1751b
Author: Shohei Okumiya <[email protected]>
AuthorDate: Mon Nov 24 12:46:50 2025 +0900
HIVE-28059: Document Iceberg REST Catalog API of Hive 4.2.0 (#76)
---
content/docs/latest/admin/iceberg-rest-catalog.md | 90 +++++++++++++++++++++
.../admin/images/hive-iceberg-rest-integration.png | Bin 0 -> 30770 bytes
content/docs/latest/admin/oauth2/_index.md | 4 -
3 files changed, 90 insertions(+), 4 deletions(-)
diff --git a/content/docs/latest/admin/iceberg-rest-catalog.md
b/content/docs/latest/admin/iceberg-rest-catalog.md
new file mode 100644
index 0000000..8769dd3
--- /dev/null
+++ b/content/docs/latest/admin/iceberg-rest-catalog.md
@@ -0,0 +1,90 @@
+---
+title: "Apache Hive : Iceberg REST Catalog API backed by Hive Metastore"
+date: 2025-11-14
+---
+
+# Apache Hive : Iceberg REST Catalog API backed by Hive Metastore
+
+{{< toc >}}
+
+## Introduction
+
+
+
+Hive Metastore offers [Iceberg REST
API](https://iceberg.apache.org/rest-catalog-spec/) endpoints for clients
native to Apache Iceberg. Consequently, Iceberg users can access Iceberg tables
via either Hive Metastore Thrift API (using HiveCatalog) or Iceberg REST
Catalog API.
+
+## Basic configurations
+
+You must configure the following parameters.
+
+| Key | Required? | Default | Value |
+|-|-|-|-|
+| metastore.catalog.servlet.port | Yes | -1 | The port number to which Iceberg
REST API listens |
+
+## Authentication
+
+Hive Metastore's Iceberg REST API supports four authentication methods.
+
+### OAuth 2
+
+OAuth 2 is the industry standard for authenticating Iceberg client usernames.
You can integrate Hive Metastore with your Authorization Server, e.g.,
Keycloak, to protect Iceberg resources. See [Apache Hive : Setting Up OAuth
2]({{< relref "oauth2/_index.md" >}}) for further details.
+
+### JWT
+
+You can configure Hive Metastore so that its Iceberg REST API accepts a JSON
Web Token (JWT) as a bearer token in the Authorization header. This is the
default authentication mechanism because the default value of
`metastore.catalog.servlet.auth` is `jwt`. The JSON Web Key Set (JWKS)
locations must be configured using the `metastore.authentication.jwt.jwks.url`
property. Hive Metastore derives the username from the `sub` claim of a
properly-signed JWT.
+
+### Simple
+
+When `metastore.catalog.servlet.auth=simple`, Hive Metastore assumes that the
value of the `x-actor-username` HTTP header is the authenticated username. You
may use it to test authorized access, but this mode is not recommend in a
production environment.
+
+### None
+
+When `metastore.catalog.servlet.auth=none`, Hive Metastore does not enforce
any authentication. This mode may be used for testing only.
+
+## Authorization
+
+You can apply database-level or table-level authorization in Hive Metastore.
See also: [Apache Hive : LanguageManual Authorization]({{< relref
"../language/languagemanual-authorization.md" >}}).
+
+For example, you can secure Iceberg REST API using Apache Ranger.
+
+```xml
+<property>
+ <name>hive.security.authorization.manager</name>
+
<value>org.apache.ranger.authorization.hive.authorizer.RangerHiveAuthorizerFactory</value>
+</property>
+<property>
+ <name>metastore.pre.event.listeners</name>
+
<value>org.apache.hadoop.hive.ql.security.authorization.plugin.metastore.HiveMetaStoreAuthorizer</value>
+</property>
+```
+
+## Example: Minimal Setup with Docker
+
+The official Docker images expose the REST API endpoints on the 9001 port with
`metastore.catalog.servlet.auth=none`. A single command lets you try Iceberg
REST Catalog.
+
+```sh
+$ docker run --rm -p 9001:9001 apache/hive:standalone-metastore-{Hive version}
+```
+
+```sh
+$ curl http://localhost:9001/iceberg/v1/config
+{"defaults":{},"overrides":{},"endpoints":["GET v1/config","GET
/v1/{prefix}/namespaces","POST /v1/{prefix}/namespaces","HEAD
/v1/{prefix}/namespaces/{namespace}","GET
/v1/{prefix}/namespaces/{namespace}","DELETE
/v1/{prefix}/namespaces/{namespace}","POST
/v1/{prefix}/namespaces/{namespace}/properties","GET
/v1/{prefix}/namespaces/{namespace}/tables","POST
/v1/{prefix}/namespaces/{namespace}/tables","HEAD
/v1/{prefix}/namespaces/{namespace}/tables/{table}","GET
/v1/{prefix}/namespaces/{n [...]
+
+$ curl -X POST \
+ http://localhost:9001/iceberg/v1/namespaces/default/tables \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "test",
+ "schema": {
+ "type": "struct",
+ "fields": [
+ {"id": 1, "name": "id", "type": "long", "required": true}
+ ]
+ },
+ "write-disposition": "create"
+ }'
+{"metadata-location":"file:/opt/hive/data/warehouse/test/metadata/00000-f1a3fec1-f0b6-499b-b635-d6a408458390.metadata.json","metadata":{"format-version":2,"table-uuid":"47ca342c-b65b-4e51-a09d-1b470f20298a","location":"file:/opt/hive/data/warehouse/test","last-sequence-number":0,"last-updated-ms":1763188388952,"last-column-id":1,"current-schema-id":0,"schemas":[{"type":"struct","schema-id":0,"fields":[{"id":1,"name":"id","required":true,"type":"long"}]}],"default-spec-id":0,"partition-sp
[...]
+
+$ curl http://localhost:9001/iceberg/v1/namespaces/default/tables/test
+{"metadata-location":"file:/opt/hive/data/warehouse/test/metadata/00000-f1a3fec1-f0b6-499b-b635-d6a408458390.metadata.json","metadata":{"format-version":2,"table-uuid":"47ca342c-b65b-4e51-a09d-1b470f20298a","location":"file:/opt/hive/data/warehouse/test","last-sequence-number":0,"last-updated-ms":1763188388952,"last-column-id":1,"current-schema-id":0,"schemas":[{"type":"struct","schema-id":0,"fields":[{"id":1,"name":"id","required":true,"type":"long"}]}],"default-spec-id":0,"partition-sp
[...]
+```
diff --git a/content/docs/latest/admin/images/hive-iceberg-rest-integration.png
b/content/docs/latest/admin/images/hive-iceberg-rest-integration.png
new file mode 100644
index 0000000..315e75f
Binary files /dev/null and
b/content/docs/latest/admin/images/hive-iceberg-rest-integration.png differ
diff --git a/content/docs/latest/admin/oauth2/_index.md
b/content/docs/latest/admin/oauth2/_index.md
index 0e70bf0..773b5c1 100644
--- a/content/docs/latest/admin/oauth2/_index.md
+++ b/content/docs/latest/admin/oauth2/_index.md
@@ -7,10 +7,6 @@ date: 2025-09-30
Hive is able to protect some resources and extract authenticated usernames
with OAuth 2.
-## WARNING
-
-This feature has not been deployed yet, is available only on the master branch.
-
## Supported Features
- Iceberg REST Catalog API
