SeaweedFS - Control Plane

Overview

SeaweedFS is a distributed object store with an S3-compatible API. This template deploys a single all-in-one node — master, volume server, filer, S3 gateway, and admin UI in one process — with persistent storage, startup bucket creation, and SigV4-authenticated S3 on port 8333. Its main use is as an in-org storage target: any workload or template that accepts an S3-compatible endpoint and a static access key pair can point at it without leaving your organization. Backing up postgres-highly-available into SeaweedFS, and restoring from it, was verified end to end with no changes on the consumer side. See Using SeaweedFS as an S3 backend.

Architecture

All-in-one node — A single stateful workload running weed mini, which starts the master, volume server, filer, S3 gateway, and admin UI in one process. The S3 API is served on port 8333; the admin UI on port 23646.
One disk for everything — Object data, filer metadata (leveldb), and master metadata all live on one persistent volume set mounted at /data.
Authenticated by default — S3 credentials come from a dictionary secret you create before installing. SeaweedFS serves S3 with no authentication at all when credentials are absent, so the chart refuses to render without one.
Private by default — External access is off (publicAccess.enabled: false); the S3 API is reachable only from inside the GVC until you turn it on. The admin UI is never publicly routed.

What Gets Created

Stateful SeaweedFS Workload — One replica serving the S3 API on port 8333, plus the admin UI on port 23646 when enabled.
Volume Set — Persistent storage at /data for objects and all metadata, with optional autoscaling. A final snapshot is retained for 7 days when the volume set is deleted.
Admin Secret (optional) — A dictionary secret holding the admin UI username and password. Created only when adminUI.enabled is true.
Identity & Policy — An identity bound to the workload with reveal on exactly the secrets it mounts: your S3 credentials secret, plus the admin secret when the admin UI is enabled.

This template does not create a GVC. You must deploy it into an existing GVC.

Prerequisites

Create the S3 credentials secret before installing. The workload references it by name (s3.credentialsSecretName, default my-seaweedfs-s3-credentials), and the deployment waits on a missing secret indefinitely rather than starting up unauthenticated. Create it as a dictionary secret containing exactly these two keys:

cpln secret create-dictionary --name my-seaweedfs-s3-credentials \
  --entry AWS_ACCESS_KEY_ID=<your-access-key> \
  --entry AWS_SECRET_ACCESS_KEY=<your-secret-key>

These are the credentials every S3 client uses. The secret is yours, not the release’s — helm uninstall leaves it in place.

Also change adminUI.password before installing. The shipped default is an obvious placeholder, not a working credential.

Install the template using your preferred method:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

The default values.yaml for this template:

# Official upstream image. Runs `weed mini` — the image's own default command —
# which starts the master, volume server, filer, S3 gateway and admin UI in one
# process. Pin a concrete released tag; never latest.
image: chrislusf/seaweedfs:4.40

resources:
  minCpu: 250m
  maxCpu: 1000m
  minMemory: 512Mi
  maxMemory: 2Gi # raise for stores holding tens of millions of objects (in-memory volume index)

# Storage: objects + filer metadata + master metadata, all at /data
volumeset:
  capacity: 20 # initial capacity in GiB (minimum is 10)
  autoscaling:
    enabled: false # set to true to grow the volume automatically as it fills
    maxCapacity: 200 # maximum capacity in GiB when autoscaling is enabled
    minFreePercentage: 10 # minimum free percentage that triggers scaling
    scalingFactor: 1.2 # how much to grow the volume when scaling is triggered

# S3 API (port 8333)
s3:
  # PREREQUISITE dictionary secret — MUST EXIST BEFORE INSTALL, or the deployment
  # waits on it forever and looks broken. These are the S3 credentials every client
  # uses; SeaweedFS serves S3 with NO authentication if they are absent.
  credentialsSecretName: my-seaweedfs-s3-credentials
  # Buckets created at startup if they do not already exist, e.g. [backups, uploads].
  # Most backup tools require the bucket to exist before they run.
  buckets: []

# Admin UI (port 23646, reachable inside the GVC only)
adminUI:
  enabled: true # cluster status, bucket browser, user and maintenance management
  username: admin
  password: change-me-seaweedfs-admin # CHANGE THIS before install

publicAccess:
  enabled: false # true = S3 API on the auto *.cpln.app HTTPS endpoint (path-style addressing)
internalAccess: # internal firewall scope
  type: same-gvc # options: none, same-gvc, same-org, workload-list
  workloads: [] # only used when type is workload-list

Image and Resources

image — The official upstream image. weed mini is the image’s own default command; the template pins every port explicitly because mini’s port layout can change between releases.
resources.minCpu / resources.maxCpu / resources.minMemory / resources.maxMemory — CPU and memory for the container. The defaults run a typical store comfortably; raise maxMemory for stores holding tens of millions of objects, since the volume index is held in memory.

