Doc: Add policy documentation (#1460)

Author: gfakbar20

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
 

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.