Cluster Toolkit is an open-source solution that simplifies deploying
high performance computing (HPC), artificial intelligence (AI), and machine
learning (ML) workloads on Google Cloud. With customizable blueprints, you can
provision infrastructure that aligns with Google Cloud best practices, which
helps to ensure an efficient and consistent setup for your compute environments.

The [`gcluster` CLI](https://docs.cloud.google.com/cluster-toolkit/docs/reference/gcluster.md.txt)
helps you deploy, review, and monitor these configured infrastructure
blueprints. Although you can update some active cluster configurations, making
fundamental architectural changes might require redeploying the cluster.

## Before you begin

1. If you are using a Linux or macOS workstation to deploy your cluster, then follow [install dependencies](https://docs.cloud.google.com/cluster-toolkit/docs/setup/install-dependencies.md.txt).
2. From either your workstation or Cloud Shell, [configure your environment](https://docs.cloud.google.com/cluster-toolkit/docs/setup/configure-environment.md.txt).
3. Verify that you have created a cluster blueprint or selected one from the [Cluster Toolkit blueprint catalog](https://docs.cloud.google.com/cluster-toolkit/docs/setup/cluster-blueprint-catalog.md.txt).

## Inspect blueprints and modules with `gcluster explain`

Before deploying, you can inspect any blueprint or module offline by running
[`gcluster explain`](https://docs.cloud.google.com/cluster-toolkit/docs/reference/gcluster-explain.md.txt):

```bash
./gcluster explain
./gcluster explain PATH_TO_BLUEPRINT_FILE
./gcluster explain -d PATH_TO_DEPLOYMENT_FILE PATH_TO_BLUEPRINT_FILE
```

Replace the following:

- `PATH_TO_BLUEPRINT_FILE`: The relative or absolute path to your cluster blueprint file.
- `PATH_TO_DEPLOYMENT_FILE`: The path to your cluster deployment configuration file.

## Deploy the cluster

To deploy your cluster using a blueprint, complete the following steps:

1. Switch to the main Cluster Toolkit working directory:

   ```bash
   cd cluster-toolkit
   ```
2. Deploy the cluster using the [`gcluster deploy`
   command](https://docs.cloud.google.com/cluster-toolkit/docs/reference/gcluster-deploy):

   - To deploy using command-line variables:

     ```bash
     ./gcluster deploy --vars project_id=PROJECT_ID PATH_TO_BLUEPRINT_FILE
     ```
   - To deploy with a [deployment file](https://docs.cloud.google.com/cluster-toolkit/docs/deploy/cluster-deployment-files.md.txt):

     ```bash
     ./gcluster deploy -d PATH_TO_DEPLOYMENT_FILE PATH_TO_BLUEPRINT_FILE
     ```

   Replace the following:
   - `PROJECT_ID`: The unique identifier for your target Google Cloud project.
   - `PATH_TO_BLUEPRINT_FILE`: The relative or absolute path to your cluster blueprint file.
   - `PATH_TO_DEPLOYMENT_FILE`: The path to your cluster deployment configuration file.
3. The `gcluster` command reports proposed changes for your cluster. To continue the
   deployment, accept the proposed changes by pressing <kbd>a</kbd>, and then pressing
   <kbd>Enter</kbd>. Optionally, you can review the proposed changes by pressing
   <kbd>d</kbd>, and then pressing <kbd>Enter</kbd>.

       Summary of proposed changes: Plan: 37 to add, 0 to change, 0 to destroy.
       (D)isplay full proposed changes,
       (A)pply proposed changes,
       (S)top and exit,
       (C)ontinue without applying
       Please select an option [d,a,s,c]: a

4. After accepting the changes, `gcluster` runs `terraform apply`
   automatically. This operation takes approximately five minutes while it displays
   progress. If the run is successful, the output is similar to the following:

       Apply complete! Resources: 37 added, 0 changed, 0 destroyed.

## Get command-line help

To view all available flags and commands, run the `--help` flag:

```bash
./gcluster --help
./gcluster deploy --help
```

## What's next

- Review [Best practices for HPC workloads](https://docs.cloud.google.com/cluster-toolkit/docs/tutorials/best-practices.md.txt).
- Learn about [GKE deployments in
  Cluster Toolkit](https://docs.cloud.google.com/cluster-toolkit/docs/deploy/gke/gke-deployments-overview).
- Learn how to manage active deployments in [Reconfigure a running cluster](https://docs.cloud.google.com/cluster-toolkit/docs/slurm/reconfigure-cluster.md.txt).