a4high-vm.yaml

# 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.

---

blueprint_name: a4high-vm-instance

vars:
  # The following variables should be edited, provided
  # via `--vars key1=value1,key2=value2`, or be added to a deployment.yaml file
  # and used with `gcluster deploy -d deployment.yaml <this-file>`
  project_id: # supply project ID
  deployment_name: a4high-vm
  region: # Supply region
  zone: # Supply zone
  a4h_reservation_name: # supply reservation name
  number_of_vms: 2


  a4h_provisioning_model: RESERVATION_BOUND
  instance_image:
    project: ubuntu-os-cloud
    family: ubuntu-2204-lts
  net0_range: 192.168.0.0/19
  net1_range: 192.168.64.0/18
  filestore_ip_range: 192.168.32.0/24
  rdma_net_range: 192.168.128.0/18
  hostname_prefix: $(vars.deployment_name)
  local_ssd_mountpoint: /mnt/localssd

deployment_groups:
- group: primary
  modules:

  - id: a4high-net-0
    source: modules/network/vpc
    settings:
      network_name: $(vars.deployment_name)-net-0
      mtu: 8896
      subnetworks:
      - subnet_name: $(vars.deployment_name)-sub-0
        subnet_region: $(vars.region)
        subnet_ip: $(vars.net0_range)
      firewall_rules:
      - name: $(vars.deployment_name)-internal-0
        ranges: [$(vars.net0_range)]
        allow:
        - protocol: tcp
        - protocol: udp
        - protocol: icmp

  - id: a4high-net-1
    source: modules/network/vpc
    settings:
      network_name: $(vars.deployment_name)-net-1
      mtu: 8896
      subnetworks:
      - subnet_name: $(vars.deployment_name)-sub-1
        subnet_region: $(vars.region)
        subnet_ip: $(vars.net1_range)
      firewall_rules:
      - name: $(vars.deployment_name)-internal-1
        ranges: [$(vars.net1_range)]
        allow:
        - protocol: tcp
        - protocol: udp
        - protocol: icmp

  - id: a4high-rdma-net
    source: modules/network/gpu-rdma-vpc
    settings:
      network_name: $(vars.deployment_name)-rdma-net
      network_profile: https://www.googleapis.com/compute/beta/projects/$(vars.project_id)/global/networkProfiles/$(vars.zone)-vpc-roce
      network_routing_mode: REGIONAL
      subnetworks_template:
        name_prefix: $(vars.deployment_name)-mrdma-sub
        count: 8
        ip_range: $(vars.rdma_net_range)
        region: $(vars.region)

  - id: homefs
    source: modules/file-system/filestore
    use: [a4high-net-0]
    settings:
      filestore_tier: HIGH_SCALE_SSD
      size_gb: 10240
      local_mount: /home
      reserved_ip_range: $(vars.filestore_ip_range)
    outputs:
    - network_storage

  - id: startup-script
    source: modules/scripts/startup-script
    settings:
      configure_ssh_host_patterns:
      - $(vars.hostname_prefix)-*
      local_ssd_filesystem:
        mountpoint: $(vars.local_ssd_mountpoint)
        permissions: "1777" # must quote numeric filesystem permissions!
      docker:
        enabled: true
        world_writable: true
        daemon_config: |
          {
            "data-root": "$(vars.local_ssd_mountpoint)/docker"
          }

      runners:
      - type: data
        destination: /etc/security/limits.d/99-unlimited.conf
        content: |
          * - memlock unlimited
          * - nproc unlimited
          * - stack unlimited
          * - nofile 1048576
          * - cpu unlimited
          * - rtprio unlimited

      # Install Nvidia driver / CUDA components
      - type: ansible-local
        destination: install_a4h_drivers.yml
        content: |
          ---
          - name: Install A4 Drivers and Utils
            hosts: all
            become: true
            vars:
              distribution: "{{ ansible_distribution | lower }}{{ ansible_distribution_version | replace('.','') }}"
              cuda_repo_url: https://developer.download.nvidia.com/compute/cuda/repos/{{ distribution }}/x86_64/cuda-keyring_1.1-1_all.deb
              cuda_repo_filename: /tmp/{{ cuda_repo_url | basename }}
              enable_nvidia_dcgm: false
              nvidia_packages:
              - nvidia-open-570
              - nvidia-utils-570
              - nvidia-container-toolkit
              - cuda-toolkit-12-8
              - datacenter-gpu-manager
              - libnvidia-nscq-570
            tasks:
            - name: Download NVIDIA repository package
              ansible.builtin.get_url:
                url: "{{ cuda_repo_url }}"
                dest: "{{ cuda_repo_filename }}"
            - name: Install NVIDIA repository package
              ansible.builtin.apt:
                deb: "{{ cuda_repo_filename }}"
                state: present
            - name: Update apt cache
              ansible.builtin.apt:
                update_cache: true
            - name: Install NVIDIA fabric and CUDA
              ansible.builtin.apt:
                name: "{{ item }}"
              loop: "{{ nvidia_packages }}"
            - name: Freeze NVIDIA fabric and CUDA
              ansible.builtin.dpkg_selections:
                name: "{{ item }}"
                selection: hold
              loop: "{{ nvidia_packages }}"
            post_tasks:
            # Enable DCGM monitoring
            - name: Enable NVIDIA DCGM by default
              ansible.builtin.service:
                name: nvidia-dcgm.service
                state: started
                enabled: true

            # Enable persistenced service
            - name: Enable nvidia-persistenced
              ansible.builtin.service:
                name: nvidia-persistenced.service
                state: started
                enabled: true

      # Install ibverbs-utils
      - type: ansible-local
        destination: install_ibverbs_utils.yml
        content: |
          ---
          - name: Install ibverbs-utils
            hosts: all
            become: true
            tasks:
            - name: Install Linux Modules Extra
              ansible.builtin.package:
                name:
                - ibverbs-utils
                state: present

      # Install NCCL
      - type: ansible-local
        destination: install_nccl.yml
        content: |
          ---
          - name: Install nccl
            hosts: all
            become: true
            tasks:
            - name: Install Linux Modules Extra
              ansible.builtin.package:
                name:
                - libnccl2
                - libnccl-dev
                state: present

      # Install OpenMPI
      - type: ansible-local
        destination: install_openmpi.yml
        content: |
          ---
          - name: Install MPI packages
            hosts: all
            become: true
            vars:
              mpi_packages:
              - libopenmpi-dev
              - libpmix-dev
              - libucx-dev
              - ucx-utils
            tasks:
            - name: Install Packages
              ansible.builtin.apt:
                name: "{{ item }}"
                update_cache: true
              loop: "{{ mpi_packages }}"

            # Configure OpenMPI parameters
            - name: add default btl_tcp_if_include
              ansible.builtin.lineinfile:
                path: /etc/openmpi/openmpi-mca-params.conf
                line: btl_tcp_if_include = enp0s19
                create: yes

      # Install NCCL-GIB Plugin
      - type: ansible-local
        destination: install_nccl_gib.yml
        content: |
          ---
          - name: Install Google NCCL-GIB Plugin
            hosts: localhost
            become: true
            tasks:
            - name: Add artifact registry gpg key
              ansible.builtin.apt_key:
                url: https://us-apt.pkg.dev/doc/repo-signing-key.gpg
                state: present
            - name: Add artifact registry gpg key
              ansible.builtin.apt_key:
                url: https://packages.cloud.google.com/apt/doc/apt-key.gpg
                state: present
            - name: Install Apt Transport AR Apt Repo
              apt_repository:
                repo: 'deb http://packages.cloud.google.com/apt apt-transport-artifact-registry-stable main'
                state: present
            - name: Install AR transport
              ansible.builtin.apt:
                name: "apt-transport-artifact-registry"
                update_cache: true
            - name: Install Google NCCL-GIB Plugin
              apt_repository:
                repo: "deb ar+https://us-apt.pkg.dev/projects/gce-ai-infra gpudirect-gib-apt main"
                state: present
            - name: Install NCCL-GIB Plugin
              ansible.builtin.apt:
                name: "nccl-gib"
                update_cache: true
            - name: Freeze NCCL GIB Plugin
              ansible.builtin.dpkg_selections:
                name: "nccl-gib"
                selection: hold

      # (Optional) Set defaults compatible with NCCL-GIB
      - type: data
        destination: /etc/environment
        content: |
          PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/snap/bin:/usr/local/cuda/bin"
          # The following are set to enable the NCCL gIB network plugin
          LD_LIBRARY_PATH=/usr/local/gib/lib64
          NCCL_CROSS_NIC=0
          NCCL_NET_GDR_LEVEL=PIX
          NCCL_P2P_NET_CHUNKSIZE=131072
          NCCL_NVLS_CHUNKSIZE=524288
          NCCL_IB_GID_INDEX=3
          NCCL_IB_ADAPTIVE_ROUTING=1
          NCCL_IB_QPS_PER_CONNECTION=4
          NCCL_IB_TC=52
          NCCL_IB_FIFO_TC=84
          NCCL_TUNER_CONFIG_PATH=/usr/local/gib/configs/tuner_config.txtpb
          # End of NCCL gIB section

      # (Optional) Update ldconfig in order to prefer NCCL-GIB
      - type: data
        destination: /etc/ld.so.conf.d/000_nccl-gib.conf
        content: |
          /usr/local/gib/lib64

      - type: ansible-local
        destination: update_ldconfig.yml
        content: |
          ---
          - name: Update ldconfig
            hosts: localhost
            become: true
            tasks:
            - name: Configure ldconfig
              ansible.builtin.command: /usr/sbin/ldconfig

  - id: a4high-vms
    source: modules/compute/vm-instance
    use: [startup-script, homefs]
    settings:
      machine_type: a4-highgpu-8g
      instance_count: $(vars.number_of_vms)
      name_prefix: $(vars.hostname_prefix)
      disk_type: hyperdisk-balanced
      automatic_restart: true
      on_host_maintenance: TERMINATE
      reservation_name: $(vars.a4h_reservation_name)
      provisioning_model: $(vars.a4h_provisioning_model)
      network_interfaces:
        $(concat(
          [{
            network=null,
            subnetwork=a4high-net-0.subnetwork_self_link,
            subnetwork_project=vars.project_id,
            nic_type="GVNIC",
            queue_count=null,
            network_ip=null,
            stack_type=null,
            access_config=[{nat_ip=null, public_ptr_domain_name=null, network_tier=null}],
            ipv6_access_config=[],
            alias_ip_range=[]
          },
          {
            network=null,
            subnetwork=a4high-net-1.subnetwork_self_link,
            subnetwork_project=vars.project_id,
            nic_type="GVNIC",
            queue_count=null,
            network_ip=null,
            stack_type=null,
            access_config=[{nat_ip=null, public_ptr_domain_name=null, network_tier=null}],
            ipv6_access_config=[],
            alias_ip_range=[]
          }],
          a4high-rdma-net.subnetwork_interfaces,
        ))

  - id: wait-for-vms
    source: community/modules/scripts/wait-for-startup
    settings:
      instance_names: $(a4high-vms.name)
      timeout: 7200