Configuration Reference

This page provides a comprehensive reference for all configuration options available in the SeaweedFS operator.

Seaweed Resource Configuration

Top-Level Configuration

Field	Type	Default	Description
image	string	-	Container image for SeaweedFS
version	string	-	SeaweedFS version
metrics	*MetricsSpec	-	Metrics configuration
master	*MasterSpec	-	Master server configuration
volume	*VolumeSpec	-	Volume server configuration
filer	*FilerSpec	-	Filer server configuration
filerBackup	*FilerBackupSpec	-	Filer backup configuration
admin	*AdminSpec	-	Admin UI configuration
schedulerName	string	-	Kubernetes scheduler name
pvReclaimPolicy	*corev1.PersistentVolumeReclaimPolicy	-	PV reclaim policy
imagePullPolicy	corev1.PullPolicy	-	Image pull policy
imagePullSecrets	[]corev1.LocalObjectReference	-	Image pull secrets
enablePVReclaim	*bool	-	Enable PVC reclaim
hostNetwork	*bool	-	Enable host networking
affinity	*corev1.Affinity	-	Pod affinity rules
nodeSelector	map[string]string	-	Node selector
annotations	map[string]string	-	Pod annotations
tolerations	[]corev1.Toleration	-	Pod tolerations
statefulSetUpdateStrategy	appsv1.StatefulSetUpdateStrategyType	-	StatefulSet update strategy
storage	*StorageSpec	-	Storage configuration
hostSuffix	*string	-	Host suffix for ingresses

MetricsSpec

Field	Type	Default	Description
enabled	bool	false	Enable metrics collection
metricsPort	*int32	5555	Port for Prometheus metrics

StorageSpec

Field	Type	Default	Description
storageClassName	*string	-	Storage class for all components
volumeServerDiskCount	int32	-	Number of disks per volume server

MasterSpec

Field	Type	Default	Description
replicas	int32	1	Number of master replicas (minimum 1)
service	*ServiceSpec	-	Service configuration
config	*string	-	Raw TOML configuration
metricsPort	*int32	-	Prometheus metrics port
volumePreallocate	*bool	-	Enable volume preallocation
volumeSizeLimitMB	*int32	-	Volume size limit in MB
garbageThreshold	*string	-	Garbage collection threshold
pulseSeconds	*int32	-	Pulse interval in seconds
defaultReplication	*string	-	Default replication setting
concurrentStart	*bool	-	Enable concurrent startup

VolumeSpec

Field	Type	Default	Description
replicas	int32	1	Number of volume replicas (minimum 1)
service	*ServiceSpec	-	Service configuration
storageClassName	*string	-	Storage class for volumes
metricsPort	*int32	-	Prometheus metrics port
compactionMBps	*int32	-	Compaction speed in MB/s
fileSizeLimitMB	*int32	-	File size limit in MB
fixJpgOrientation	*bool	-	Fix JPEG orientation
idleTimeout	*int32	-	Idle timeout in seconds
maxVolumeCounts	*int32	-	Maximum volume counts
minFreeSpacePercent	*int32	-	Minimum free space percentage

FilerSpec

Field	Type	Default	Description
replicas	int32	1	Number of filer replicas (minimum 1)
service	*ServiceSpec	-	Service configuration
config	*string	-	Raw TOML configuration
metricsPort	*int32	-	Prometheus metrics port
persistence	*PersistenceSpec	-	Persistence configuration
maxMB	*int32	-	Maximum file size in MB
s3	bool	true	Enable S3 compatibility

AdminSpec

Field	Type	Default	Description
replicas	int32	1	Number of admin replicas (minimum 1)
service	*ServiceSpec	-	Service configuration
port	*int32	23646	Admin server port
masters	string	-	Comma-separated master servers
dataDir	string	-	Data directory
adminUser	string	"admin"	Admin username
adminPassword	string	-	Admin password
adminPasswordSecretRef	*AdminPasswordSecretRef	-	Admin password secret reference
persistence	*PersistenceSpec	-	Persistence configuration
tls	*AdminTLSSpec	-	TLS configuration

ServiceSpec

Field	Type	Default	Description
type	corev1.ServiceType	-	Service type
annotations	map[string]string	-	Service annotations
loadBalancerIP	*string	-	Load balancer IP
clusterIP	*string	-	Cluster IP

PersistenceSpec

Field	Type	Default	Description
enabled	bool	false	Enable persistence
existingClaim	*string	-	Use existing PVC
mountPath	*string	"/data"	Volume mount path
subPath	*string	""	Subdirectory to mount
accessModes	[]corev1.PersistentVolumeAccessMode	["ReadWriteOnce"]	Volume access modes
selector	*metav1.LabelSelector	-	Volume selector
resources	corev1.VolumeResourceRequirements	{requests:{storage:"4Gi"}}	Volume resource requirements
volumeName	string	-	Volume name
storageClassName	*string	-	Storage class
volumeMode	*corev1.PersistentVolumeMode	-	Volume mode
dataSource	*corev1.TypedLocalObjectReference	-	Data source

