GoogleCloudPlatform/cluster-toolkit

Google Cloud Cluster Toolkit (formerly HPC Toolkit)

What it is – An open‑source Google‑provided tool that helps you spin up and manage AI/ML or high‑performance‑computing (HPC) clusters on Google Cloud. It does this by letting you describe a cluster in a simple YAML blueprint and then generating the Terraform/Packer code needed to provision the resources.

Core pieces

• Blueprints – YAML files that capture the desired infrastructure (network, storage, compute, Slurm, GKE, etc.).
• Modules – Re‑usable Terraform or Packer building blocks (e.g., a Slurm controller, a GPU node pool) that a blueprint assembles.
• gcluster CLI – The command‑line driver that turns a blueprint into a self‑contained deployment folder and runs terraform apply/destroy for you.
• Deployment folder – A directory containing the generated Terraform/Packer files; you can version‑control it or use it in CI/CD.

Typical workflow

1. Install the gcluster binary (pre‑built bundle or build from source).
2. Pick or write a blueprint (e.g., examples/hpc-slurm.yaml).
3. Run gcluster create <blueprint> → creates a deployment folder.
4. Run gcluster deploy <folder> → provisions the cluster via Terraform.
5. Use gcluster job submit … to launch AI/ML workloads on a GKE cluster (supports pre‑built images or on‑the‑fly container builds).
6. When finished, gcluster destroy <folder> tears everything down.

Key capabilities

• Deploy Slurm‑based HPC clusters (including on A4, H4D, or custom VM types).
• Deploy AI‑optimized GKE clusters with Kueue, JobSet, and optional TPU slicing or Pathways support.
• Automatic download of missing Terraform/Packer binaries (--download-dependencies).
• Built‑in blueprint validation and telemetry (opt‑out available).
• Integration with Google Cloud AI Hypercomputer for large‑scale AI training.

Who should use it

• Researchers or engineers who need reproducible, repeatable HPC or AI clusters on GCP without hand‑crafting Terraform.
• Teams that want a single CLI to both provision infrastructure and submit containerised AI jobs.
• CI/CD pipelines that need to spin up temporary clusters for benchmarking or training runs.

Installation

• Pre‑built bundle (recommended): download the OS‑specific gcluster_bundle_*.tgz from the releases page, extract, and run ./gcluster --help.
• From source: git clone https://github.com/GoogleCloudPlatform/cluster-toolkit && make && ./gcluster --version.
• Requires Go, Terraform, and (for Windows) WSL2 if you need shell‑based provisioners.

Getting started

• Enable required GCP APIs (Compute, Filestore, Cloud Storage, Service Usage).
• Authenticate with gcloud auth application-default login.
• Choose a quick‑start guide, e.g., Deploy an HPC cluster with Slurm or Create a self‑managed Slurm cluster with an A4 VM.
• Follow the three‑step create → deploy → destroy cycle.

Job submission

• gcluster job submit works with GKE clusters that have Kueue/JobSet enabled.
• Supports both pre‑built container images and on‑the‑fly builds (--base-image, --build-context).
• Provides helpers to set default project/cluster/location, list jobs, view logs, and cancel jobs.

Advanced features

• Dynamic TPU slicing, Pathways distributed‑training orchestration, and GKE Node Auto‑Provisioning flags for large AI workloads.

Development

• Uses pre‑commit, TFLint, and ShellCheck for linting.
• Contributing guidelines are in CONTRIBUTING.md.

Bottom line – The Google Cloud Cluster Toolkit is a production‑grade, open‑source framework that abstracts away the complexity of Terraform‑based cluster provisioning and gives a unified CLI for both infrastructure and AI job management on Google Cloud.