Docs/improve idp documentation #2695

olsoloviov · 2025-09-26T14:13:10Z

Some improvements in documentation, mainly for IDP integration and telemetry

- Fix link to getting started from landing page - Fix mentioning role-arn as required

…to checks still fails)

dimas-b

LGTM with minor comments 👍 Thanks for your contribution, @olsoloviov !

dimas-b · 2025-09-26T15:30:58Z

site/content/in-dev/unreleased/getting-started/creating-a-catalog/s3/_index.md

 ```text
 --storage-type s3
--role-arn  (Required for S3) A role ARN to use when connecting to S3
+--role-arn  (Only for S3) A role ARN to use when connecting to S3


It's required only for AWS. MinIO does not need it. I guess other non-AWS systems do not need it either.

dimas-b · 2025-09-26T15:33:22Z

site/content/in-dev/unreleased/getting-started/using-polaris/keycloak-idp.md


 For more information about how to configure Polaris with external authentication, see the
-[Polaris documentation]({{% ref "../external-idp" %}}).
+[Polaris documentation](https://polaris.apache.org/in-dev/unreleased/managing-security/external-idp/).


Can this be a "hugo" ref? Docs will be "frozen" after a release, so links to in-dev from old versions are likely to become invalid pretty soon.

Thanks for catching!

dimas-b · 2025-09-26T15:37:29Z

site/content/in-dev/unreleased/command-line-interface.md

+      --path-style-access  (Only for S3) Whether to use path-style-access for S3
      --allowed-location  An allowed location for files tracked by the catalog. Multiple locations can be provided by specifying this option more than once.
-      --role-arn  (Required for S3) A role ARN to use when connecting to S3
+      --role-arn  (Only for S3) A role ARN to use when connecting to S3


Only for AWS

Thanks, fixed. Since it's a dumped output from CLI tool, I changed corresponding Python files as well.

…cloak guide.

flyrain

Thanks a lot for @olsoloviov for the doc change! Looks great overall! Left one minor question.

flyrain · 2025-09-26T21:30:55Z

client/python/cli/command/__init__.py

        """
        Used to validate a command. Should always be called before `execute`. The arg parser will catch many issues
        with options, but this is used to apply additional constraints that the arg parser can't currently handle.
-        One example is that a catalog cannot be created with the `s3` storage type without a `--role-arn` option, but


Why do we delete this? We could say that AWS s3 to be more specific if s3 is too board here.

Thanks for your review, @flyrain! I removed that comment since the actual validation of role-arn for S3 storage has been removed from catalogs command in #2339, so the comment might be misleading now. We could specify AWS S3 but there is no specific validation for AWS S3 as well. I can replace it with a different relevant example if that makes sense.

In that case, we are fine here. Sorry, I didn't notice #2339 has removed the check completely.

* (Based on PR#2223)Support Namespace/Table level RBAC for external passthrough catalogs (apache#2673) Creates missing synthetic entities for securables in external passthrough catalogs. Based on Option 1 discussed in the RBAC section of catalog federation design doc. In the future, we could remove calls to PolarisEntity.Builder() and replace them with entities fetched from the remote catalog. (enabling Option 2). --------- Co-authored-by: Pooja Nilangekar <poojan@umd.edu> * Docs: Add more details about v1 schema user to upgrade from 1.0 to 1.1 (apache#2674) * Site: The link https://iceberg.apache.org/concepts/catalog/ doesn't exist anymore. (apache#2683) * Docs: Add analytics for polaris.apache.org (apache#2676) * Make ENABLE_SUB_CATALOG_RBAC_FOR_FEDERATED_CATALOGS configurable per catalog (apache#2688) * Update ENABLE_SUB_CATALOG_RBAC_FOR_FEDERATED_CATALOGS to be configurable per catalog * chore(deps): update postgres docker tag to v18 (apache#2692) * fix(deps): update dependency org.eclipse.persistence:eclipselink to v4.0.8 (apache#2682) * fix(deps): update dependency org.apache.logging.log4j:log4j-core to v2.25.2 (apache#2646) * chore(deps): update dependency openapi-generator-cli to v7.15.0 (apache#2410) * chore(deps): update dependency io.quarkus to v3.27.0 (apache#2663) Co-authored-by: Mend Renovate <bot@renovateapp.com> * Publish Develocity builds scans for PRs and local use (apache#2596) This PR enables Develocity build scans for all PRs and contributors w/o an Apache account. CI build scans in the `apache/polaris` repo against branches and tags and having access to the ASF's Develocity secret continue to publish to the ASF's Develocity instance (no behavioral change). All other build scans are published to Gradle's public Develocity instance: - Build scans from local developer (non-CI) runs are only published, if Gradle is invoked with the `--scan` option. - Build scans from or targeting another repository than `apache/polaris` do need be enabled explicity by accepting Gradle's terms of service, via a repository variable, because this is a decision of the owner of a repository. Advanced options to configure another Develocity server or project-ID are available (for non-`apache/polaris` repositories). Detailed instructions in the `README.md`. * Fix & enhancements to the Events API hierarchy (apache#2629) Summary of changes: - Turned `PolarisEventListener` into an interface to facilitate implementation / mocking - Added missing `implements PolarisEvent` to many event records - Removed unused method overrides - Added missing method overrides to `TestPolarisEventListener` * fix(deps): update dependency org.kordamp.gradle:jandex-gradle-plugin to v2.3.0 (apache#2694) * Auth: reorganize internal authentication components (apache#2634) This PR contains no functional and no user-facing change. It is merely a refactor to better organize auth code. Summary of changes: - Moved all internal authentication components to the `org.apache.polaris.service.auth.internal` package and subpackages - Reduced visibility of utility classes - Renamed `TokenBroker` class hierarchy to stick to the naming standard: `<Algorithm>JWTBroker` - Introduced `@PolarisImmutable` whenever appropriate - Removed unused `NoneTokenBrokerFactory` (we already have `DisabledOAuth2ApiService`) - Removed unused `TokenBrokerFactoryConfig` * Enhancement : adding support for Aurora postgres AWS IAM authentication (apache#2650) Add support for postgres AWS IAM authentication using the `apache-client` lib. * Remove unused `name` arg from findCatalogByName in PolarisAdminService (apache#2691) * remove unused name param * Rename for better readability * Fix a race condition in sendNotification where concurrent parent-namespace creation causes failures (apache#2693) * Fix a race condition in sendNotification where concurrent parent-namespace creation causes failures The semantics of the createNonExistingNamespaces method used during sendNotification were supposed to be "create if needed". However, the behavior ended up surfacing an AlreadyExistsException if multiple concurrent sendNotification attempts were made for a brand-new namespace (where the notifications may be different tables). This would cause a table sync to fail if a sibling table was being synced at the same time, even though the new table should successfully get created under the shared namespace. * Also better future-proof the createNamespaceInternal logic by explicitly checking for ENTITY_ALREADY_EXISTS, per review suggestion. Log a less scary message since it's not an error scenario type of race condition, per review suggestion * Client: add credential reset option (apache#2698) * Client: add credential reset option * Client: add credential reset option * Client: add credential reset option * Add integration testing * Fix lint * fix(deps): update dependency software.amazon.awssdk:bom to v2.34.5 (apache#2702) * fix(deps): update dependency com.gradleup.shadow:shadow-gradle-plugin to v9.2.2 (apache#2661) * Support S3 storage that does not have STS (apache#2672) * Support S3 storage that does not have STS This change is backward compatible with old catalogs that have storage configuration for S3 systems with STS. * Add new property to S3 storage config: `stsUnavailable` (defaults to "available"). * Do not call STS when unavailable in `AwsCredentialsStorageIntegration`, but still put other properties (e.g. s3.endpoint) into `AccessConfig` Relates to apache#2615 Relates apache#2207 * Docs/improve idp documentation (apache#2695) * Fix Github links in IDP documentation * Separate IDP docs for usage and development * - Add telemetry config example - Fix link to getting started from landing page - Fix mentioning role-arn as required * Fix some relative links (local Hugo resolves them properly, but PR auto checks still fails) * Docs: narrow down --role-arn usage for AWS S3 only; fix a link in keycloak guide. * Docs: fix a link in keycloak guide. * chore(deps): update gradle/actions digest to 748248d (apache#2708) * Client: fix integration testing (apache#2700) * Add fallback in case the VERSION table is not present (apache#2653) * initial commit * wire up * pastefix * change to postgres specific code * [Catalog Federation] Add feature flag to disallow setting sub-RBAC for federated catalog at catalog level (apache#2696) In apache#2688 (comment), we've identified that configuring polaris.config.enable-sub-catalog-rbac-for-federated-catalogs at catalog level should not be allowed in all cases, especially when the owner is not the same subject as the catalog user or admin. This PR add a feature flag, ALLOW_SETTING_SUB_CATALOG_RBAC_FOR_FEDERATED_CATALOGS to allow owner to disable catalog level setting polaris.config.enable-sub-catalog-rbac-for-federated-catalogs * Fix `delegationModes` parameter propagation in `createTableStaged()` (apache#2713) This is follow-up bugfix for apache#2589 The bugfix part apache#2711 is extracted here since apache#2711 proved to be non-trivial and may require extra time. * Use the `delegationModes` method parameter as intended (as opposed to a local constant). * Generate Request IDs (if not specified); Return Request ID as a Header (apache#2602) * fix(deps): update dependency org.junit:junit-bom to v5.14.0 (apache#2715) * NoSQL persistence: add Java/Vert.X executor abstraction layer (apache#2527) Provides an abstraction to submit asynchronous tasks, optionally with a delay or delay + repetition and implementations based on Java's `ThreadPoolExecutor` and Vert.X. * Fix RDS devservices config + adopt for `:polaris-admin:test` (apache#2723) Changes: * Disables devservices for `:polaris-admin` tests as well, which is necessary to _not_ spin up test containers. * Use the explicit devservices-config as everywhere else. The first bullet point can cause excessive memory usage, especially with more test classes, eventually killing the whole GH runner. * fix(deps): update dependency io.smallrye:jandex to v3.5.0 (apache#2722) * fix(deps): update dependency org.jboss.weld:weld-junit5 to v5.0.2.final (apache#2721) * chore(deps): update quay.io/keycloak/keycloak docker tag to v26.4.0 (apache#2719) * Last merged commit 4024557 * NoSQL: Minor-ish changes to "nodes" projects Adopt nodes projects to OSS PR content * NoSQL: adapt to async package rename * Build: remove unnecessary explicit vertx-core dependency The async-vertx implementation should not propagate a different Vert.X dependency than Quarkus provides. This wouldn't be an issue if we could just use `enforcedPlatform()` for all Quarkus-builds, but sadly we cannot for the spark-plugin-inttests. --------- Co-authored-by: Honah (Jonas) J. <honahx@apache.org> Co-authored-by: Pooja Nilangekar <poojan@umd.edu> Co-authored-by: Prashant Singh <35593236+singhpk234@users.noreply.github.com> Co-authored-by: JB Onofré <jbonofre@apache.org> Co-authored-by: Mend Renovate <bot@renovateapp.com> Co-authored-by: Alexandre Dutra <adutra@apache.org> Co-authored-by: fabio-rizzo-01 <fabio.rizzocascio@jpmorgan.com> Co-authored-by: Dennis Huo <7410123+dennishuo@users.noreply.github.com> Co-authored-by: Yong Zheng <yongzheng0809@gmail.com> Co-authored-by: Dmitri Bourlatchkov <dmitri.bourlatchkov@gmail.com> Co-authored-by: olsoloviov <40199597+olsoloviov@users.noreply.github.com> Co-authored-by: Eric Maynard <eric.maynard+oss@snowflake.com> Co-authored-by: Adnan Hemani <adnan.h@berkeley.edu>

olsoloviov added 3 commits September 24, 2025 10:05

Fix Github links in IDP documentation

4885317

Separate IDP docs for usage and development

e8ab330

- Add telemetry config example

34bebbe

- Fix link to getting started from landing page - Fix mentioning role-arn as required

github-project-automation bot added this to Basic Kanban Board Sep 26, 2025

github-project-automation bot moved this to PRs In Progress in Basic Kanban Board Sep 26, 2025

Fix some relative links (local Hugo resolves them properly, but PR au…

282cceb

…to checks still fails)

dimas-b reviewed Sep 26, 2025

View reviewed changes

dimas-b requested a review from adutra September 26, 2025 15:38

olsoloviov added 2 commits September 26, 2025 17:34

Docs: narrow down --role-arn usage for AWS S3 only; fix a link in key…

081ac24

…cloak guide.

Docs: fix a link in keycloak guide.

8f4f0c6

dimas-b approved these changes Sep 26, 2025

View reviewed changes

github-project-automation bot moved this from PRs In Progress to Ready to merge in Basic Kanban Board Sep 26, 2025

flyrain reviewed Sep 26, 2025

View reviewed changes

flyrain approved these changes Sep 26, 2025

View reviewed changes

adutra approved these changes Sep 29, 2025

View reviewed changes

dimas-b merged commit 2cfa41b into apache:main Sep 29, 2025
14 checks passed

github-project-automation bot moved this from Ready to merge to Done in Basic Kanban Board Sep 29, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Docs/improve idp documentation #2695

Docs/improve idp documentation #2695

Uh oh!

olsoloviov commented Sep 26, 2025

Uh oh!

dimas-b left a comment

Uh oh!

dimas-b Sep 26, 2025

Uh oh!

dimas-b Sep 26, 2025 •

edited

Loading

Uh oh!

olsoloviov Sep 26, 2025

Uh oh!

dimas-b Sep 26, 2025

Uh oh!

olsoloviov Sep 26, 2025

Uh oh!

flyrain left a comment

Uh oh!

flyrain Sep 26, 2025

Uh oh!

olsoloviov Sep 26, 2025

Uh oh!

flyrain Sep 26, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Docs/improve idp documentation #2695

Docs/improve idp documentation #2695

Uh oh!

Conversation

olsoloviov commented Sep 26, 2025

Uh oh!

dimas-b left a comment

Choose a reason for hiding this comment

Uh oh!

dimas-b Sep 26, 2025

Choose a reason for hiding this comment

Uh oh!

dimas-b Sep 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

olsoloviov Sep 26, 2025

Choose a reason for hiding this comment

Uh oh!

dimas-b Sep 26, 2025

Choose a reason for hiding this comment

Uh oh!

olsoloviov Sep 26, 2025

Choose a reason for hiding this comment

Uh oh!

flyrain left a comment

Choose a reason for hiding this comment

Uh oh!

flyrain Sep 26, 2025

Choose a reason for hiding this comment

Uh oh!

olsoloviov Sep 26, 2025

Choose a reason for hiding this comment

Uh oh!

flyrain Sep 26, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

dimas-b Sep 26, 2025 •

edited

Loading