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

> Easily deploy a Swarm Bee node cluster on Kubernetes with Beekeeper. Automate StatefulSet, Service, and PVC provisioning using the BeeCluster custom resource for scalable deployments.

- Repository: [Ethersphere/awesome-swarm](https://github.com/ethersphere/awesome-swarm)
- Tags: how-to-guide
- Published: 2026-03-01

---

**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`](https://github.com/ethersphere/awesome-swarm/blob/main/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`](https://github.com/ethersphere/awesome-swarm/blob/main/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`](https://github.com/ethersphere/awesome-swarm/blob/main/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`](https://github.com/ethersphere/awesome-swarm/blob/main/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`](https://github.com/ethersphere/awesome-swarm/blob/main/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.

```bash
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:

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

```

Verify the operator pod is running:

```bash
kubectl get pods -n beekeeper-system

```

The operator binary in [`cmd/operator/main.go`](https://github.com/ethersphere/awesome-swarm/blob/main/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.

```yaml
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:

```bash
kubectl apply -f beecluster.yaml

```

### 4. Verify Operator Reconciliation

The operator in [`controllers/beecluster_controller.go`](https://github.com/ethersphere/awesome-swarm/blob/main/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:

```bash
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:

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

```

Test node health:

```bash
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.

```bash
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`](https://github.com/ethersphere/awesome-swarm/blob/main/controllers/beecluster_controller.go) and scales the underlying StatefulSet to eight replicas.

### Performing Rolling Upgrades

Update the Bee version by modifying the container image:

```bash
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:

```bash
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`](https://github.com/ethersphere/awesome-swarm/blob/main/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`](https://github.com/ethersphere/awesome-swarm/blob/main/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`](https://github.com/ethersphere/awesome-swarm/blob/main/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.