docs(seaweedfs): add object storage guide (pools, buckets, users)#438
docs(seaweedfs): add object storage guide (pools, buckets, users)#438sircthulhu wants to merge 2 commits intomainfrom
Conversation
Add how-to documentation for SeaweedFS storage pools and bucket management with per-user credentials via COSI. Covers enabling SeaweedFS on a tenant, configuring tiered storage pools (Simple and MultiZone topologies), zone parameters with defaults, bucket creation with storagePool selection, object locking, and the users map for granular credential management. Co-Authored-By: Claude <[email protected]> Signed-off-by: Kirill Ilin <[email protected]>
✅ Deploy Preview for cozystack ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces comprehensive documentation for Cozystack's S3-compatible object storage solution, powered by SeaweedFS and its COSI driver. The new guides explain how to configure storage pools for tiered storage, create and manage S3 buckets with options like object locking, and provision and access per-user credentials. This enhances user understanding and operational guidance for leveraging object storage capabilities within Cozystack. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Changelog
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
📝 WalkthroughWalkthroughAdds three new documentation pages describing Cozystack's S3-compatible object storage powered by SeaweedFS: an architecture overview, bucket creation/management (including per-user credentials and object locking), and storage pool configuration for single- and multi-zone deployments. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds comprehensive documentation for Cozystack's object storage feature, covering storage pools, bucket creation, and user management. The new guides are well-structured and detailed. I've provided a couple of suggestions to improve the clarity and consistency of the examples, mainly regarding the use of namespaces and providing more explicit tables for resource naming logic.
|
|
||
| ```text | ||
| {seaweedfs-namespace}[-{storagePool}][-readonly] | ||
| ``` |
There was a problem hiding this comment.
For better clarity and consistency with how the BucketClass selection logic is presented, please add a table here that explicitly shows how the BucketAccessClass is determined. For example:
| storagePool | readonly | BucketAccessClass Used |
| ----------- | -------- | --------------------------- |
| *(empty)* | `false` | `tenant-example` |
| *(empty)* | `true` | `tenant-example-readonly` |
| `ssd` | `false` | `tenant-example-ssd` |
| `ssd` | `true` | `tenant-example-ssd-readonly` || Before configuring pools, enable SeaweedFS on the tenant: | ||
|
|
||
| ```bash | ||
| kubectl patch -n tenant-root tenants.apps.cozystack.io root --type=merge -p '{ |
There was a problem hiding this comment.
The use of the root tenant and tenant-root namespace in the initial setup commands is inconsistent with later examples in this document which use the tenant-example namespace. To make the documentation consistent and easier to follow, I suggest using a single example tenant throughout. This would involve changing root to example here, and then using the tenant-example namespace in the subsequent commands on lines 33 and 48.
| kubectl patch -n tenant-root tenants.apps.cozystack.io root --type=merge -p '{ | |
| kubectl patch -n tenant-root tenants.apps.cozystack.io example --type=merge -p '{ |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
content/en/docs/v1/operations/services/object-storage/storage-pools.md (1)
20-34: Keep namespace examples consistent within the workflow.Commands at Line 23 and Line 33 use
tenant-root, while full specs at Line 78/Line 209 and later commands usetenant-example. Consider using one namespace through each end-to-end path (or call out the intentional switch) to reduce operator mistakes.Also applies to: 71-95, 157-181
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@content/en/docs/v1/operations/services/object-storage/storage-pools.md` around lines 20 - 34, The examples mix two tenant namespaces (tenant-root and tenant-example) which can confuse operators; standardize the namespace across the end-to-end workflow by replacing all occurrences of "tenant-root" and "tenant-example" with a single chosen namespace (e.g., tenant-example) or explicitly add a short note where an intentional switch occurs; update the commands shown (e.g., the kubectl patch command and kubectl -n ... get hr seaweedfs) as well as the later examples referenced (blocks around the earlier "Before configuring pools..." snippet and the full specs at the later examples) to use the same namespace string so the documented steps are consistent.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@content/en/docs/v1/operations/services/object-storage/buckets.md`:
- Around line 68-70: Update the documentation around the users map and the
Secret naming `{bucket-name}-{username}` to explicitly state that the resulting
Secret name must follow Kubernetes DNS-1123 subdomain rules: max 253 characters,
only lowercase a–z, digits, hyphens and dots, must start and end with an
alphanumeric character (no uppercase letters, underscores or other symbols); add
a short note near the `users` map and the Secret naming examples that
keys/usernames must be chosen or normalized to meet these constraints and that
violating them will cause validation failures when creating the Secret (refer to
the `{bucket-name}-{username}` naming in the same paragraphs to show where this
applies).
---
Nitpick comments:
In `@content/en/docs/v1/operations/services/object-storage/storage-pools.md`:
- Around line 20-34: The examples mix two tenant namespaces (tenant-root and
tenant-example) which can confuse operators; standardize the namespace across
the end-to-end workflow by replacing all occurrences of "tenant-root" and
"tenant-example" with a single chosen namespace (e.g., tenant-example) or
explicitly add a short note where an intentional switch occurs; update the
commands shown (e.g., the kubectl patch command and kubectl -n ... get hr
seaweedfs) as well as the later examples referenced (blocks around the earlier
"Before configuring pools..." snippet and the full specs at the later examples)
to use the same namespace string so the documented steps are consistent.
ℹ️ Review info
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
content/en/docs/v1/operations/services/object-storage/_index.mdcontent/en/docs/v1/operations/services/object-storage/buckets.mdcontent/en/docs/v1/operations/services/object-storage/storage-pools.md
| The `users` map defines named S3 users for the bucket. | ||
| Each entry creates a COSI BucketAccess resource and a corresponding Kubernetes Secret with S3 credentials. | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
find . -name "buckets.md" -path "*/object-storage/*" | head -5Repository: cozystack/website
Length of output: 127
🌐 Web query:
Kubernetes Secret metadata.name DNS-1123 naming constraints RFC uppercase underscores allowed
💡 Result:
Secret.metadata.namemust be a valid DNS subdomain in Kubernetes. For DNS subdomain names, Kubernetes requires: ≤253 chars, only lowercasea-z, digits0-9,-or., and it must start and end with an alphanumeric character. Uppercase and_are not allowed inmetadata.name. [1][2]- Although RFC 1123 host name syntax is case-insensitive (no distinction between upper/lower case) and mainly relaxes the first-character rule to allow digits, Kubernetes intentionally applies a stricter “lowercase only” validation for DNS-1123-style names. [3][4]
- Underscores are allowed for Secret data keys (the keys under
data:/stringData:may include-,_,.and alphanumerics), but that does not apply tometadata.name. [2]
Sources:
[1] Kubernetes “Object Names and IDs” (DNS subdomain rules)
[2] Kubernetes “Secrets” (Secret name must be DNS subdomain; data key character set)
[3] RFC 1123 §2.1 (host name syntax update)
[4] Kubernetes issue discussing RFC allowing uppercase vs Kubernetes DNS-1123 validators
🏁 Script executed:
cat -n ./content/en/docs/v1/operations/services/object-storage/buckets.md | sed -n '60,110p'Repository: cozystack/website
Length of output: 1993
Document username/key naming constraints to prevent invalid Secret names.
Lines 68–70 and 100–101 describe Secret naming as {bucket-name}-{username} but omit critical constraints. User keys must conform to Kubernetes DNS-1123 rules (≤253 characters, lowercase a-z, digits, hyphens and dots only; no uppercase or underscores; must start and end with alphanumeric). Add explicit requirements and note that violating these rules will cause validation failures when provisioning the Secret.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@content/en/docs/v1/operations/services/object-storage/buckets.md` around
lines 68 - 70, Update the documentation around the users map and the Secret
naming `{bucket-name}-{username}` to explicitly state that the resulting Secret
name must follow Kubernetes DNS-1123 subdomain rules: max 253 characters, only
lowercase a–z, digits, hyphens and dots, must start and end with an alphanumeric
character (no uppercase letters, underscores or other symbols); add a short note
near the `users` map and the Secret naming examples that keys/usernames must be
chosen or normalized to meet these constraints and that violating them will
cause validation failures when creating the Secret (refer to the
`{bucket-name}-{username}` naming in the same paragraphs to show where this
applies).
Co-Authored-By: Claude <[email protected]> Signed-off-by: Kirill Ilin <[email protected]>
There was a problem hiding this comment.
♻️ Duplicate comments (1)
content/en/docs/v1/operations/services/object-storage/buckets.md (1)
68-90:⚠️ Potential issue | 🟡 MinorDocument DNS-1123 naming constraints for Secret names.
The
usersmap and the resulting Secret naming pattern{bucket-name}-{username}(shown in the table) lack explicit documentation of Kubernetes DNS-1123 subdomain constraints. Secret names must be ≤253 characters, contain only lowercasea-z, digits, hyphens, and dots, and start/end with an alphanumeric character. Uppercase letters and underscores are not allowed.Add a note explaining these constraints and warning that invalid names will cause provisioning failures.
📝 Suggested documentation addition
Consider adding a note after line 69 or in the User Parameters section:
The `users` map defines named S3 users for the bucket. Each entry creates a COSI BucketAccess resource and a corresponding Kubernetes Secret with S3 credentials. + +{{< note >}} +User keys must conform to Kubernetes DNS-1123 naming rules. The resulting Secret name `{bucket-name}-{username}` must be ≤253 characters, contain only lowercase letters, digits, hyphens, and dots, and start/end with an alphanumeric character. Uppercase letters and underscores are not allowed. +{{< /note >}}🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@content/en/docs/v1/operations/services/object-storage/buckets.md` around lines 68 - 90, Add a note documenting Kubernetes DNS-1123 subdomain constraints for Secret names generated from the users map and the `{bucket-name}-{username}` pattern: state that Secret names must be ≤253 characters, only lowercase a–z, digits, hyphens and dots are allowed, must start and end with an alphanumeric character, and that uppercase letters/underscores will cause provisioning failures; place this note near the users map or the User Parameters section and include a short warning to validate/normalize bucket or username inputs to avoid invalid Secret names.
🧹 Nitpick comments (1)
content/en/docs/v1/operations/services/object-storage/buckets.md (1)
110-131: Consider documenting zero-downtime credential rotation.The current two-step rotation procedure (remove user, re-add user) is clearly documented with an appropriate warning about downtime. For production scenarios, users may prefer a zero-downtime approach: create a new user with a different name (e.g.,
admin-v2), update applications to use the new credentials, then remove the old user.Adding this alternative to the documentation would help users choose the approach that best fits their operational requirements.
📋 Example zero-downtime procedure
### Zero-Downtime Rotation (Optional) For production environments where downtime is unacceptable, use a rolling rotation: 1. Add a new user with a different name: ```yaml spec: users: admin: {} # existing user admin-v2: {} # new user with fresh credentials
Update applications to use
{bucket-name}-admin-v2credentialsRemove the old user once all applications are updated:
spec: users: admin-v2: {}</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@content/en/docs/v1/operations/services/object-storage/buckets.mdaround
lines 110 - 131, Add an alternative "Zero-Downtime Rotation (Optional)"
subsection under the existing "Rotating Credentials" heading that describes
creating a new user with a different name, switching applications to the new
user's Secret, then removing the old user; reference the same spec: users: YAML
structure from the current snippets and include the three-step flow (create
admin-v2, update apps to use {bucket-name}-admin-v2 credentials, remove admin)
and a short note about cleaning up Secrets once cutover is complete so readers
can perform rolling credential rotation without downtime.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In@content/en/docs/v1/operations/services/object-storage/buckets.md:
- Around line 68-90: Add a note documenting Kubernetes DNS-1123 subdomain
constraints for Secret names generated from the users map and the
{bucket-name}-{username}pattern: state that Secret names must be ≤253
characters, only lowercase a–z, digits, hyphens and dots are allowed, must start
and end with an alphanumeric character, and that uppercase letters/underscores
will cause provisioning failures; place this note near the users map or the User
Parameters section and include a short warning to validate/normalize bucket or
username inputs to avoid invalid Secret names.
Nitpick comments:
In@content/en/docs/v1/operations/services/object-storage/buckets.md:
- Around line 110-131: Add an alternative "Zero-Downtime Rotation (Optional)"
subsection under the existing "Rotating Credentials" heading that describes
creating a new user with a different name, switching applications to the new
user's Secret, then removing the old user; reference the same spec: users: YAML
structure from the current snippets and include the three-step flow (create
admin-v2, update apps to use {bucket-name}-admin-v2 credentials, remove admin)
and a short note about cleaning up Secrets once cutover is complete so readers
can perform rolling credential rotation without downtime.</details> --- <details> <summary>ℹ️ Review info</summary> **Configuration used**: defaults **Review profile**: CHILL **Plan**: Pro <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between f50977701fd2dd274be154ef709d0910911074b6 and a77301d7210b69cf0e4c3cd62ba49b7b5a58c17f. </details> <details> <summary>📒 Files selected for processing (1)</summary> * `content/en/docs/v1/operations/services/object-storage/buckets.md` </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
kvaps
left a comment
kvaps
left a comment
There was a problem hiding this comment.
LGTM, do-not-merge until feature released
2 participants
Summary
storagePoolselection and object locking, and per-user credential management via theusersmapTest plan
Summary by CodeRabbit