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 weed mini process — with persistent storage, startup bucket creation and signed-request (SigV4) authentication 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 data leaving your organization. Both sets of credentials — the S3 keys and the admin UI login — come from dictionary secrets you create before installing; the template creates no secrets of its own.

This template deploys into an existing GVC that you already have. It does not create or manage a GVC. Pass the GVC with --gvc GVC_NAME at install time.

What Gets Created

Resource	Name	Purpose	Optional
Workload	`RELEASE_NAME-seaweedfs`	All-in-one SeaweedFS node (stateful, 1 replica); S3 API on port `8333`, admin UI on port `23646`	—
Volume set	`RELEASE_NAME-seaweedfs-data`	Persistent disk at `/data` for objects, filer metadata and master metadata (20 GiB by default); a final snapshot is kept for 7 days on deletion	—
Identity	`RELEASE_NAME-seaweedfs-identity`	Workload identity used to read the prerequisite secrets	—
Policy	`RELEASE_NAME-seaweedfs-policy`	Grants the identity `reveal` on your S3 credentials secret, plus your admin credentials secret while `adminUI.enabled` is `true`	—

The admin UI port 23646 is only declared on the workload when adminUI.enabled is true (the default).

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 guards 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. Every S3 client uses these, and SeaweedFS serves S3 with no authentication at all when they are absent:

cpln secret create-dictionary --name S3_CREDENTIALS_SECRET_NAME \
  --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 ADMIN_CREDENTIALS_SECRET_NAME \
  --entry username=admin \
  --entry password="$(openssl rand -hex 24)"

Set adminUI.credentialsSecretName to the name you used.

Read either secret back later

Pass -o yaml; a bare cpln secret reveal prints only a summary table, not the values:

cpln secret reveal ADMIN_CREDENTIALS_SECRET_NAME -o yaml

A missing prerequisite secret wedges the install rather than failing it. cpln helm install reports success and all four resources are created, but the workload never starts. Because the container never ran, cpln logs returns zero lines, which looks like a platform fault rather than a missing step.The only place the missing secret is named is status.versions[].message:

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

The secret ADMIN_CREDENTIALS_SECRET_NAME no longer exists. Workload updates are
paused until the secret is added or the reference to the secret removed.

Use get-deployments — plain cpln workload get has no versions key. Once the secret exists the deployment recovers on its own after several minutes, or immediately with a forced redeployment:

cpln workload force-redeployment RELEASE_NAME-seaweedfs --gvc GVC_NAME

Installation

With both secrets in place, install into your existing GVC, passing the names of the two secrets you created above:

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/seaweedfs \
  --version 1.1.0 --gvc GVC_NAME \
  --set s3.credentialsSecretName=S3_CREDENTIALS_SECRET_NAME \
  --set adminUI.credentialsSecretName=ADMIN_CREDENTIALS_SECRET_NAME

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

Upgrading a release installed with 1.0.0 is a breaking change. adminUI.username and adminUI.password no longer exist, and an upgrade that still sets either one is refused before anything is applied. Follow the upgrade notes under Operations first.

Configuration

Image and Resources

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)

weed mini is the image’s own default command; the template pins every port explicitly because the port layout can change between upstream releases. Pin a concrete released tag, never latest.

Storage

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

One volume holds object data, filer metadata and master metadata. The chart refuses to render when capacity is below 10 or when autoscaling is enabled with maxCapacity smaller than capacity. Data survives restarts, redeployments and helm upgrade under the same release name; uninstalling deletes the volume set and every stored object, 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:
  # 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: []

s3.buckets entries must be lowercase letters, digits, dots and hyphens, 3–63 characters, starting with a letter or digit; the chart refuses to render otherwise. Buckets are only ever created, never deleted — removing a name from the list leaves the bucket in place, and adding one takes effect on the next restart. You can also create buckets at any time through the admin UI or with aws s3 mb.

Admin UI

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

The admin UI listens on port 23646 and is reachable from inside the GVC only; it is never publicly routed. Setting adminUI.enabled: false removes the port and the credential references from the workload and narrows the policy to the S3 credentials secret alone — the admin routes then return 404. With the UI disabled, credentialsSecretName may be left empty.

