Modify a cluster

This document explains how to modify a cluster in Cluster Director.

After you create a cluster in Cluster Director, you can modify its configuration to meet the needs of your workload. For example, you can add or remove virtual machine (VM) instances, update prolog or epilog scripts, or edit the compute resources that a cluster's partitions use. Modifying a cluster can help you to save costs or optimize performance when the needs of your workload change.

Caution: To modify the compute, storage, or networking resources in a cluster, Cluster Director might need to recreate VMs. To minimize disruptions, we recommend that you modify these resources during a planned maintenance. You can instead update a cluster's description or labels at any time without disruptions.

Limitations

You can't modify or delete Compute Engine resources that contain the label hypercomputeClusterResource set to true. Cluster Director provisions and manages these resources. If you modify them, then you might encounter errors. To check the labels for a Compute Engine resource, see View labels.

Before you begin

Before you modify a cluster, consider the following:

• Before you delete a storage resource, back up any data that you want to retain. Deleting a storage resource is irreversible.

• Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  In the Google Cloud console, activate Cloud Shell.

  Activate Cloud Shell

  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.

  REST

  To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

  Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command:

  gcloud init

  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.

  For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

Required roles

To get the permission that you need to modify clusters, ask your administrator to grant you the following IAM roles:

• To manage the cluster: Cluster Director Editor (roles/hypercomputecluster.editor) on your project
• To update resources in the cluster:
  • Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1) on the Compute Engine default service account
  • Logs Writer (roles/logging.logWriter) on the Compute Engine default service account
  • Monitoring Metric Writer (roles/monitoring.metricWriter) on the Compute Engine default service account
  • Storage Object Viewer (roles/storage.objectViewer) on the Compute Engine default service account

For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the hypercomputecluster.clusters.update permission, which is required to modify clusters.

You might also be able to get this permission with custom roles or other predefined roles.

Modifiable cluster properties

You can only modify the following properties in a running cluster:

• Description: you can update the cluster's description.

• Labels: you can add, change, or delete the labels associated with the cluster.

• Compute resources: you can add or make modifications to compute resource configurations for your cluster, such as changing the machine type and zone.

• Network resources: you can add or remove VPC networks.

• Storage resources: you can add or remove Filestore instances, Google Cloud Managed Lustre instances, or Cloud Storage buckets.

• Orchestrator: you can modify the Slurm orchestrator's configuration, including login nodes, prolog or epilog scripts, nodesets, and partitions.

If you need to change any other properties in a cluster, then you must first create a replacement cluster with updated properties, and then delete the original cluster if you no longer need it.

Modify a cluster

If you delete a compute resource configuration, then you must also delete the nodesets in your cluster that use that configuration. Otherwise, modifying your cluster fails.

To modify a cluster's description, labels, networking resources, or storage resources, use the gcloud CLI or REST API. Otherwise, select one of the following options:

Console

1. In the Google Cloud console, go to the Cluster Director page.

   Go to Cluster Director

2. In the navigation menu, click Clusters. The Clusters page appears.

3. In the Clusters table, in the Name column, click the name of the cluster that you want to modify. The page that gives the details of your cluster appears.

4. Click Edit. A page that gives the details of your cluster appears.

5. In the Compute section, you can modify the compute resource configurations that your cluster uses. To do so, do one of more of the following:

   • To add or edit a compute resource configuration, do one of the following:

     • To add resource configuration, click Add resource configuration.

     • To edit resource configuration, click Edit resource configuration.

   • In the Add resource configuration pane that appears, you can do one or more of the following:

     • To specify a machine type, click the General purpose or GPUs tab, and then follow the prompts to specify the machine type.

     • In the Number of instances field, enter the number of VMs for the resource configuration.

   • To delete a resource configuration, click Delete resource configuration.

6. Click Continue.

7. To modify your login nodesettings, expand the Login node section, and then do one or more of the following:

   • In the Node count field, enter the number of VMs for the node.

   • In the Source image list, select the OS image.

   • In the Startup script field, enter or modify the startup script for your cluster.

   • In the Boot disk type list, select the type of boot disk that you want your login node to use.

   • In the Boot disk size field, enter the number of GB for the disk. You must enter a value of 50 or higher.

8. To manage partitions and nodesets, expand the Partitions section, and then add, remove, or edit the partitions and nodesets as needed.

9. To add or edit prolog or epilog scripts, expand Advanced orchestration settings, and then add or edit your scripts.

10. Click Save.

    A page that gives the details of your cluster appears. Based on the properties that you modify in your cluster, modifying the cluster can take some time to complete.

gcloud

To modify a cluster, use the gcloud alpha cluster-director clusters update command.

