Configure the Cluster Validation Suite (CVS) cluster file

Configure the Cluster Validation Suite (CVS) cluster file#

2026-10-27

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.

On a Slurm or SPUR cluster, you can skip this file when cvs run is launched as a job step (see Run Cluster Validation Suite (CVS) on managed compute for more information).

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.

Prerequisites#

Create a cluster file#

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

  • 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.

  • 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

Next steps#

Contents