Zombienet

⚠️ 🚧 Under Active Development 🚧 ⚠️

This project is still in early stage and very much a work in progress. More features will be added, docs may be missing or outdated and api/config may change.

NOTE: polkadot-collator has recently been renamed polkadot-parachain.

What is Zombienet?

Zombienet aims to be a testing framework for Substrate based blockchains, providing a simple cli tool that allows users to spawn and test ephemeral networks. The assertions used in the tests can include on-chain storage, metrics, logs and custom javascript scripts that interact with the chain. To make it easy to define those, zombienet has a natural language built-in allowing developers to write tests as smooth as possible.

Internally zombienet is a javascript library, designed to run on Node.js and support different backend providers to run the nodes, at this moment kubernetes, podman and native are supported.

Usage

Zombienet releases are available in github. Each one provides an executable for both linux and macos created with pkg and allows to run zombienet cli without having Node.js installed but each provider defines it's own requirements (e.g. k8s, podman).

Note: Currently, it is only possible to use podman for Zombienet users on Linux machines. Although podman comes with support for macOS, it is done using an internal VM and the Zombienet provider code expects podman to be running natively.

Status

At the moment Zombienet only works with local chains (e.g. rococo-local, polkadot-local, etc).

Requirements by provider

With kubernetes

Zombienet should work with any k8s cluster (e.g GKE, docker-desktop, kind) but you need to have kubectl installed to interact with your cluster.

Also, you need permission to create resources (e.g namespaces, pods and cronJobs) in the target cluster.

Using Zombienet GKE cluster (internally).

Zombienet project has it's own k8s cluster in GCP, to use it please ping Javier(@javier:matrix.parity.io) in element to gain access and steps to use.

With Podman

Zombienet support Podman rootless as provider, you only need to have podman installed in your environment to use and either set in the network file or with the --provider flag in the cli. Podman for zombienet is currently only supported for Linux machines. This is mostly related to paths and directories used by store configuration (chain-spec) and the data directory.

With Native

Zombienet native provider allows you to run the nodes as a local process in your environment. You only need to have the binaries used in your network (e.g polkadot or polkadot-parachain). To use it either set in the network file or with the --provider flag in the cli.

NOTE: The native provider only use the command config for nodes/collators, both relative and absolute paths are supported. You can use default_command config to set the binary to spawn all the nodes in the relay chain.

Alternative: You can set the command to the binary directly if is available in your PATH.

Features by provider

kubernetes

With k8s zombienet use "Prometheus operator" (if it is available) to offload the monitoring/visibility layer, so only the network's pods are deployed by zombienet.

Podman

With podman zombienet deploys a couple of extra pods to add a layer of monitoring/visibility to the running network. In particular pods for prometheus, tempo and grafana are deployed. Also, grafana is configured to have prometheus and tempo as datasource.

To access those services you can find the url in the output of zombinet:

  Monitor: prometheus - url: https://127.0.0.1:34123

  Monitor: tempo - url: https://127.0.0.1:34125

  Monitor: grafana - url: https://127.0.0.1:41461

Note: Grafana is deployed with the default admin access.

Once the network is stopped, by ctrl+c on a running spawn or by finishing the test, these pods are removed with the rest of the pods launched by zombienet.

Native

Native provider doesn't run any extra layer/process at the moment.

Cli usage

For this example we will use the macos version of the executable

❯ ./zombienet-macos
Usage: zombienet-macos [options] [command]

Options:
  -c, --spawn-concurrency   Number of concurrent spawning process to launch, default is 1
  -p, --provider               Override provider to use (choices: "podman", "kubernetes", "native")
                                         default: kubernetes
  -d, --dir