Based on how you want to specify the cluster configuration, use one of the following methods. To modify network or storage resources, you must modify the cluster by specifying a configuration file.

• Specify a configuration file: to modify a cluster by specifying the cluster configuration in a JSON file, use the --config flag. To run the command, select one of the following options:

  Bash

  gcloud alpha cluster-director clusters update CLUSTER_NAME \
      --location=REGION \
      --config=CONFIGURATION_FILE
  

  Powershell

  gcloud alpha cluster-director clusters update CLUSTER_NAME `
      --location=REGION `
      --config=CONFIGURATION_FILE
  

  cmd.exe

  gcloud alpha cluster-director clusters update CLUSTER_NAME ^
      --location=REGION ^
      --config=CONFIGURATION_FILE
  

  Replace the following:

  • CLUSTER_NAME: the name of the cluster that you want to modify.

  • REGION: the region where your cluster exists.

  • CONFIGURATION_FILE: the path to the JSON file that contains the configuration details for the cluster. To review the configuration details that you can specify, review the request body for modifying a cluster by using REST.

• Specify each cluster property: to modify a cluster by specifying each configuration property directly, include one or more of the following flags based on the cluster properties that you want to modify:

  • To modify the cluster description: --description

  • To add or remove labels in the cluster, use one of the following flags:

    • To add labels: --add-labels

    • To remove labels: --remove-labels

  • To modify the Slurm node sets, use one of the following flags:

    • To add a node set: --add-slurm-node-sets

    • To update a node set: --update-slurm-node-sets

    • To remove a node set: --remove-slurm-node-sets

  • To modify the Slurm partitions, use one of the following flags:

    • To add a partition: --add-slurm-partitions

    • To update a partition: --update-slurm-partitions

    • To remove a partition: --remove-slurm-partitions

    • To modify the default partition: --slurm-default-partition

  • To add or remove on-demand VMs, use one of the following flags:

    • To add on-demand VMs: --add-on-demand-instances

    • To remove on-demand VMs: --remove-on-demand-instances

  • To add or remove reserved VMs, use one of the following flags:

    • To add reserved VMs: --add-reserved-instances

    • To remove reserved VMs: --remove-reserved-instances

  • To add or remove Spot VMs, use one of the following flags:

    • To add Spot VMs: --add-spot-instances

    • To remove Spot VMs: --remove-spot-instances

  • To add or remove Flex-start VMs, use one of the following flags:

    • To add Flex-start VMs: --add-dws-flex-instances

    • To remove Flex-start VMs: --remove-dws-flex-instances

  For example, assume that you want to modify a cluster by modifying the cluster description, adding a new label, modifying the login nodes, adding a new nodeset, partition, and compute resource configuration. To make these changes in your cluster, select one of the following options:

  Bash

  gcloud alpha cluster-director clusters update CLUSTER_NAME \
      --location=REGION \
      --description="DESCRIPTION" \
      --add-labels=CLUSTER_LABEL_KEY=CLUSTER_LABEL_VALUE \
      --add-on-demand-instances=id=NEW_COMPUTE_RESOURCE_NAME,zone=NEW_ZONE,machineType=NEW_MACHINE_TYPE \
      --add-slurm-node-sets=id=NODESET_NAME,computeId=COMPUTE_RESOURCE_NAME,staticNodeCount=STATIC_NUMBER_VMS,maxDynamicNodeCount=MAX_DYNAMIC_NUMBER_VMS,startupScript=STARTUP_SCRIPT_NODESET,labels="NODESET_LABEL" \
      --add-slurm-partitions=id=PARTITION_NAME,nodesetIds=[NODESET_NAME]
  

  Powershell

  gcloud alpha cluster-director clusters update CLUSTER_NAME `
      --location=REGION `
      --description="DESCRIPTION" `
      --add-labels=CLUSTER_LABEL_KEY=CLUSTER_LABEL_VALUE `
      --add-on-demand-instances=id=NEW_COMPUTE_RESOURCE_NAME,zone=NEW_ZONE,machineType=NEW_MACHINE_TYPE `
      --add-slurm-node-sets=id=NODESET_NAME,computeId=COMPUTE_RESOURCE_NAME,staticNodeCount=STATIC_NUMBER_VMS,maxDynamicNodeCount=MAX_DYNAMIC_NUMBER_VMS,startupScript=STARTUP_SCRIPT_NODESET,labels="NODESET_LABEL" `
      --add-slurm-partitions=id=PARTITION_NAME,nodesetIds=[NODESET_NAME]
  

  cmd.exe

  gcloud alpha cluster-director clusters update CLUSTER_NAME ^
      --location=REGION ^
      --description="DESCRIPTION" ^
      --add-labels=CLUSTER_LABEL_KEY=CLUSTER_LABEL_VALUE ^
      --add-on-demand-instances=id=NEW_COMPUTE_RESOURCE_NAME,zone=NEW_ZONE,machineType=NEW_MACHINE_TYPE ^
      --add-slurm-node-sets=id=NODESET_NAME,computeId=COMPUTE_RESOURCE_NAME,staticNodeCount=STATIC_NUMBER_VMS,maxDynamicNodeCount=MAX_DYNAMIC_NUMBER_VMS,startupScript=STARTUP_SCRIPT_NODESET,labels="NODESET_LABEL" ^
      --add-slurm-partitions=id=PARTITION_NAME,nodesetIds=[NODESET_NAME]
  

  Replace the following:

  • CLUSTER_NAME: the name of the cluster that you want to modify.

  • REGION: the region where your cluster exists.

  • DESCRIPTION: a new description for your cluster.

  • CLUSTER_LABEL_KEY: the key for the new label that you want to apply to your cluster. For more information about applying labels to Compute Engine resources, see Organize resources using labels.

  • CLUSTER_LABEL_VALUE: the value for the new label.

  • NEW_COMPUTE_RESOURCE_NAME: the name of the new compute resource configuration.

  • NEW_ZONE: the new zone for the new compute resource configuration.

  • NEW_MACHINE_TYPE: a supported machine type based on your specified consumption option.

  • NODESET_NAME: the name of the new nodeset to add to your cluster.

  • COMPUTE_RESOURCE_NAME: the name of the compute resource configuration for the new nodeset to use.

  • STATIC_NUMBER_VMS: the minimum number of VMs that your nodeset must use.

  • MAX_DYNAMIC_NUMBER_VMS: the maximum number of VMs that Cluster Director can add to the nodeset.

  • STARTUP_SCRIPT_NODESET: the startup script for the nodeset.

  • NODESET_LABEL: a label to apply to the nodeset.

  • PARTITION_NAME: the name of the new partition.

