SeaweedFS

Distributed file system with S3-compatible API and CSI driver for Kubernetes PersistentVolumes. Buckets (swbucket) and PVs (pv) are sub-components.

Architecture

                Master - Metadata management + volume assignment (StatefulSet)

                Volume - Data storage nodes with persistent storage (StatefulSet)

                Filer - POSIX-like filesystem layer (StatefulSet)

                S3 API - AWS S3-compatible endpoint on Filer (:{port} attribute)

                CSI Driver - K8s PV provisioner (optional, seaweed_csi = true)

Attributes

Attribute	Example	Description
`namespace` REQ	`seaweedfs`	Kubernetes namespace for all SeaweedFS resources
`access_key` REQ	`admin`	Root S3 API access key (admin identity with Admin+Read+Write actions)
`secret_key` REQ	`changeme123`	Root S3 API secret key
`port`	`8333`	S3 API port — used in Service and all S3 endpoint URLs
`replicas`	`3`	Replica count for ALL StatefulSets (master, volume, filer)
`pvc_size`	`100Gi`	PVC storage per Volume node. Master=10Gi, Filer=25Gi (fixed).
`resource_profile`	`medium`	Selects resource sizing (small/medium/large/x-large). Sets CPU+memory for master, volume, filer. See Resource Profiles.
`global_version`	`3.71`	SeaweedFS Helm chart version
`seaweed_csi`	`true`	Enables CSI driver (controller + node DaemonSet + StorageClass). Required for `pv` sub-components.
`seaweed_csi_version`	`0.2.2`	CSI driver Helm chart version. Only relevant when `seaweed_csi = true`.

Sub-Components

swbucket - S3 Bucket

Each swbucket creates an S3 bucket via init Job, a per-bucket K8s Secret with credentials, and an S3 identity entry with scoped IAM permissions.

Attribute	Example	Impact
`bucket` REQ	`loki-chunks`	S3 bucket name — created by init Job, used for IAM action scoping
`access_key` REQ	`loki-user`	Per-bucket access key → stored in `{name}-credentials` Secret. Must be unique across all swbuckets.
`secret_key` REQ	`secret123`	Per-bucket secret key → stored in `{name}-credentials` Secret. Must be unique across all swbuckets.
`bucket_actions`	`[read, write]`	S3 IAM permissions. If empty: defaults to Read, Write, List, Tagging. Each action scoped as `Action:bucket_name`.

pv - PersistentVolume (CSI)

Shared filesystem storage via CSI driver. Default ReadWriteMany — multiple pods can read/write simultaneously. Requires seaweed_csi = true. Apps link to pv and get a PVC + volumeMount auto-generated.

Attribute	Default	Impact
`pvc_size`	`5Gi`	PV capacity storage
`accessMode`	`ReadWriteMany`	ReadWriteMany for shared access (HPA/replicas). ReadWriteOnce for single-pod.
`path`	(empty)	Filer path prefix for the volume
`collection_name`	{pv name}	SeaweedFS collection name. Defaults to pv sub-component name.
`seaweed_replication`	(empty)	Data replication strategy (e.g., "001" = one replica on different rack)
`disk_type`	(empty)	Storage tier (e.g., "ssd", "hdd")
`data_locality`	(empty)	Data placement (e.g., "write_preferlocaldc")

Links

Link Type	Direction	What Gets Automated
`prometheus-seaweedfs`	Prometheus → SeaweedFS	3 ServiceMonitor CRs (master, volume, filer) scraping /metrics every 30s
`loki-seaweedfs`	Loki → SeaweedFS	SeaweedFS becomes Loki's S3 chunk storage backend
`velero-seaweedfs`	Velero → SeaweedFS	SeaweedFS S3 as Velero BackupStorageLocation
`istio-seaweedfs`	Istio → SeaweedFS	Sidecar injection + mTLS on all SeaweedFS pods
`kong-seaweedfs`	Kong → SeaweedFS	Kong Ingress route exposing S3 API
`react-seaweedfs`	React → SeaweedFS	S3 storage env vars injected into React app
`topic-swbucket`	Kafka Topic → swbucket	Kafka Connect CamelMinioSink auto-configured to write topic data to S3 bucket
`apisix-seaweedfs`	SeaweedFS → APISIX	APISIX route for S3 API external access
`backend-storage`	Backend App → swbucket	S3 credentials + endpoint injected as ENV vars (S3_ENDPOINT, AWS_ACCESS_KEY_ID, etc.)
`database-swbucket`	PostgreSQL db → swbucket	Filer metadata on PostgreSQL + database backup to S3 bucket
`external_source_code-pv` `image_base-pv`	App → pv	PVC + volumeMount auto-generated on the app. Link attribute: `mount_path` (e.g. `/data`)

Generated Files

File	Condition	Contains
`k8s/deploy/base/seaweedfs.yaml`	Always	ServiceAccount, Service (S3:{port}, Filer:8888), Master/Volume/Filer StatefulSets
`k8s/deploy/base/namespace.yaml`	Always	Namespace definition
`k8s/deploy/base/kustomization.yaml`	Always	Kustomize resources, secretGenerator, labels, resource patches
`k8s/deploy/base/service-monitor.yaml`	If prometheus linked	3 ServiceMonitor CRs (master, volume, filer) scraping /metrics every 30s
`k8s/deploy/base/swbucket.yaml`	If swbucket sub-components	K8s Job that creates each S3 bucket via `mc mb`
`k8s/deploy/base/seaweedfs-csi.yaml`	If seaweed_csi = true	CSI controller Deployment, node DaemonSet, mount service DaemonSet, StorageClass
`k8s/deploy/base/pv.yaml`	If pv sub-components	One PersistentVolume per pv sub-component (CSI driver, Retain reclaim policy)
`k8s/deploy/base/patch/resource-{size}.yaml`	ONE selected by resource_profile	CPU+memory requests+limits for master, volume, filer
`k8s/deploy/base/patch/csi-priority.yaml`	If seaweed_csi = true	Removes hardcoded priorityClassName from CSI components
`k8s/deploy/base/secret/s3-secret.yaml`	Always	K8s Secret: admin credentials + S3 config JSON with per-bucket identities and IAM actions
`k8s/deploy/base/secret/seaweedfs.env`	Always (SOPS)	Root S3 credentials (accessKey + secretKey)
`k8s/deploy/base/secret/cloud.env`	Always (SOPS)	S3_ENDPOINT + S3_REGION
`k8s/deploy/base/secret/swbucket-secret.yaml`	If swbucket sub-components (SOPS)	One Secret per swbucket: `{name}-credentials` with access-key, secret-key, endpoint, bucket name
`docker/swbucket-job/Dockerfile`	Always	Docker image for bucket creation Job (mc client)
`helm/helm-values.yaml`	Always	SeaweedFS Helm chart values
`helm/csi-values.yaml`	If seaweed_csi = true	CSI driver Helm chart values

Resource Profiles

Profile	Master (req/limit)	Volume (req/limit)	Filer (req/limit)
small	100m/256Mi → 200m/512Mi	200m/1Gi → 500m/2Gi	100m/512Mi → 300m/1Gi
medium	250m/512Mi → 500m/1Gi	500m/2Gi → 1/4Gi	250m/1Gi → 500m/2Gi
large	500m/1Gi → 1/2Gi	1/4Gi → 2/8Gi	500m/2Gi → 1/4Gi
x-large	1/2Gi → 2/4Gi	2/8Gi → 4/16Gi	1/4Gi → 2/8Gi