Skip to content

Commit 237ce0c

Browse files
jbonofrejbonofre
committed
Add 0.9.0 documentation
1 parent 99f1fc3 commit 237ce0c

10 files changed

+2225
-15
lines changed

‎_index.adoc‎ renamed to ‎0.9.0/_index.md‎

Lines changed: 11 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -17,23 +17,19 @@
1717
# specific language governing permissions and limitations
1818
# under the License.
1919
#
20-
title: All Apache Polaris Versions
20+
title: 'POLARIS VERSION INDEX MD TEMPLATE'
21+
toc_hide: true
22+
hide_summary: true
23+
params:
24+
show_page_toc: false
2125
cascade:
22-
type: releases
26+
# The latest release specifies 'false', all others must be 'true'
27+
exclude_search: false
2328
params:
24-
no_list: true
25-
params:
26-
top_hidden: true
27-
# Parameter used to identify the "root" page over all released-version pages.
28-
all_releases_root: true
29+
show_page_toc: true
30+
# This file will be copied as `_index.md` into a new release's versioned docs folder.
2931
---
3032

31-
Please find all released Polaris versions in the sidebar.
32-
33-
{{% alert title="Info" color="primary" %}}
34-
35-
The whole `releases/` folder lives in a separate Git branch `versioned-docs` in the Polaris main repository.
36-
The main source tree would does not contain the `releases/` folder - the site itself renders fine for local development
37-
even without the `releases/` folder.
33+
== Apache Polaris version {{< releaseVersion >}}
3834

39-
{{% /alert %}}
35+
Download from ...

