Ethereum Swarm Beekeeper
Ethereum Swarm Beekeeper is tool used for orchestrating cluster of Ethereum Swarm Bee and running integration tests and simulations against it in the Kubernetes.
Requirements
- Kubernetes cluster (v1.19+)
- Geth Swap node
Installation
make binary
cp dist/beekeeper /usr/local/bin/beekeeperRun unit tests
Runs available unit tests in pkg folder
make test
Configuration
Beekeeper is configured with:
- config file - sets Beekeeper's internals, and
- config directory - sets Bee cluster configuration, checks and simulations
Config file
Config file is used to set Beekeeper internals:
- config directory location
- Kubernetes client
- Swap client
Default location for config file is: $HOME/.beekeeper.yaml
Location can also be set with --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 a local machine by default, but it also supports reading config-dir from a Git repo. If field config-git-repo is set, it will override config-dir and configuration will be read from a Git repo.
If config-dir is kept in a Git repo, field config-git-repo should point to it, along with config-git-branch specifying proper branch. Fields config-git-username and config-git-password can be set when repo is private.
Official GitHub repository with Beekeeper's configuration is https://github.com/ethersphere/beekeeper-config
NOTE: command flags can be also set through the config file
Config directory
Config directory is used to group configuration (.yaml) files describing:
- Bee cluster setup in Kubernetes
- checks (integration tests), and
- simulations
Default location for config dir is: $HOME/.beekeeper/
Location can also be set with --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 with
- node-groups - defines Bee node groups that are part of the cluster. Node group is a collection of Bee nodes sharing same configuration parameters.
- bee-configs - defines Bee configuration that can be assigned to node-groups
- checks - defines checks Beekeeper can execute against the cluster
- simulations - defines simulations Beekeeper can execute against the cluster
- stages - defines stages for dynamic execution of checks and simulations
Inheritance
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 light-node bee-config will inherit all parameters from the default bee-config, overriding only full-node parameter.
Action types
Action types can be set in every check or simulation definition.
Action types allow defining same check or simulation with different parameters.
example:
checks:
pushsync-chunks:
options:
chunks-per-node: 1
metrics-enabled:
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:
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 pushsync check can be executed choosing pushsync-chunks or pushsync-light-chunks variation.
Usage
beekeeper has following commands:
| command | description |
|---|---|
| check | runs integration tests on a Bee cluster |
| create | creates Bee infrastructure |
| delete | Delete Bee infrastructure |
| fund | Fund Ethereum addresses |
| help | Help about any command |
| Print information about a Bee cluster | |
| simulate | Run simulations on a Bee cluster |
| version | Print version number |
check
Command check runs ingegration 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
create
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) --with-funding fund nodes (default true)example:
beekeeper create bee-cluster default -
k8s-namespace - creates Kubernetes namespace
example:
beekeeper create k8s-namespace beekeeper
delete
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 storageexample:
beekeeper delete bee-cluster default -
k8s-namespace - deletes Kubernetes namespace
example:
beekeeper delete k8s-namespace beekeeper
fund
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
--geth-url string Geth node URL (default "http://geth-swap.geth-swap.dai.internal")
--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 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
simulate
Command simulate runs simulations on a Bee cluster.
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
version
Command version prints version number.
example:
beekeeper version
Global flags
Global flags can be used with any command.
example:
--config string config file (default is $HOME/.beekeeper.yaml)
--config-dir string config directory (default is $HOME/.beekeeper/) (default "C:\\Users\\ljubi\\.beekeeper")
--config-git-branch string Git branch (default "main")
--config-git-password string Git password or personal access tokens (needed for private repos)
--config-git-repo string Git repository with configurations (uses config directory when Git repo is not specified) (default "")
--config-git-username string Git username (needed for private repos)
--log-verbosity string log verbosity level 0=silent, 1=error, 2=warn, 3=info, 4=debug, 5=trace (default "info")
--loki-endpoint string loki http endpoint for pushing local logs (use http://loki.testnet.internal/loki/api/v1/push)
--tracing-enable enable tracing
--tracing-endpoint string endpoint to send tracing data (default "tempo-tempo-distributed-distributor.observability:6831")
--tracing-host string host to send tracing data
--tracing-port string port to send tracing data
--tracing-service-name string service name identifier for tracing (default "beekeeper")