The output is similar to the following:

Update request issued for: [cluster000]
Waiting for operation [projects/example-project/locations/us-central1/operations/operation-1759940551889-640a8176bd2a2-0e460b9d-4281a5ca] to complete...working...

Based on the properties that you modify in your cluster, modifying the cluster can take some time to complete. When it does complete, the output is similar to the following:

Updated cluster [cluster000].

REST

To modify a cluster, make a PATCH request to the clusters.patch method.

Your request must include the following HTTP method and request URL:

PATCH https://hypercomputecluster.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_NAME?updateMask=FIELDS_TO_UPDATE

Based on the cluster properties that you want to modify, include one or more of the following fields in the request body:

• description: a description for your cluster.

• labels: key-value pairs of labels to help you organize and filter your clusters, as well as their associated resources.

• computeResources: the compute resources for your cluster, including the machine types and provisioning models to use for the VMs in the cluster.

• storageResources: the storage resources for your cluster; namely, the Filestore instances, Managed Lustre instances, or Cloud Storage buckets.

• orchestrator: the settings for the Slurm workload scheduler for your cluster, as well as the configurations for the cluster nodesets and partitions.

For example, assume that you want to modify a cluster by modifying the cluster description, adding a new label, modifying the login nodes, adding a new nodeset, partition, and compute resource configuration. To make these changes in your cluster, include the following in a JSON file named request-body.json:

{
  "description": "DESCRIPTION",
  "labels": {
    "CLUSTER_LABEL_KEY": "CLUSTER_LABEL_VALUE"
  },
  "orchestrator": {
    "slurm": {
      "loginNodes": {
        "count": "LOGIN_NODE_VMS",
        "startupScript": "STARTUP_SCRIPT"
      },
      "nodeSets": [
        {
          "id": "NODESET_NAME",
          "computeId": "COMPUTE_RESOURCE_NAME",
          "storageConfigs": [
            {
              "id": "STORAGE_NAME",
              "localMount": "STORAGE_PATH"
            }
          ],
          "staticNodeCount": "STATIC_NUMBER_VMS",
          "maxDynamicNodeCount": "MAX_DYNAMIC_NUMBER_VMS",
          "computeInstance": {
            "startupScript": "STARTUP_SCRIPT_NODESET",
            "labels": {
              "nodesetLabel": "NODESET_LABEL"
            },
            "bootDisk": {
              "type": "projects/PROJECT_ID/zones/DISK_ZONE/diskTypes/DISK_TYPE",
              "sizeGb": "DISK_SIZE"
            }
          }
        }
      ],
      "partitions": [
        {
          "id": "PARTITION_NAME",
          "nodeSetIds": [
            "NODESET_NAME"
          ]
        }
      ]
    }
  },
  "computeResources": {
    "NEW_COMPUTE_RESOURCE_NAME": {
      "config": {
        "newOnDemandInstances": {
          "machineType": "NEW_MACHINE_TYPE",
          "zone": "NEW_ZONE"
        }
      }
    }
  }
}