BucketClaim Resource Configuration

BucketClaimSpec

Field	Type	Required	Default	Description
bucketName	string	Yes	-	Name of the bucket to be created
clusterRef	ClusterReference	Yes	-	Reference to the Seaweed cluster
replication	string	No	"000"	Replication setting for the bucket
collection	string	No	-	Collection setting for the bucket
ttlSec	*int32	No	-	TTL in seconds for objects in the bucket
readOnly	bool	No	false	Whether the bucket should be read-only

ClusterReference

Field	Type	Required	Description
name	string	Yes	Name of the Seaweed cluster
namespace	string	No	Namespace of the Seaweed cluster (defaults to BucketClaim namespace)

Component Configuration Inheritance

The SeaweedFS operator uses a hierarchical configuration system where component-level settings can override cluster-level settings:

ComponentSpec (Base for all components)

Field	Type	Description
version	*string	Override cluster-level version
imagePullPolicy	*corev1.PullPolicy	Override cluster-level imagePullPolicy
imagePullSecrets	[]corev1.LocalObjectReference	Override cluster-level imagePullSecrets
hostNetwork	*bool	Override cluster-level hostNetwork
affinity	*corev1.Affinity	Override cluster-level affinity
priorityClassName	*string	Component-specific priority class
schedulerName	*string	Override cluster-level schedulerName
nodeSelector	map[string]string	Merge with cluster-level nodeSelector
annotations	map[string]string	Merge with cluster-level annotations
tolerations	[]corev1.Toleration	Override cluster-level tolerations
env	[]corev1.EnvVar	Additional environment variables
terminationGracePeriodSeconds	*int64	Pod termination grace period
statefulSetUpdateStrategy	appsv1.StatefulSetUpdateStrategyType	Override cluster-level strategy

Resource Requirements

All components support Kubernetes resource requirements:

spec:
  master:
    resources:
      requests:
        memory: "256Mi"
        cpu: "250m"
      limits:
        memory: "512Mi"
        cpu: "500m"

Environment Variables

You can add custom environment variables to any component:

spec:
  filer:
    env:
    - name: CUSTOM_VAR
      value: "custom-value"
    - name: SECRET_VAR
      valueFrom:
        secretKeyRef:
          name: my-secret
          key: secret-key

Node Selectors

Place pods on specific nodes:

spec:
  nodeSelector:
    storage: ssd
    zone: us-west-1a

Tolerations

Allow pods to be scheduled on tainted nodes:

spec:
  tolerations:
  - key: "dedicated"
    operator: "Equal"
    value: "seaweedfs"
    effect: "NoSchedule"

Storage Classes

Configure storage for different components:

spec:
  storage:
    storageClassName: "fast-ssd"
  volume:
    storageClassName: "high-iops"  # Override for volume servers

TLS Configuration

Configure TLS for the admin UI:

spec:
  admin:
    tls:
      enabled: true
      certificateSecretRef:
        name: admin-tls-secret
        mapping:
          cert: tls.crt
          key: tls.key
          ca: ca.crt

Backup Configuration

Configure backup destinations:

spec:
  filerBackup:
    sink:
      s3:
        enabled: true
        region: "us-west-2"
        bucket: "seaweedfs-backup"
        directory: "backups"
        awsCredentialsSecretRef:
          name: aws-credentials
          mapping:
            awsAccessKeyID: access-key
            awsSecretAccessKey: secret-key

Validation Rules

Required Fields

• BucketClaimSpec.bucketName: Must be a valid bucket name
• BucketClaimSpec.clusterRef.name: Must reference an existing Seaweed cluster
• SeaweedSpec.master.replicas: Must be at least 1
• SeaweedSpec.volume.replicas: Must be at least 1
• SeaweedSpec.filer.replicas: Must be at least 1

Default Values

• BucketClaimSpec.replication: "000" (no replication)
• BucketClaimSpec.readOnly: false
• AdminSpec.adminUser: "admin"
• AdminSpec.port: 23646
• MetricsSpec.metricsPort: 5555
• PersistenceSpec.mountPath: "/data"
• PersistenceSpec.accessModes: ["ReadWriteOnce"]
• PersistenceSpec.resources.requests.storage: "4Gi"

Best Practices

Resource Sizing

• Start with small resource requests and adjust based on usage
• Monitor resource usage and scale accordingly
• Use resource limits to prevent resource exhaustion

Storage Configuration

• Use appropriate storage classes for your workload
• Consider using fast storage for volume servers
• Use persistent storage for filer and admin components

Security

• Use secrets for sensitive configuration
• Enable TLS for admin UI in production
• Configure appropriate RBAC permissions

Monitoring

• Enable metrics for all components
• Set up alerts for resource usage
• Monitor cluster health and performance

Related Resources

• Seaweed Resource - Main SeaweedFS cluster resource
• BucketClaim Resource - Bucket management resource
• Quick Start - Getting started guide
• Examples - Practical configuration examples