docs: Polaris Admin Tool

site/content/in-dev/unreleased/admin-tool.md

@@ -0,0 +1,153 @@
+---
+#
+# 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.
+#
+linkTitle: Polaris Admin Tool
+title: Apache Polaris (incubating) Admin Tool
+type: docs
+weight: 300
+---
+
+In order to help administrators manage their Polaris database, Polaris provides an administration
+tool.
+
+The tool is built using [Quarkus](https://quarkus.io/).
+
+## How to Download the Admin Tool
+
+As of January 2025, there is currently no binary release or official Docker image available for
+the tool. For now, you need to build the artifacts yourself, for example, by running the following
+command:
+
+```shell
+./gradlew :polaris-quarkus-admin:build -Dquarkus.container-image.build=true
+```
+
+The above command will generate:
+
+- One standalone JAR in `quarkus/admin/build/polaris-quarkus-admin-*-runner.jar`
+- Two distribution archives in `quarkus/admin/build/distributions`
+- Two Docker image named `apache/polaris-admin-tool:latest` and `apache/polaris-admin-tool:<version>`
+
+## Usage
+
+To run the standalone JAR, use the following command:
+
+```shell
+java -jar quarkus/admin/build/polaris-quarkus-admin-*-runner.jar --help
+```
+
+To unpack and run the distribution, you can use the following command:
+
+```shell
+cd quarkus/admin/build/distributions
+unzip polaris-quarkus-admin-*.zip
+cd polaris-quarkus-admin-*/
+java -jar polaris-quarkus-admin-*-runner.jar --help
+```
+
+To run the Docker image, use the following command:
+
+```shell
+docker run apache/polaris-admin-tool:latest --help
+```
+`
+The basic usage of the Polaris Admin Tool is outlined below:
+
+```
+Usage: polaris-quarkus-admin-runner.jar [-hV] [COMMAND]
+Polaris Admin Tool
+  -h, --help      Show this help message and exit.
+  -V, --version   Print version information and exit.
+Commands:
+  help       Display help information about the specified command.
+  bootstrap  Bootstraps realms and principal credentials.
+  purge      Purge principal credentials.
+```
+
+## Configuration
+
+The Polaris Admin Tool must be executed with the same configuration as the Polaris server. The
+configuration can be done via environment variables or system properties.
+
+At a minimum, it is necessary to configure the Polaris Admin Tool to connect to the same database
+used by the Polaris server. This can be done by setting the following system properties:
+
+```shell
+java -jar quarkus/admin/build/polaris-quarkus-admin-*-runner.jar \
+    -Dpolaris.persistence.eclipselink.configuration-file=/path/to/persistence.xml
+    -Dpolaris.persistence.eclipselink.persistence-unit=polaris
+```
+
+See the [metastore documentation]({{% ref "metastores" %}}) for more information on configuring the
+database connection.
+
+## Bootstrapping Principal Credentials
+
+The `bootstrap` command is used to bootstrap realms and create the necessary principal credentials for the Polaris
+server. This command is idempotent and can be run multiple times without causing any issues.
+
+```shell
+java -jar quarkus/admin/build/polaris-quarkus-admin-*-runner.jar bootstrap --help
+```
+
+The basic usage of the `bootstrap` command is outlined below:
+
+```
+Usage: polaris-quarkus-admin-runner.jar bootstrap [-hV] [-c=<credentials>]...
+       -r=<realms> [-r=<realms>]...
+Bootstraps realms and principal credentials.
+  -c, --credential=<credentials>
+                         Principal credentials to bootstrap. Must be of the
+                           form 'realm,clientId,clientSecret'.
+  -h, --help             Show this help message and exit.
+  -r, --realm=<realms>   The name of a realm to bootstrap.
+  -V, --version          Print version information and exit.
+```
+
+For example, to bootstrap the `realm1` realm and create its root principal credential with the
+client ID `admin` and client secret `admin`, you can run the following command:
+
+```shell
+java -jar quarkus/admin/build/polaris-quarkus-admin-*-runner.jar bootstrap -r realm1 -c realm1,admin,admin
+```
+
+## Purging Principal Credentials
+
+The `purge` command is used to remove realms and principal credentials from the Polaris server. This
+command is idempotent and can be run multiple times without causing any issues.
+
+```shell
+java -jar quarkus/admin/build/polaris-quarkus-admin-*-runner.jar purge --help
+```
+
+The basic usage of the `purge` command is outlined below:
+
+```
+Usage: polaris-quarkus-admin-runner.jar purge [-hV] -r=<realms> [-r=<realms>]...
+Purge principal credentials.
+  -h, --help             Show this help message and exit.
+  -r, --realm=<realms>   The name of a realm to purge.
+  -V, --version          Print version information and exit.
+```
+
+For example, to purge the `realm1` realm, you can run the following command:
+
+```shell
+java -jar quarkus/admin/build/polaris-quarkus-admin-*-runner.jar purge -r realm1
+```