docs: Polaris Admin Tool

quarkus/admin/src/main/java/org/apache/polaris/admintool/BootstrapCommand.java

@@ -27,19 +27,21 @@
 @CommandLine.Command(
     name = "bootstrap",
     mixinStandardHelpOptions = true,
-    description = "Bootstraps realms and principal credentials.")
+    description = "Bootstraps realms and root principal credentials.")
 public class BootstrapCommand extends BaseCommand {
 
   @CommandLine.Option(
       names = {"-r", "--realm"},
+      paramLabel = "<realm>",
       required = true,
       description = "The name of a realm to bootstrap.")
   List<String> realms;
 
   @CommandLine.Option(
       names = {"-c", "--credential"},
+      paramLabel = "<realm,clientId,clientSecret>",
       description =
-          "Principal credentials to bootstrap. Must be of the form 'realm,userName,clientId,clientSecret'.")
+          "Root principal credentials to bootstrap. Must be of the form 'realm,clientId,clientSecret'.")
   List<String> credentials;
 
   @Override

quarkus/admin/src/main/java/org/apache/polaris/admintool/PurgeCommand.java

@@ -24,11 +24,12 @@
 @CommandLine.Command(
     name = "purge",
     mixinStandardHelpOptions = true,
-    description = "Purge principal credentials.")
+    description = "Purge realms and all associated entities.")
 public class PurgeCommand extends BaseCommand {
 
   @CommandLine.Option(
       names = {"-r", "--realm"},
+      paramLabel = "<realm>",
       required = true,
       description = "The name of a realm to purge.")
   List<String> realms;

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

@@ -0,0 +1,146 @@
+---
+#
+# 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 metastore, Polaris provides an administration
+tool.
+
+## How to Download the Admin Tool
+
+Make sure the admin tool and Polaris server are with the same version. If you are using Polaris from
+the source code, you need to build the artifacts yourself 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 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 Realms and 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. If a realm is already bootstrapped, running the `bootstrap` command again will not have any
+effect on that realm.
+
+```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=<realm,clientId,
+       clientSecret>]... -r=<realm> [-r=<realm>]...
+Bootstraps realms and root principal credentials.
+  -c, --credential=<realm,clientId,clientSecret>
+                        Root principal credentials to bootstrap. Must be of the form
+                          'realm,clientId,clientSecret'.
+  -h, --help            Show this help message and exit.
+  -r, --realm=<realm>   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 Realms and Principal Credentials
+
+The `purge` command is used to remove realms and principal credentials from the Polaris server.
+
+> Warning: Running the `purge` command will remove all data associated with the specified realms!
+  This includes all entities (catalogs, namespaces, tables, views, roles), all principal 
+  credentials, grants, and any other data associated with the realms.
+
+```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=<realm> [-r=<realm>]...
+Purge realms and all associated entities.
+  -h, --help            Show this help message and exit.
+  -r, --realm=<realm>   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
+```