Proxbase

Create a Proxmox VE cluster (or resume a failed create of the same name). Without config, it creates 1 node with 4 vCPUs, 4G memory, a 32G ZFS root disk and one 32G data disk holding the ZFS pool "tank". Set nodes: 3 for a real cluster, storage: ceph for Ceph (3+ nodes). The create runs in the background on this host and survives this connection; the tool reports progress and returns when the cluster is ready, or with running=true after timeoutSeconds (then call cluster_wait). Cancelling the call cancels the create (re-run to resume). With snapshot="baseline" it saves a live snapshot when ready, which cluster_reset returns to in seconds. templates in config provide VM templates from cloud images and container templates as fixtures. Needs free memory for all nodes; the first create downloads a ~1.5 GB ISO.

Delete a cluster: kill its VMs and remove all its disks, snapshots and credentials. Also stops a create running in the background. Set confirm to the cluster name.

Collect what explains a cluster problem, in one read-only call: the cluster status and, for every node, the quorum seen by it, failed systemd units, PVE tasks that failed, error log lines of corosync, pmxcfs (pve-cluster), pveproxy, pvedaemon, pvestatd, HA and Ceph from the last sinceMinutes, the clock offset, and ceph health detail. For nodes that are not running it returns the end of their serial console. Also lists the log files on this host.

Return what API and SSH clients need: API endpoint, API token (proxbase@pve!api, full privileges), the cluster CA certificate (PEM and path), SSH user, key path and ports per node. Root password only if includeRootPassword is set.

Delete every expired cluster on this host (see ttlMinutes of cluster_create and cluster_ttl), with its disks and snapshots; clusters with a running job are left. dryRun only lists them.

List all proxbase clusters on this host with phase and running nodes.

Work out what cluster_create would set up, without creating anything: nodes with IPs and ports (a new cluster takes the first free port range), the memory and disk of all nodes, whether the ISO is cached, the host's free memory and disk, warnings, and the resolved cluster file. Takes the parameters of cluster_create.

Return a cluster to a snapshot in one call (default "baseline"): power the nodes off, restore the snapshot and start the cluster. A live snapshot resumes with its memory in seconds; a disk snapshot boots the nodes. Changes since the snapshot are lost. cluster_create with snapshot="baseline" saves one when the cluster is ready; snapshot_save saves one at any time.

Boot a stopped cluster and wait for quorum, the API and storage. Also boots nodes killed by fault_apply kill. If the call limit (50 s for clients that cancel tool calls after a minute) passes first, it returns healthy=false with what is pending while the nodes keep booting.

Show a cluster: phase, quorum, nodes (running/online, IP, web UI URL, SSH port), Ceph health, active faults, and the progress of a create running in the background. healthy=true means ready, quorate, all nodes online and Ceph HEALTH_OK.

Shut all nodes of a cluster down (cleanly, then hard after the timeout). Disks are kept; cluster_start boots it again. Clears all faults.

Set how long a cluster may live: it expires minutes from now (0: never). cluster_gc deletes expired clusters; set a lifetime on clusters you create so that forgotten ones are cleaned up.

Wait for the background job of a cluster (after cluster_create, node_add or node_remove returned running=true), reporting its progress. Returns running=false with the status when it finished, or running=true again after timeoutSeconds.

Check a cluster file (YAML) without creating anything; returns errors, warnings and the file with all defaults. The schema is the resource https://proxbase.virtbase.com/schema/v1alpha1/cluster.json.

Inject a failure into a running cluster to test HA, fencing, Ceph or applications: kill, freeze, thaw, link-down, link-up, partition or degrade. fault_clear undoes them.

Undo all injected faults (thaw, plug cables in, heal partitions and degradations). Killed nodes need cluster_start.

Read a file of a node: text as content, other data as contentBase64; at most maxBytes (default 256 KiB, max 4 MiB), truncated=true if the file is longer.

Write a file on a node as root, e.g. a config, script or test fixture: text in content, or binary data in contentBase64 (at most 4 MiB). The file is replaced atomically; missing directories are created. Files in /etc/pve (the cluster file system, shared by all nodes) get its fixed permissions.

Check whether this host can run clusters: KVM, nested virtualization, QEMU, free memory, KSM, disk space, free ports and path lengths (as proxbase doctor).

List the cached base images (golden images) with the clusters that use them.

Delete the base images no cluster uses (dryRun only lists them). The next create with a deleted image builds it again.

Add nodes to a ready cluster: install (or clone) them, join them and set up ZFS or Ceph as configured. Runs in the background like cluster_create; returns when done or with running=true (then call cluster_wait). Cancelling the call stops it; cluster_create with the cluster's name finishes an interrupted add.

Run a shell command as root on a running node over SSH and return stdout, stderr and the exit code. Use it for pvesh, qm, pct, pvecm, ceph and the like. Non-interactive; output is capped at 64 KiB per stream.

Remove a node from a cluster: drain and destroy its Ceph daemons, take it out of the cluster and delete its VM and disks. Refuses with guests on the node or Ceph pools that would be left degraded unless force is set. Runs in the background like cluster_create. Set confirm to the node name.

Change something through the Proxmox VE API of a cluster with its API token: POST, PUT or DELETE a path with params, e.g. POST /nodes/pve1/qemu {"vmid": 100, "memory": 2048} or POST /nodes/pve1/qemu/100/status/start. If the call starts a task (returns a UPID), waits for it and returns its exit status and log; a failed task is an error.

Read from the Proxmox VE API of a cluster with its API token (proxbase@pve!api) and return the response data as JSON. Paths are those of pvesh and the API viewer, e.g. /cluster/resources, /cluster/status, /nodes/pve1/qemu, /nodes/pve1/storage, /nodes/pve1/tasks (recent tasks) or /nodes/pve1/tasks/<upid>/log.

Delete a snapshot of a cluster.

List the snapshots of a cluster.

Reset all disks of a stopped cluster to a snapshot (call cluster_stop first). Changes since the snapshot are lost. After a disk snapshot call cluster_start; a live snapshot starts the cluster in its saved state by itself.

Snapshot all disks of a stopped cluster (call cluster_stop first), or with live=true the running cluster including its memory. Restoring is much faster than creating again.

List the Proxmox VE tasks of a cluster, newest first: VM and container operations, migrations, backups, storage and Ceph jobs. Reads every node, or one. Filter by errorsOnly, running, type (e.g. qmstart, qmigrate, vzdump), vmid and sinceMinutes. task_log shows a task's log, task_wait waits for one to end.

Return the status and the end of the log of a Proxmox VE task, by its UPID (from task_list, pve_call or an error).

Wait for a Proxmox VE task (UPID) to end and return its exit status and the end of its log; a failed task is an error. Use it for tasks that pve_call or task_list reported as running.

Create an API token that may only do what a role allows on a path, to test code with least privilege or check that an operation is refused: e.g. role PVEAuditor on /, PVEVMAdmin on /vms/100, PVEDatastoreUser on /storage/tank. Replaces a token of the same name. cluster_env with token returns the endpoint and CA with it.

Delete a scoped API token and its grant. The main token proxbase@pve!api cannot be deleted.

List the scoped API tokens of a cluster with their role and path (without secrets).