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 22a2e8ac86..84c0348fc8 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,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 = "", required = true, description = "The name of a realm to bootstrap.") List realms; @CommandLine.Option( names = {"-c", "--credential"}, + paramLabel = "", 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 credentials; @Override 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 e28d0efa26..733efbce7d 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 @@ @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 = "", required = true, description = "The name of a realm to purge.") List 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 0000000000..7d0d7e54a4 --- /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:` + +## 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=]... -r= [-r=]... +Bootstraps realms and root principal credentials. + -c, --credential= + Root principal credentials to bootstrap. Must be of the form + 'realm,clientId,clientSecret'. + -h, --help Show this help message and exit. + -r, --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= [-r=]... +Purge realms and all associated entities. + -h, --help Show this help message and exit. + -r, --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