This is an automated email from the ASF dual-hosted git repository.
yufei pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/polaris.git
The following commit(s) were added to refs/heads/main by this push:
new 1fb194ed5 Doc: Add policy documentation (#1460)
1fb194ed5 is described below
commit 1fb194ed58f730a7ff9b3af0f8777078fab04c72
Author: gfakbar20 <[email protected]>
AuthorDate: Sun Apr 27 04:22:33 2025 +0700
Doc: Add policy documentation (#1460)
---
site/content/in-dev/unreleased/access-control.md | 19 +++++++++++++++++++
site/content/in-dev/unreleased/entities.md | 8 ++++++--
2 files changed, 25 insertions(+), 2 deletions(-)
diff --git a/site/content/in-dev/unreleased/access-control.md
b/site/content/in-dev/unreleased/access-control.md
index c94458521..560fd9e96 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,21 @@ 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
+
+| 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 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. |
+| 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 c0ee241a9..04d625bb9 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,13 +70,18 @@ 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.
+## Policy
+
+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 of the same type declared at the higher level
entities.
+
## 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.
