How to Set Up a Swarm Bee Node Cluster Using Beekeeper and Kubernetes

Deploy a scalable Swarm Bee cluster on Kubernetes by installing the Beekeeper operator and applying a declarative BeeCluster custom resource that automates StatefulSet, Service, and PVC provisioning.

Setting up a Swarm Bee node cluster manually requires managing multiple StatefulSets, persistent volumes, and network configurations. The Beekeeper project—specifically the ethersphere/beekeeper repository—simplifies this through a Kubernetes-native operator that treats Bee nodes as custom resources. This guide walks through the complete deployment flow using the operator's reconciliation logic, real configuration files, and production-ready scaling strategies.

What Is Beekeeper?

Beekeeper is a Kubernetes operator that automates the lifecycle management of Swarm Bee nodes. Instead of manually creating Deployments or StatefulSets for each Bee instance, you define a single BeeCluster custom resource (CR). The operator watches these CRs and automatically generates the necessary Kubernetes primitives—StatefulSets for stable network identities, headless Services for peer discovery, and PersistentVolumeClaims for storage.

According to the ethersphere/beekeeper source code, the operator's entry point in cmd/operator/main.go initializes controllers that continuously reconcile the cluster state with your declared configuration.

Architecture and Key Components

Understanding the architecture helps troubleshoot deployment issues and optimize resource allocation. The system consists of the following components:

• BeeCluster CRD – Defined in config/crd/bases/bee.beekeeper.ethswarm.io_beeclusters.yaml, this schema validates your cluster specification (node count, resources, storage).
• Beekeeper Operator – Runs as a Deployment in the beekeeper-system namespace. The reconciliation loop in controllers/beecluster_controller.go translates CRD changes into Kubernetes API calls.
• Bee Binary – The official ethersphere/bee container runs inside each pod, handling Swarm protocol operations.
• StatefulSet – Generated by the operator to provide stable hostnames (bee-0, bee-1, etc.) and ordered deployment guarantees.
• Headless Service – Enables DNS-based discovery between Bee nodes for P2P communication.
• ClusterIP Service – Exposes the Bee HTTP API (default port 1634) for external interaction.

The Go structs mapping YAML to internal objects reside in api/v1alpha1/beecluster_types.go, ensuring type safety during configuration parsing.

Prerequisites

Before deploying, ensure your environment meets these requirements:

• A running Kubernetes cluster (v1.20+) with kubectl configured
• storageClass available for PersistentVolumeClaims (e.g., standard on GKE, gp2 on AWS)
• Cluster-admin permissions to install Custom Resource Definitions (CRDs)
• (Optional) Helm 3.x if customizing operator deployment via helm/charts/beekeeper/values.yaml

Step-by-Step Deployment Guide

1. Install the Beekeeper CRDs

First, apply the BeeCluster custom resource definition to your cluster. This registers the schema that the operator will watch.

kubectl apply -f https://raw.githubusercontent.com/ethersphere/beekeeper/master/config/crd/bases/bee.beekeeper.ethswarm.io_beeclusters.yaml

This creates the bee.beekeeper.ethswarm.io/v1alpha1 API group and BeeCluster kind, validating subsequent manifests against the structural definition.

2. Deploy the Beekeeper Operator

Install the operator itself, which runs as a controller in its own namespace:

kubectl apply -f https://raw.githubusercontent.com/ethersphere/beekeeper/master/config/operator.yaml

Verify the operator pod is running:

kubectl get pods -n beekeeper-system

The operator binary in cmd/operator/main.go starts the controller manager, which begins watching for BeeCluster resources across all namespaces.

3. Create a BeeCluster Resource

Define your Swarm Bee node cluster in a YAML file. The specification supports node count, resource limits, storage classes, and monitoring sidecars.

apiVersion: bee.beekeeper.ethswarm.io/v1alpha1
kind: BeeCluster
metadata:
  name: production-swarm
  namespace: default
spec:
  size: 5
  image: ethersphere/bee:latest
  resources:
    limits:
      cpu: "2"
      memory: "4Gi"
  storage:
    className: standard
    size: 200Gi
  network:
    swarmPort: 1633
    apiPort: 1634
  monitoring:
    enabled: true

Key fields include:

• size: Number of Bee nodes (creates equivalent StatefulSet replicas)
• storage.className: Must match your cluster's StorageClass
• monitoring.enabled: Deploys Prometheus exporter sidecars for metrics collection

