tengqm commented on code in PR #7111: URL: https://github.com/apache/gravitino/pull/7111#discussion_r2079064709
########## docs/admin/iceberg-server.md: ########## @@ -0,0 +1,1351 @@ +--- +title: Iceberg REST catalog service +slug: /iceberg-rest-service +keywords: + - Iceberg REST catalog +license: "This software is licensed under the Apache License version 2." +--- + +## Background + +The Apache Gravitino Iceberg REST Server follows the +[Apache Iceberg REST API specification](https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml) +and acts as an Iceberg REST catalog server, +you could access the Iceberg REST endpoint at `http://$ip:$port/iceberg/`. + +### Capabilities + +- Supports the Apache Iceberg REST API defined in Iceberg 1.5, and supports all namespace and table interfaces. + The following interfaces are not implemented yet: + - multi-table transaction + - pagination +- Works as a catalog proxy, supporting `Hive` and `JDBC` as catalog backend. +- Supports credential vending for `S3`、`GCS`、`OSS` and `ADLS`. +- Supports different storages like `S3`, `HDFS`, `OSS`, `GCS`, `ADLS`. +- Capable of supporting other storages. +- Supports event listener. +- Supports Audit log. +- Supports OAuth2 and HTTPS. +- Provides a pluggable metrics store interface to store and delete Iceberg metrics. + +## Server management + +There are three deployment scenarios for Gravitino Iceberg REST server: + +- A standalone server in a standalone Gravitino Iceberg REST server package, the CLASSPATH is `libs`. +- A standalone server in the Gravitino server package, the CLASSPATH is `iceberg-rest-server/libs`. +- An auxiliary service embedded in the Gravitino server, the CLASSPATH is `iceberg-rest-server/libs`. + +For detailed instructions on how to build and install the Gravitino server package, +please refer to [the build guide](../develop/how-to-build.md) and [the installation guide](../install/install.md). +To build the Gravitino Iceberg REST server package, use the command `./gradlew compileIcebergRESTServer -x test`. +Alternatively, to create the corresponding compressed package in the distribution directory, +use `./gradlew assembleIcebergRESTServer -x test`. +The Gravitino Iceberg REST server package includes the following files: + +```text +├─ ... +└─ distribution/gravitino-iceberg-rest-server + ├─ bin/ + │ └─ gravitino-iceberg-rest-server.sh # Launching scripts. + ├─ conf/ # All configurations. + │ ├─ gravitino-iceberg-rest-server.conf # Server configuration. + │ ├─ gravitino-env.sh # Environment variables, e.g. JAVA_HOME, GRAVITINO_HOME, etc. + │ ├─ log4j2.properties # log4j configurations. + │ └─ hdfs-site.xml & core-site.xml # HDFS configuration files. + ├─ libs/ # Dependencies libraries. + └─ logs/ # Logs directory. Auto-created after the server starts. +``` + +## Server configuration + +There are distinct configuration files for standalone and auxiliary server: + +- `gravitino-iceberg-rest-server.conf` is used for the standalone server; +- `gravitino.conf` is for the auxiliary server. + +Although the configuration files differ, the configuration items remain the same. + +Starting with version `0.6.0-incubating`, the prefix `gravitino.auxService.iceberg-rest.` +for auxiliary server configurations has been deprecated. +If both `gravitino.auxService.iceberg-rest.key` and `gravitino.iceberg-rest.key` are present, +the latter will take precedence. +The configurations listed below use the `gravitino.iceberg-rest.` prefix. + +### Configuration to enable Iceberg REST service in Gravitino server. + +<table> +<thead> +<tr> + <th>Configuration item</th> + <th>Description</th> + <th>Default value</th> + <th>Required</th> + <th>Since Version</th> +</tr> +</thead> +<tbody> +<tr> + <td><tt>gravitino.auxService.names</tt></td> + <td> + The auxiliary service name of the Gravitino Iceberg REST catalog service. + Use `iceberg-rest`. + </td> + <td>(none)</td> + <td>Yes</td> + <td>`0.2.0`</td> +</tr> +<tr> + <td><tt>gravitino.iceberg-rest.classpath</tt></td> + <td> + The CLASSPATH of the Gravitino Iceberg REST catalog service, + including the directory containing JARs and configuration. + It supports both absolute and relative paths. + For example, `iceberg-rest-server/libs,iceberg-rest-server/conf`. + </td> + <td>(none)</td> + <td>Yes</td> + <td>`0.2.0`</td> +</tr> +</tbody> +</table> Review Comment: Several points for your consideration: 1. The markdown syntax can be used in HTML table cells. It is an advantage of MDX. That is the reason why you can still see syntax like ```<td>`0.2.0`</td>``` rather than ```<td><code>0.2.0</code></td>``` on line 108, for example. I think this is the convenience you wanted. 2. I don't think we want too many decorations in a table, I can be wrong though. The HTML table is strongly recommended for "wide" tables. Let me show you an example: https://github.com/apache/gravitino/pull/7111/commits/1b4b82a45c53467fecbdc7e5853ab23c75414c09#diff-99584be1316e20d819487c41b400c0254536d9248322b21ae8e6a92998dd5215R132 We can mix Markdown and HTML tags in table cells. And .. you can imagine that next time when we have new event to add to the list, the developer doesn't need to change the whole table. It is simply clean as it is. 3. I am not advocating HTML tables everywhere. For example, [here](https://github.com/apache/gravitino/pull/7111/commits/21b68bc201dc5481b2cce5575eb02c15b072e486#diff-7168d4d433813a6f833ad1b5968c190e00abf3d676cfbd0d5ef6530702d78efbL97-L114) we retain the Markdown table as is. It is pretty clean and straightforward. Changing this to HTML table is a stupid move because it doesn't buy us anything. The only change I made to that page was to ensure that the table rows are properly sorted. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
