kemko/nomad
1
0
Fork 0
mirror of https://github.com/kemko/nomad.git synced 2026-01-01 16:05:42 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs: expand docs on implicit ACL capabilities grants (#19681)

Browse Source 
An audit of Nomad's ACLs resulted in some confusion around whether the
`NamespaceValidator` method is conjunctive ("add", as implied by the docs) or
disjunctive ("or", as it is by design). Clarify the ACL documentation as
follows:

* Call out where fine-grained capabilities imply grants to other
  capabilities (for example, that `csi-read-volume` grants `csi-list-volume`).
* Fix an incorrectly documented ACL requirement for the CSI List External
  Volumes API.
* Clarify how ACLs are expected to work for the two search API endpoints, such
  that you need list/read access to the objects in the search context.
This commit is contained in:
Tim Gross
2024-01-09 13:25:05 -05:00
committed by GitHub
parent a3a03dff78
commit c875f3e49a
3 changed files with 32 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
website/content/api-docs/search.mdx
View File

@@ -22,14 +22,15 @@ The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
| Blocking Queries | ACL Required |
| ---------------- | ------------------------------------------------ |
| `NO` | `node:read, node_pool:read, namespace:read-jobs` |
| Blocking Queries | ACL Required |
|------------------|--------------|
| `NO` | see below |
When ACLs are enabled, requests must have a token valid for `node:read`,
`node_pool:read`, or `namespace:read-jobs` roles. If the token is only valid
for a portion of these capabilities, then results will include results
including only data readable with the given token.
When ACLs are enabled, requests must have a token that grants access to "list"
or "read" capabilities for the objects in the search context. For example,
`node:read`, `node_pool:read`, `plugin:read`, or `namespace:read-jobs` roles. If
the token is only valid for a portion of these capabilities, then results will
include results including only data readable with the given token.
### Parameters
@@ -141,14 +142,15 @@ The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).
| Blocking Queries | ACL Required |
| ---------------- | --------------------------------------------------------------------------- |
| `NO` | `node:read, node_pool:read, namespace:read-jobs, namespace:csi-list-plugin` |
| Blocking Queries | ACL Required |
|------------------|--------------|
| `NO` | see below |
When ACLs are enabled, requests must have a token valid for `node:read`,
`node_pool:read`, `plugin:read`, or `namespace:read-jobs` roles. If the token
is only valid for a portion of these capabilities, then results will include
results including only data readable with the given token.
When ACLs are enabled, requests must have a token that grants access to "list"
or "read" capabilities for the objects in the search context. For example,
`node:read`, `node_pool:read`, `plugin:read`, or `namespace:read-jobs` roles. If
the token is only valid for a portion of these capabilities, then results will
include results including only data readable with the given token.
### Parameters

2
website/content/api-docs/volumes.mdx
View File

@@ -546,7 +546,7 @@ The table below shows this endpoint's support for
| Blocking Queries | ACL Required |
| ---------------- | ---------------------------- |
| `YES` | `namespace:csi-write-volume` |
| `YES` | `namespace:csi-list-volume` |
### Parameters

23
website/content/docs/other-specifications/acl-policy.mdx
View File

@@ -120,13 +120,16 @@ of `capabilities`. This includes:
- `deny` - When multiple policies are associated with a token, deny will take
precedence and prevent any capabilities.
- `list-jobs` - Allows listing the jobs and seeing coarse grain status.
- `list-jobs` - Allows listing the jobs and seeing coarse grain status. This
implicitly grants `csi-list-volume`.
- `parse-job` - Allows parsing a job from HCL to JSON.
- `read-job` - Allows inspecting a job and seeing fine grain status.
- `read-job` - Allows inspecting a job and seeing fine grain status. This
implicitly grants `csi-read-volume`.
- `submit-job` - Allows jobs to be submitted, updated, or stopped.
- `dispatch-job` - Allows jobs to be dispatched
- `read-logs` - Allows the logs associated with a job to be viewed.
- `read-fs` - Allows the filesystem of allocations associated to be viewed.
- `read-fs` - Allows the filesystem of allocations associated to be
viewed. Implicitly grants `read-logs`.
- `alloc-exec` - Allows an operator to connect and run commands in running
allocations.
- `alloc-node-exec` - Allows an operator to connect and run commands in
@@ -135,11 +138,15 @@ of `capabilities`. This includes:
manually.
- `csi-register-plugin` - Allows jobs to be submitted that register themselves
as CSI plugins.
- `csi-write-volume` - Allows CSI volumes to be registered or deregistered.
- `csi-read-volume` - Allows inspecting a CSI volume and seeing fine grain
status.
- `csi-list-volume` - Allows listing CSI volumes and seeing coarse grain status.
- `csi-mount-volume` - Allows jobs to be submitted that claim a CSI volume.
- `csi-write-volume` - Allows CSI volumes to be registered or deregistered. This
implicitly grants `csi-read-volume`.
- `csi-read-volume` - Allows inspecting a CSI volume, seeing fine grain status,
and listing external volumes and snapshots. This implicitly grants
`csi-list-volume`.
- `csi-list-volume` - Allows listing CSI volumes, seeing coarse grain status,
and listing external volumes and snapshots.
- `csi-mount-volume` - Allows jobs to be submitted that claim a CSI volume. This
implicitly grants `csi-read-volume`.
- `list-scaling-policies` - Allows listing scaling policies.
- `read-scaling-policy` - Allows inspecting a scaling policy.
- `read-job-scaling` - Allows inspecting the current scaling of a job.