Replace the following:

• PROJECT_ID: the ID of your project.

• REGION: the region where your cluster exists.

• CLUSTER_NAME: the name of the cluster that you want to modify.

• FIELDS_TO_UPDATE: a comma-separated list of fields that you want to update. Based on how you want to update a field, do one of the following:

  • To update the field's value, specify the field in the updateMask query parameter and in the request body.

  • To delete a field from the cluster configuration details, specify the field in the updateMask query parameter but omit it from the request body.

  For this example, the updateMask query parameter is as follows:

  description,labels,orchestrator.slurm.loginNodes.count,orchestrator.slurm.loginNodes.startupScript,orchestrator.slurm.nodeSets,orchestrator.slurm.partitions,computeResources
  

• DESCRIPTION: a new description for your cluster.

• CLUSTER_LABEL_KEY: the key for the new label that you want to apply to your cluster. For more information about applying labels to Compute Engine resources, see Organize resources using labels.

• CLUSTER_LABEL_VALUE: the value for the new label.

• LOGIN_NODE_VMS: the new number of VMs for the login nodeset.

• STARTUP_SCRIPT: the startup script for the login nodeset. For more information about using startup scripts in VMs, see About startup scripts.

• NODESET_NAME: the name of the new nodeset to add to your cluster.

• COMPUTE_RESOURCE_NAME: the name of the compute resource configuration for the new nodeset to use.

• STORAGE_NAME: the name of the storage resource to mount.

• STORAGE_PATH: the path on the VM where the storage resource is mounted. For example, to mount the storage resource in your home directory, enter /home.

• STATIC_NUMBER_VMS: the minimum number of VMs that your nodeset must use.

• MAX_DYNAMIC_NUMBER_VMS: the maximum number of VMs that Cluster Director can add to the nodeset.

• STARTUP_SCRIPT_NODESET: the startup script for the nodeset.

• NODESET_LABEL: a label to apply to the nodeset.

• DISK_ZONE: the zone where you want to create the boot disks for the nodesets.

• DISK_TYPE: the type of boot disk for the nodeset. Based on the machine type in the node, specify one of the following values:

  • For A4X VMs: hyperdisk-balanced or hyperdisk-extreme

  • For A4 VMs: hyperdisk-balanced or hyperdisk-extreme

  • For A3 Ultra VMs: hyperdisk-balanced, hyperdisk-extreme, or hyperdisk-ml

  • For A3 Mega VMs: hyperdisk-balanced, hyperdisk-extreme, or hyperdisk-ml

  • For N2 VMs: pd-standard

  For an overview of the different types of boot disks that you can use, see Choose a disk type in the Compute Engine documentation.

• DISK_SIZE: the size of the boot disk in GB. The value must be 10 or higher.

• PARTITION_NAME: the name of the new partition.

• NEW_COMPUTE_RESOURCE_NAME: the name of the new compute resource configuration.

• NEW_MACHINE_TYPE: a supported machine type based on your specified consumption option.

• NEW_ZONE: the new zone for the new compute resource configuration.

To send your request, select one of the following options:

curl (Bash)

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --bodyd @request.json \
     "https://hypercomputecluster.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_NAME?updateMask=FIELDS_TO_UPDATE"

Powershell

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request-body.json `
    -Uri "https://hypercomputecluster.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_NAME?updateMask=FIELDS_TO_UPDATE" | Select-Object -Expand Content

curl (cmd.exe)

curl -X PATCH ^
     -H "Authorization: Bearer $(gcloud auth print-access-token)" ^
     -H "Content-Type: application/json; charset=utf-8" ^
     --bodyd @request.json ^
     "https://hypercomputecluster.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_NAME?updateMask=FIELDS_TO_UPDATE"

The response is similar to the following:

{
  "name": "projects/example-project/locations/us-central1/operations/operation-1758842430697-63fa86a4c3030-028b6436-2fbda8e1",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.hypercomputecluster.v1.OperationMetadata",
    "createTime": "2025-09-25T23:20:30.707315354Z",
    "target": "projects/example-project/locations/us-central1/clusters/clusterp6a",
    "verb": "update",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

Based on the properties that you modify in your cluster, modifying the cluster can take some time to complete.

What's next?

• View clusters

• Connect to a login node in a cluster