Skip to content

Commit

Permalink
[#5033] improvement(docs): Add the documents about access control (#5044
Browse files Browse the repository at this point in the history 
)

### What changes were proposed in this pull request?

Add the documents about access control.

### Why are the changes needed?

Fix: #5033

### Does this PR introduce _any_ user-facing change?
No.

### How was this patch tested?
Just docs.

Co-authored-by: roryqi <[email protected]>
  • Loading branch information
@github-actions @jerqi
github-actions[bot] and jerqi authored Sep 29, 2024
1 parent a0dee14 commit 66948cd
Show file tree
Hide file tree
Showing 7 changed files with 598 additions and 37 deletions.
79 changes: 79 additions & 0 deletions docs/open-api/groups.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,42 @@ paths:
parameters:
- $ref: "./openapi.yaml#/components/parameters/metalake"

get:
tags:
- access control
summary: List groups (names)
operationId: listGroups
parameters:
- $ref: "#/components/parameters/details"
responses:
"200":
description: Returns the list of groups if {details} is true, otherwise returns the list of group name
content:
application/vnd.gravitino.v1+json:
schema:
oneOf:
- $ref: "#/components/responses/GroupListResponse"
- $ref: "./openapi.yaml#/components/schemas/NameListResponse"
examples:
GroupListResponse:
$ref: "#/components/examples/GroupListResponse"
NameListResponse:
$ref: "#/components/examples/NameListResponse"
"400":
$ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse"
"404":
description: Not Found - The specified metalake does not exist
content:
application/vnd.gravitino.v1+json:
schema:
$ref: "./openapi.yaml#/components/schemas/ErrorModel"
examples:
NoSuchMetalakeException:
$ref: "./metalakes.yaml#/components/examples/NoSuchMetalakeException"

"5xx":
$ref: "./openapi.yaml#/components/responses/ServerErrorResponse"

post:
tags:
- access control
Expand Down Expand Up @@ -108,6 +144,15 @@ paths:
$ref: "./openapi.yaml#/components/responses/ServerErrorResponse"

components:
parameters:
details:
name: details
in: query
description: Include detailed information about the group
required: false
schema:
type: boolean
default: false

schemas:
Group:
Expand Down Expand Up @@ -148,12 +193,33 @@ components:
group:
$ref: "#/components/schemas/Group"

GroupListResponse:
type: object
properties:
code:
type: integer
format: int32
description: Status code of the response
enum:
- 0
groups:
type: array
description: A list of group objects
items:
$ref: "#/components/schemas/Group"

examples:
GroupAddRequest:
value: {
"name": "group1",
}

NameListResponse:
value: {
"code": 0,
"names": [ "group1", "group2" ]
}

GroupResponse:
value: {
"code": 0,
Expand All @@ -167,6 +233,19 @@ components:
}
}

GroupListResponse:
value: {
"code": 0,
"groups": [{
"name": "group1",
"roles": [],
"audit": {
"creator": "gravitino",
"createTime": "2023-12-08T06:41:25.595Z"
},
}]
}

