README.md

Description

This module creates one or more compute VM instances.

Example

- id: compute
  source: modules/compute/vm-instance
  use: [network1]
  settings:
    instance_count: 8
    name_prefix: compute
    machine_type: c2-standard-60

This creates a cluster of 8 compute VMs that are:

• named compute-[0-7]
• on the network defined by the network1 module
• of type c2-standard-60

NOTE: Simultaneous Multithreading (SMT) is deactivated by default (threads_per_core=1), which means only the physical cores are visible on the VM. With SMT disabled, a machine of type c2-standard-60 will only have the 30 physical cores visible. To change this, set threads_per_core=2 under settings.

VPC Networks

There are two methods for adding network connectivity to the vm-instance module. The first is shown in the example above, where a vpc module or pre-existing-vpc module is used by the vm-instance module. When this happens, the network_self_link and subnetwork_self_link outputs from the network are provided as input to the vm-instance and a network interface is defined based on that. This can also be done updating the network_self_link and subnetwork_self_link settings directly.

The alternative option can be used when more than one network needs to be added to the vm-instance or further customization is needed beyond what is provided via other variables. For this option, the network_interfaces variable can be used to set up one or more network interfaces on the VM instance. The format is consistent with the terraform google_compute_instance network_interface block, and more information can be found in the terraform docs.

NOTE: When supplying the network_interfaces variable, networks associated with the vm-instance via use will be ignored in favor of the networks added in network_interfaces. In addition, bandwidth_tier and disable_public_ips will not apply to networks defined in network_interfaces.

SSH key metadata

This module will ignore all changes to the ssh-keys metadata field that are typically set by external Google Cloud tools that automate SSH access when not using OS Login. For example, clicking on the Google Cloud Console SSH button next to VMs in the VM Instances list will temporarily modify VM metadata to include a dynamically-generated SSH public key.

Placement

The placement_policy variable can be used to control where your VM instances are physically located relative to each other within a zone. See the official placement guide and api documentation.

Use the following settings for compact placement:

  ...
  settings:
    instance_count: 4
    machine_type: c2-standard-60
    placement_policy:
      collocation: "COLLOCATED"

By default the above placement policy will always result in the most compact set of VMs available. If you would like that provisioning failed if some level of compactness is not obtainable, you can enforce this with the max_distance setting:

  ...
  settings:
    instance_count: 4
    machine_type: c2-standard-60
    placement_policy:
      collocation: "COLLOCATED"
      max_distance: 1

Use the following settings for spread placement:

  ...
  settings:
    instance_count: 4
    machine_type: n2-standard-4
    placement_policy:
      availability_domain_count: 2

When vm_count is not set, as shown in the examples above, then the VMs will be added to the placement policy incrementally. This is the recommended way to use placement policies.

If vm_count is specified then VMs will stay in pending state until the specified number of VMs are created. See the warning below if using this field.

GPU Support

More information on GPU support in vm-instance and other Cluster Toolkit modules can be found at docs/gpu-support.md

Lifecycle

The vm-instance module will be replaced when the instance_image variable is changed and terraform apply is run on the deployment group folder or gcluster deploy is run. However, it will not be automatically replaced if a new image is created in a family.

To selectively replace the vm-instance(s), consider running terraform apply -replace such as:

See https://developer.hashicorp.com/terraform/cli/commands/plan#replace-address for precise syntax terraform apply -replace=ADDRESS

terraform state list
# search for the module ID and resource
terraform apply -replace="address"

License

Copyright 2026 Google LLC

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

 http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Requirements

Providers

Modules

Resources

Inputs

object({
    count = optional(number, 0)
    type  = optional(string, "pd-balanced")
    size  = optional(number, 200)
  })

object({
    address_type = optional(string, "INTERNAL")
    purpose      = optional(string),
    network_tier = optional(string),
    ip_version   = optional(string, "IPV4"),
  })

list(object({
    type  = string,
    count = number
  }))

{
  "family": "hpc-rocky-linux-8",
  "project": "cloud-hpc-image-public"
}

list(object({
    #If both network and subnetwork are specified, the subnetwork must belong to the provided network to avoid configuration errors.
    network            = string,
    subnetwork         = string,
    subnetwork_project = string,
    network_ip         = string,
    nic_type           = string,
    stack_type         = string,
    queue_count        = number,
    access_config = list(object({
      nat_ip                 = string,
      public_ptr_domain_name = string,
      network_tier           = string
    })),
    ipv6_access_config = list(object({
      public_ptr_domain_name = string,
      network_tier           = string
    })),
    alias_ip_range = list(object({
      ip_cidr_range         = string,
      subnetwork_range_name = string
    }))
  }))

list(object({
    server_ip             = string,
    remote_mount          = string,
    local_mount           = string,
    fs_type               = string,
    mount_options         = string,
    client_install_runner = map(string)
    mount_runner          = map(string)
  }))

object({
    vm_count                  = optional(number)
    availability_domain_count = optional(number)
    collocation               = optional(string)
    max_distance              = optional(number)
    gpu_topology              = optional(string)
  })

object({
    email  = string,
    scopes = set(string)
  })

[
  "https://www.googleapis.com/auth/cloud-platform"
]

Outputs