Skip to content

Basic Cluster

Jump to bottom
Nikita Ganzikov edited this page Jul 25, 2025 · 3 revisions

This example demonstrates how to create a basic SeaweedFS cluster with minimal configuration.

Overview

A basic SeaweedFS cluster consists of:

  • Master: Coordinates volume servers and manages metadata
  • Volume: Stores actual data files
  • Filer: Provides file system interface and S3 compatibility

Basic Configuration

Minimal Cluster

Create a simple SeaweedFS cluster with default settings:

apiVersion: seaweed.seaweedfs.com/v1
kind: Seaweed
metadata:
  name: basic-cluster
  namespace: default
spec:
  version: "3.67"
  master:
    replicas: 1
  volume:
    replicas: 3
  filer:
    replicas: 1
    s3: true

Production-Ready Cluster

A more robust configuration for production use:

apiVersion: seaweed.seaweedfs.com/v1
kind: Seaweed
metadata:
  name: production-cluster
  namespace: seaweedfs-system
  labels:
    environment: production
    app: seaweedfs
spec:
  version: "3.67"
  
  # Enable metrics for monitoring
  metrics:
    enabled: true
    metricsPort: 5555
  
  # Master configuration
  master:
    replicas: 3  # High availability
    resources:
      requests:
        cpu: 250m
        memory: 256Mi
      limits:
        cpu: 500m
        memory: 512Mi
    service:
      type: ClusterIP
    volumePreallocate: true
    volumeSizeLimitMB: 30000
    garbageThreshold: "0.3"
    pulseSeconds: 5
    defaultReplication: "001"
  
  # Volume configuration
  volume:
    replicas: 5  # Multiple volume servers
    resources:
      requests:
        cpu: 500m
        memory: 1Gi
      limits:
        cpu: 1000m
        memory: 2Gi
    storageClassName: "fast-ssd"
    compactionMBps: 2
    fileSizeLimitMB: 256
    maxVolumeCounts: 7
    minFreeSpacePercent: 1
  
  # Filer configuration
  filer:
    replicas: 2  # High availability
    resources:
      requests:
        cpu: 250m
        memory: 512Mi
      limits:
        cpu: 500m
        memory: 1Gi
    s3: true
    maxMB: 4
    persistence:
      enabled: true
      mountPath: "/data"
      resources:
        requests:
          storage: 10Gi
      accessModes:
        - ReadWriteOnce
      storageClassName: "fast-ssd"
  
  # Storage configuration
  storage:
    storageClassName: "fast-ssd"
    volumeServerDiskCount: 1
  
  # Node selection
  nodeSelector:
    storage: ssd
    zone: us-west-1a

Deployment Steps

1. Create the Cluster

# Apply the basic configuration
kubectl apply -f basic-cluster.yaml

# Or apply the production configuration
kubectl apply -f production-cluster.yaml

2. Monitor Deployment

# Check cluster status
kubectl get seaweed basic-cluster

# Watch pods being created
kubectl get pods -l app.kubernetes.io/name=seaweed -w

# Check all resources
kubectl get all -l app.kubernetes.io/name=seaweed

3. Verify Cluster Health

# Check master status
kubectl logs -l app.kubernetes.io/component=master

# Check volume server status
kubectl logs -l app.kubernetes.io/component=volume

# Check filer status
kubectl logs -l app.kubernetes.io/component=filer

Accessing the Cluster

Port Forwarding

# Access master
kubectl port-forward svc/basic-cluster-master 9333:9333

# Access filer
kubectl port-forward svc/basic-cluster-filer 8888:8888

# Access S3 endpoint
kubectl port-forward svc/basic-cluster-filer 8333:8333

Service URLs

Once the cluster is running, you can access:

  • Master: http://basic-cluster-master:9333
  • Filer: http://basic-cluster-filer:8888
  • S3: http://basic-cluster-filer:8333

Testing the Cluster

1. Upload a File via Filer

# Create a test file
echo "Hello SeaweedFS!" > test.txt

# Upload via curl
curl -X POST -F "file=@test.txt" http://localhost:8888/submit

2. Access via S3

# Using AWS CLI
aws s3 ls s3:// --endpoint-url http://localhost:8333

# Create a bucket
aws s3 mb s3://test-bucket --endpoint-url http://localhost:8333

# Upload a file
aws s3 cp test.txt s3://test-bucket/ --endpoint-url http://localhost:8333

3. Check Cluster Status

# Get cluster status from master
curl http://localhost:9333/cluster/status

# Get volume status
curl http://localhost:9333/vol/status

Scaling the Cluster

Scale Volume Servers

# Scale to 10 volume servers
kubectl patch seaweed basic-cluster --type='merge' -p='
spec:
  volume:
    replicas: 10
'

Scale Filer Servers

# Scale to 3 filer servers
kubectl patch seaweed basic-cluster --type='merge' -p='
spec:
  filer:
    replicas: 3
'

Monitoring

Enable Metrics

# Enable metrics if not already enabled
kubectl patch seaweed basic-cluster --type='merge' -p='
spec:
  metrics:
    enabled: true
'

Access Metrics

# Port forward metrics endpoint
kubectl port-forward svc/basic-cluster-master 5555:5555

# Access metrics
curl http://localhost:5555/metrics

Troubleshooting

Common Issues

1. Pods Not Starting

# Check pod events
kubectl describe pod -l app.kubernetes.io/name=seaweed

# Check resource limits
kubectl top pods -l app.kubernetes.io/name=seaweed

2. Storage Issues

# Check PVC status
kubectl get pvc -l app.kubernetes.io/name=seaweed

# Check storage class
kubectl get storageclass

3. Network Issues

# Check service endpoints
kubectl get endpoints -l app.kubernetes.io/name=seaweed

# Test connectivity
kubectl run test-pod --image=busybox --rm -it --restart=Never -- nslookup basic-cluster-master

Debug Commands

# Check all events
kubectl get events --sort-by='.lastTimestamp'

# Check operator logs
kubectl logs -n seaweedfs-operator-system deployment/seaweedfs-operator-controller-manager

# Check cluster status
kubectl describe seaweed basic-cluster

Cleanup

# Delete the cluster
kubectl delete seaweed basic-cluster

# Wait for cleanup
kubectl get pods -l app.kubernetes.io/name=seaweed

# Delete any remaining PVCs
kubectl delete pvc -l app.kubernetes.io/name=seaweed

Next Steps

Related Resources

Clone this wiki locally