View topology of a compute instance

This document explains how to view the physical location of your A4X Max, A4X, A4, or A3 Ultra Compute Engine instances that run on reserved blocks of capacity.

After you create A4X Max, A4X, A4, or A3 Ultra instances , you can view their arrangements to verify which instances are closest to each other. By understanding instance proximity, you can do the following:

• Adjust your application or workload design to further minimize network latency.

• Troubleshoot network latency or performance issues of instances that communicate frequently, if they are unexpectedly located far apart.

Before you begin

• Review the terminology that is used in Cluster Director features.

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

  Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command:

  gcloud  
  init

  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity .

  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 permissionssection:

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

Understand compute instance topology

When you view the details of a running compute instance, you can understand its physical location in a cluster by checking the Physical hostfield (for the Google Cloud console), or the physicalHostTopology field (for the gcloud 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 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 hostor physicalHostTopology fields between instances. The more sub-fields the instances share, the closer they are physically located.

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 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:

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

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

 {
  "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"
        }
      }
    },
    ...
  ]
} 

View compute instance topology by querying metadata key

To view the physical location of a running compute instance by querying the physical_host_topology metadata key, select one of the following options:

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