Skip to content

Commit 4e210dd

Browse files
sircthulhusircthulhu
authored
docs(seaweedfs): add object storage guide (pools, buckets, users) (#438)
## Summary - Add object storage documentation section covering SeaweedFS storage pools (tiered storage by disk type), bucket creation with `storagePool` selection and object locking, and per-user credential management via the `users` map ## Test plan - [x] Verify Hugo builds without errors - [x] Check that new pages render correctly in the sidebar under Cluster Services > Object Storage - [x] Verify internal links between object-storage sub-pages and existing SeaweedFS references resolve <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added a comprehensive guide for S3-compatible object storage, including architecture overview and conceptual diagrams * New step-by-step docs for creating and managing buckets, users, credentials, object locking, and access classes * New storage-pools guide explaining pool configuration, single-zone and multi-zone topologies, naming rules, examples, and verification steps <!-- end of auto-generated comment: release notes by coderabbit.ai -->
2 parents acd30be + 4df81b4 commit 4e210dd

3 files changed

Lines changed: 494 additions & 0 deletions

File tree

‎content/en/docs/v1/operations/services/object-storage/_index.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
title: "Object Storage"
3+
linkTitle: "Object Storage"
4+
description: "S3-compatible object storage in Cozystack using SeaweedFS and COSI"
5+
weight: 10
6+
---
7+
8+
Cozystack provides S3-compatible object storage powered by [SeaweedFS](https://github.com/seaweedfs/seaweedfs) and the [SeaweedFS COSI Driver](https://github.com/seaweedfs/seaweedfs-cosi-driver/).
9+
10+
## How It Works
11+
12+
Object storage in Cozystack is built from several layers:
13+
14+
1. **SeaweedFS** runs as a cluster service in the tenant namespace, providing the S3 backend.
15+
2. **Storage pools** (optional) partition volume servers by disk type (SSD, HDD, NVMe), each creating its own set of COSI resources.
16+
3. **BucketClasses** define how buckets are provisioned. Each pool creates a standard and a `-lock` BucketClass (for object locking).
17+
4. **BucketAccessClasses** define credential policies: read-write and read-only.
18+
5. **Buckets** are user-facing resources that claim storage from a BucketClass and create per-user credentials via BucketAccess.
19+
20+
```text
21+
SeaweedFS Cluster
22+
└── Storage Pool "ssd" (diskType: ssd)
23+
│ ├── BucketClass: tenant-seaweedfs-ssd
24+
│ ├── BucketClass: tenant-seaweedfs-ssd-lock
25+
│ ├── BucketAccessClass: tenant-seaweedfs-ssd (readwrite)
26+
│ └── BucketAccessClass: tenant-seaweedfs-ssd-readonly (readonly)
27+
└── Storage Pool "hdd" (diskType: hdd)
28+
├── BucketClass: tenant-seaweedfs-hdd
29+
├── ...
30+
```
31+
32+
## Guides
33+
34+
- [Storage Pools]({{% ref "storage-pools" %}}) -- configure SeaweedFS storage pools for tiered storage
35+
- [Buckets]({{% ref "buckets" %}}) -- create buckets and manage user credentials
36+
37+
## Reference
38+
39+
- [SeaweedFS Service Reference]({{% ref "/docs/v1/operations/services/seaweedfs" %}}) -- auto-generated parameter table for the SeaweedFS package
40+
- [SeaweedFS Multi-DC Configuration]({{% ref "/docs/v1/operations/stretched/seaweedfs-multidc" %}}) -- deploying SeaweedFS across multiple data centres

‎content/en/docs/v1/operations/services/object-storage/buckets.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
---
2+
title: "Buckets and Users"
3+
linkTitle: "Buckets"
4+
description: "Create S3 buckets and manage user credentials"
5+
weight: 20
6+
---
7+
8+
The Bucket application creates an S3 bucket via COSI and provisions per-user credentials as Kubernetes Secrets.
9+
10+
## Creating a Bucket
11+
12+
A minimal bucket uses the default BucketClass and creates no users:
13+
14+
```yaml
15+
apiVersion: apps.cozystack.io/v1alpha1
16+
kind: Bucket
17+
metadata:
18+
name: my-bucket
19+
namespace: tenant-example
20+
spec: {}
21+
```
22+
23+
This provisions a BucketClaim against the default BucketClass (`tenant-example`).
24+
To make the bucket useful, add at least one user (see [Users](#users) below).
25+
26+
## Selecting a Storage Pool
27+
28+
If your SeaweedFS instance defines [storage pools]({{% ref "storage-pools" %}}), use the `storagePool` field to target a specific pool:
29+
30+
```yaml
31+
apiVersion: apps.cozystack.io/v1alpha1
32+
kind: Bucket
33+
metadata:
34+
name: my-bucket
35+
namespace: tenant-example
36+
spec:
37+
storagePool: ssd
38+
```
39+
40+
This provisions the BucketClaim against the `tenant-example-ssd` BucketClass.
41+
42+
When `storagePool` is empty (the default), the bucket uses the default BucketClass.
43+
44+
## Object Locking
45+
46+
To create a bucket with object locking enabled, set `locking: true`:
47+
48+
```yaml
49+
apiVersion: apps.cozystack.io/v1alpha1
50+
kind: Bucket
51+
metadata:
52+
name: my-bucket
53+
namespace: tenant-example
54+
spec:
55+
storagePool: ssd
56+
locking: true
57+
```
58+
59+
This provisions the BucketClaim against the `-lock` BucketClass (e.g. `tenant-example-ssd-lock`).
60+
Lock-enabled BucketClasses use a `Retain` deletion policy and configure COMPLIANCE-mode object locking with a default retention period.
61+
62+
{{< note >}}
63+
Object locking cannot be enabled or disabled after bucket creation. Create a new bucket if you need to change this setting.
64+
{{< /note >}}
65+
66+
## Users
67+
68+
The `users` map defines named S3 users for the bucket.
69+
Each entry creates a COSI BucketAccess resource and a corresponding Kubernetes Secret with S3 credentials.
70+
71+
```yaml
72+
apiVersion: apps.cozystack.io/v1alpha1
73+
kind: Bucket
74+
metadata:
75+
name: my-bucket
76+
namespace: tenant-example
77+
spec:
78+
storagePool: ssd
79+
users:
80+
admin: {}
81+
reader:
82+
readonly: true
83+
```
84+
85+
This creates two users:
86+
87+
| User | Access | BucketAccessClass Used | Secret Name |
88+
| --- | --- | --- | --- |
89+
| `admin` | read-write | `tenant-example-ssd` | `my-bucket-admin` |
90+
| `reader` | read-only | `tenant-example-ssd-readonly` | `my-bucket-reader` |
91+
92+
### User Parameters
93+
94+
| Parameter | Type | Default | Description |
95+
| --- | --- | --- | --- |
96+
| `readonly` | `bool` | `false` | When `true`, provisions credentials from the `-readonly` BucketAccessClass |
97+
98+
### Accessing Credentials
99+
100+
Each user gets a Kubernetes Secret named `{bucket-name}-{username}` in the same namespace.
101+
The Secret contains S3 credentials provisioned by the COSI driver:
102+
103+
```bash
104+
kubectl get secret my-bucket-admin -n tenant-example -o yaml
105+
```
106+
107+
The Secret contains the fields needed to configure an S3 client (endpoint, access key, secret key).
108+
The exact fields depend on the COSI driver implementation.
109+
110+
### Rotating Credentials
111+
112+
Bucket user credentials (access key and secret key) are generated once when the user is first created and cannot be updated in place.
113+
To rotate credentials for a user, remove the user from the `users` map and apply, then add the user back and apply again:
114+
115+
```yaml
116+
# Step 1: remove the user to delete existing credentials
117+
spec:
118+
users: {}
119+
```
120+
121+
```yaml
122+
# Step 2: re-add the user to provision a fresh set of credentials
123+
spec:
124+
users:
125+
admin: {}
126+
```
127+
128+
{{< warning >}}
129+
Any applications using the old credentials will lose access between step 1 and step 2.
130+
Update your applications with the new credentials from the Secret after step 2 completes.
131+
{{< /warning >}}
132+
133+
## BucketClass Selection Logic
134+
135+
The BucketClass name is composed from three parts:
136+
137+
```text
138+
{seaweedfs-namespace}[-{storagePool}][-lock]
139+
```
140+
141+
| storagePool | locking | BucketClass Used |
142+
| --- | --- | --- |
143+
| *(empty)* | `false` | `tenant-example` |
144+
| *(empty)* | `true` | `tenant-example-lock` |
145+
| `ssd` | `false` | `tenant-example-ssd` |
146+
| `ssd` | `true` | `tenant-example-ssd-lock` |
147+
148+
Similarly, the BucketAccessClass is composed as:
149+
150+
```text
151+
{seaweedfs-namespace}[-{storagePool}][-readonly]
152+
```
153+
154+
## Complete Example
155+
156+
Deploy a bucket on the `ssd` pool with one admin user and one read-only user:
157+
158+
```yaml
159+
apiVersion: apps.cozystack.io/v1alpha1
160+
kind: Bucket
161+
metadata:
162+
name: media-assets
163+
namespace: tenant-example
164+
spec:
165+
storagePool: ssd
166+
locking: false
167+
users:
168+
app:
169+
readonly: false
170+
backup-reader:
171+
readonly: true
172+
```
173+
174+
After the bucket is provisioned, retrieve the credentials:
175+
176+
```bash
177+
# Read-write credentials for the "app" user
178+
kubectl get secret media-assets-app -n tenant-example \
179+
-o jsonpath='{.data}' | jq 'map_values(@base64d)'
180+
181+
# Read-only credentials for the "backup-reader" user
182+
kubectl get secret media-assets-backup-reader -n tenant-example \
183+
-o jsonpath='{.data}' | jq 'map_values(@base64d)'
184+
```
185+
186+
## Related Documentation
187+
188+
- [Storage Pools]({{% ref "storage-pools" %}}) -- configure tiered storage for pool selection
189+
- [SeaweedFS Service Reference]({{% ref "/docs/v1/operations/services/seaweedfs" %}}) -- full parameter reference

0 commit comments

Comments
 (0)