View H4D cluster topology

After youcreate 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 communicatefrequently.

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 administratorto grant you theCompute Instance Admin (v1)IAM role on your project. For more information about grantingroles, seeManage 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 theRequired permissionssection:

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 aboutits physical location within a cluster by checking thePhysical host field(for the Google Cloud console), or thephysicalHostTopology field (for theGoogle Cloud CLI), Compute Engine API, or byquerying 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 VMis located.
  • sub-block: the organization-specific ID of the sub-block where the VM islocated.
  • host: the organization-specific ID of the host where the VM runs on.

For definitions of these terms, seeCluster terminology.

To understand how close the VMs are to each other, compare the values of thePhysical host orphysicalHostTopology fields between VMs. The moresub-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.ThephysicalHostTopology fields of a reservation and a VM show the sameblockandcluster fields. When you view a specific reserved block, you can view thename and sub-block of all the VMs that are deployed in the block. For moreinformation about the topology of a reservation, seeView the topology of a reservation.

View VMs topology

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

Console

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

    Go to VM instances

  • In theName column, click the name of the VM to view its details. Apage that gives the VM details appears. TheDetails tab is selected bydefault.

  • In theBasic information section, check the value of thePhysical host field.

Google Cloud CLI

To view the physical location of a running VM, use thegcloud compute instances describecommand with theflatten=resourceStatus.physicalHostTopology.

Replace the following:

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

The output is similar to the following:

---cluster: europe-west1-cluster-jfhbblock: 3e3056e23cf91a5cb4a8621b6a52c100subBlock: 0fc09525cbd5abd734342893ca1c083fhost: 1215168a4ecdfb434fd4d28056589059

REST

To view the physical location of your running VMs, make one of the followingGET requests. When you make a request, you must include thefields queryparameter and specify to only show thename,machineType, andphysicalHostTopology fields of a VM. You must also include thefilterquery 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
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 inthefilterquery parameter.

View VMs topology by querying metadata key

To view the physical location of a running VM by querying thephysical_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 thecurltool. To query thephysical_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 theInvoke-RestMethod.To query thephysical_host_topology metadata key on Windows VMs, run thefollowing 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

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.