‎0.9.0/access-control.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
---
2+
#
3+
# Licensed to the Apache Software Foundation (ASF) under one
4+
# or more contributor license agreements. See the NOTICE file
5+
# distributed with this work for additional information
6+
# regarding copyright ownership. The ASF licenses this file
7+
# to you under the Apache License, Version 2.0 (the
8+
# "License"); you may not use this file except in compliance
9+
# with the License. You may obtain a copy of the License at
10+
#
11+
# http://www.apache.org/licenses/LICENSE-2.0
12+
#
13+
# Unless required by applicable law or agreed to in writing,
14+
# software distributed under the License is distributed on an
15+
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16+
# KIND, either express or implied. See the License for the
17+
# specific language governing permissions and limitations
18+
# under the License.
19+
#
20+
Title: Access Control
21+
type: docs
22+
weight: 500
23+
---
24+
25+
This section provides information about how access control works for Apache Polaris (Incubating).
26+
27+
Polaris uses a role-based access control (RBAC) model in which the Polaris administrator assigns access privileges to catalog roles
28+
and then grants access to resources to service principals by assigning catalog roles to principal roles.
29+
30+
These are the key concepts to understanding access control in Polaris:
31+
32+
- **Securable object**
33+
- **Principal role**
34+
- **Catalog role**
35+
- **Privilege**
36+
37+
## Securable object
38+
39+
A securable object is an object to which access can be granted. Polaris
40+
has the following securable objects:
41+
42+
- Catalog
43+
- Namespace
44+
- Iceberg table
45+
- View
46+
47+
## Principal role
48+
49+
A principal role is a resource in Polaris that you can use to logically group Polaris service principals together and grant privileges on
50+
securable objects.
51+
52+
Polaris supports a many-to-one relationship between service principals and principal roles. For example, to grant the same privileges to
53+
multiple service principals, you can grant a single principal role to those service principals. A service principal can be granted one
54+
principal role. When registering a service connection, the Polaris administrator specifies the principal role that is granted to the
55+
service principal.
56+
57+
You don't grant privileges directly to a principal role. Instead, you configure object permissions at the catalog role level, and then grant
58+
catalog roles to a principal role.
59+
60+
The following table shows examples of principal roles that you might configure in Polaris:
61+
62+
| Principal role name | Description |
63+
| -----------------------| ----------- |
64+
| Data_engineer | A role that is granted to multiple service principals for running data engineering jobs. |
65+
| Data_scientist | A role that is granted to multiple service principals for running data science or AI jobs. |
66+
67+
## Catalog role
68+
69+
A catalog role belongs to a particular catalog resource in Polaris and specifies a set of permissions for actions on the catalog or objects
70+
in the catalog, such as catalog namespaces or tables. You can create one or more catalog roles for a catalog.
71+
72+
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
73+
principals.
74+
75+
> **Note**
76+
>
77+
> 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
78+
> revoke or grant some privileges for a catalog, the updated privileges won't take effect on any service principal with access to that catalog
79+
> for up to one hour.
80+
81+
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
82+
principal roles. Likewise, a principal role can be granted to one or more catalog roles.
83+
84+
The following table displays examples of catalog roles that you might
85+
configure in Polaris:
86+
87+
| Example Catalog role | Description |
88+
| -----------------------| ----------- |
89+
| Catalog administrators | A role that has been granted multiple privileges to emulate full access to the catalog.<br /><br />Principal roles that have been granted this role are permitted to create, alter, read, write, and drop tables in the catalog. |
90+
| Catalog readers | A role that has been granted read-only privileges to tables in the catalog.<br /><br />Principal roles that have been granted this role are allowed to read from tables in the catalog. |
91+
| Catalog contributor | A role that has been granted read and write access privileges to all tables that belong to the catalog.<br /><br />Principal roles that have been granted this role are allowed to perform read and write operations on tables in the catalog. |
92+
93+
## RBAC model
94+
95+
The following diagram illustrates the RBAC model used by Polaris. For each catalog, the Polaris administrator assigns access
96+
privileges to catalog roles and then grants service principals access to resources by assigning catalog roles to principal roles. Polaris
97+
supports a many-to-one relationship between service principals and principal roles.
98+
99+
![Diagram that shows the RBAC model for Apache Polaris.](/img/rbac-model.svg "Apache Polaris RBAC model")
100+
101+
## Access control privileges
102+
103+
This section describes the privileges that are available in the Polaris access control model. Privileges are granted to catalog roles, catalog
104+
roles are granted to principal roles, and principal roles are granted to service principals to specify the operations that service principals can
105+
perform on objects in Polaris.
106+
107+
> **Important**
108+
>
109+
> You can only grant privileges at the catalog level. Fine-grained access controls are not available. For example, you can grant read
110+
> privileges to all tables in a catalog but not to an individual table in the catalog.
111+
112+
To grant the full set of privileges (drop, list, read, write, etc.) on an object, you can use the *full privilege* option.
113+
114+
### Table privileges
115+
116+
| Privilege | Description |
117+
| --------- | ----------- |
118+
| TABLE_CREATE | Enables registering a table with the catalog. |
119+
| TABLE_DROP | Enables dropping a table from the catalog. |
120+
| TABLE_LIST | Enables listing any tables in the catalog. |
121+
| TABLE_READ_PROPERTIES | Enables reading [properties](https://iceberg.apache.org/docs/nightly/configuration/#table-properties) of the table. |
122+
| TABLE_WRITE_PROPERTIES | Enables configuring [properties](https://iceberg.apache.org/docs/nightly/configuration/#table-properties) for the table. |
123+
| TABLE_READ_DATA | Enables reading data from the table by receiving short-lived read-only storage credentials from the catalog. |
124+
| TABLE_WRITE_DATA | Enables writing data to the table by receiving short-lived read+write storage credentials from the catalog. |
125+
| TABLE_FULL_METADATA | Grants all table privileges, except TABLE_READ_DATA and TABLE_WRITE_DATA, which need to be granted individually. |
126+
127+
### View privileges
128+
129+
| Privilege | Description |
130+
| --------- | ----------- |
131+
| VIEW_CREATE | Enables registering a view with the catalog. |
132+
| VIEW_DROP | Enables dropping a view from the catalog. |
133+
| VIEW_LIST | Enables listing any views in the catalog. |
134+
| VIEW_READ_PROPERTIES | Enables reading all the view properties. |
135+
| VIEW_WRITE_PROPERTIES | Enables configuring view properties. |
136+
| VIEW_FULL_METADATA | Grants all view privileges. |
137+
138+
### Namespace privileges
139+
140+
| Privilege | Description |
141+
| --------- | ----------- |
142+
| NAMESPACE_CREATE | Enables creating a namespace in a catalog. |
143+
| NAMESPACE_DROP | Enables dropping the namespace from the catalog. |
144+
| NAMESPACE_LIST | Enables listing any object in the namespace, including nested namespaces and tables. |
145+
| NAMESPACE_READ_PROPERTIES | Enables reading all the namespace properties. |
146+
| NAMESPACE_WRITE_PROPERTIES | Enables configuring namespace properties. |
147+
| NAMESPACE_FULL_METADATA | Grants all namespace privileges. |
148+
149+
### Catalog privileges
150+
151+
| Privilege | Description |
152+
| -----------------------| ----------- |
153+
| 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. |
154+
| 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> |
155+
| CATALOG_MANAGE_METADATA | Enables full management of the catalog, catalog roles, namespaces, and tables. |
156+
| CATALOG_READ_PROPERTIES | Enables listing catalogs and reading properties of the catalog. |
157+
| CATALOG_WRITE_PROPERTIES | Enables configuring catalog properties. |
158+
159+
## RBAC example
160+
161+
The following diagram illustrates how RBAC works in Polaris and
162+
includes the following users:
163+
164+
- **Alice:** A service admin who signs up for Polaris. Alice can
165+
create service principals. She can also create catalogs and
166+
namespaces and configure access control for Polaris resources.
167+
168+
- **Bob:** A data engineer who uses Apache Spark&trade; to
169+
interact with Polaris.
170+
171+
- Alice has created a service principal for Bob. It has been
172+
granted the Data_engineer principal role, which in turn has been
173+
granted the following catalog roles: Catalog contributor and
174+
Data administrator (for both the Silver and Gold zone catalogs
175+
in the following diagram).
176+
177+
- The Catalog contributor role grants permission to create
178+
namespaces and tables in the Bronze zone catalog.
179+
180+
- The Data administrator roles grant full administrative rights to
181+
the Silver zone catalog and Gold zone catalog.
182+
183+
- **Mark:** A data scientist who uses trains models with data managed
184+
by Polaris.
185+
186+
- Alice has created a service principal for Mark. It has been
187+
granted the Data_scientist principal role, which in turn has
188+
been granted the catalog role named Catalog reader.
189+
190+
- The Catalog reader role grants read-only access for a catalog
191+
named Gold zone catalog.
192+
193+
![Diagram that shows an example of how RBAC works in Apache Polaris.](/img/rbac-example.svg "Apache Polaris RBAC example")

0 commit comments

Comments
 (0)