Repository navigation
docs: document object store credentials for owners and Agents - #591
Merged
Merged
Conversation
Since the owner writes every object block, an Agent process needs only read access under its root's prefix. The new page lists the keys each role touches and the operations it performs, gives example IAM policies for the read-only Agent role and the owner role, shows how to run an Agent on a short-lived STS session taken from the environment, and names the TLS gate scenario that exercises the boundary. The index, the security policy, and the README link to it. Signed-off-by: wchwawa <wch19961116@gmail.com>
Signed-off-by: wchwawa <wch19961116@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
TLDR
A new page lists the object keys and operations each NoKV role touches, with example IAM policies and an STS session recipe, so a deployment can run Agents on read-only credentials now that the owner writes every object.
Problem
Since the owner-mediated upload path landed (#586, the R5 slice of #566), no Agent process writes objects, but nothing told an operator which permissions each process still needs. The architecture and security pages say the owner writes and Agents read, without the key prefixes, the operations per prefix, or a policy an operator could attach. No separate issue exists for this; it closes the documentation item of R5 under #566.
Consequences
Deployments keep handing Agents the owner's read-write credential because the least-privilege shape is undocumented. A leaked Agent credential can then still overwrite or delete artifacts, which defeats the point of moving writes to the owner.
Example
An operator serves a root with
--object-root /tenant-aand wants a harness job to publish results with a one-hour credential that cannot delete anything. Before this change they had to read the source for the key layout and guess at a policy. After it they attach the Agent policy from the page (s3:GetObjectonBUCKET/tenant-a/nokv/system/object-namespaceandBUCKET/tenant-a/nokv/artifacts/*), assume the role with STS, export the session, and run the put; the blocks travel to the owner, which writes them with its own credential.Solution
Add
docs/object-credentials.md: a table of the keys each role touches and the operations it performs (Agent: namespace marker GET, artifact GET and HEAD; owner: artifacts PUT/GET/HEAD/DELETE, the admission probe prefix, the recovery prefixes), an Agent policy and an owner policy in IAM syntax, an STS assume-role recipe that exports the session through the environment, the PythonObjectStoreConfig.s3(..., session_token=...)form, what the page does not cover, and the TLS gate scenario that exercises the boundary. Link it from the docs index,SECURITY.md, and the README.Gain
An operator can grant Agents prefix-scoped read-only credentials without reading code, and the example policy matches what the TLS gate enforces: every Agent process in that gate reaches the provider through an endpoint that forwards only GET and HEAD.
Tradeoffs
The policies use AWS IAM syntax; RustFS, MinIO, and Ceph RGW accept the same statements, but the page does not test them. A session that expires mid-publication fails the Agent's next object read with the provider's error; the page documents that instead of adding a retry.
Validation
Documentation only; no code changed and no tests were run. The key prefixes were taken from the object key constructors (
nokv/artifacts/...,nokv/system/object-namespace,nokv/system/provider-admission/v1/*,nokv/recovery/checkpoints/v1/*,nokv/recovery/log-segments/v1/*) and the linked files exist.python3 scripts/ci/pr_description.py --pull-request-json <this title and body>passes locally.