roachprod

roachprod provisions, configures, and manages CockroachDB clusters across cloud providers and local Docker. It is the operational tool used by the Cockroach Labs team and by roachtest for nightly cluster tests.

Source

• Library: pkg/roachprod/ — VMs, providers (AWS, GCP, Azure, IBM, local), DNS, install, ssh, monitoring.
• CLI: pkg/cmd/roachprod/.
• Centralized backend: pkg/cmd/roachprod-centralized/ — a service that owns shared cluster ownership and credentials.
• Microbench harness: pkg/cmd/roachprod-microbench/.

What it does

Typical usage:

roachprod create alice-test --clouds=gce --nodes=4
roachprod stage alice-test cockroach release-25.4
roachprod start alice-test
roachprod sql alice-test:1
roachprod destroy alice-test

Subcommands include:

• create / destroy — VM lifecycle.
• stage — upload a cockroach binary, workloads, or a custom artifact.
• start / stop / signal — manage the cockroach process.
• run — SSH a command on every node.
• pgurl — print a connection URL for the cluster.
• monitor — show a tail of process logs.
• prometheus / grafana — install the observability stack.
• extend — extend the auto-destroy lifetime.
• gc — garbage-collect expired clusters.

Providers

pkg/roachprod/vm/ has a sub-package per cloud:

• aws/
• gce/
• azure/
• ibm/
• local/ — Docker-in-Docker for laptop testing.

Each implements vm.Provider and uses cloud-native APIs to provision a homogeneous fleet.

Centralized service

roachprod-centralized (pkg/cmd/roachprod-centralized/) is a service that holds shared cluster metadata so the team's various roachprod CLIs see a consistent view. Without it, two engineers could collide on the same cluster.

Related pages

• apps/roachtest — biggest consumer.
• features/workload — workloads usually run via roachprod.