View Compute Engine instance topology

This document explains how to view the topology of your running Compute Engine instances. After you create and start compute instances, you can view their physical location in a zone to understand your cluster's topology. This information helps you do the following:

• Organize jobs: you can adjust your workload design to, for example, place communication-heavy tasks on the physically closest compute instances.

• Troubleshoot issues: you can investigate network latency or performance issues if specific compute instances are unexpectedly located far apart.

To verify which compute instances are running in your project, view a list of compute instances .

Limitations

You can only view the topology of compute instances that meet one or more of the following requirements:

• The compute instances use one of the following machine types:

  • A4X Max

  • A4X

  • A4

  • A3 Ultra

  • A3 Mega

  • A3 High with 8 GPUs

  • H4D

• The compute instances specify a compact placement policy .

• The compute instances are part of a managed instance group (MIG) that specifies a workload policy with a high throughput ( HIGH_THROUGHPUT ) type .

Understand compute instance topology

Each compute instance runs on a physical server, a host , that is on a server block. Each block belongs to a cluster, which resides in a data center within a Google Cloud zone. When you view compute instances that meet specific requirements , you can understand their topology in relation to other compute instances that meet the same requirements. Specifically, you can understand the physical location of your compute instances by checking the following sub-fields in each compute instance's physicalHostTopology field:

• Cluster ( cluster ): the global name of the cluster where your compute instance exists. A cluster is a high-level logical grouping of multiple hosts, which can span across several blocks, that work together as a single pool of resources.

• Block ( block ): the organization-specific ID of the block where your compute instance exists. A block is a collection of multiple hosts grouped together. Compute instances in the same block experience low network latency.

• Sub-block ( subBlock ): the organization-specific ID of the sub-block where your compute instance exists. A sub-block is a physical subdivision in a block, grouping hosts within a single physical enclosure. Compute instances in the same sub-block experience lower network latency than compute instances in the same block.

• Host ( host ): the organization-specific ID of the host where your compute instance exists. A host is a single physical server on which your compute instances run. Each host has its own physical vCPU, memory, storage, and network interface card (NIC). Compute instances in adjacent hosts experience the lowest possible network latency.

The more sub-fields that two running compute instances share, the physically closer they are to each other. This information helps you optimize your workloads by organizing your jobs so that you can minimize network latency, or by designing more resilient systems.

Before you begin

• If you haven't already, set up authentication . Authentication verifies your identity for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:

  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

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

  2. Set a default region and zone .

  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.

  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 verify the topology of your compute instances, ask your administrator to grant you the Compute Viewer ( roles/compute.viewer ) IAM role on the project. For more information about granting roles, see Manage access to projects, folders, and organizations .

This predefined role contains the permissions required to verify the topology of your compute instances. 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 .

Verify compute instance topology

To verify the topology of your running compute instances, use one of the following methods:

• Verify compute instance topology by using the Google Cloud console, gcloud CLI, or REST

• Verify compute instance topology by querying metadata key

Verify compute instance topology by using the Google Cloud console, gcloud CLI, or REST

To view the topology for multiple compute instances simultaneously, use the REST API. Otherwise, select one of the following options:

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

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

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

Verify compute instance topology by querying metadata key

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

What's next

• Learn more about host events in a compute instance .

• Learn how to monitor compute instances .