Skip to content

Installation Guide

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

This guide covers different methods to install the SeaweedFS operator in your Kubernetes cluster.

Prerequisites

Before installing the SeaweedFS operator, ensure you have:

  • Kubernetes cluster (v1.19 or later)
  • kubectl configured to access your cluster
  • Helm (optional, for Helm installation)
  • Sufficient cluster resources for the operator

System Requirements

  • CPU: Minimum 2 cores, recommended 4+ cores
  • Memory: Minimum 2GB RAM, recommended 4GB+ RAM
  • Storage: At least 10GB available storage
  • Network: Internet access for pulling container images

Installation Methods

Method 1: Helm Installation (Recommended)

Helm is the recommended installation method as it provides easy management and upgrades.

1. Add the Helm Repository

helm repo add seaweedfs-operator https://nnstd.github.io/seaweedfs-operator
helm repo update

2. Install the Operator

# Install with default settings
helm install seaweedfs-operator seaweedfs-operator/operator \
  --namespace seaweedfs-operator-system \
  --create-namespace

# Install with custom values
helm install seaweedfs-operator seaweedfs-operator/operator \
  --namespace seaweedfs-operator-system \
  --create-namespace \
  --values custom-values.yaml

3. Verify Installation

# Check operator pods
kubectl get pods -n seaweedfs-operator-system

# Check CRDs
kubectl get crd | grep seaweed

# Check operator deployment
kubectl get deployment -n seaweedfs-operator-system

Method 2: kubectl Installation

For users who prefer direct kubectl installation or don't have Helm available.

1. Install CRDs

# Install Seaweed CRD
kubectl apply -f https://raw.githubusercontent.com/seaweedfs/seaweedfs-operator/main/config/crd/bases/seaweed.seaweedfs.com_seaweeds.yaml

# Install BucketClaim CRD
kubectl apply -f https://raw.githubusercontent.com/seaweedfs/seaweedfs-operator/main/config/crd/bases/seaweed.seaweedfs.com_bucketclaims.yaml

2. Install RBAC Resources

kubectl apply -f https://raw.githubusercontent.com/seaweedfs/seaweedfs-operator/main/config/rbac/

3. Install the Operator

kubectl apply -f https://raw.githubusercontent.com/seaweedfs/seaweedfs-operator/main/config/manager/

4. Verify Installation

# Check operator deployment
kubectl get deployment -n seaweedfs-operator-system

# Check operator pods
kubectl get pods -n seaweedfs-operator-system

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

Method 3: Operator Lifecycle Manager (OLM)

For clusters with OLM installed.

1. Install via OLM

# Create operator group
kubectl apply -f - <<EOF
apiVersion: operators.coreos.com/v1
kind: OperatorGroup
metadata:
  name: seaweedfs-operator-group
  namespace: seaweedfs-operator-system
spec:
  targetNamespaces:
  - seaweedfs-operator-system
EOF

# Create subscription
kubectl apply -f - <<EOF
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: seaweedfs-operator
  namespace: seaweedfs-operator-system
spec:
  channel: stable
  name: seaweedfs-operator
  source: operatorhubio-catalog
  sourceNamespace: olm
EOF

Configuration Options

Helm Values

Create a custom-values.yaml file to customize the installation:

# Operator configuration
operator:
  image:
    repository: ghcr.io/seaweedfs/seaweedfs-operator
    tag: v0.0.1
    pullPolicy: IfNotPresent
  
  # Resource limits
  resources:
    requests:
      cpu: 100m
      memory: 128Mi
    limits:
      cpu: 500m
      memory: 512Mi
  
  # Replica count
  replicaCount: 1
  
  # Node selector
  nodeSelector: {}
  
  # Tolerations
  tolerations: []
  
  # Affinity
  affinity: {}

# Webhook configuration
webhook:
  enabled: true
  port: 9443
  certDir: /tmp/certs

# Metrics configuration
metrics:
  enabled: true
  port: 8080
  serviceMonitor:
    enabled: false

# Security context
securityContext:
  runAsNonRoot: true
  runAsUser: 1000
  fsGroup: 1000

Environment Variables

You can configure the operator using environment variables:

# Set operator image
export OPERATOR_IMAGE=ghcr.io/seaweedfs/seaweedfs-operator:v0.0.1

# Set log level
export LOG_LEVEL=info

# Enable leader election
export ENABLE_LEADER_ELECTION=true

# Set metrics port
export METRICS_PORT=8080

Post-Installation Steps

1. Verify CRDs

Ensure all custom resource definitions are installed:

kubectl get crd | grep seaweed

Expected output:

bucketclaims.seaweed.seaweedfs.com
seaweeds.seaweed.seaweedfs.com

2. Check Operator Status

Verify the operator is running correctly:

# Check operator deployment
kubectl get deployment seaweedfs-operator-controller-manager -n seaweedfs-operator-system

# Check operator pods
kubectl get pods -n seaweedfs-operator-system -l control-plane=controller-manager

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

3. Test Installation

Create a simple SeaweedFS cluster to test the installation:

# test-cluster.yaml
apiVersion: seaweed.seaweedfs.com/v1
kind: Seaweed
metadata:
  name: test-cluster
  namespace: default
spec:
  version: "3.67"
  master:
    replicas: 1
  volume:
    replicas: 1
  filer:
    replicas: 1
    s3: true
kubectl apply -f test-cluster.yaml
kubectl get seaweed test-cluster

Upgrading the Operator

Helm Upgrade

# Update repository
helm repo update

# Upgrade operator
helm upgrade seaweedfs-operator seaweedfs-operator/operator \
  --namespace seaweedfs-operator-system

kubectl Upgrade

# Apply updated manifests
kubectl apply -f https://raw.githubusercontent.com/seaweedfs/seaweedfs-operator/main/config/crd/bases/
kubectl apply -f https://raw.githubusercontent.com/seaweedfs/seaweedfs-operator/main/config/manager/

Uninstalling the Operator

Helm Uninstall

# Uninstall operator
helm uninstall seaweedfs-operator -n seaweedfs-operator-system

# Delete namespace
kubectl delete namespace seaweedfs-operator-system

kubectl Uninstall

# Delete operator deployment
kubectl delete -f https://raw.githubusercontent.com/seaweedfs/seaweedfs-operator/main/config/manager/

# Delete RBAC resources
kubectl delete -f https://raw.githubusercontent.com/seaweedfs/seaweedfs-operator/main/config/rbac/

# Delete CRDs (this will also delete all custom resources)
kubectl delete -f https://raw.githubusercontent.com/seaweedfs/seaweedfs-operator/main/config/crd/bases/

# Delete namespace
kubectl delete namespace seaweedfs-operator-system

Troubleshooting

Common Issues

1. CRD Installation Failed

# Check if CRDs exist
kubectl get crd | grep seaweed

# Reinstall CRDs
kubectl apply -f https://raw.githubusercontent.com/seaweedfs/seaweedfs-operator/main/config/crd/bases/

2. Operator Pod Not Starting

# Check pod status
kubectl get pods -n seaweedfs-operator-system

# Check pod events
kubectl describe pod -n seaweedfs-operator-system <pod-name>

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

3. Permission Issues

# Check RBAC resources
kubectl get clusterrole,clusterrolebinding | grep seaweed

# Check service account
kubectl get serviceaccount -n seaweedfs-operator-system

4. Image Pull Issues

# Check image pull policy
kubectl get deployment seaweedfs-operator-controller-manager -n seaweedfs-operator-system -o yaml

# Check image pull secrets
kubectl get secrets -n seaweedfs-operator-system

Debug Commands

# Check all resources in operator namespace
kubectl get all -n seaweedfs-operator-system

# Check events
kubectl get events -n seaweedfs-operator-system --sort-by='.lastTimestamp'

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

# Check CRD status
kubectl get crd seaweed.seaweedfs.com_seaweeds -o yaml
kubectl get crd seaweed.seaweedfs.com_bucketclaims -o yaml

Security Considerations

RBAC Permissions

The operator requires the following permissions:

  • Create, read, update, delete Seaweed and BucketClaim resources
  • Manage StatefulSets, Services, ConfigMaps, and other Kubernetes resources
  • Access to secrets for configuration
  • Cluster-wide permissions for CRD management

Network Policies

Consider implementing network policies to restrict operator access:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: seaweedfs-operator-network-policy
  namespace: seaweedfs-operator-system
spec:
  podSelector:
    matchLabels:
      control-plane: controller-manager
  policyTypes:
  - Ingress
  - Egress
  ingress:
  - from:
    - namespaceSelector:
        matchLabels:
          name: default
  egress:
  - to:
    - namespaceSelector: {}

Pod Security Standards

The operator supports Pod Security Standards. Configure appropriate security contexts:

securityContext:
  runAsNonRoot: true
  runAsUser: 1000
  fsGroup: 1000
  capabilities:
    drop:
    - ALL

Support

For installation issues and support:

Related Resources

Clone this wiki locally