Updating docs/overview.md and docs/access-control.md (#105)

Author: sfc-gh-jbasden

docs/access-control.md

@@ -18,25 +18,25 @@
 
 This section provides information about how access control works for Polaris Catalog.
 
-Polaris Catalog uses a role-based access control (RBAC) model, in which the Polaris administrator assigns access privileges to catalog roles,
-and then grants service principals access to resources by assigning catalog roles to principal roles.
+Polaris Catalog uses a role-based access control (RBAC) model in which the Polaris administrator assigns access privileges to catalog roles
+and then grants access to resources to service principals by assigning catalog roles to principal roles.
 
-The key concepts to understanding access control in Polaris are:
+These are the key concepts to understanding access control in Polaris:
 
--   **Securable object**
--   **Principal role**
--   **Catalog role**
--   **Privilege**
+- **Securable object**
+- **Principal role**
+- **Catalog role**
+- **Privilege**
 
 ## Securable object
 
 A securable object is an object to which access can be granted. Polaris
 has the following securable objects:
 
--   Catalog
--   Namespace
--   Iceberg table
--   View
+- Catalog
+- Namespace
+- Iceberg table
+- View
 
 ## Principal role
 
@@ -60,17 +60,17 @@ The following table shows examples of principal roles that you might configure i
 
 ## Catalog role
 
-A catalog role belongs to a particular catalog resource in Polaris and specifies a set of permissions for actions on the catalog, or on objects
+A catalog role belongs to a particular catalog resource in Polaris and specifies a set of permissions for actions on the catalog or objects
 in the catalog, such as catalog namespaces or tables. You can create one or more catalog roles for a catalog.
 
-You grant privileges to a catalog role, and then grant the catalog role to a principal role to bestow the privileges to one or more service
+You grant privileges to a catalog role and then grant the catalog role to a principal role to bestow the privileges to one or more service
 principals.
 
-**Note**
-
-If you update the privileges bestowed to a service principal, the updates won\'t take effect for up to one hour. This means that if you
-revoke or grant some privileges for a catalog, the updated privileges won\'t take effect on any service principal with access to that catalog
-for up to one hour.
+> **Note**
+>
+> If you update the privileges bestowed to a service principal, the updates won't take effect for up to one hour. This means that if you
+> revoke or grant some privileges for a catalog, the updated privileges won't take effect on any service principal with access to that catalog
+> for up to one hour.
 
 Polaris also supports a many-to-many relationship between catalog roles and principal roles. You can grant the same catalog role to one or more
 principal roles. Likewise, a principal role can be granted to one or more catalog roles.
@@ -87,102 +87,101 @@ configure in Polaris:
 ## RBAC model
 
 The following diagram illustrates the RBAC model used by Polaris Catalog. For each catalog, the Polaris administrator assigns access
-privileges to catalog roles, and then grants service principals access to resources by assigning catalog roles to principal roles. Polaris
+privileges to catalog roles and then grants service principals access to resources by assigning catalog roles to principal roles. Polaris
 supports a many-to-one relationship between service principals and principal roles.
 
-![Diagram that shows the RBAC model for Polaris Catalog.](./img/rbac-model.svg "Polaris Catalog RBAC model")
+![Diagram that shows the RBAC model for Polaris Catalog.](img/rbac-model.svg "Polaris Catalog RBAC model")
 
 ## Access control privileges
 
 This section describes the privileges that are available in the Polaris access control model. Privileges are granted to catalog roles, catalog
 roles are granted to principal roles, and principal roles are granted to service principals to specify the operations that service principals can
 perform on objects in Polaris.
 
+> **Important**
+>
+> You can only grant privileges at the catalog level. Fine-grained access controls are not available. For example, you can grant read 
+> privileges to all tables in a catalog but not to an individual table in the catalog.
+
 To grant the full set of privileges (drop, list, read, write, etc.) on an object, you can use the *full privilege* option.
 
 ### Table privileges
 
-**Note**
-
-The TABLE_FULL_METADATA full privilege doesn't grant access to the TABLE_READ_DATA or TABLE_WRITE_DATA individual privileges.
-
-| Full privilege | Individual privilege | Description |
-| -----------------------| ----------- | ---- |
-| TABLE_FULL_METADATA | TABLE_CREATE | Enables registering a table with the catalog. |
-|  | TABLE_DROP | Enables dropping a table from the catalog. |
-|  | TABLE_LIST | Enables listing any tables in the catalog. |
-|  | TABLE_READ_PROPERTIES | Enables reading [properties](https://iceberg.apache.org/docs/nightly/configuration/#table-properties) of the table. |
-|  | TABLE_WRITE_PROPERTIES | Enables configuring [properties](https://iceberg.apache.org/docs/nightly/configuration/#table-properties) for the table. |
-| N/A | TABLE_READ_DATA | Enables reading data from the table by receiving short-lived read-only storage credentials from the catalog. |
-| N/A | TABLE_WRITE_DATA | Enables writing data to the table by receiving short-lived read+write storage credentials from the catalog. |
+| Privilege | Description |
+| --------- | ----------- |
+| TABLE_CREATE | Enables registering a table with the catalog. |
+| TABLE_DROP | Enables dropping a table from the catalog. |
+| TABLE_LIST | Enables listing any tables in the catalog. |
+| TABLE_READ_PROPERTIES | Enables reading [properties](https://iceberg.apache.org/docs/nightly/configuration/#table-properties) of the table. |
+| TABLE_WRITE_PROPERTIES | Enables configuring [properties](https://iceberg.apache.org/docs/nightly/configuration/#table-properties) for the table. |
+| 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. |
 
 ### View privileges
 
-| Full privilege | Individual privilege | Description |
-| -----------------------| ----------- | ---- |
-| VIEW_FULL_METADATA | VIEW_CREATE  | Enables registering a view with the catalog. |
-|  | VIEW_DROP | Enables dropping a view from the catalog. |
-|  | VIEW_LIST | Enables listing any views in the catalog.  |
-|  | VIEW_READ_PROPERTIES | Enables reading all the view properties. |
-|  | VIEW_WRITE_PROPERTIES | Enables configuring view properties. |
+| Privilege | Description |
+| --------- | ----------- |
+| VIEW_CREATE  | Enables registering a view with the catalog. |
+| VIEW_DROP | Enables dropping a view from the catalog. |
+| VIEW_LIST | Enables listing any views in the catalog.  |
+| VIEW_READ_PROPERTIES | Enables reading all the view properties. |
+| VIEW_WRITE_PROPERTIES | Enables configuring view properties. |
+| VIEW_FULL_METADATA | Grants all view privileges. |
 
 ### Namespace privileges
 
-| Full privilege | Individual privilege | Description |
-| -----------------------| ----------- | ---- |
-| NAMESPACE_FULL_METADATA | NAMESPACE_CREATE | Enables creating a namespace in a catalog. |
-|  | NAMESPACE_DROP | Enables dropping the namespace from the catalog. |
-|  | NAMESPACE_LIST | Enables listing any object in the namespace, including nested namespaces and tables. |
-|  | NAMESPACE_READ_PROPERTIES | Enables reading all the namespace properties. |
-|  | NAMESPACE_WRITE_PROPERTIES | Enables configuring namespace properties. |
+| Privilege | Description |
+| --------- | ----------- |
+| NAMESPACE_CREATE | Enables creating a namespace in a catalog. |
+| NAMESPACE_DROP | Enables dropping the namespace from the catalog. |
+| NAMESPACE_LIST | Enables listing any object in the namespace, including nested namespaces and tables. |
+| NAMESPACE_READ_PROPERTIES | Enables reading all the namespace properties. |
+| NAMESPACE_WRITE_PROPERTIES | Enables configuring namespace properties. |
+| NAMESPACE_FULL_METADATA | Grants all namespace privileges. |
 
 ### Catalog privileges
 
 | Privilege | Description |
 | -----------------------| ----------- |
 | CATALOG_MANAGE_ACCESS | Includes the ability to grant or revoke privileges on objects in a catalog to catalog roles, and the ability to grant or revoke catalog roles to or from principal roles. |
 | CATALOG_MANAGE_CONTENT | Enables full management of content for the catalog. This privilege encompasses the following privileges:<ul><li>CATALOG_MANAGE_METADATA</li><li>TABLE_FULL_METADATA</li><li>NAMESPACE_FULL_METADATA</li><li>VIEW_FULL_METADATA</li><li>TABLE_WRITE_DATA</li><li>TABLE_READ_DATA</li><li>CATALOG_READ_PROPERTIES</li><li>CATALOG_WRITE_PROPERTIES</li></ul> |
-| CATALOG_MANAGE_METADATA | Enables full management of the catalog, as well as catalog roles, namespaces, and tables.  |
+| 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. |
 
 ## RBAC example
 
-The following diagram illustrates how RBAC works in Polaris, and
+The following diagram illustrates how RBAC works in Polaris and
 includes the following users:
 
--   **Alice**: A service admin who signs up for Polaris. Alice can
+- **Alice:** A service admin who signs up for Polaris. Alice can
     create service principals. She can also create catalogs and
-    namespaces, and configure access control for Polaris resources.
-
-> **Note**
->
-> The service principal for Alice is not visible in the Polaris Catalog
-> user interface.
+    namespaces and configure access control for Polaris resources.
 
--   **Bob**: A data engineer who uses Snowpipe Streaming (in Snowflake)
-    and Apache Spark connections to interact with Polaris.
+- **Bob:** A data engineer who uses Snowpipe Streaming (in Snowflake)
+    and Apache Spark&trade; connections to interact with Polaris.
 
-    -   Alice has created a service principal for Bob. It has been
+    - Alice has created a service principal for Bob. It has been
         granted the Data_engineer principal role, which in turn has been
         granted the following catalog roles: Catalog contributor and
         Data administrator (for both the Silver and Gold zone catalogs
         in the following diagram).
 
-    -   The Catalog contributor role grants permission to create
+    - The Catalog contributor role grants permission to create
         namespaces and tables in the Bronze zone catalog.
 
-    -   The Data administrator roles grant full administrative rights to
+    - The Data administrator roles grant full administrative rights to
         the Silver zone catalog and Gold zone catalog.
 
--   **Mark**: A data scientist who uses Snowflake AI services to
+- **Mark:** A data scientist who uses Snowflake AI services to
     interact with Polaris.
 
-    -   Alice has created a service principal for Mark. It has been
+    - Alice has created a service principal for Mark. It has been
         granted the Data_scientist principal role, which in turn has
         been granted the catalog role named Catalog reader.
 
-    -   The Catalog reader role grants read-only access for a catalog
+    - The Catalog reader role grants read-only access for a catalog
         named Gold zone catalog.
 
-![Diagram that shows an example of how RBAC works in Polaris Catalog.](./img/rbac-example.svg "Polaris Catalog RBAC example")
+![Diagram that shows an example of how RBAC works in Polaris Catalog.](img/rbac-example.svg "Polaris Catalog RBAC example")