dimas-b commented on code in PR #830: URL: https://github.com/apache/polaris/pull/830#discussion_r1922777903
########## 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'. Review Comment: `realm` has a dedicated option `-r` :thinking: does the value have to repeat it? It looks off from the usability perspective. ########## 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> Review Comment: suggestion: we should probably support reading secrets from the shell console and/or env. variables and/or files (as a follow-up PR) ########## 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 Review Comment: Shall we mention "realms" in the section title too? Could you add a paragraph on the implications of purging a realm? ########## 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. Review Comment: nit: `realms` (plural) looks odd as a placeholder for a singular option. -- 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]
