Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
annafil merged 1 commit into from
Aug 8, 2024
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 64 additions & 65 deletions docs/access-control.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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.
Expand All @@ -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")
444 changes: 202 additions & 242 deletions docs/index.html
View file
Open in desktop

Large diffs are not rendered by default.

Loading