- Introduction
- Quick Start
- Requirements
- Installation
- Run unit tests
- Configuration
- Config file
- Config directory
- Usage
- Global flags
- Public Testnet Checks
Ethereum Swarm Beekeeper is an orchestration and testing tool for managing Ethereum Swarm Bee clusters. It enables:
- Cluster Management: Automate creation and deletion of Bee clusters in Kubernetes.
- Integration Checks: Run tests (e.g.,
pingpong
,pushsync
) to validate network behavior. - Static Endpoints Support: Execute checks without Kubernetes by using static Bee node endpoints.
- Node Funding: Automate funding Bee nodes with ETH and BZZ tokens (Kubernetes optional).
- Dynamic Configuration: Use flexible YAML-based configs for customizable actions.
Beekeeper simplifies the management and testing of Bee nodes, whether deployed in Kubernetes or standalone environments.
This setup is used both in our CI environment and for local development. It provides a consistent development environment that mirrors our production testing infrastructure.
CI Usage: Our CI pipeline uses this local development setup to run automated tests against Bee clusters, ensuring code quality and integration testing before deployment.
Local Development: Developers can use this same setup locally to test changes, debug issues, and validate functionality before pushing code. This ensures that what works locally will work in CI and production.
Prerequisites:
- Docker
- kubectl
- make
- go
Note: The setup uses K3s (lightweight Kubernetes) and k3d (K3s in Docker) for local cluster management. These tools provide a fast, lightweight Kubernetes environment perfect for development and testing.
Quick setup:
# Clone and build Beekeeper
git clone https://github.com/ethersphere/beekeeper
cd beekeeper
make binary
# Clone Bee repository for local setup
git clone https://github.com/ethersphere/bee
cd bee
# Install K3s cluster and Geth node
make beelocal ACTION=prepare SETUP_CONTRACT_IMAGE_TAG=0.9.2 OPTS='skip-vet'
> **Important:** The `SETUP_CONTRACT_IMAGE_TAG=0.9.2` parameter is required and must match exactly. This ensures compatibility with our CI pipeline and production environment. See our [CI workflow](https://github.com/ethersphere/bee/blob/3a5de30aba477560bfc503632479f4793d68dcef/.github/workflows/beekeeper.yml#L15) for reference.
# Deploy Bee nodes locally
cd ../beekeeper
./dist/beekeeper create bee-cluster --cluster-name=local-dns
# Verify deployment
./dist/beekeeper check --cluster-name=local-dns --checks=ci-pingpong
Need help? See the Bee Deployment Guide for detailed step-by-step instructions.
- Kubernetes cluster (v1.31+)
- Geth Swap node
make binary
cp dist/beekeeper /usr/local/bin/beekeeper
copy dist\beekeeper.exe C:\Windows\System32\beekeeper.exe
You can also add the dist/
directory to your system PATH instead of copying the binary:
- macOS/Linux: Add
export PATH="$PATH:$(pwd)/dist"
to your shell profile - Windows: Add the full path to
dist\
in your system Environment Variables
Note:
- If you installed Beekeeper system-wide (e.g., copied to
/usr/local/bin
orC:\Windows\System32
), usebeekeeper
in your commands.- If you are running directly from the build output without installing, use
./dist/beekeeper
(macOS/Linux) or.\dist\beekeeper.exe
(Windows) instead ofbeekeeper
in all command examples.
Runs available unit tests in pkg folder
make test
Beekeeper is configured with:
- config file - sets Beekeeper's internals, and
- config directory - sets Bee cluster configuration, checks and simulations
Config file is used to set Beekeeper internals:
config-dir
: config directory locationenable-k8s
: Kubernetes clientgeth-url
: Swap client - RPC endpoint, URL of the Ethereum-compatible blockchain RPC endpoint
Default location for config file is: $HOME/.beekeeper.yaml
Location can also be set with the --config
flag.
example:
config-dir: <user home dir>/.beekeeper/
config-git-repo: ""
config-git-branch: main
config-git-username: <GitHub username>
config-git-password: <GitHub Personal Access Token>
enable-k8s: true
in-cluster: false
kubeconfig: "~/.kube/config"
geth-url: http://geth-swap.geth-swap.dai.internal
bzz-token-address: 0x6aab14fe9cccd64a502d23842d916eb5321c26e7
eth-account: 0x62cab2b3b55f341f10348720ca18063cdb779ad5
log-verbosity: "info"
loki-endpoint: http://loki.testnet.internal/loki/api/v1/push
Beekeeper reads config-dir from the local machine by default, but it also supports reading config-dir from a Git repo. If the field config-git-repo is set, it will override config-dir and the configuration will be read from the Git repo.
If config-dir is kept in a Git repo, the field config-git-repo should point to it, along with config-git-branch specifying the proper branch. Fields config-git-username and config-git-password can be set when the repo is private.
Official GitHub repository with Beekeeper's configuration is https://github.com/ethersphere/beekeeper-config
General Notes:
- command flags can also be set through the config file
- k8s client can be disabled with enable-k8s flag (default is true)
Config directory is used to group configuration (.yaml) files describing:
- Bee cluster setup in Kubernetes
- checks (integration tests), and
- simulations
Default location for the config dir is: $HOME/.beekeeper/
Location can also be set with the --config-dir
flag.
Examples of .yaml files can be found in the Beekeeper repo.
Config dir's .yaml files have several main blocks:
clusters
: defines clusters Beekeeper works withnode-groups
: defines Bee node groups that are part of the cluster. Node group is a collection of Bee nodes sharing the same configuration parameters.bee-configs
: defines Bee configuration that can be assigned to node-groupschecks
: defines checks Beekeeper can execute against the clustersimulations
: defines simulations Beekeeper can execute against the clusterstages
: defines stages for dynamic execution of checks and simulations
Inheritance can be set through the field _inherit.
Clusters, node-groups and bee-configs blocks support inheritance.
example:
bee-configs:
light-node:
_inherit: default
full-node: false
This setting means that the light-node bee-config will inherit all parameters from the default bee-config, overriding only the full-node parameter.
Action types can be set in every check or simulation definition.
Action types allow defining the same check or simulation with different parameters.
example:
checks:
pushsync-chunks:
options:
chunks-per-node: 1
metrics-enabled: false
mode: chunks
postage-amount: 1000
postage-depth: 16
postage-wait: 5s
retries: 5
retry-delay: 1s
upload-node-count: 1
timeout: 5m
type: pushsync
pushsync-light-chunks:
options:
chunks-per-node: 1
metrics-enabled: false
mode: light-chunks
postage-amount: 1000
postage-depth: 16
postage-wait: 5s
retries: 5
retry-delay: 1s
upload-node-count: 1
timeout: 5m
type: pushsync
This setting means that the pushsync check can be executed by choosing the pushsync-chunks or pushsync-light-chunks variation.
beekeeper has the following commands:
command | description |
---|---|
check | runs integration tests on a Bee cluster |
create | creates Bee infrastructure |
delete | Deletes Bee infrastructure |
fund | Fund Ethereum addresses |
help | Help about any command |
nuke | Nuke Bee nodes in the cluster |
Print information about a Bee cluster | |
simulate | [DEPRECATED] Run simulations on a Bee cluster |
version | Print version number |
node-funder | Fund (top up) Bee nodes |
node-operator | Auto-funds (top up) Bee nodes on deployment. |
restart | Restart Bee nodes in Kubernetes |
stamper | Manage postage batches for nodes |
Command check runs integration tests on a Bee cluster.
It has following flags:
--checks strings list of checks to execute (default [pingpong])
--cluster-name string cluster name (default "default")
--create-cluster creates cluster before executing checks
--help help for check
--metrics-enabled enable metrics
--metrics-pusher-address string prometheus metrics pusher address (default "pushgateway.staging.internal")
--seed int seed, -1 for random (default -1)
--timeout duration timeout (default 30m0s)
example:
beekeeper check --checks=pingpong,pushsync
Command create creates Bee infrastructure. It has two subcommands:
- bee-cluster - creates Bee cluster
It has following flags:
--cluster-name string cluster name (default "default")
--help help for bee-cluster
--timeout duration timeout (default 30m0s)
--wallet-key string Hex-encoded private key for the Bee node wallet. Required.
It is required to specify the geth-url and wallet-key flags for funding Bee nodes, either by using flags or the config file.
example:
beekeeper create bee-cluster --cluster-name=default
- k8s-namespace - creates Kubernetes namespace
example:
beekeeper create k8s-namespace beekeeper
Command delete deletes Bee infrastructure. It has two subcommands:
- bee-cluster - deletes Bee cluster
It has following flags:
--cluster-name string cluster name (default "default")
--help help for bee-cluster
--timeout duration timeout (default 15m0s)
--with-storage delete storage
example:
beekeeper delete bee-cluster default
- k8s-namespace - deletes Kubernetes namespace
example:
beekeeper delete k8s-namespace beekeeper
Command fund makes BZZ tokens and ETH deposits to given Ethereum addresses.
It has the following flags:
--addresses strings Bee node Ethereum addresses (must start with 0x)
--address-create if enabled, creates Ethereum address(es)
--address-count number of Ethereum addresses to create
--bzz-deposit float BZZ tokens amount to deposit
--bzz-token-address string BZZ token address (default "0x6aab14fe9cccd64a502d23842d916eb5321c26e7")
--eth-account string ETH account address (default "0x62cab2b3b55f341f10348720ca18063cdb779ad5")
--eth-deposit float ETH amount to deposit
--help help for fund
--password password for generating Ethereum addresses (default "beekeeper")
--timeout duration timeout (default 5m0s)
examples:
beekeeper fund --addresses=0xf176839c150e52fe30e5c2b5c648465c6fdfa532,0xebe269e07161c68a942a3a7fce6b4ed66867d6f0 --bzz-deposit 100 --eth-deposit 0.01
beekeeper fund --address-create --address-count 2 --bzz-deposit 100 --eth-deposit 0.01
Command nuke executes a database nuke operation across Bee nodes in a Kubernetes cluster, forcing each node to resynchronize all data on the next startup.
This command provides StatefulSet update and rollback procedures to maintain cluster stability during the nuke process, ensuring safe and coordinated resets of node state.
It has the following flags:
--cluster-name string Target Beekeeper cluster name.
--namespace string Kubernetes namespace (overrides cluster name).
--label-selector string Kubernetes label selector for filtering resources when namespace is set (use empty string for all). (default "app.kubernetes.io/name=bee")
--restart-args strings Command to run in the Bee cluster, e.g. 'db,nuke,--config=.bee.yaml' (default [bee,start,--config=.bee.yaml])
--use-random-neighborhood Use random neighborhood for Bee nodes (default: false)
--timeout duration timeout (default 30m0s)
examples:
# Basic usage with cluster name
beekeeper nuke --cluster-name=default --restart-args="bee,start,--config=.bee.yaml"
# Namespace-based targeting
beekeeper nuke --namespace=my-namespace --restart-args="bee,start,--config=.bee.yaml"
# With random neighborhood targeting
beekeeper nuke --cluster-name=default --restart-args="bee,start,--config=.bee.yaml" --use-random-neighborhood=true
Command print prints information about a Bee cluster.
It has following flags:
--cluster-name string cluster name (default "default")
--help help for print
--timeout duration timeout (default 15m0s)
example:
beekeeper print overlays
Command simulate runs simulations on a Bee cluster. This command is deprecated and will be removed in a future version.
It has following flags:
--cluster-name string cluster name (default "default")
--create-cluster creates cluster before executing simulations
--help help for check
--metrics-enabled enable metrics
--metrics-pusher-address string prometheus metrics pusher address (default "pushgateway.staging.internal")
--seed int seed, -1 for random (default -1)
--simulations strings list of simulations to execute (default [upload])
--timeout duration timeout (default 30m0s)
example:
beekeeper simulate --simulations=upload
Command version prints the version number.
example:
beekeeper version
Command node-funder uses the https://github.com/ethersphere/node-funder tool to fund (top up) bee nodes up to the specified amount. It can fund all nodes in a k8s namespace or only specified addresses.
It has following flags:
--addresses strings Comma-separated list of Bee node addresses (must start with 0x). Overrides namespace and cluster name.
--cluster-name string Name of the Beekeeper cluster to target. Ignored if a namespace is specified.
--help help for node-funder
--label-selector string Kubernetes label selector for filtering resources within the specified namespace. Use an empty string to select all resources. (default "beekeeper.ethswarm.org/node-funder=true")
--min-native float Minimum amount of chain native coins (xDAI) nodes should have.
--min-swarm float Minimum amount of swarm tokens (xBZZ) nodes should have.
--namespace string Kubernetes namespace. Overrides cluster name if set.
--periodic-check duration Periodic execution check interval.
--timeout duration Operation timeout (e.g., 5s, 10m, 1.5h). (default 5m0s)
--wallet-key string Hex-encoded private key for the Bee node wallet. Required.
beekeeper node-funder --geth-url="http://geth-swap.default.testnet.internal" --wallet-key="4663c222787e30c1994b59044aa5045377a6e79193a8ead88293926b535c722d" --addresses=0xf176839c150e52fe30e5c2b5c648465c6fdfa532,0xebe269e07161c68a942a3a7fce6b4ed66867d6f0 --min-swarm=180 --min-native=2.2
beekeeper node-funder --geth-url="http://geth-swap.default.testnet.internal" --wallet-key="4663c222787e30c1994b59044aa5045377a6e79193a8ead88293926b535c722d" --namespace=default --min-swarm=180 --min-native=2.2 --label-selector="app=bee"
beekeeper node-funder --geth-url="http://geth-swap.default.testnet.internal" --wallet-key="4663c222787e30c1994b59044aa5045377a6e79193a8ead88293926b535c722d" --cluster-name=default --min-swarm=180 --min-native=2.2
Command node-operator uses the https://github.com/ethersphere/node-funder tool to fund (top up) bee nodes up to the specified amount. It runs in the Kubernetes namespace and watches for Bee node deployments. When a new deployment is created, it will fund it with the specified amount. It uses the filter "app.kubernetes.io/name=bee" on the label to determine which deployments to watch.
It has following flags:
--help help for node-operator
--min-native float Minimum amount of chain native coins (xDAI) nodes should have.
--min-swarm float Minimum amount of swarm tokens (xBZZ) nodes should have.
--namespace string Kubernetes namespace to scan for scheduled pods.
--label-selector string Kubernetes label selector for filtering resources within the specified namespace. An empty string disables filtering, allowing all resources to be selected.
--timeout duration Operation timeout (e.g., 5s, 10m, 1.5h). Default is 0, which means no timeout.
--wallet-key string Hex-encoded private key for the Bee node wallet. Required.
example:
beekeeper node-operator --geth-url="http://geth-swap.default.testnet.internal" --wallet-key="4663c222787e30c1994b59044aa5045377a6e79193a8ead88293926b535c722d" --namespace=default --min-swarm=180 --min-native=2.2 --log-verbosity=3
Command restart restarts bee nodes in Kubernetes, with optional targeting by namespace, label selectors, and node groups.
It has following flags:
--cluster-name string Kubernetes cluster to operate on (overrides namespace and label selector).
--namespace string Namespace to delete pods from (only used if cluster name is not set).
--label-selector string Label selector for resources in the namespace (only used with namespace). An empty string disables filtering, allowing all resources to be selected.
--image string Container image to use when restarting pods (defaults to current image if not set).
--node-groups strings Comma-separated list of node groups to target for restarts (applies to all groups if not set).
--timeout duration Operation timeout (e.g., 5s, 10m, 1.5h). (default 5m0s)
example:
beekeeper restart --cluster-name=default --image="bee:latest" --node-groups="group1,group2" --timeout=10m
or
beekeeper restart --namespace=default --label-selector="app=bee" --timeout=10m
Command stamper manages postage batches for nodes.
General Notes:
namespace
orcluster-name
must be specified to locate the bee nodes.- If both are provided,
namespace
takes precedence. - When
namespace
is set, you can use alabel-selector
to filter specific nodes. - Use
batch-ids
to target specific postage batches; this is applied after finding/filtering nodes. Ifbatch-ids
is not provided, all batches in the filtered nodes are targeted. - If
timeout
is set to 0 andperiodic-check
is greater than 0, the operation will run indefinitely with periodic checks.
It has the following subcommands:
-
create - creates a postage batch for selected nodes
It has following flags:
--cluster-name string Target Beekeeper cluster name. --depth uint16 Batch depth which specifies how many chunks can be signed with the batch. It is a logarithm. Must be higher than default bucket depth (16) (default 17) --duration duration Duration of the postage batch (default 24h0m0s) --help help for create --label-selector string Kubernetes label selector for filtering resources (use empty string for all). (default "beekeeper.ethswarm.org/node-funder=true") --namespace string Kubernetes namespace (overrides cluster name). --postage-label string Postage label for the batch (default "beekeeper") --timeout duration Operation timeout (e.g., 5s, 10m, 1.5h). (default 5m0s)
example:
beekeeper stamper create --cluster-name=default --amount=1000 --depth=16 --timeout=5m
or
beekeeper stamper create --namespace=default --label-selector="app=bee" --amount=1000 --depth=16 --timeout=5m
-
topup - tops up postage batches for selected nodes
It has following flags:
--batch-ids strings Comma separated list of postage batch IDs to top up. If not provided, all batches are topped up. Overrides postage labels. --cluster-name string Target Beekeeper cluster name. --help help for topup --label-selector string Kubernetes label selector for filtering resources (use empty string for all). (default "beekeeper.ethswarm.org/node-funder=true") --namespace string Kubernetes namespace (overrides cluster name). --periodic-check duration Periodic check interval. Default is 0, which means no periodic check. --postage-labels strings Comma separated list of postage labels to top up. If not provided, all batches are topped up. --timeout duration Operation timeout (e.g., 5s, 10m, 1.5h). (default 5m0s) --topup-to duration Duration to top up the TTL of a stamp to. (default 720h0m0s) --ttl-threshold duration Threshold for the remaining TTL of a stamp. Actions are triggered when TTL drops below this value. (default 120h0m0s)
example:
beekeeper stamper topup --cluster-name=default --topup-to=720h --ttl-threshold=120h --periodic-check=1h --timeout=24h
or
beekeeper stamper topup --namespace=default --label-selector="app=bee" --topup-to=720h --ttl-threshold=120h --periodic-check=1h --timeout=24h
-
dilute - dilutes postage batch for selected nodes
It has following flags:
--batch-ids strings Comma separated list of postage batch IDs to dilute. If not provided, all batches are diluted. Overrides postage labels. --cluster-name string Target Beekeeper cluster name. --dilution-depth uint8 Number of levels by which to increase the depth of a stamp during dilution. (default 1) --help help for dilute --label-selector string Kubernetes label selector for filtering resources (use empty string for all). (default "beekeeper.ethswarm.org/node-funder=true") --namespace string Kubernetes namespace (overrides cluster name). --periodic-check duration Periodic check interval. Default is 0, which means no periodic check. --postage-labels strings Comma separated list of postage labels to top up. If not provided, all batches are topped up. --timeout duration Operation timeout (e.g., 5s, 10m, 1.5h). (default 5m0s) --usage-threshold float Percentage threshold for stamp utilization. Triggers dilution when usage exceeds this value. (default 90)
example:
beekeeper stamper dilute --cluster-name=default --dilution-depth=1 --usage-threshold=90 --periodic-check=1h --timeout=24h
or
beekeeper stamper dilute --namespace=default --label-selector="app=bee" --dilution-depth=1 --usage-threshold=90 --periodic-check=1h --timeout=24h
-
set - sets postage batch for selected nodes
It has following flags:
--batch-ids strings Comma separated list of postage batch IDs to set. If not provided, all batches are set. Overrides postage labels. --cluster-name string Target Beekeeper cluster name. --dilution-depth uint16 Number of levels by which to increase the depth of a stamp during dilution. (default 1) --help help for set --label-selector string Kubernetes label selector for filtering resources (use empty string for all). (default "beekeeper.ethswarm.org/node-funder=true") --namespace string Kubernetes namespace (overrides cluster name). --periodic-check duration Periodic check interval. Default is 0, which means no periodic check. --postage-labels strings Comma separated list of postage labels to set. If not provided, all batches are set. --timeout duration Operation timeout (e.g., 5s, 10m, 1.5h). (default 5m0s) --topup-to duration Duration to top up the TTL of a stamp to. (default 720h0m0s) --ttl-threshold duration Threshold for the remaining TTL of a stamp. Actions are triggered when TTL drops below this value. (default 120h0m0s) --usage-threshold float Percentage threshold for stamp utilization. Triggers dilution when usage exceeds this value. (default 90)
example:
beekeeper stamper set --cluster-name=default --dilution-depth=1 --usage-threshold=90 --ttl-threshold=120h --topup-to=720h --periodic-check=1h --timeout=24h
or
beekeeper stamper set --namespace=default --label-selector="app=bee" --dilution-depth=1 --usage-threshold=90 --ttl-threshold=120h --topup-to=720h --periodic-check=1h --timeout=24h
Global flags can be used with any command.
example:
--config string Path to the configuration file (default is $HOME/.beekeeper.yaml)
--config-dir string Directory for configuration files (default "C:\\Users\\ljubi\\.beekeeper")
--config-git-branch string Git branch to use for configuration files (default "main")
--config-git-dir string Directory within the Git repository containing configuration files. Defaults to the root directory (default ".")
--config-git-password string Git password or personal access token for authentication (required for private repositories)
--config-git-repo string URL of the Git repository containing configuration files (uses the config-dir if not specified)
--config-git-username string Git username for authentication (required for private repositories)
--enable-k8s Enable Kubernetes client functionality (default true)
--geth-url string URL of the Ethereum-compatible blockchain RPC endpoint
--in-cluster Use the in-cluster Kubernetes client
--kubeconfig string Path to the kubeconfig file (default "~/.kube/config")
--log-verbosity string Log verbosity level (0=silent, 1=error, 2=warn, 3=info, 4=debug, 5=trace) (default "info")
--loki-endpoint string HTTP endpoint for sending logs to Loki (e.g., http://loki.testnet.internal/loki/api/v1/push)
--tracing-enable Enable tracing for performance monitoring and debugging
--tracing-endpoint string Endpoint for sending tracing data, specified as host:port (default "127.0.0.1:6831")
--tracing-host string Host address for sending tracing data
--tracing-port string Port for sending tracing data
--tracing-service-name string Service name identifier used in tracing data (default "beekeeper")
./dist/beekeeper check --cluster-name=bee-testnet --checks=pingpong
./dist/beekeeper check --cluster-name=bee-testnet --checks=pt-retrieval
./dist/beekeeper check --cluster-name=bee-testnet --checks=pt-settlements
./dist/beekeeper check --cluster-name=bee-testnet --checks=pt-manifest
./dist/beekeeper check --cluster-name=bee-testnet --checks=pt-pss
./dist/beekeeper check --cluster-name=bee-testnet --checks=pt-soc
./dist/beekeeper check --cluster-name=bee-testnet --checks=pt-pushsync-chunks
./dist/beekeeper check --cluster-name=bee-testnet --checks=pt-postage
./dist/beekeeper check --cluster-name=bee-testnet --checks=pt-gsoc
./dist/beekeeper check --cluster-name=bee-testnet --timeout=2h --checks=pingpong,pt-retrieval,pt-settlements,pt-manifest,pt-pss,pt-soc,pt-pushsync-chunks,pt-postage,pt-gsoc