Storage

volumeset.capacity — Initial volume size in GiB (minimum 10). This one volume holds object data, filer metadata, and master metadata.
volumeset.autoscaling.enabled — Automatically expand the volume as it fills. When enabled:
- maxCapacity — Maximum volume size in GiB. Must be greater than or equal to volumeset.capacity.
- minFreePercentage — Trigger a scale-up when free space drops below this percentage.
- scalingFactor — Multiply the current capacity by this factor when scaling up.

Data survives restarts, redeployments, and helm upgrade under the same release name. Uninstalling deletes the volume set — and every stored object with it — keeping a final snapshot for 7 days.

SeaweedFS derives its volume file size from the disk capacity at startup, so growing the volume set takes effect on the next restart. This is harmless: SeaweedFS simply creates more volume files.

S3 API

s3.credentialsSecretName — Name of the prerequisite dictionary secret holding AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. Required; the chart fails to render if it is empty.
s3.buckets — Buckets created at startup if they do not already exist, for example [backups, uploads]. Names must be lowercase letters, digits, dots, and hyphens, 3–63 characters, starting with a letter or digit. Buckets are only ever created, never deleted — removing a name from this list leaves the bucket in place. You can also create buckets at runtime through the admin UI or with aws s3 mb.

Rotating the credentials secret and redeploying genuinely rotates the keys: the S3 identity is rebuilt from the environment on every boot rather than stored on disk. The old access key is rejected with InvalidAccessKeyId once the new replica is serving; stored objects are untouched.

Admin UI

adminUI.enabled — Cluster status, bucket browser, user, and maintenance management on port 23646. Reachable from inside the GVC only.
adminUI.username / adminUI.password — Login credentials, stored in a dictionary secret the template creates. Required when the admin UI is enabled.

Setting adminUI.enabled: false removes the port, the credentials, and the secret, and narrows the policy to the S3 credentials secret alone. The admin routes then return 404.

Upstream weed mini still starts the admin component in-process when the UI is disabled — only its routes are unregistered. Because the port is not declared on the workload and no credentials are injected, nothing is reachable from outside the container.

Access

publicAccess.enabled — false by default. When set to true, the S3 API is served over HTTPS on the automatically assigned *.cpln.app canonical endpoint, using path-style addressing. Only port 8333 is exposed this way; the admin UI is never publicly routed.
internalAccess.type — Internal firewall scope of the workload:

Type	Description
`none`	No internal access.
`same-gvc`	Allow access from all workloads in the same GVC (default).
`same-org`	Allow access from all workloads in the same organization, including other GVCs.
`workload-list`	Allow access only from workloads listed in `internalAccess.workloads`, e.g. `//gvc/GVC_NAME/workload/WORKLOAD_NAME`.

Firewall changes take 60–90 seconds to propagate, and a client that cached a negative DNS answer can lag an allow by roughly another 30 seconds.

Using SeaweedFS as an S3 Backend

Any client that speaks S3 works, subject to three rules:

Path-style addressing is required (http://host:8333/bucket/key). Virtual-host style (bucket.host) is not served.
Any region value works. The region is read from the client’s signature scope and never compared against a server-side value, so a consumer hardcoded to us-east-1 is fine as-is.
The bucket must already exist for most backup tools. Create it with s3.buckets, through the admin UI, or with aws s3 mb.

Verifying from inside the GVC

aws configure set default.s3.addressing_style path
aws --endpoint-url http://RELEASE_NAME-seaweedfs:8333 s3 ls
aws --endpoint-url http://RELEASE_NAME-seaweedfs:8333 s3 cp ./file s3://BUCKET/file

Catalog templates

Endpoint and credentials for the common catalog consumers. accessKey / secretKey (or accessSecret) are the two values you put in the prerequisite secret.

Consumer template	Values to set
postgres-highly-available, timescaledb-highly-available	`backup.provider: minio`, `backup.minio.endpoint: http://RELEASE_NAME-seaweedfs:8333`, plus `backup.minio.bucket`, `backup.minio.accessKey`, `backup.minio.secretKey`, `backup.minio.prefix`
thanos, mimir	`storage.type: minio`, `storage.minio.endpoint: RELEASE_NAME-seaweedfs.GVC_NAME.cpln.local:8333` (host:port, no scheme), `storage.minio.insecure: true`, `storage.minio.region: us-east-1`, plus `bucket`, `accessKey`, `accessSecret`
prometheus	Same fields, nested one level deeper: `thanos.objectStorage.enabled: true`, `thanos.objectStorage.type: minio`, then `thanos.objectStorage.minio.*`
sftpgo	`storage.type: minio`, `storage.minio.endpoint: http://RELEASE_NAME-seaweedfs:8333`, plus `bucket`, `region`, `accessKey`, `accessSecret`
docmost	`storage.type: s3`, `storage.s3.endpoint: http://RELEASE_NAME-seaweedfs:8333`, `storage.s3.forcePathStyle: true`, `storage.s3.bucket`, `storage.s3.region: us-east-1`, and `storage.s3.auth.secretName` pointing at a separate dictionary secret — see the warning below
n8n, metabase, keycloak, unleash	Backups of their bundled database: `postgresHA.backup.provider: minio` (or `postgres.backup.provider: minio` in single-instance mode) with the matching `…backup.minio.endpoint`, `bucket`, `accessKey`, `secretKey`, `prefix`

Docmost needs a second secret with different key names. Its static-key secret must contain AWS_S3_ACCESS_KEY_ID and AWS_S3_SECRET_ACCESS_KEY — the same two values as this template’s secret, under different keys. Point storage.s3.auth.secretName at that secret, not at s3.credentialsSecretName.

Templates whose object-storage support is limited to named providers — ghost and clickhouse, which offer only aws/gcp and similar — cannot point at an arbitrary S3 endpoint, so they cannot use this template as their storage target.

Connecting

Target	Address	Notes
S3 API, same GVC	`http://RELEASE_NAME-seaweedfs:8333`	Short name; resolves from any workload in the same GVC.
S3 API, same GVC (FQDN)	`http://RELEASE_NAME-seaweedfs.GVC_NAME.cpln.local:8333`	Same host, fully qualified.
S3 API, host:port form	`RELEASE_NAME-seaweedfs.GVC_NAME.cpln.local:8333`	For clients that take a bare host:port, such as Thanos and Mimir. Pair with `insecure: true`.
S3 API, public (if enabled)	`https://<canonical>.cpln.app`	Port 443, no port suffix. Requires `publicAccess.enabled: true`.
Admin UI	`http://RELEASE_NAME-seaweedfs.GVC_NAME.cpln.local:23646`	Inside the GVC only. Log in with `adminUI.username` / `adminUI.password`.
Health check	`GET /healthz` on port `8333`	Unauthenticated by design.

Same-GVC clients use plain http:// over the mesh’s mTLS; external clients use https://, with TLS terminated at the platform edge. The canonical hostname appears under status.canonicalEndpoint in cpln workload get RELEASE_NAME-seaweedfs --gvc GVC_NAME -o yaml. Requests without a valid signature are rejected: unsigned requests get 403, and a wrong secret key gets SignatureDoesNotMatch.

Important Notes

Create the S3 credentials secret before installing. A missing secret leaves the deployment waiting indefinitely, and omitting credentials entirely would make SeaweedFS serve S3 unauthenticated.
Change adminUI.password before installing — the shipped default is a placeholder, not a working credential.
The template deploys a single replica by design. weed mini runs one master, one filer, and one volume server in a single process, so raising the replica count would create separate, divergent object stores. Multi-node clustering is a planned follow-up.
A redeploy or upgrade is a full S3 outage. Measured at 337 failed requests over an 80.8 second gap (at roughly 5 requests/second), with the store serving again about 128 seconds after the redeploy was triggered. Almost all of that is platform teardown and reschedule — SeaweedFS itself boots in about 1.5 seconds. Schedule upgrades accordingly, and expect the same window whenever the platform reschedules the replica.
Clients must use path-style addressing; virtual-host style is not served.
Only the S3 API is publicly routable. publicAccess exposes port 8333 alone — reach the admin UI from inside the GVC.
Rotating the credentials secret and redeploying rotates the keys, leaving stored data untouched. Update every consumer at the same time.
Data survives restarts and upgrades; uninstall deletes the volume set and every stored object, keeping a final snapshot for 7 days.
Uninstall does not delete your S3 credentials secret — it is your resource, created outside the release, and it stays until you remove it.

External References

SeaweedFS on GitHub

Source, releases, and issue tracker

Quick Start with weed mini

The all-in-one mode this template runs

Amazon S3 API Support

Which S3 operations SeaweedFS implements

S3 Credentials

How SeaweedFS resolves S3 identities and access keys

Admin UI

Cluster status, bucket browser, and maintenance

SeaweedFS Template

View the source files, default values, and chart definition

​Overview

​Architecture

​What Gets Created

​Prerequisites

UI

CLI

Terraform

Pulumi

​Configuration

​Image and Resources

​Storage

​S3 API

​Admin UI

​Access

​Using SeaweedFS as an S3 Backend

​Verifying from inside the GVC

​Catalog templates

​Connecting

​Important Notes

​External References

SeaweedFS on GitHub

Quick Start with weed mini

Amazon S3 API Support

S3 Credentials

Admin UI

SeaweedFS Template

Overview

Architecture

What Gets Created

Prerequisites

Configuration

Image and Resources

Storage

S3 API

Admin UI

Access

Using SeaweedFS as an S3 Backend

Verifying from inside the GVC

Catalog templates

Connecting

Important Notes

External References