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. Both sets of credentials — the S3 keys and the admin UI login — come from secrets you create before installing. Nothing sensitive passes through Helm values, and as of 1.1.0 the template creates no secret of its own at all.

Upgrading an install created with 1.0.0 is a breaking change. adminUI.username and adminUI.password no longer exist, and an upgrade that still sets either one stops with an error naming its replacement — even when adminUI.enabled is false. See Upgrading From 1.0.0. The S3 half is unchanged: s3.credentialsSecretName worked exactly this way in 1.0.0 and needs no edit.

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.
The admin login is a prerequisite too — The admin UI’s username and password come from a second dictionary secret you create. The template creates no secrets, so no credential ever lands in the Helm release.
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.
Identity & Policy — An identity bound to the workload with reveal on exactly the secrets it mounts: your S3 credentials secret, plus your admin credentials secret when the admin UI is enabled. Nothing else, and no cloud access at all.

This template creates no secrets. Both credentials live in secrets you own, which means uninstalling the release never destroys them — verified on a real uninstall, where both survived with their contents intact.

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

Prerequisites

Two secrets must exist before you install. They are deliberately separate: the S3 keys are handed to every client application, while the admin login reaches the bucket browser and maintenance tools. Secrets are org-level, so no GVC flag is involved.

Create the S3 credentials secret

A dictionary secret holding exactly the keys AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. These are the credentials every S3 client uses, and SeaweedFS serves S3 with no authentication at all without them:

cpln secret create-dictionary --name my-seaweedfs-s3-credentials \
  --entry AWS_ACCESS_KEY_ID="$(openssl rand -hex 10)" \
  --entry AWS_SECRET_ACCESS_KEY="$(openssl rand -hex 24)"

Set s3.credentialsSecretName to the name you used.

Create the admin UI credentials secret

A dictionary secret holding exactly the keys username and password, guarding the admin login form. Required whenever adminUI.enabled is true, which is the default:

cpln secret create-dictionary --name my-seaweedfs-admin-credentials \
  --entry username=admin \
  --entry password="$(openssl rand -hex 24)"

Set adminUI.credentialsSecretName to the name you used.

Read either secret back later

-o yaml is required; without it the command prints the secret’s metadata table rather than its contents:

cpln secret reveal my-seaweedfs-admin-credentials -o yaml

The S3 half is unchanged from 1.0.0. s3.credentialsSecretName was already a prerequisite secret, so anything already backing up into SeaweedFS — postgres-highly-available, thanos, mimir — needs no change whatsoever.

A missing prerequisite secret wedges the install rather than failing it. cpln helm install still exits 0 and reports success, all four resources are created, and the workload then never starts — it sits at zero replicas. Because the container never ran, cpln logs returns zero lines, which reads as a broken platform rather than a missing prerequisite.The only diagnostic is status.versions[].message, which names the missing secret:

cpln workload get-deployments RELEASE_NAME-seaweedfs --gvc GVC_NAME -o yaml

The secret my-seaweedfs-admin-credentials no longer exists. Workload updates are
paused until the secret is added or the reference to the secret removed.

It is get-deployments — plain cpln workload get has no versions key at all. Creating the missing secret clears the wedge on its own, but slowly: recovery was measured at 7 minutes 15 seconds here, inside the 5.5–8.5 minute range seen across the catalog. A forced redeployment shortcuts it to roughly 90 seconds.

Installation

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

The node reaches ready about 52 seconds after install, with the master, volume server, filer, S3 gateway, and admin UI all up in the one process.

Upgrading From 1.0.0

Version 1.1.0 moved the admin UI login out of Helm values. 1.0.0 shipped a working username and password as values, used exactly as written, guarding the bucket browser and maintenance tools — a published default sitting in the release for the life of the install.

	`1.0.0`	`1.1.0`
Admin UI login	`adminUI.username` and `adminUI.password` values	`adminUI.credentialsSecretName` — a dictionary secret you create with `username` and `password`
Chart-created secret	Held the admin credentials	None; the template creates no secrets at all
S3 credentials	`s3.credentialsSecretName` prerequisite secret	Unchanged

