Configure the Cluster Validation Suite (CVS) cluster file (cluster.json)

Configure the Cluster Validation Suite (CVS) cluster file (cluster.json)#

2026-09-24

4 min read time

Applies to Linux

The cluster file (--cluster_file) tells CVS how to reach your cluster nodes: SSH credentials, which hosts to use, and whether to run on bare metal or in containers. You pass it to cvs run, cvs exec, and cvs scp.

For the complete field reference — every parameter, its type, default value, the container block schema, and the lifetime state matrix — see Cluster Validation Suite (CVS) cluster file: configuration and backend selection.

Create a cluster file#

You can create cluster.json in either of these ways:

  1. Copy a template and edit manually — use cvs config copy to copy cluster.json (or cluster_container.json for container runs), then edit SSH credentials, the head node, and worker addresses. For smaller clusters this is convenient. See Copy a cluster file template.

  2. Generate from a host list — use cvs generate cluster_json with a hosts file or comma-separated host list to build cluster.json from your node inventory. Use this when you have many nodes or when you already maintain a host list. See Generate a cluster JSON file.

Copy a cluster file template#

CVS ships cluster templates under cvs/input/. Copy them with cvs config copy:

cvs config copy cluster.json --output ~/cvs_workspace/cluster.json
cvs config copy cluster_container.json --output ~/cvs_workspace/cluster_container.json

Edit cluster.json and replace every <changeme> placeholder with your SSH user, private key path, head node address, and worker node addresses. CVS exits with an error if any placeholder remains unresolved.

Generate a cluster JSON file#

For many nodes, generate cluster.json from a hosts file or comma-separated host list:

Option 1: hosts file

cvs generate cluster_json \
  --input_hosts_file /tmp/hosts.txt \
  --output_json_file ~/cvs_workspace/cluster.json \
  --username myuser --key_file ~/.ssh/id_rsa --head_node 192.168.1.10

The hosts file supports one IP or hostname per line, ranges like 192.168.1.11-15, and bracket notation like server[01-05].

Option 2: comma-separated hosts

cvs generate cluster_json \
  --hosts "192.168.1.10,192.168.1.11-15,server[01-05]" \
  --output_json_file ~/cvs_workspace/cluster.json \
  --username myuser --key_file ~/.ssh/id_rsa --head_node 192.168.1.10

Passwordless SSH#

Passwordless SSH from the head node to every worker is required. See Set up passwordless SSH for Cluster Validation Suite (CVS) cluster nodes for more information.

Container backend#

For container-based suites, use cluster_container.json and see Run Cluster Validation Suite (CVS) test suites with a per-host Docker container backend for more information.

Next steps#

Contents