View VMs topology

This document explains how to view the physical location of your A3 Ultra virtual machine (VM) instances within a Hypercompute Cluster. For more information about Hypercompute Cluster, see Hypercompute Cluster.

After creating VMs, you can view their arrangements to verify which VMs are closest to each other. By understanding VM proximity, you can then adjust your application or workload design to further minimize network latency. This can also help you understand and troubleshoot network latency or performance issues of VMs that communicate frequently, if they are unexpectedly located far apart.

Before you begin

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

    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, then initialize it by running the following command: 

      gcloud init

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

Required roles

To get the permissions that you need to view VMs topology, ask your administrator to grant you the Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the permissions required to view VMs topology. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to view VMs topology:

  • To view the details of a VM: compute.instances.get on the project
  • To view a list of VMs: compute.instances.list on the project

You might also be able to get these permissions with custom roles or other predefined roles.

Overview

When viewing a VM, you can understand its physical location within a Hypercompute Cluster by viewing the following fields within the physicalHostTopology field:

  • cluster: the global name of the cluster.

  • block: the organization-specific ID of the reserved block in which the VM is located.

  • subBlock: the organization-specific ID of the sub-block in which the VM is located.

  • host: the organization-specific ID of the host on which the VM is located.

To learn more about cluster, block, sub-block, and host, see Terminology.

To understand VM proximity, compare the values of the physicalHostTopology fields. The more fields VMs share, the closer they are physically located.

You can also view the topology of a reservation in which the VMs are created. The physicalTopology of a reservation and the physicalHostTopology of a VM show the same block and cluster fields. For more information about reservation topology, see View the topology of a reservation

View VMs topology

You can view the physical location of multiple VMs simultaneously or individual VMs in your Hypercompute Cluster. For multiple VMs, use the REST API. For individual VMs, select any of the following options:

gcloud

To view the physical location of a VM, use the gcloud beta compute instances describe command with the --flatten=resourceStatus.physicalHostTopology flag:

gcloud beta compute instances describe VM_NAME \
    --flatten=resourceStatus.physicalHostTopology \
    --zone=ZONE

Replace the following:

  • VM_NAME: the VM name.

  • ZONE: the zone where the VM is located.

The output is similar to the following:

---
cluster: europe-west1-cluster-jfhb
block: 3e3056e23cf91a5cb4a8621b6a52c100
subBlock: 0fc09525cbd5abd734342893ca1c083f
host: 1215168a4ecdfb434fd4d28056589059

REST

To view the topology of your VMs, make one of the following GET requests using URL-encoded values. The fields query parameter specifies to only show the name, machineType, and physicalHostTopology fields. The filter query parameter further specifies to only list VMs using an a3-ultragpu-8g machine type.

  • To view VMs across all zones: beta instances.aggregatedList method.

    GET https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/aggregated/instances?fields=items.name,items.machineType,items.resourceStatus.physicalHostTopology&filter=machineType%20eq%20%2E%2Aa3-ultragpu-8g

  • To view VMs in a specific zone: beta instances.list method.

    GET https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instances?fields=items.name,items.machineType,items.resourceStatus.physicalHostTopology&filter=machineType%20eq%20%2E%2Aa3-ultragpu-8g

Replace the following:

  • PROJECT_ID: the ID of the project where the VMs are located.

  • ZONE: the zone where the VMs are located.

The output is similar to the following:

{
  "items": [
    {
      "name": "vm-01",
      "machineType": "https://www.googleapis.com/compute/beta/projects/example-project/zones/europe-west1-b/machineTypes/a3-ultragpu-8g",
      "resourceStatus": {
        "physicalTopology": {
          "cluster": "europe-west1-cluster-jfhb",
          "block": "3e3056e23cf91a5cb4a8621b6a52c100",
          "subBlock": "0fc09525cbd5abd734342893ca1c083f",
          "host": "1215168a4ecdfb434fd4d28056589059"
        }
      }
    },
    {
      "name": "vm-02",
      "machineType": "https://www.googleapis.com/compute/beta/projects/example-project/zones/europe-west1-b/machineTypes/a3-ultragpu-8g",
      "resourceStatus": {
        "physicalTopology": {
          "cluster": "europe-west1-cluster-jfhb",
          "block": "3e3056e23cf91a5cb4a8621b6a52c100",
          "subBlock": "1fc18636cbd4abd623553784ca2c174e",
          "host": "2326279b5ecdfc545fd5e39167698168"
        }
      }
    }
  ]
}

Optionally, to further narrow down a list of VMs, set the filter query parameter to a different filter expression. For example, to view a list of VMs across all zones that are located in a block with an ID of abcd1234, make the following GET request using URL-encoded values:

GET https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/aggregated/instances?fields=items.name,items.resourceStatus.physicalHost&filter=resourceStatus.physicalHostTopology.block%20eq%20%abcd1234

View VMs topology using metadata key

To view a VM topology by querying the physical_host_topology metadata key, select one of the following options:

Linux VMs

  1. Connect to your Linux VM.

  2. From your Linux VM, use the curl tool to make a query. To query the physical_host_topology metadata key on Linux VMs, run the following command:

    user@myinst:~$ curl -s -H "Metadata-Flavor: Google" http://metadata.google.internal/computeMetadata/beta/instance/attributes/physical_host_topology

    The output is similar to the following:

    {
  "cluster": "europe-west1-cluster-jfhb",
  "block": "3e3056e23cf91a5cb4a8621b6a52c100",
  "subBlock": "1fc18636cbd4abd623553784ca2c174e",
  "host": "2326279b5ecdfc545fd5e39167698168"
}

Windows VMs

  1. Connect to your Windows VM.

  2. From your Windows VM, use the Invoke-RestMethod command to make a query. To query the physical_host_topology metadata key on Windows VMs, run the following command:

    PS C:\> 
$value = (Invoke-RestMethod `
        -Headers @{'Metadata-Flavor' = 'Google'} `
        -Uri "http://metadata.google.internal/computeMetadata/beta/instance/attributes/physical_host_topology")
$value

    The output is similar to the following:

    {
  "cluster": "europe-west1-cluster-jfhb",
  "block": "3e3056e23cf91a5cb4a8621b6a52c100",
  "subBlock": "1fc18636cbd4abd623553784ca2c174e",
  "host": "2326279b5ecdfc545fd5e39167698168"
}

What's next