A helm upgrade that still carries either removed key is rejected before anything is applied, and the guard deliberately fires even when adminUI.enabled is false — otherwise a stale password: in your values would be silently accepted while you believed a credential was still in force. A real cpln helm upgrade carrying the old keys failed at render, created no Helm revision, and left the running release healthy and untouched:

adminUI.username and adminUI.password were removed in seaweedfs 1.1.0 — the admin UI login form is
now guarded by a REQUIRED prerequisite dictionary secret. Create one holding the keys 'username' and
'password', then set adminUI.credentialsSecretName to its name.

Leaving adminUI.credentialsSecretName empty while the UI is enabled is refused the same way. With adminUI.enabled: false an empty name renders fine — the feature is simply off, with no admin port, no credential environment, and no admin secret in the policy.

To upgrade an existing install:

Create the admin credentials secret

Follow Prerequisites. Put your existing username and password into it if you want current logins to keep working; otherwise choose new ones — the shipped 1.0.0 default was public.

Drop the removed keys from your values

Remove adminUI.username and adminUI.password, and set adminUI.credentialsSecretName instead. Leave s3.credentialsSecretName exactly as it is.

Upgrade

The single replica restarts and the store is briefly unavailable — see the outage window in Important Notes. Stored objects on the volume set are untouched.

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
  # REQUIRED PREREQUISITE SECRET when adminUI.enabled is true — CREATE IT BEFORE
  # YOU INSTALL. A `dictionary` secret holding exactly two keys, `username` and
  # `password`, guarding the admin login form. If it does not exist at install
  # time the deployment WEDGES silently — `cpln logs` returns nothing at all.
  credentialsSecretName: my-seaweedfs-admin-credentials

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.credentialsSecretName — Name of the prerequisite dictionary secret holding the username and password that guard the login form. Required whenever the admin UI is enabled; the chart fails to render if it is empty.

Setting adminUI.enabled: false removes the port and the credential references, and narrows the policy to the S3 credentials secret alone. The admin routes then return 404. Reach the UI from your laptop with a tunnel — it is never publicly routed, and the tunnel works even when the workload is closed to both the internet and the GVC:

cpln port-forward RELEASE_NAME-seaweedfs 23646:23646 --gvc GVC_NAME

Then open http://localhost:23646 and log in with the two values from your admin secret. Authentication is genuinely enforced against that secret: an unauthenticated request redirects to /login, the protected API returns 401, and a wrong username or password is refused with Invalid credentials.

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.

Port 23646 is not reachable from outside, even with publicAccess.enabled: true. The workload declares 8333 first, so the canonical endpoint binds to the S3 gateway and there is no public route to the admin port at all. Requesting /login on the public endpoint returns S3 XML that parses the path as a bucket name — <BucketName>login</BucketName> — which proves the request reached the S3 gateway rather than the admin server.

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 a minute or two to take effect. Turning publicAccess.enabled on was measured at 132 seconds end to end, stepping through 403 (closed) and 503 (routing not yet up) before serving 200. A client that cached a negative DNS answer can lag an allow by another 30 seconds or so. Re-test before concluding a knob is broken.

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, never publicly routed. From a laptop, tunnel with `cpln port-forward RELEASE_NAME-seaweedfs 23646:23646 --gvc GVC_NAME`. Log in with the `username` / `password` from your admin credentials secret.
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 both prerequisite secrets before installing. A missing one wedges the deployment with no log output at all; Prerequisites gives the one command that diagnoses it.
The template creates no secrets — both credentials are yours, so helm uninstall leaves them in place.
Install to ready takes about 52 seconds on the shipped defaults.
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 or through cpln port-forward.
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 either credentials secret — both are your resources, created outside the release, and they stay until you remove them.

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

​Installation

UI

CLI

Terraform

Pulumi

​Upgrading From 1.0.0

​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

Installation

Upgrading From 1.0.0

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