From 1d66283a6812b3b00ed47f21e9d32fbc39ee927c Mon Sep 17 00:00:00 2001 From: gfakbar20 Date: Thu, 24 Apr 2025 22:22:45 +0700 Subject: [PATCH 1/4] Add polaris policy documentation --- site/content/in-dev/unreleased/access-control.md | 11 +++++++++++ site/content/in-dev/unreleased/entities.md | 4 ++++ 2 files changed, 15 insertions(+) diff --git a/site/content/in-dev/unreleased/access-control.md b/site/content/in-dev/unreleased/access-control.md index c944585210..67a1218f06 100644 --- a/site/content/in-dev/unreleased/access-control.md +++ b/site/content/in-dev/unreleased/access-control.md @@ -156,6 +156,17 @@ To grant the full set of privileges (drop, list, read, write, etc.) on an object | CATALOG_READ_PROPERTIES | Enables listing catalogs and reading properties of the catalog. | | CATALOG_WRITE_PROPERTIES | Enables configuring catalog properties. | +### Policy privileges + +| Privilege | Description | +| -----------------------| ----------- | +| POLICY_CREATE | Enables creating a policy under specified namespace | +| POLICY_READ | Enables reading policy content and metadata | +| POLICY_WRITE | Enables updating the policy details such as | +| POLICY_LIST | Enable listing any policy from the catalog | +| POLICY_DROP | Enable dropping a policy if it is not attached to any resource entity | +| POLICY_FULL_METADATA | Grants all policy privileges. | + ## RBAC example The following diagram illustrates how RBAC works in Polaris and diff --git a/site/content/in-dev/unreleased/entities.md b/site/content/in-dev/unreleased/entities.md index c0ee241a94..188ec2daaf 100644 --- a/site/content/in-dev/unreleased/entities.md +++ b/site/content/in-dev/unreleased/entities.md @@ -82,6 +82,10 @@ Each catalog role may have multiple [privileges](#privilege) granted to it, and Polaris privileges are granted to [catalog roles](#catalog-role) in order to grant principals with a given principal role some degree of access to catalogs with a given catalog role. When a privilege is granted to a catalog role, any principal roles granted that catalog role receive the privilege. In turn, any principals who are granted that principal role receive it. +## Policy + +Polaris policy is a set of rules governing actions on specified resources under predefined conditions. + A privilege can be scoped to any entity inside a catalog, including the catalog itself. For a list of supported privileges for each privilege class, see the API docs: From 5c659b8112786230d40256240e7070586b29d0ab Mon Sep 17 00:00:00 2001 From: gfakbar20 Date: Thu, 24 Apr 2025 22:42:09 +0700 Subject: [PATCH 2/4] proof read fix --- site/content/in-dev/unreleased/access-control.md | 6 +++--- site/content/in-dev/unreleased/entities.md | 10 ++++------ 2 files changed, 7 insertions(+), 9 deletions(-) diff --git a/site/content/in-dev/unreleased/access-control.md b/site/content/in-dev/unreleased/access-control.md index 67a1218f06..b19687a517 100644 --- a/site/content/in-dev/unreleased/access-control.md +++ b/site/content/in-dev/unreleased/access-control.md @@ -162,9 +162,9 @@ To grant the full set of privileges (drop, list, read, write, etc.) on an object | -----------------------| ----------- | | POLICY_CREATE | Enables creating a policy under specified namespace | | POLICY_READ | Enables reading policy content and metadata | -| POLICY_WRITE | Enables updating the policy details such as | -| POLICY_LIST | Enable listing any policy from the catalog | -| POLICY_DROP | Enable dropping a policy if it is not attached to any resource entity | +| POLICY_WRITE | Enables updating the policy details such as its content or description | +| POLICY_LIST | Enables listing any policy from the catalog | +| POLICY_DROP | Enables dropping a policy if it is not attached to any resource entity | | POLICY_FULL_METADATA | Grants all policy privileges. | ## RBAC example diff --git a/site/content/in-dev/unreleased/entities.md b/site/content/in-dev/unreleased/entities.md index 188ec2daaf..7f7eeccb5a 100644 --- a/site/content/in-dev/unreleased/entities.md +++ b/site/content/in-dev/unreleased/entities.md @@ -46,7 +46,6 @@ In Polaris, namespaces can be nested. For example, `a.b.c.d.e.f.g` is a valid na For information on managing namespaces with the REST API or for more information on what data can be associated with a namespace, see [the API docs]({{% github-polaris "client/python/docs/CreateNamespaceRequest.md" %}}). - ## Table Polaris tables are entities that map to [Apache Iceberg tables](https://iceberg.apache.org/docs/nightly/configuration/), [Delta tables](https://docs.databricks.com/aws/en/delta/table-properties), or [Hudi tables](https://hudi.apache.org/docs/next/configurations#TABLE_CONFIG). @@ -71,21 +70,20 @@ Polaris principal roles are labels that may be granted to [principals](#principa For information on managing principal roles with the REST API or for more information on what data can be associated with a principal role, see [the API docs]({{% github-polaris "client/python/docs/CreatePrincipalRoleRequest.md" %}}). - ## Catalog Role Polaris catalog roles are labels that may be granted to [catalogs](#catalog). Each catalog may have one or more catalog roles, and the same catalog role may be granted to multiple catalogs. Catalog roles may be assigned based on the nature of data that will reside in a catalog, or by the groups of users and services that might need to access that data. Each catalog role may have multiple [privileges](#privilege) granted to it, and each catalog role can be granted to one or more [principal roles](#principal-role). This is the mechanism by which principals are granted access to entities inside a catalog such as namespaces and tables. -## Privilege - -Polaris privileges are granted to [catalog roles](#catalog-role) in order to grant principals with a given principal role some degree of access to catalogs with a given catalog role. When a privilege is granted to a catalog role, any principal roles granted that catalog role receive the privilege. In turn, any principals who are granted that principal role receive it. - ## Policy Polaris policy is a set of rules governing actions on specified resources under predefined conditions. +## Privilege + +Polaris privileges are granted to [catalog roles](#catalog-role) in order to grant principals with a given principal role some degree of access to catalogs with a given catalog role. When a privilege is granted to a catalog role, any principal roles granted that catalog role receive the privilege. In turn, any principals who are granted that principal role receive it. + A privilege can be scoped to any entity inside a catalog, including the catalog itself. For a list of supported privileges for each privilege class, see the API docs: From 8a701dba62b4661ad9e3a67418bcfc8b5fef50f9 Mon Sep 17 00:00:00 2001 From: gfakbar20 Date: Fri, 25 Apr 2025 21:10:10 +0700 Subject: [PATCH 3/4] add more elaborate description of policy --- site/content/in-dev/unreleased/entities.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/site/content/in-dev/unreleased/entities.md b/site/content/in-dev/unreleased/entities.md index 7f7eeccb5a..c8dd7304ce 100644 --- a/site/content/in-dev/unreleased/entities.md +++ b/site/content/in-dev/unreleased/entities.md @@ -78,7 +78,9 @@ Each catalog role may have multiple [privileges](#privilege) granted to it, and ## Policy -Polaris policy is a set of rules governing actions on specified resources under predefined conditions. +Polaris policy is a set of rules governing actions on specified resources under predefined conditions. Polaris support policy for table compaction, snapshot retention, row-level access control, and custom policy definitions. + +Policy can be applied at catalog level, namespace level, or table level. Policy inheritance can be achieved by attaching one to a higher-level scope, such as namespace or catalog. As a result, tables registered under those entities do not need to be declared individually for the same policy. If a table or a namespace requires a different policy, user can assign a different policy, hence overriding policy declared at the higher level entities. ## Privilege From c7977a48a43cf0401f22916ac8c9f18bffffccea Mon Sep 17 00:00:00 2001 From: gfakbar20 Date: Sat, 26 Apr 2025 17:08:47 +0700 Subject: [PATCH 4/4] back up commit - add other policy documentation. --- site/content/in-dev/unreleased/access-control.md | 8 ++++++++ site/content/in-dev/unreleased/entities.md | 4 ++-- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/site/content/in-dev/unreleased/access-control.md b/site/content/in-dev/unreleased/access-control.md index b19687a517..560fd9e961 100644 --- a/site/content/in-dev/unreleased/access-control.md +++ b/site/content/in-dev/unreleased/access-control.md @@ -123,6 +123,8 @@ To grant the full set of privileges (drop, list, read, write, etc.) on an object | TABLE_READ_DATA | Enables reading data from the table by receiving short-lived read-only storage credentials from the catalog. | | TABLE_WRITE_DATA | Enables writing data to the table by receiving short-lived read+write storage credentials from the catalog. | | TABLE_FULL_METADATA | Grants all table privileges, except TABLE_READ_DATA and TABLE_WRITE_DATA, which need to be granted individually. | +| TABLE_ATTACH_POLICY | Enables attaching policy to a table. Applying policy at a table will override the same policy type defined at namespace and catalog | +| TABLE_DETACH_POLICY | Enables detaching policy from a table | ### View privileges @@ -145,6 +147,8 @@ To grant the full set of privileges (drop, list, read, write, etc.) on an object | NAMESPACE_READ_PROPERTIES | Enables reading all the namespace properties. | | NAMESPACE_WRITE_PROPERTIES | Enables configuring namespace properties. | | NAMESPACE_FULL_METADATA | Grants all namespace privileges. | +| NAMESPACE_ATTACH_POLICY | Enables attaching policy to a namespace. A policy applied at this level will override the same policy type define at the parent namespace and catalog and all entities registered under the namespace will inherit this policy unless they have a different policy of the same type. Only inheritable policy such as, table compaction and snapshot expiry policy are allowed in this level. | +| NAMESPACE_DETACH_POLICY | Enables detaching policy from a namespace. | ### Catalog privileges @@ -155,6 +159,8 @@ To grant the full set of privileges (drop, list, read, write, etc.) on an object | CATALOG_MANAGE_METADATA | Enables full management of the catalog, catalog roles, namespaces, and tables. | | CATALOG_READ_PROPERTIES | Enables listing catalogs and reading properties of the catalog. | | CATALOG_WRITE_PROPERTIES | Enables configuring catalog properties. | +| NAMESPACE_ATTACH_POLICY | Enables attaching policy to a catalog. All entities registered under the namespace will inherit this policy unless they have a different policy of the same type. Only inheritable policy such as, table compaction and snapshot expiry policy are allowed in this level. | +| CATALOG_DETACH_POLICY | Enables detaching policy from a catalog. | ### Policy privileges @@ -166,6 +172,8 @@ To grant the full set of privileges (drop, list, read, write, etc.) on an object | POLICY_LIST | Enables listing any policy from the catalog | | POLICY_DROP | Enables dropping a policy if it is not attached to any resource entity | | POLICY_FULL_METADATA | Grants all policy privileges. | +| POLICY_ATTACH | Enables policy to be attached to entities | +| POLICY_DETACH | Enables policy to be detached from entities | ## RBAC example diff --git a/site/content/in-dev/unreleased/entities.md b/site/content/in-dev/unreleased/entities.md index c8dd7304ce..04d625bb94 100644 --- a/site/content/in-dev/unreleased/entities.md +++ b/site/content/in-dev/unreleased/entities.md @@ -78,9 +78,9 @@ Each catalog role may have multiple [privileges](#privilege) granted to it, and ## Policy -Polaris policy is a set of rules governing actions on specified resources under predefined conditions. Polaris support policy for table compaction, snapshot retention, row-level access control, and custom policy definitions. +Polaris policy is a set of rules governing actions on specified resources under predefined conditions. Polaris support policy for Iceberg table compaction, snapshot expiry, row-level access control, and custom policy definitions. -Policy can be applied at catalog level, namespace level, or table level. Policy inheritance can be achieved by attaching one to a higher-level scope, such as namespace or catalog. As a result, tables registered under those entities do not need to be declared individually for the same policy. If a table or a namespace requires a different policy, user can assign a different policy, hence overriding policy declared at the higher level entities. +Policy can be applied at catalog level, namespace level, or table level. Policy inheritance can be achieved by attaching one to a higher-level scope, such as namespace or catalog. As a result, tables registered under those entities do not need to be declared individually for the same policy. If a table or a namespace requires a different policy, user can assign a different policy, hence overriding policy of the same type declared at the higher level entities. ## Privilege