Kits

A kit is a self-contained package of configuration and scripts that installs, starts, stops, and optionally backs up a workload on your cluster. Each kit defines its full lifecycle in a kit.yaml file using typed steps — no Kubernetes YAML wrangling required.

easy-db-lab ships with built-in kits (ClickHouse, Presto, Trino, TiDB, memcached, Neo4j, sysbench, clickhouse-benchmark). You can also create your own kits for any workload you want to benchmark or test.

Discovering kits

List all available kits:

easy-db-lab kit list

Inspect a kit before installing it — see its args, endpoints, and available commands:

easy-db-lab kit info clickhouse

Run from a cluster workspace, kit info lists each endpoint at its node's private IP. Before the cluster has hosts of that node type, it lists the bare NodePort (:30123).

Installing a kit

easy-db-lab kit install clickhouse --clickhouse-version 25.4 --size 100Gi

Args vary by kit. Run kit info <name> to see what a kit accepts, or pass --help:

easy-db-lab kit install clickhouse --help

After install, the kit's files are written into a subdirectory of the cluster workspace. The kit's lifecycle commands are registered automatically.

Bench kits — benchmarking a database

Bench kits are a special class of kit that run against an already-running database kit. They require a --target flag pointing at the installed database kit you want to benchmark.

# Install sysbench targeting your running TiDB instance
easy-db-lab kit install sysbench --target tidb

# Run the prepare, start, and stop lifecycle as usual
easy-db-lab sysbench-tidb prepare
easy-db-lab sysbench-tidb start
easy-db-lab sysbench-tidb stop

The kit is installed into a directory named <bench-kit>-<target> (e.g. sysbench-tidb). This lets you run the same bench kit against multiple databases simultaneously and compare results:

easy-db-lab kit install sysbench --target tidb
easy-db-lab kit install sysbench --target my-custom-db

# Both run at the same time — compare results in Grafana
easy-db-lab sysbench-tidb start
easy-db-lab sysbench-my-custom-db start

The target must expose a wire protocol endpoint the bench tool can speak — sysbench supports MySQL and PostgreSQL. See Sysbench for the full lifecycle, flags, and metrics.

TARGET_* environment variables

When a bench kit starts, easy-db-lab reads the target database's endpoint configuration and injects it as environment variables into every phase script:

Which variables are populated depends on what endpoints the target kit declares. A kit that supports both JDBC and PostgreSQL wire protocol will populate both sets.

Running kit commands

Every installed kit gains a set of subcommands:

easy-db-lab clickhouse start       # deploy and start the workload
easy-db-lab clickhouse status      # show running state and connection endpoints
easy-db-lab clickhouse stop        # stop and remove the workload
easy-db-lab clickhouse backup --name my-backup   # back up data
easy-db-lab clickhouse restore --name my-backup  # restore from backup
easy-db-lab clickhouse uninstall   # stop and remove all kit resources

memcached

The memcached kit runs one memcached pod on a db node. By default it runs from RAM only and creates no persistent volumes; --extstore-size adds extstore on the db node's NVMe (see extstore below).

Install it, optionally setting the cache size in megabytes with --memory (default 1024, passed to memcached as -m):

easy-db-lab kit install memcached --memory 4096

Start it:

easy-db-lab memcached start

memcached is published on NodePort 31211, so it is reachable on any node's private IP. memcached start, memcached status and kit info memcached all print the endpoint resolved to each db node's private IP:

easy-db-lab kit info memcached
# Endpoints:
#   memcached  db  <db node private IP>:31211  native

Connect from a pod in the cluster, or from your machine over Tailscale:

printf 'set greeting 0 0 5\r\nhello\r\nget greeting\r\nquit\r\n' | nc <db node private IP> 31211

A memcached-exporter sidecar serves Prometheus metrics on port 9150. The collector finds the pod by label and scrapes it, so the series land in Mimir under job="memcached". The kit's METRICS.md lists them.

memcached extstore

extstore lets memcached keep item values on flash once RAM is full. It is off unless you pass --extstore-size, which sets the size of the extstore file (a whole number with an M, G or T suffix):

easy-db-lab kit install memcached --memory 4096 --extstore-size 100G

With extstore on, kit install creates a local PersistentVolume on the db node's NVMe, and the memcached container mounts it at /data and runs with -o ext_path=/data/extstore:<size>.

These install options tune extstore. Each one is passed to memcached only when you set it, so memcached's own default applies otherwise. Without --extstore-size they are ignored.

easy-db-lab kit install memcached --extstore-size 100G --extstore-threads 8 --extstore-item-size 512

memcached uninstall also deletes the extstore volume claim, the PersistentVolume, and its directory on the node.

Stopping and uninstalling

Stop it, or uninstall it to also remove the kit directory. stop deletes the Deployment, its ReplicaSet and pods, the Service and the ConfigMap labelled easydblab/kit=memcached; uninstall deletes those plus the extstore volume claim, then the extstore PersistentVolume:

easy-db-lab memcached stop
easy-db-lab memcached uninstall

Installing memcached a second time fails with a collision error and exits non-zero, leaving the running kit untouched. Pass --force to overwrite the scaffold. Running memcached start while memcached is already running also fails with a collision error; run memcached stop first. stop returns once the memcached pod is gone, so start can follow it straight away.

Installing a custom kit

Place your kit directory under the profile kits folder and it will appear in kit list and be installable by name like any built-in kit:

~/.easy-db-lab/profiles/default/kits/<kit-name>/

Custom kits in the profile directory take precedence over built-in kits with the same name.

mkdir -p ~/.easy-db-lab/profiles/default/kits/my-kit
cp -r /path/to/my-kit/* ~/.easy-db-lab/profiles/default/kits/my-kit/

# Now it appears in kit list and can be installed by name:
easy-db-lab kit install my-kit

Using kits from external projects

If you keep kit definitions alongside a private project (a POC, internal tooling, etc.), you can register that project's kits directory without copying files into your profile.

A typical project structure looks like this:

myapp/
├── src/
├── kits/
│   └── myapp-workload/
│       ├── kit.yaml
│       └── bin/
│           ├── start.sh
│           └── stop.sh
└── README.md

Clone your project and register the kits directory by name:

git clone https://github.com/myorg/myapp ~/myapp
easy-db-lab kit source add myapp ~/myapp/kits

The kits it contains now appear in kit list and can be installed by name:

easy-db-lab kit list
easy-db-lab kit install myapp-workload

Registered sources are persisted in ~/.easy-db-lab/profiles/<profile>/kit-sources.yaml and survive CLI restarts. When you kit install a kit from an external source, its files are copied into the cluster workspace exactly like any other kit — the installed kit is self-contained.

Managing registered sources

# List all registered sources (shows name and path, flags missing paths)
easy-db-lab kit source list

Output looks like:

Registered kit sources:
  myapp  /Users/jon/myapp/kits

If a registered path no longer exists on disk, [missing] appears next to it so you know which sources need attention.

# Remove a source by name
easy-db-lab kit source remove myproject

Updating a path (upsert behavior): Sources are identified by name. If you move or reclone a project to a different location, just re-add the source with the new path — no need to remove the old registration first:

# If you move or reclone the project, just update the path — no need to remove first
easy-db-lab kit source add myapp ~/new-location/myapp/kits
# Updated kit source 'myapp': /new-location/myapp/kits

Resolution priority

When multiple sources provide a kit with the same name, the first match wins:

1. Profile kits directory (~/.easy-db-lab/profiles/<profile>/kits/)
2. Registered additional sources (in registration order)
3. Built-in kits

For a full walkthrough of building and publishing your own kit, see the Kit Development guide.