docs: Polaris Admin Tool #830

adutra · 2025-01-20T17:35:32Z

No description provided.

dimas-b

The doc change looks valuable for Polaris users so +1 in general.

I've got some minor comments, most of which are not about the doc, but about the tool itself 😅 Those can certainly be addressed in separate PR.

dimas-b · 2025-01-20T19:10:10Z

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

+Usage: polaris-quarkus-admin-runner.jar bootstrap [-hV] [-c=<credentials>]...
+       -r=<realms> [-r=<realms>]...
+Bootstraps realms and principal credentials.
+  -c, --credential=<credentials>


suggestion: we should probably support reading secrets from the shell console and/or env. variables and/or files (as a follow-up PR)

Yeah, the tool is currently extremely rudimentary at this point. The idea of reading from stdin or file is excellent.

dimas-b · 2025-01-20T19:11:22Z

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

+Bootstraps realms and principal credentials.
+  -c, --credential=<credentials>
+                         Principal credentials to bootstrap. Must be of the
+                           form 'realm,clientId,clientSecret'.


realm has a dedicated option -r 🤔 does the value have to repeat it? It looks off from the usability perspective.

It looks clumsy indeed, but the rationale is that you may want to bootstrap a realm without specifying credentials for it.

I think it's usable :) and it's better to document a usable tool with rough edges, than not have a doc at all :)

dimas-b · 2025-01-20T19:11:58Z

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

+                         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.


nit: realms (plural) looks odd as a placeholder for a singular option.

Need to look into picocli options to fix this.

Looks like this is fixed in the latest commit, right?

Whoops yes, pushed one more commit.

dimas-b · 2025-01-20T19:14:31Z

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

+
+## Purging Principal Credentials
+
+The `purge` command is used to remove realms and principal credentials from the Polaris server. This


Shall we mention "realms" in the section title too? Could you add a paragraph on the implications of purging a realm?

flyrain · 2025-01-21T19:30:37Z

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

+```shell
+docker run apache/polaris-admin-tool:latest --help
+```
+`


Suggested change

`

flyrain · 2025-01-21T19:37:42Z

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

+weight: 300
+---
+
+In order to help administrators manage their Polaris database, Polaris provides an administration


Can we be consistent with the name?

Suggested change

In order to help administrators manage their Polaris database, Polaris provides an administration

In order to help administrators manage their Polaris metastore, Polaris provides an administration

flyrain · 2025-01-21T19:42:28Z

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

+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:


I think it makes sense to use a matched version for both polaris server and admin tool, even after the binary release. In that case, if a user/developer is using the main branch, they should compile the admin tool anyway.

Suggested change

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:

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:

I'll apply the suggestion, but for the record, while it is definitely better if server and tool have the exact same version, that is not a hard requirement. What needs to match is the metastore/database schema.

Makes sense to me. I think version matching is fine for a normal user, it's even harder for any user to check the metastore schema.

flyrain · 2025-01-21T19:43:56Z

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

+In order to help administrators manage their Polaris database, Polaris provides an administration
+tool.
+
+The tool is built using [Quarkus](https://quarkus.io/).


Nit: do we need to call it out explicitly?

Why not? IMHO, it informs users about the technology stack (e.g. how to configure stuff).

I just wanted to double-check if this is truly necessary. Typically, users don’t need to know the inner workings of a tool, especially since this document already explicitly states that configurations should remain consistent. Plus, there are a bunch of technologies behind it, we don't want to enumerate all of them. That said, it’s not a blocker, and I’m fine with proceeding either way.

Let's remove, I think it's pretty obvious already that Quarkus is being used.

flyrain · 2025-01-21T19:47:06Z

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

+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
+```


Do we need this unpack instruction? I'd prefer to leave for users/developers to figure it out by themselves if they want to do this.

flyrain · 2025-01-21T19:55:24Z

Thanks @adutra for documenting this. I think all other places related to bootstrapping and purging are needed to be changed as well, includes but not limited to the boostramp section in the page of polaris-in-production https://github.com/polaris-catalog/polaris/blob/1369461eb98c79ade21a96110fbee6cca5c9a412/docs/configuring-polaris-for-production.md#L71-L71. I'm OK if we want to file another PR for these places, but I think it's still an urgent tasks to make sure all documents are consistent with the Quarkus change. cc @eric-maynard @collado-mike @dennishuo

adutra · 2025-01-22T11:21:22Z

Thanks @adutra for documenting this. I think all other places related to bootstrapping and purging are needed to be changed as well [...] I'm OK if we want to file another PR for these places, but I think it's still an urgent tasks to make sure all documents are consistent with the Quarkus change.

I agree that it would be awesome to have all documentation consistent with the Quarkus change. That is why I opened #700. But then I was asked to split that PR into smaller pieces. This PR is one of them. There is another PR being prepared for configuring-polaris-for-production.md, but I was waiting for #610 to be approved first.

adutra · 2025-01-22T14:11:12Z

@flyrain PR for production settings: #841.

docs: Polaris Admin Tool

18043a4

adutra requested review from ashvina, dennishuo, dimas-b, eric-maynard, jackye1995, jbonofre, vvcephei, collado-mike, snazy, RussellSpitzer, takidau, flyrain and ebyhr as code owners January 20, 2025 17:35

dimas-b reviewed Jan 20, 2025

View reviewed changes

adutra added 3 commits January 21, 2025 18:24

review

35ff887

update docs

3c0b191

update docs some more

a29d999

dimas-b approved these changes Jan 21, 2025

View reviewed changes

flyrain reviewed Jan 21, 2025

View reviewed changes

review

d03061b

adutra added the documentation Improvements or additions to documentation label Jan 22, 2025

flyrain approved these changes Jan 22, 2025

View reviewed changes

adutra merged commit d47a052 into apache:main Jan 22, 2025
5 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Polaris Admin Tool #830

docs: Polaris Admin Tool #830

adutra commented Jan 20, 2025

dimas-b left a comment

dimas-b Jan 20, 2025

adutra Jan 21, 2025 •

edited

Loading

dimas-b Jan 20, 2025

adutra Jan 21, 2025

dimas-b Jan 21, 2025

dimas-b Jan 20, 2025

adutra Jan 21, 2025

dimas-b Jan 21, 2025

adutra Jan 21, 2025

dimas-b Jan 20, 2025

flyrain Jan 21, 2025

flyrain Jan 21, 2025

flyrain Jan 21, 2025

adutra Jan 22, 2025

flyrain Jan 22, 2025

flyrain Jan 21, 2025

dimas-b Jan 21, 2025

flyrain Jan 21, 2025

adutra Jan 22, 2025

flyrain Jan 21, 2025

flyrain commented Jan 21, 2025

adutra commented Jan 22, 2025

adutra commented Jan 22, 2025


		## Purging Principal Credentials

		The `purge` command is used to remove realms and principal credentials from the Polaris server. This

	In order to help administrators manage their Polaris database, Polaris provides an administration
	In order to help administrators manage their Polaris metastore, Polaris provides an administration

docs: Polaris Admin Tool #830

docs: Polaris Admin Tool #830

Conversation

adutra commented Jan 20, 2025

dimas-b left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

adutra Jan 21, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

flyrain commented Jan 21, 2025

adutra commented Jan 22, 2025

adutra commented Jan 22, 2025

adutra Jan 21, 2025 •

edited

Loading