GroupAlreadyExistsException:
value: {
"code": 1004,
Expand Down
24 changes: 23 additions & 1 deletion docs/open-api/openapi.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,9 @@ paths:
/metalakes/{metalake}/objects/{metadataObjectType}/{metadataObjectFullName}/tags:
$ref: "./tags.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1objects~1%7BmetadataObjectType%7D~1%7BmetadataObjectFullName%7D~1tags"

/metalakes/{metalake}/objects/{metadataObjectType}/{metadataObjectFullName}/roles:
$ref: "./roles.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1objects~1%7BmetadataObjectType%7D~1%7BmetadataObjectFullName%7D~1roles"

/metalakes/{metalake}/objects/{metadataObjectType}/{metadataObjectFullName}/tags/{tag}:
$ref: "./tags.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1objects~1%7BmetadataObjectType%7D~1%7BmetadataObjectFullName%7D~1tags~1%7Btag%7D"

Expand Down Expand Up @@ -144,6 +147,12 @@ paths:
/metalakes/{metalake}/permissions/groups/{group}/revoke:
$ref: "./permissions.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1permissions~1groups~1%7Bgroup%7D~1revoke"

/metalakes/{metalake}/permissions/roles/{role}/{metadataObjectType}/{metadataObjectFullName}/grant:
$ref: "./permissions.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1permissions~1roles~1%7Brole%7D~1%7BmetadataObjectType%7D~1%7BmetadataObjectFullName%7D~1grant"

/metalakes/{metalake}/permissions/roles/{role}/{metadataObjectType}/{metadataObjectFullName}/revoke:
$ref: "./permissions.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1permissions~1roles~1%7Brole%7D~1%7BmetadataObjectType%7D~1%7BmetadataObjectFullName%7D~1revoke"

components:

schemas:
Expand Down Expand Up @@ -208,8 +217,21 @@ components:
type: string
description: The name of the entity

responses:
NameListResponse:
type: object
properties:
code:
type: integer
format: int32
description: Status code of the response
enum:
- 0
names:
type: array
items:
type: string

responses:
EntityListResponse:
description: A list of entities
content:
Expand Down
152 changes: 138 additions & 14 deletions docs/open-api/permissions.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -207,23 +207,108 @@ paths:
"5xx":
$ref: "./openapi.yaml#/components/responses/ServerErrorResponse"

/metalakes/{metalake}/permissions/roles/{role}/{metadataObjectType}/{metadataObjectFullName}/grant:
parameters:
- $ref: "./openapi.yaml#/components/parameters/metalake"
- $ref: "./openapi.yaml#/components/parameters/role"
- $ref: "./openapi.yaml#/components/parameters/metadataObjectType"
- $ref: "./openapi.yaml#/components/parameters/metadataObjectFullName"

put:
tags:
- access control
summary: Grant privileges to a role
operationId: grantPrivilegeToRole
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/PrivilegeGrantRequest"
examples:
PrivilegeGrantRequest:
$ref: "#/components/examples/PrivilegeGrantRequest"

responses:
"200":
description: Returns the granted role object
content:
application/vnd.gravitino.v1+json:
schema:
$ref: "./roles.yaml#/components/responses/RoleResponse"
examples:
GroupResponse:
$ref: "./roles.yaml#/components/examples/RoleResponse"

"404":
description: Not Found - The specified medata object or role does not exist in the specified metalake
content:
application/vnd.gravitino.v1+json:
schema:
$ref: "./openapi.yaml#/components/schemas/ErrorModel"
examples:
NoSuchMetalakeException:
$ref: "./metalakes.yaml#/components/examples/NoSuchMetalakeException"
NoSuchMetadataObjectException:
$ref: "./roles.yaml#/components/examples/NoSuchMetadataObjectException"
NoSuchRoleException:
$ref: "./roles.yaml#/components/examples/NoSuchRoleException"

"5xx":
$ref: "./openapi.yaml#/components/responses/ServerErrorResponse"

/metalakes/{metalake}/permissions/roles/{role}/{metadataObjectType}/{metadataObjectFullName}/revoke:
parameters:
- $ref: "./openapi.yaml#/components/parameters/metalake"
- $ref: "./openapi.yaml#/components/parameters/role"
- $ref: "./openapi.yaml#/components/parameters/metadataObjectType"
- $ref: "./openapi.yaml#/components/parameters/metadataObjectFullName"

put:
tags:
- access control
summary: Revoke privileges from a role
operationId: revokePrivilegeFromRole
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/PrivilegeRevokeRequest"
examples:
PrivilegeRevokeRequest:
$ref: "#/components/examples/PrivilegeRevokeRequest"

responses:
"200":
description: Returns the revoked role object
content:
application/vnd.gravitino.v1+json:
schema:
$ref: "./roles.yaml#/components/responses/RoleResponse"
examples:
GroupResponse:
$ref: "./roles.yaml#/components/examples/RoleResponse"

"404":
description: Not Found - The specified medata object or role does not exist in the specified metalake
content:
application/vnd.gravitino.v1+json:
schema:
$ref: "./openapi.yaml#/components/schemas/ErrorModel"
examples:
NoSuchMetalakeException:
$ref: "./metalakes.yaml#/components/examples/NoSuchMetalakeException"
NoSuchMetadataObjectException:
$ref: "./roles.yaml#/components/examples/NoSuchMetadataObjectException"
NoSuchRoleException:
$ref: "./roles.yaml#/components/examples/NoSuchRoleException"

"5xx":
$ref: "./openapi.yaml#/components/responses/ServerErrorResponse"


components:

schemas:
User:
type: object
required:
- name
properties:
name:
type: string
description: The name of the user
roles:
type: array
items:
type: string
description: The roles of the user

RoleGrantRequest:
type: object
required:
Expand All @@ -246,6 +331,27 @@ components:
items:
type: string

PrivilegeGrantRequest:
type: object
required:
- privileges
properties:
privileges:
type: array
description: The privileges need to grant
items:
$ref: "./roles.yaml#/components/schemas/Privilege"

PrivilegeRevokeRequest:
type: object
required:
- privileges
properties:
privileges:
type: array
description: The privileges need to revoke
items:
$ref: "./roles.yaml#/components/schemas/Privilege"

examples:

Expand All @@ -257,4 +363,22 @@ components:
RoleRevokeRequest:
value: {
"roleNames": [ "role1" ],
}

PrivilegeGrantRequest:
value: {
"privileges": [
{
"name": "SELECT_TABLE",
"condition": "ALLOW"
} ]
}

PrivilegeRevokeRequest:
value: {
"privileges": [
{
"name": "SELECT_TABLE",
"condition": "ALLOW"
} ]
}
Loading

0 comments on commit 66948cd

Please sign in to comment.