View topology of a compute instance

Clustered GPUs

This document explains how to view the physical location, also known as topology, of your Compute Engine instances in a zone. To view the topology of a cluster in Cluster Director, see View cluster topology.

After you create A4X Max, A4X, A4, A3 Ultra, A3 Mega, and A3 High (8 GPUs) instances or compute instances that specify a compact placement policy or a workload policy, you can view the physical location of your compute instances in relation to each other. When you know the proximity of your compute instances, you can adjust your application or workload design to run latency-sensitive jobs on the compute instances that are closest to each other. For all other types of compute instances, you can see the ID of the host that they run on after you expose the host ID.

Before you begin

Review the terminology for compute instance topology.
Select the tab for how you plan to use the samples on this page:
Console

When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

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.
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 compute instance 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 compute instance topology. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to view compute instance topology:

To view the details of a compute instance: compute.instances.get on the project
To view a list of compute instances: compute.instances.list on the project

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

Understand compute instance topology

To understand the physical location of a compute instance in a cluster, check the Physical host field in the Google Cloud console. If you use the gcloud CLI, the Compute Engine API, or a metadata key query, check the physicalHostTopology field. 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 instance is located.
sub-block: the organization-specific ID of the sub-block where the instance is located.
host: the organization-specific ID of the host where the instance runs on.

To understand instance proximity, compare the values of the Physical host or physicalHostTopology fields between compute instances. The more sub-fields the compute instances share, the closer they are to each other.

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

View compute instance topology

To view the physical location of multiple running compute instances at once, use the REST API. Otherwise, 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 compute instance that you want to view the details of. A page that gives the details of the compute instance appears and the Details tab is selected.
In the Basic information section, check the value of the Physical host field.

gcloud

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

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

Replace the following:

INSTANCE_NAME: the name of the compute instance.
ZONE: the zone where the compute instance exists.

The output is similar to the following:

If you can view the ID of the cluster, block, sub-block, and host of a compute instance, then the output is similar to the following:

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

If you can only view the ID of the host after you expose it, then the output is similar to the following:
```
---
cluster: null
block: null
subBlock: null
host: 1215168a4ecdfb434fd4d28056589059
```

REST

To view the physical location of your running compute instances, 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 compute instance. You must also include the filter query parameter and specify to only list running compute instances.

To view a list of your instances across all zones: instances.aggregatedList method

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 instances 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 compute instances exist.
ZONE: the zone where the compute instances exist.

The output is similar to the following:

If you can view the ID of the cluster, block, sub-block, and host of your compute instances, then the output is similar to the following:

{
  "items": [
    {
      "name": "vm-01",
      "machineType": "https://www.googleapis.com/compute/v1/projects/example-project/zones/europe-west1-b/machineTypes/a3-ultragpu-8g",
      "resourceStatus": {
        "physicalHostTopology": {
          "cluster": "europe-west1-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/a3-ultragpu-8g",
      "resourceStatus": {
        "physicalHostTopology": {
          "cluster": "europe-west1-cluster-jfhb",
          "block": "3e3056e23cf91a5cb4a8621b6a52c100",
          "subBlock": "1fc18636cbd4abd623553784ca2c174e",
          "host": "2326279b5ecdfc545fd5e39167698168"
        }
      }
    },
    ...
  ]
}

If you can only view the ID of your compute instances of the host after you expose it, then the output is similar to the following:

{
  "items": [
    {
      "name": "vm-01",
      "machineType": "https://www.googleapis.com/compute/v1/projects/example-project/zones/europe-west1-b/machineTypes/a3-ultragpu-8g",
      "resourceStatus": {
        "physicalHostTopology": {
          "cluster": null,
          "block": null,
          "subBlock": null,
          "host": "1215168a4ecdfb434fd4d28056589059"
        }
      }
    },
    {
      "name": "vm-02",
      "machineType": "https://www.googleapis.com/compute/v1/projects/example-project/zones/europe-west1-b/machineTypes/a3-ultragpu-8g",
      "resourceStatus": {
        "physicalHostTopology": {
          "cluster": null,
          "block": null,
          "subBlock": null,
          "host": "2326279b5ecdfc545fd5e39167698168"
        }
      }
    },
    ...
  ]
}

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

View compute instance topology with a metadata key query

To view the physical location of a running compute instance with a query to the physical_host_topology metadata key, select one of the following options:

Linux instances

Connect to your Linux compute instance.

From your Linux instance, create a query by using the curl tool. To query the physical_host_topology metadata key on Linux instances, run the following command:

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

The output is similar to the following:

If you can view the ID of the cluster, block, sub-block, and host of a compute instance, then the output is similar to the following:

{
  "cluster": "europe-west1-cluster-jfhb",
  "block": "3e3056e23cf91a5cb4a8621b6a52c100",
  "subBlock": "0fc09525cbd5abd734342893ca1c083f",
  "host": "1215168a4ecdfb434fd4d28056589059"
}

If you can only view the ID of the host after you expose it, then the output is similar to the following:

{
  "cluster": null,
  "block": null,
  "subBlock": null,
  "host": "1215168a4ecdfb434fd4d28056589059"
}

Windows instances

Connect to your Windows compute instance.

From your Windows instance, create a query with the Invoke-RestMethod command. To query the physical_host_topology metadata key on Windows instances, run the following command:

PS C:\> 
$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:

If you can view the ID of the cluster, block, sub-block, and host of a compute instance, then the output is similar to the following:

{
  "cluster": "europe-west1-cluster-jfhb",
  "block": "3e3056e23cf91a5cb4a8621b6a52c100",
  "subBlock": "0fc09525cbd5abd734342893ca1c083f",
  "host": "1215168a4ecdfb434fd4d28056589059"
}

If you can only view the ID of the host after you expose it, then the output is similar to the following:

{
  "cluster": null,
  "block": null,
  "subBlock": null,
  "host": "1215168a4ecdfb434fd4d28056589059"
}

What's next

Learn how to manage host events:
- Manage host events across compute instances
- Manage host events across reservations
Monitor compute instances and clusters

View topology of a compute instance Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Console

gcloud

REST

Required roles

Required permissions

Understand compute instance topology

View compute instance topology

Console

gcloud

REST

View compute instance topology with a metadata key query

Linux instances

Windows instances

What's next

View topology of a compute instance