Fuzzball Documentation
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

Requirements

Requirements differ depending on how you deploy Fuzzball. Use the Kubernetes Operator tab for a multi-node, production-style deployment, or the Docker Compose tab for a single-host deployment suited to local development and testing.

Please select your environment.

For information about setting up a basic RKE2 cluster and the dependencies necessary to install Fuzzball, please see the RKE2 cluster installation guide in the appendices.

This guide was developed on Rocky v9.6 instances running within the Vultr cloud platform, sharing a virtual network.

Hardware

  • The Server node should have at least 10 cores and 16 GBs of memory.
  • The Compute nodes will comprise the actual cluster that runs user workflows. The hardware requirements will therefore be determined by the expected workflows.
  • The nodes are assumed to share an internal network.

Access to CIQ Depot

This guide assumes access to CIQ Depot. Depot provides a secure delivery platform for a number of asset types, including RPM packages and SIF/OCI container images. It will be used to obtain the Fuzzball operator and the Fuzzball image that the operator will deploy.

NFS

Fuzzball Orchestrate uses NFS to distribute configuration to compute nodes and exchange containers.

The Fuzzball Operator deploys nfs-subdir-external-provisioner to create volumes on that NFS share, so every K8s node that runs Fuzzball Orchestrate must have the NFS client tools installed, even if the NFS server runs on a separate machine. Install nfs-utils on Rocky Linux, RHEL, and other EL-based systems, or nfs-common on Debian and Ubuntu.

Kubernetes and Some Associated Tooling

Fuzzball needs Kubernetes 1.30 or later. This guide was developed using RKE2. Other K8s flavors should also work but are untested at this time.

Fuzzball Orchestrate is expected to run in your existing K8s cluster if you have one, but it is not guaranteed to be compatible with existing services that are already running in your cluster. Exercise caution when deploying Fuzzball in an existing K8s instance that is already hosting other services.

Cluster DNS domain

Fuzzball works with any cluster DNS domain, not only the Kubernetes default cluster.local. The operator detects the domain from its own pod’s DNS configuration. If your cluster uses another domain (for example, k3s or RKE2 installed with cluster-domain) and detection does not find it, set it in the clusterDomain field of the FuzzballOrchestrate or FuzzballFederate resource, described in the Cluster DNS Domain reference.

Ingress controller

Fuzzball installs its own ingress controller, Kong. To use one that the cluster already runs instead, ingress-nginx, Kong, or Traefik, pass fuzzball cluster kubernetes deploy --existing-ingress its IngressClass.

Load balancer

With --ingress nodeport, the default, Fuzzball needs no load balancer. With --ingress loadbalancer, the cluster needs one that assigns external addresses. On a bare-metal cluster without one, fuzzball cluster kubernetes deploy --install-metallb installs MetalLB.

A default StorageClass

The Fuzzball Operator keeps its state on a volume from a StorageClass: the cluster’s default, or the one --storage-class names. On a cluster without a default, fuzzball cluster kubernetes deploy --install-storage-class local-path installs Local Path Provisioner as the default. It keeps volumes on the nodes’ local disks, so it suits a single-node Orchestrate cluster.

Helm

The CLI installs the Fuzzball Operator itself. The CLI host needs Helm only to apply the files that fuzzball cluster kubernetes deploy --dry-run --output-dir writes.

If you need to install a basic set of these dependencies on a fresh machine, head to the RKE2 cluster installation guide in the appendices. If you already have these dependencies installed, you can feel free to advance to the Deployment guide.

The Docker Compose deployment runs Fuzzball Orchestrate together with one or more Fuzzball Substrate nodes and is suited to local development, evaluation, and testing rather than production use.

The Docker Compose deployment is intended for single-host development and testing. For production deployments, use the Kubernetes Operator deployment.

The Docker Compose deployment requires a working Docker installation with the Compose plugin (docker compose) available on the host where you run the fuzzball CLI. The CLI shells out to the docker binary, so it must be present in your PATH.

Docker keeps the stack’s images and data, including the PostgreSQL and Keycloak databases, under its data root, /var/lib/docker by default. If /var is small, move the data root to a large local disk before you deploy. Don’t put it on NFS. Set data-root in /etc/docker/daemon.json, then restart Docker:

{
  "data-root": "/srv/docker"
}
# systemctl restart docker

If the host reaches the internet through an HTTP proxy, Docker needs the proxy settings to pull the stack’s images from depot.ciq.com. Add them in a systemd drop-in, and list the stack’s domain and your cluster network in NO_PROXY so traffic to the stack itself bypasses the proxy:

# mkdir -p /etc/systemd/system/docker.service.d

# cat >/etc/systemd/system/docker.service.d/http-proxy.conf <<EOF
[Service]
Environment="HTTP_PROXY=http://proxy.example.com:3128"
Environment="HTTPS_PROXY=http://proxy.example.com:3128"
Environment="NO_PROXY=localhost,127.0.0.1,.fb.example.internal,10.0.0.0/24"
EOF

# systemctl daemon-reload

# systemctl restart docker

To reach the deployed services you also need the stack’s subdomains to resolve to the host and to trust its self-signed TLS certificate. Both are covered under DNS resolution in the Docker Compose tab of the Deployment guide.