View H4D cluster topology

After you create an H4D cluster on reserved blocks of capacity, you can view the physical arrangement of the VMs that make up the cluster. Understanding the arrangement of your VMs, lets you do the following:

  • Adjust your application or workload design to further minimize network latency, especially for workloads leveraging Cloud RDMA.
  • Troubleshoot network latency or performance issues of VMs that communicate frequently.

Before you begin

Make sure you have the necessary permissions to view VM topoloy information.

Required roles

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

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

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

Understand VMs topology

When you view the details of a running VM, you can retrieve information about its physical location within a cluster by checking the Physical host field (for the Google Cloud console), or the physicalHostTopology field (for the Google Cloud CLI), Compute Engine API, or by querying the metadata key. These fields contain the following sub-fields:

  • cluster: the global name of the cluster.
  • block: the organization-specific ID of the reserved block where the VM is located.
  • sub-block: the organization-specific ID of the sub-block where the VM is located.
  • host: the organization-specific ID of the host where the VM runs on.

For definitions of these terms, see Cluster terminology.

To understand how close the VMs are to each other, compare the values of the Physical host or physicalHostTopology fields between VMs. The more sub-fields the VMs share, the closer they are physically located.

You can also view the topology of a reservation in which the VMs are created. The physicalHostTopology fields of a reservation and a VM show the same block and cluster fields. When you view a specific reserved block, you can view the name and sub-block of all the VMs that are deployed in the block. For more information about the topology of a reservation, see View the topology of a reservation.

View VMs topology

To view the physical location of multiple running VMs, select any of the following options:

Console

  • In the Google Cloud console, go to the VM instances page.

    Go to VM instances

  • In the Name column, click the name of the VM to view its details. A page that gives the VM details appears. The Details tab is selected by default.

  • In the Basic information section, check the value of the Physical host field.

Google Cloud CLI

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

Replace the following:

  • VM_NAME: the VM name.
  • ZONE: the zone where the VM exists.

The output is similar to the following:

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

REST

To view the physical location of your running VMs, make one of the following GET requests. When you make a request, you must include the fields query parameter and specify to only show the name, machineType, and physicalHostTopology fields of a VM. You must also include the filter query parameter and specify to only list running VMs.

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/aggregated/instances?fields=items.name,items.machineType,items.resourceStatus.physicalHostTopology&filter=status=RUNNING
  • To view a list of your VMs in a specific zone: instances.list method.
GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances?fields=items.name,items.machineType,items.resourceStatus.physicalHostTopology&filter=status=RUNNING

Replace the following: * PROJECT_ID: the ID of the project where the VMs exist. * ZONE: the zone where the VMs exist.

The output is similar to the following:

{
  "items": [
    {
      "name": "vm-01",
      "machineType": "https://www.googleapis.com/compute/v1/projects/example-project/zones/europe-west4-b/machineTypes/h4d-highmem-192-lssd",
      "resourceStatus": {
        "physicalHostTopology": {
          "cluster": "europe-west4-cluster-jfhb",
          "block": "3e3056e23cf91a5cb4a8621b6a52c100",
          "subBlock": "0fc09525cbd5abd734342893ca1c083f",
          "host": "1215168a4ecdfb434fd4d28056589059"
        }
      }
    },
    {
      "name": "vm-02",
      "machineType": "https://www.googleapis.com/compute/v1/projects/example-project/zones/europe-west1-b/machineTypes/h4d-highmem-192-lssd",
      "resourceStatus": {
        "physicalHostTopology": {
          "cluster": "europe-west4-cluster-jfhb",
          "block": "3e3056e23cf91a5cb4a8621b6a52c100",
          "subBlock": "1fc18636cbd4abd623553784ca2c174e",
          "host": "2326279b5ecdfc545fd5e39167698168"
        }
      }
    },
    ...
  ]
}

If you want to refine your list of VMs, then edit the filter expression in the filter query parameter.

View VMs topology by querying metadata key

To view the physical location of a running VM 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, create a query by using the curl tool. To query the physical_host_topology metadata key on Linux VMs, run the following command:
curl -s -H "Metadata-Flavor: Google" http://metadata.google.internal/computeMetadata/v1/instance/attributes/physical_host_topology

The output is similar to the following:

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

Windows VMs

  1. Connect to your Windows VM.
  2. From your Windows VM, create a query by using the Invoke-RestMethod. To query the physical_host_topology metadata key on Windows VMs, run the following command:
$value = (Invoke-RestMethod `
  -Headers @{'Metadata-Flavor' = 'Google'} `
  -Uri "http://metadata.google.internal/computeMetadata/v1/instance/attributes/physical_host_topology")
$value

The output is similar to the following:

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

What's next