Access

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
  # workloads:
  #   - //gvc/GVC_NAME/workload/WORKLOAD_NAME

`internalAccess.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 the workloads listed in `internalAccess.workloads`.

publicAccess.enabled: true serves the S3 API 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. Access changes can take a few minutes to take effect.

Connecting

Target	Address	Notes
S3 API, inside the GVC	`http://RELEASE_NAME-seaweedfs.GVC_NAME.cpln.local:8333`	Plain `http://`; path-style addressing.
S3 API, host:port form	`RELEASE_NAME-seaweedfs.GVC_NAME.cpln.local:8333`	For clients that take a bare host:port (Thanos, Mimir, Prometheus, DuckDB). Pair with their `insecure: true` or equivalent.
S3 API, public	`https://<canonical>.cpln.app`	Only with `publicAccess.enabled: true`; port 443, no port suffix. Read it from `status.canonicalEndpoint`.
Admin UI	`http://RELEASE_NAME-seaweedfs.GVC_NAME.cpln.local:23646`	Inside the GVC only. From your machine, use the port-forward below.
Health check	`GET /healthz` on port `8333`	Unauthenticated by design.
S3 credentials	`cpln secret reveal S3_CREDENTIALS_SECRET_NAME -o yaml`	`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`.
Admin UI credentials	`cpln secret reveal ADMIN_CREDENTIALS_SECRET_NAME -o yaml`	`username` / `password`.

Find the canonical hostname with:

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

Verify the S3 API from your machine through a tunnel — it works even when the workload is closed to the internet. Export the two keys from your S3 credentials secret first, then:

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

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

Requests without a valid signature are rejected: unsigned requests get 403, and a wrong secret key gets SignatureDoesNotMatch. To reach the admin UI from your machine:

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

Then open http://localhost:23646 and log in with the username and password from your admin credentials secret.

Using SeaweedFS as an S3 Backend

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

Path-style addressing is required. Objects are addressed as http://RELEASE_NAME-seaweedfs.GVC_NAME.cpln.local:8333/BUCKET/KEY; virtual-host style (BUCKET.host) is not served. Set forcePathStyle: true / addressing_style = path on the client.
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.

Endpoint form and credential shape for the common catalog consumers. In every case the two credential values are the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY from your S3 credentials secret — most consumers want them in a second dictionary secret under their own key names:

