Stay organized with collections
Save and categorize content based on your preferences.
To use Cluster Toolkit, you need a
Google Cloud project.
In your project, you need to enable APIs, permissions, and grant credentials
to Terraform. You also need to clone and build the Cluster Toolkit repository.
Before you begin
Sign in to your Google Cloud account. If you're new to
Google Cloud,
create an account to evaluate how our products perform in
real-world scenarios. New customers also get $300 in free credits to
run, test, and deploy workloads.
In the Google Cloud console, on the project selector page,
select or create a Google Cloud project.
At the bottom of the Google Cloud console, a
Cloud Shell
session starts and displays a command-line prompt. Cloud Shell is a shell environment
with the Google Cloud CLI
already installed and with values already set for
your current project. It can take a few seconds for the session to initialize.
Set a default project
To set a default project, run the following command:
Replace PROJECT_ID with your project ID.
gcloud config set project PROJECT_ID
Ensure that the default Compute Engine service account is enabled
Cluster Toolkit requires that the default Compute Engine service account
is enabled in your project and that the roles/editor IAM role is enabled on the
service account. This is the default setting that is set up by Google Cloud
for projects.
However, if you had disabled the default Compute Engine service account and
the roles/editor IAM role in your project, complete the following steps to
enable these settings:
Enable the default Compute Engine service account.
gcloud iam service-accounts enable \
--project PROJECT_ID \
PROJECT_NUMBER-compute@developer.gserviceaccount.com
Grant the roles/editor IAM role to the service account.
To generate cloud credentials associated with your Google Cloud account, run
the following command:
gcloud auth application-default login
This grants the Application Default Credentials (ADC) to Terraform.
Enable OS Login at the project-level
To be able to connect to a VM in your cluster by using ssh, you must enable
OS Login. If OS Login is already enabled at the organization level,
you don't need to enable it on your project.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[[["\u003cp\u003eCluster Toolkit requires a Google Cloud project with enabled APIs, permissions, and granted credentials for Terraform.\u003c/p\u003e\n"],["\u003cp\u003eSetting up Cluster Toolkit involves configuring your CLI, setting a default project, and enabling the default Compute Engine service account with the \u003ccode\u003eroles/editor\u003c/code\u003e IAM role.\u003c/p\u003e\n"],["\u003cp\u003eUser access credentials for Terraform can be granted using \u003ccode\u003egcloud auth application-default login\u003c/code\u003e, but are not required in cloud shell.\u003c/p\u003e\n"],["\u003cp\u003eOS Login must be enabled at the project level (or organization level) to allow SSH access to VMs in your cluster.\u003c/p\u003e\n"],["\u003cp\u003eThe Cluster Toolkit repository needs to be cloned and its binary built using \u003ccode\u003emake\u003c/code\u003e, after which you can deploy clusters.\u003c/p\u003e\n"]]],[],null,["To use Cluster Toolkit, you need a\n[Google Cloud project](/resource-manager/docs/creating-managing-projects).\nIn your project, you need to enable APIs, permissions, and grant credentials\nto Terraform. You also need to clone and build the Cluster Toolkit repository.\n\nBefore you begin\n\nSign in to your Google Cloud account. If you're new to Google Cloud, [create an account](https://console.cloud.google.com/freetrial) to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.\n\nIn the Google Cloud console, on the project selector page,\nselect or create a Google Cloud project.\n| **Note**: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.\n\n[Go to project selector](https://console.cloud.google.com/projectselector2/home/dashboard)\n\n\n[Verify that billing is enabled for your Google Cloud project](/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project).\n\n\nEnable the Compute Engine, Filestore, Cloud Storage, Service Usage, and Resource Manager APIs.\n\n\n[Enable the APIs](https://console.cloud.google.com/flows/enableapi?apiid=compute.googleapis.com,file.googleapis.com,storage.googleapis.com,serviceusage.googleapis.com,cloudresourcemanager.googleapis.com) \nIn the Google Cloud console, on the project selector page,\nselect or create a Google Cloud project.\n| **Note**: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.\n\n[Go to project selector](https://console.cloud.google.com/projectselector2/home/dashboard)\n\n\n[Verify that billing is enabled for your Google Cloud project](/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project).\n\n\nEnable the Compute Engine, Filestore, Cloud Storage, Service Usage, and Resource Manager APIs.\n\n\n[Enable the APIs](https://console.cloud.google.com/flows/enableapi?apiid=compute.googleapis.com,file.googleapis.com,storage.googleapis.com,serviceusage.googleapis.com,cloudresourcemanager.googleapis.com)\n\n\u003cbr /\u003e\n\nOverview\n\nTo set up Cluster Toolkit, you need to complete the following steps:\n\n- [Set up your CLI](#setup-cli)\n- [Set the default project](#default-project)\n- [Ensure that the default Compute Engine service account is enabled](#service-account)\n- [Grant user access credentials to Terraform](#grant-credentials-terraform)\n- [Enable OS Login at the project-level](#enable-oslogin)\n- [Clone the Cluster Toolkit GitHub repository](#clone-repo)\n- [Build the Cluster Toolkit binary](#build-binary)\n\nSet up your CLI\n\nIn the Google Cloud console, activate Cloud Shell.\n\n[Activate Cloud Shell](https://console.cloud.google.com/?cloudshell=true)\n\n\nAt the bottom of the Google Cloud console, a\n[Cloud Shell](/shell/docs/how-cloud-shell-works)\nsession starts and displays a command-line prompt. Cloud Shell is a shell environment\nwith the Google Cloud CLI\nalready installed and with values already set for\nyour current project. It can take a few seconds for the session to initialize.\n| **Note:** If you are using a local shell, ensure that you have installed the [dependencies](/cluster-toolkit/docs/setup/install-dependencies). If you use Cloud Shell, the dependencies are already pre-installed.\n\nSet a default project\n\nTo set a default project, run the following command:\n\nReplace \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e with your project ID. \n\n```\ngcloud config set project PROJECT_ID\n```\n\nEnsure that the default Compute Engine service account is enabled\n\nCluster Toolkit requires that the default Compute Engine service account\nis enabled in your project and that the `roles/editor` IAM role is enabled on the\nservice account. This is the default setting that is set up by Google Cloud\nfor projects.\n\nHowever, if you had disabled the default Compute Engine service account and\nthe `roles/editor` IAM role in your project, complete the following steps to\nenable these settings:\n\n1. Enable the default Compute Engine service account.\n\n ```\n gcloud iam service-accounts enable \\\n --project PROJECT_ID \\\n PROJECT_NUMBER-compute@developer.gserviceaccount.com\n ```\n2. Grant the `roles/editor` IAM role to the service account.\n\n ```\n gcloud projects add-iam-policy-binding PROJECT_ID \\\n --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \\\n --role=roles/editor\n ```\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: your project ID\n- \u003cvar translate=\"no\"\u003ePROJECT_NUMBER\u003c/var\u003e: the automatically generated unique\n identifier for your project\n\n For more information, see\n [Identifying projects](/resource-manager/docs/creating-managing-projects#identifying_projects).\n\nGrant user access credentials to Terraform **Note:** If you are using Cloud Shell, you can skip this step.\n\nTo generate cloud credentials associated with your Google Cloud account, run\nthe following command: \n\n```\ngcloud auth application-default login\n```\n\nThis grants the Application Default Credentials (ADC) to Terraform.\n\nEnable OS Login at the project-level\n\nTo be able to connect to a VM in your cluster by using `ssh`, you must enable\nOS Login. If OS Login is already enabled at the organization level,\nyou don't need to enable it on your project. \n\n```\ngcloud compute project-info add-metadata \\\n --metadata enable-oslogin=TRUE\n```\n\nClone the Cluster Toolkit GitHub repository\n\n1. Clone the GitHub repository:\n\n ```\n git clone https://github.com/GoogleCloudPlatform/cluster-toolkit.git\n ```\n2. Go to the main working directory:\n\n ```\n cd cluster-toolkit/\n ```\n\nBuild the Cluster Toolkit binary\n\n1. To build the Cluster Toolkit binary from source, run the\n following command:\n\n ```\n make\n ```\n2. To verify the build, run the following command:\n\n ```\n ./gcluster --version\n ```\n\nAfter building the binary, you are now ready to deploy clusters to run your\njobs or workloads.\n\nWhat's next\n\n- Learn about [Cluster blueprints](/cluster-toolkit/docs/setup/cluster-blueprint).\n- Review [best practices for running HPC workloads](/cluster-toolkit/docs/tutorials/best-practices).\n- Try a quickstart tutorial, see [Deploy an HPC cluster with Slurm](/cluster-toolkit/docs/quickstarts/slurm-cluster)."]]
