This is an automated email from the ASF dual-hosted git repository.
adutra pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/polaris.git
The following commit(s) were added to refs/heads/main by this push:
new d47a0521 docs: Polaris Admin Tool (#830)
d47a0521 is described below
commit d47a0521ae584cd73f04242f2f537972eda5125b
Author: Alexandre Dutra <[email protected]>
AuthorDate: Wed Jan 22 21:04:00 2025 +0100
docs: Polaris Admin Tool (#830)
---
.../apache/polaris/admintool/BootstrapCommand.java | 4 +-
.../org/apache/polaris/admintool/PurgeCommand.java | 3 +-
site/content/in-dev/unreleased/admin-tool.md | 146 +++++++++++++++++++++
3 files changed, 151 insertions(+), 2 deletions(-)
diff --git
a/quarkus/admin/src/main/java/org/apache/polaris/admintool/BootstrapCommand.java
b/quarkus/admin/src/main/java/org/apache/polaris/admintool/BootstrapCommand.java
index c9765420..84c0348f 100644
---
a/quarkus/admin/src/main/java/org/apache/polaris/admintool/BootstrapCommand.java
+++
b/quarkus/admin/src/main/java/org/apache/polaris/admintool/BootstrapCommand.java
@@ -27,17 +27,19 @@ import picocli.CommandLine;
@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 =
"Root principal credentials to bootstrap. Must be of the form
'realm,clientId,clientSecret'.")
List<String> credentials;
diff --git
a/quarkus/admin/src/main/java/org/apache/polaris/admintool/PurgeCommand.java
b/quarkus/admin/src/main/java/org/apache/polaris/admintool/PurgeCommand.java
index e28d0efa..733efbce 100644
--- a/quarkus/admin/src/main/java/org/apache/polaris/admintool/PurgeCommand.java
+++ b/quarkus/admin/src/main/java/org/apache/polaris/admintool/PurgeCommand.java
@@ -24,11 +24,12 @@ import picocli.CommandLine;
@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;
diff --git a/site/content/in-dev/unreleased/admin-tool.md
b/site/content/in-dev/unreleased/admin-tool.md
new file mode 100644
index 00000000..7d0d7e54
--- /dev/null
+++ b/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
+```
\ No newline at end of file