Consumer template	Endpoint value	Credentials
postgres-highly-available, timescaledb-highly-available	`backup.provider: minio`, `backup.minio.endpoint: http://RELEASE_NAME-seaweedfs.GVC_NAME.cpln.local:8333`	`backup.minio.credentialsSecretName` → a dictionary secret with keys `accessKey` and `secretKey`
thanos, mimir	`storage.type: minio`, `storage.minio.endpoint: RELEASE_NAME-seaweedfs.GVC_NAME.cpln.local:8333` (no scheme), `storage.minio.insecure: true`	`storage.minio.credentialsSecretName` → a dictionary secret with keys `accessKey` and `secretKey`
prometheus	Same fields nested under the Thanos sidecar: `thanos.objectStorage.type: minio`, `thanos.objectStorage.minio.endpoint`, `thanos.objectStorage.minio.insecure: true`	`thanos.objectStorage.minio.credentialsSecretName` → a dictionary secret with keys `accessKey` and `secretKey`
sftpgo	`storage.type: minio`, `storage.minio.endpoint: http://RELEASE_NAME-seaweedfs.GVC_NAME.cpln.local:8333`	`storage.minio.accessKey` and `storage.minio.accessSecret` as values
docmost	`storage.type: s3`, `storage.s3.endpoint: http://RELEASE_NAME-seaweedfs.GVC_NAME.cpln.local:8333`, `storage.s3.forcePathStyle: true`	`storage.s3.auth.secretName` → a dictionary secret with keys `AWS_S3_ACCESS_KEY_ID` and `AWS_S3_SECRET_ACCESS_KEY`
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`	`…backup.minio.credentialsSecretName` → a dictionary secret with keys `accessKey` and `secretKey`
polaris, duckdb	See each page — both document SeaweedFS as a tested target.	—

Each consumer’s own page carries the exact create-secret command for its credentials secret. Templates whose object-storage support is limited to named cloud providers — ghost and clickhouse among them — have no arbitrary-endpoint option and cannot use this template as their storage target.

Operations

Backing Up

Everything SeaweedFS stores — objects and all metadata — lives on the single RELEASE_NAME-seaweedfs-data volume set, so a volume set snapshot captures the whole store consistently. Take one on demand:

cpln volumeset snapshot create RELEASE_NAME-seaweedfs-data --gvc GVC_NAME --snapshot-name NAME

cpln volumeset snapshot get RELEASE_NAME-seaweedfs-data --gvc GVC_NAME

For a scheduled snapshot policy, see the volume set reference. A final snapshot is also taken automatically when the volume set is deleted and kept for 7 days. For an object-level copy that any S3 tool can read, mirror a bucket with a standard S3 client over the tunnel from Connecting:

aws --endpoint-url http://localhost:8333 s3 sync s3://BUCKET ./BUCKET-copy

Restoring a Backup

Restoring a volume set snapshot onto this template has not been verified. The snapshot captures the disk, but restoring it into a running release — including how the single replica is re-attached to the restored volume — has not been exercised on this chart. Treat volume set snapshots as a safety net rather than a tested recovery path until you have rehearsed a restore yourself. See the volume set reference for the platform’s snapshot commands.

Restoring an object-level copy is an ordinary upload: create the bucket if it does not exist (through s3.buckets, the admin UI or aws s3 mb), then sync the copy back:

aws --endpoint-url http://localhost:8333 s3 sync ./BUCKET-copy s3://BUCKET

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 — a published default guarding the bucket browser and maintenance tools 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
S3 credentials	`s3.credentialsSecretName` prerequisite secret	Unchanged

An upgrade that still carries either removed key is rejected at render time, before anything is applied — and the guard fires even when adminUI.enabled is false, so a stale password: in your values cannot be silently accepted. The running release is left 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.

Create the admin credentials secret

Follow Prerequisites. Put your existing username and password into it if current logins should 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 — the S3 half is unchanged, and anything already backing up into SeaweedFS needs no edit.

Upgrade the release

Run cpln helm upgrade with --version 1.1.0 and your updated values, as described in the CLI guide. The single replica restarts and the S3 API is unavailable until it is back; stored objects on the volume set are untouched.

Rotating Credentials

Both secrets are read when a replica starts, so rotating one takes effect only after a redeployment. Update the secret’s values, then force a redeployment:

cpln workload force-redeployment RELEASE_NAME-seaweedfs --gvc GVC_NAME

Rotating the S3 credentials secret genuinely rotates the keys — the S3 identity is rebuilt from the environment on every boot rather than stored on disk. Once the new replica is serving, the old access key is rejected with InvalidAccessKeyId and stored objects are untouched. Update every consumer at the same time.

Scaling and Availability

The template deploys a single replica by design and exposes no replica count. weed mini runs one master, one filer and one volume server in a single process, so additional replicas would each hold a separate, divergent object store behind one name. Consequences:

A redeploy, helm upgrade or platform reschedule is a full S3 outage until the replica is back. Schedule upgrades accordingly.
Durability comes from the persistent volume set, not from replication: data survives restarts and reschedules, and a node failure re-attaches the same volume.
Grow capacity vertically — raise resources.maxMemory for very large object counts and volumeset.capacity (or enable volumeset.autoscaling) for more data.

Troubleshooting

Deployment never starts and cpln logs returns nothing

Symptom: cpln helm install succeeded, but the workload sits at zero replicas and cpln logs '{gvc="GVC_NAME", workload="RELEASE_NAME-seaweedfs"}' --limit 50 --since 10m returns no lines at all.Cause: One of the two prerequisite secrets does not exist, so the container is never started. The deployment message names it:

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

The secret S3_CREDENTIALS_SECRET_NAME no longer exists. Workload updates are
paused until the secret is added or the reference to the secret removed.

Fix: Create the missing secret as shown in Prerequisites. The deployment recovers on its own after several minutes, or immediately with cpln workload force-redeployment RELEASE_NAME-seaweedfs --gvc GVC_NAME.

helm upgrade fails with 'adminUI.username and adminUI.password were removed in seaweedfs 1.1.0'

Symptom: The upgrade stops at render time with that message and no revision is created.Cause: Your values still carry adminUI.username or adminUI.password, which 1.1.0 removed. The guard fires even with adminUI.enabled: false.Fix: Follow the steps under Upgrading from 1.0.0 above: create the admin credentials secret, remove both keys from your values, set adminUI.credentialsSecretName, then upgrade again.

S3 client gets 403 or SignatureDoesNotMatch

Symptom: aws s3 ls or a consumer template’s backup job is refused with 403 or an error body containing SignatureDoesNotMatch.Cause: The request is unsigned, or the client’s secret key does not match the value in your S3 credentials secret. A client using virtual-host-style addressing (bucket.host) also fails, because only path-style is served.Fix: Compare the client’s keys against cpln secret reveal S3_CREDENTIALS_SECRET_NAME -o yaml, and set path-style addressing on the client (aws configure set default.s3.addressing_style path, forcePathStyle: true, or the consumer’s equivalent).

S3 client gets InvalidAccessKeyId after rotating the secret

Symptom: Clients that worked before now fail with InvalidAccessKeyId.Cause: The S3 credentials secret was rotated and the node redeployed, so the old access key is no longer valid; the client still holds the old key.Fix: Update every consumer with the new AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY. Stored objects are unaffected.

Admin UI returns 404 or is unreachable

Symptom: Requests to port 23646 return 404, or the port cannot be reached at all.Cause: With adminUI.enabled: false the admin routes are unregistered and the port is not declared on the workload. With it enabled, the UI is still never publicly routed — publicAccess.enabled: true exposes port 8333 only, and requesting /login on the public endpoint reaches the S3 gateway instead.Fix: Set adminUI.enabled: true (with adminUI.credentialsSecretName pointing at an existing secret), and reach the UI with cpln port-forward RELEASE_NAME-seaweedfs 23646:23646 --gvc GVC_NAME or from a workload inside the GVC.

Changing publicAccess or internalAccess appears to have no effect

Symptom: Right after a helm upgrade that flipped an access setting, requests still get the old answer.Cause: Firewall changes take a few minutes to propagate.Fix: Wait and re-test before concluding the setting is broken.

Important Notes

Create both prerequisite secrets before installing. A missing one wedges the deployment with no log output; cpln workload get-deployments is the one command that names it.
The template creates no secrets. Both credentials are yours, so helm uninstall leaves them in place.
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 through cpln port-forward or from inside the GVC.
Single replica by design — every redeploy or upgrade is a full S3 outage until the replica is back.
Rotating a secret requires a forced redeployment to take effect; update every consumer at the same time.
Uninstall deletes the volume set and every stored object, keeping a final snapshot for 7 days.
Upgrading from 1.0.0 requires the admin credentials secret and removing adminUI.username / adminUI.password from your values.

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

Admin UI

Cluster status, bucket browser, and maintenance

SeaweedFS Template

View the source files, default values, and chart definition

​Overview

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Image and Resources

​Storage

​S3 API

​Admin UI

​Access

​Connecting

​Using SeaweedFS as an S3 Backend

​Operations

​Backing Up

​Restoring a Backup

​Upgrading from 1.0.0

​Rotating Credentials

​Scaling and Availability

​Troubleshooting

​Important Notes

​External References

SeaweedFS on GitHub

Quick Start with weed mini

Amazon S3 API Support

Admin UI

SeaweedFS Template

Overview

What Gets Created

Prerequisites

Installation

Configuration

Image and Resources

Storage

S3 API

Admin UI

Access

Connecting

Using SeaweedFS as an S3 Backend

Operations

Backing Up

Restoring a Backup

Upgrading from 1.0.0

Rotating Credentials

Scaling and Availability

Troubleshooting

Important Notes

External References