Buckets and Users

The Bucket application creates an S3 bucket via COSI and provisions per-user credentials as Kubernetes Secrets.

Creating a Bucket

A minimal bucket uses the default BucketClass and creates no users:

apiVersion: apps.cozystack.io/v1alpha1
kind: Bucket
metadata:
  name: my-bucket
  namespace: tenant-example
spec: {}

This provisions a BucketClaim against the default BucketClass (tenant-example). To make the bucket useful, add at least one user (see Users below).

Selecting a Storage Pool

If your SeaweedFS instance defines storage pools, use the storagePool field to target a specific pool:

apiVersion: apps.cozystack.io/v1alpha1
kind: Bucket
metadata:
  name: my-bucket
  namespace: tenant-example
spec:
  storagePool: ssd

This provisions the BucketClaim against the tenant-example-ssd BucketClass.

When storagePool is empty (the default), the bucket uses the default BucketClass.

Object Locking

To create a bucket with object locking enabled, set locking: true:

apiVersion: apps.cozystack.io/v1alpha1
kind: Bucket
metadata:
  name: my-bucket
  namespace: tenant-example
spec:
  storagePool: ssd
  locking: true

This provisions the BucketClaim against the -lock BucketClass (e.g. tenant-example-ssd-lock). Lock-enabled BucketClasses use a Retain deletion policy and configure COMPLIANCE-mode object locking with a default retention period.

Users

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.

apiVersion: apps.cozystack.io/v1alpha1
kind: Bucket
metadata:
  name: my-bucket
  namespace: tenant-example
spec:
  storagePool: ssd
  users:
    admin: {}
    reader:
      readonly: true

This creates two users:

User Parameters

Accessing Credentials

Each user gets a Kubernetes Secret named {bucket-name}-{username} in the same namespace. The Secret contains S3 credentials provisioned by the COSI driver:

kubectl get secret my-bucket-admin -n tenant-example -o yaml

The Secret contains the fields needed to configure an S3 client (endpoint, access key, secret key). The exact fields depend on the COSI driver implementation.

Rotating Credentials

Bucket user credentials (access key and secret key) are generated once when the user is first created and cannot be updated in place. To rotate credentials for a user, remove the user from the users map and apply, then add the user back and apply again:

# Step 1: remove the user to delete existing credentials
spec:
  users: {}

# Step 2: re-add the user to provision a fresh set of credentials
spec:
  users:
    admin: {}

BucketClass Selection Logic

The BucketClass name is composed from three parts:

{seaweedfs-namespace}[-{storagePool}][-lock]

Similarly, the BucketAccessClass is composed as:

{seaweedfs-namespace}[-{storagePool}][-readonly]

Complete Example

Deploy a bucket on the ssd pool with one admin user and one read-only user:

apiVersion: apps.cozystack.io/v1alpha1
kind: Bucket
metadata:
  name: media-assets
  namespace: tenant-example
spec:
  storagePool: ssd
  locking: false
  users:
    app:
      readonly: false
    backup-reader:
      readonly: true

After the bucket is provisioned, retrieve the credentials:

# Read-write credentials for the "app" user
kubectl get secret media-assets-app -n tenant-example \
  -o jsonpath='{.data}' | jq 'map_values(@base64d)'

# Read-only credentials for the "backup-reader" user
kubectl get secret media-assets-backup-reader -n tenant-example \
  -o jsonpath='{.data}' | jq 'map_values(@base64d)'

Related Documentation

• Storage Pools – configure tiered storage for pool selection
• SeaweedFS Service Reference – full parameter reference