Apply the manifest:

kubectl apply -f beecluster.yaml

4. Verify Operator Reconciliation

The operator in controllers/beecluster_controller.go processes the new resource and creates:

1. A StatefulSet named production-swarm-bee
2. A headless Service production-swarm-bee-headless for inter-node P2P communication
3. A ClusterIP Service production-swarm-bee-api exposing port 1634
4. Individual PersistentVolumeClaims for each replica (e.g., data-production-swarm-bee-0)

Check the deployment status:

kubectl get statefulset production-swarm-bee
kubectl get pvc -l app=production-swarm-bee

5. Interact with the Cluster

Access the Bee HTTP API by port-forwarding the generated Service:

kubectl port-forward svc/production-swarm-bee-api 1634:1634

Test node health:

curl http://localhost:1634/health

For production workloads, expose the Service via Ingress or LoadBalancer instead of port-forwarding, targeting port 1634 defined in the apiPort field.

Managing and Scaling the Cluster

Scaling Node Count

Increase the cluster size by patching the size field. The operator performs a rolling update, creating new PVCs and pods while preserving existing data.

kubectl patch beecluster production-swarm -p '{"spec":{"size":8}}' --type=merge

The operator detects the change through its watch mechanism in controllers/beecluster_controller.go and scales the underlying StatefulSet to eight replicas.

Performing Rolling Upgrades

Update the Bee version by modifying the container image:

kubectl set image statefulset/production-swarm-bee bee=ethersphere/bee:v2.0.0

The operator ensures zero-downtime by respecting the StatefulSet's partition update strategy, restarting nodes sequentially while maintaining Swarm network connectivity through the remaining pods.

Storage Management

Each node's data persists independently via dedicated PVCs. To inspect storage utilization:

kubectl exec -it production-swarm-bee-0 -- df -h /app/data

Backing up a node requires snapshotting its corresponding PVC, identified by the naming convention data-<cluster-name>-bee-<index>.

Summary

• Beekeeper abstracts complexity by translating a single BeeCluster YAML into complete Kubernetes resource graphs (StatefulSets, Services, PVCs).
• Declarative management in config/crd/bases/bee.beekeeper.ethswarm.io_beeclusters.yaml enables version-controlled infrastructure.
• StatefulSets provide stability with persistent identities and storage, critical for Swarm's P2P overlay network.
• Scaling and upgrades are handled gracefully through the operator's reconciliation loop defined in controllers/beecluster_controller.go.
• Monitoring integration via the monitoring.enabled flag deploys Prometheus exporters automatically for observability.

Frequently Asked Questions

What is the difference between Beekeeper and running Bee nodes manually?

Beekeeper automates lifecycle management through a Kubernetes operator pattern. While manual deployments require you to manage individual Pod specs, Services, and PVCs, Beekeeper consolidates this into a single BeeCluster custom resource. The operator continuously ensures the actual cluster state matches your declared specification, handling rolling upgrades, scaling, and failure recovery automatically.

Which Kubernetes storage class should I use for Bee nodes?

Use a StorageClass that supports ReadWriteOnce (RWO) access mode with SSD-backed volumes for optimal Swarm performance. The storage.className field in your BeeCluster spec should reference classes like standard (GKE), gp2 or gp3 (AWS), or managed-csi-premium (Azure). Bee nodes are I/O intensive, so avoid slow magnetic storage to prevent chunk syncing bottlenecks.

How does Beekeeper handle Bee node upgrades without data loss?

The operator leverages StatefulSet rolling updates combined with PersistentVolumeClaims. When you update the image field or patch the container version, the operator modifies the StatefulSet spec, which triggers a partitioned rollout. Each pod terminates gracefully (allowing Bee to complete in-flight operations), restarts with the new image, and reattaches its existing PVC, preserving all Swarm data and overlay addresses.

Can I run Beekeeper on managed Kubernetes services like GKE or EKS?

Yes, Beekeeper is platform-agnostic and runs on any CNCF-compliant Kubernetes distribution, including Google GKE, Amazon EKS, Azure AKS, and local KinD clusters. The config/operator.yaml manifest uses standard Kubernetes APIs without cloud-specific dependencies. Ensure your cloud provider supports the StorageClass specified in your BeeCluster spec for persistent storage provisioning.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}