RBAC server implementation documentation #8886
Conversation
|
🎊 PR Preview 21dc28c has been successfully built and deployed to https://treeverse-lakeFS-preview-pr-8886.surge.sh 🕐 Build time: 0.011s
🤖 By surge-preview |
E2E Test Results - Quickstart |
E2E Test Results - DynamoDB Local - Local Block Adapter |
Annaseli
added
docs
|
@Annaseli Is this ready for review? |
api/authorization.yml
Outdated
| parameters: | ||
| PaginationPrefix: | ||
| description: Indicates the prefix that all returned items must start with. lakeFS uses this value to filter |
There was a problem hiding this comment.
Relevant to the complete file - remove the use of lakeFS in the description as it makes the spec focus on lakeFS service while it is important to describe the use-case without specifying the component name.
There was a problem hiding this comment.
@nopcoder
I removed all mentions of lakeFS except for this one:
- in: query
description: Used only in lakeFS Enterprise; not applicable in the lakeFS OSS version.
name: external_id
schema:
type: string
Should I replace "Used only in lakeFS Enterprise; not applicable in the lakeFS OSS version." with "For internal use only"?
api/authorization.yml
Outdated
| max_per_page: | ||
| type: integer | ||
| minimum: 0 | ||
| description: Maximal number of entries per page | ||
| description: Maximum number of entries per page. Not currently used, so it can be set to 0. |
There was a problem hiding this comment.
Maximum number of entries per page. Set to zero when not in use.
There was a problem hiding this comment.
@nopcoder
I wanted to note that while we expect this Pagination schema in the response, we don’t actually use the max_per_page parameter. Should I update the description to:
“Maximum number of entries per page. Not used internally.”?
api/authorization.yml
Outdated
| external_id: | ||
| type: string | ||
| description: For internal usage. Can be empty. |
There was a problem hiding this comment.
The field is not required so no need to add the description for this one or the other that it can be empty - unless empty value "" have a meaning.
There was a problem hiding this comment.
@nopcoder
Should I write: "description: For internal use only."
or would it be better to remove the description completely?
There was a problem hiding this comment.
general description at the level of the operation/api will explain that the data should be loaded/stored. on the field itself if we want to specify what the field does we can - in this case we use the field for external system association.
|
@nopcoder |
|
feel free to push updates, I'll restart tomorrow |
…ile with Swagger colors.
…le of contents and notes and updated the links for the authorization.yml file to show up in a page.
Annaseli
force-pushed
the
docs/document-RBAC-implementation-684
branch
from
21ea119 to
ce2843e
Compare
| description: Specifies the number of items the server should return. It is used to determine how many results to | ||
| display on the current page. |
There was a problem hiding this comment.
without the "display" and "current page" - we describe API and not the usage
| encryptedPassword: | ||
| deprecated: true |
There was a problem hiding this comment.
this is new? we no longer use this field?
| - in: query | ||
| deprecated: true | ||
| name: id | ||
| allowEmptyValue: true | ||
| schema: | ||
| type: integer | ||
| format: int64 | ||
| - in: query | ||
| deprecated: true |
There was a problem hiding this comment.
If the deprecation is new I suggest to do it in a non documentation PR
| name: email | ||
| allowEmptyValue: true | ||
| schema: | ||
| type: string | ||
| - in: query | ||
| description: Used only in lakeFS Enterprise; not applicable in the lakeFS OSS version. |
There was a problem hiding this comment.
Used by the implementor to link external system
| - `PUT /auth/policies/{policyId}` | ||
| - `DELETE /auth/policies/{policyId}` | ||
|
|
||
| ### 2. LakeFS Configuration |
There was a problem hiding this comment.
| ### 2. LakeFS Configuration | |
| ### 2. lakeFS Configuration |
| rbac: internal | ||
| api: | ||
| endpoint: {ENDPOINT_TO_YOUR_RBAC_SERVER} # e.g., http://localhost:9006/api/v1 | ||
| token: |
There was a problem hiding this comment.
sample of how token looks like or comment
| > The `auth.api.token` parameter is optional. If unspecified, lakeFS uses the `auth.encrypt.secret_key` as | ||
| > the token. If specified, provide a JWT token directly or via the environment variable `LAKEFS_AUTH_API_TOKEN`. |
There was a problem hiding this comment.
secret_key is not used as token as it doesn't leave the local environment.
explain the process of how the request get token when no explicit token is specified.
| When lakeFS starts for the first time, it initializes users, groups, and policies. Once initialized, | ||
| the authorization method cannot change. If lakeFS starts without an RBAC server and later tries connecting to one, | ||
| it will fail to authenticate. You must re-initialize lakeFS from scratch to connect to a new RBAC server. |
There was a problem hiding this comment.
unclear - if we must "re-initialize" it means we can initialize and we said that lakeFS done it automatically.
- verify that lakeFS create something on startup without explicit command
- if we instruct the user to "re-iinitialize" we need to explain how
| 2. Run lakeFS with the updated configuration file: | ||
|
|
||
| ```shell | ||
| ./lakefs -c {PATH_TO_YOUR_CONFIG_FILE} run |
There was a problem hiding this comment.
Running a command similar to ./lakefs -c config.yaml run provides more detailed output.
Or note to remember to replace "config.yaml" with the actual path to your configuration file.
Closes https://github.com/treeverse/product/issues/684
Change Description
Added documentation for RBAC server implementation. The documentation includes the following:
docs/security/RBAC-server-implementation.md.api/authorization.ymlfile, provided under thedescriptionfields within the YAML.authorization.ymlfile.:To support this, the following files were added:
docs/security/authorization-yaml.mddocs/_includes/authorization.htmldocs/assets/js/swagger-ui-authorization.jsdocs/assets/js/authorization.yml