View the physical location of a Compute Engine instance

This document explains how to view the physical location of the running Compute Engine instances in your Google Cloud organization.

After you create and start compute instances, you can view which physical host each compute instance runs on in a zone. Use the physical location of the compute instances in your cluster to do the following:

  • Minimize network latency: adjust your application or workload design to run latency-sensitive jobs on compute instances that are the closest to each other.

  • Improve workload reliability: distribute compute instances across separate physical hosts to limit the impact of host errors in your application.

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

Limitations

You can view the ID of the cluster, block, sub-block, and host of compute instances that meet one or more of the following requirements:

If a compute instance doesn't meet any of the preceding requirements, then you can view its host ID after you expose it, as described in this document.

Understand compute instance topology

Each compute instance runs on a physical server, a host, that exists in a server block. Each block belongs to a cluster in a zone. When you view the details of compute instances that meet specific requirements, you can understand their topology relative to other compute instances that meet the same requirements.

Compute Engine exposes the following sub-fields in the physicalHostTopology field of each compute instance. The more sub-fields that two running compute instances share, the closer they reside to each other.

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

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

  • Host (host): the organization or project-specific ID of the host on which your compute instance runs. The host ID changes as follows:

    • If the compute instance specifies a compact placement policy or a workload policy, then the host ID is specific to your project.

    • If the compute instance specifies a supported machine series or you expose its host ID, then the host ID is specific to your organization.

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 Admin (roles/compute.admin) 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 verify the topology of your compute instances. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to verify the topology of your compute instances:

  • To view the details of a compute instance: compute.instances.get
  • To view a list of compute instances: compute.instances.list
  • To expose the host ID when you create a compute instance:
    • compute.instances.create on the project
    • To use a custom image to create the VM: compute.images.useReadOnly on the image
    • To use a snapshot to create the VM: compute.snapshots.useReadOnly on the snapshot
    • To use an instance template to create the VM: compute.instanceTemplates.useReadOnly on the instance template
    • To assign a legacy network to the VM: compute.networks.use on the project
    • To specify a static IP address for the VM: compute.addresses.use on the project
    • To assign an external IP address to the VM when using a legacy network: compute.networks.useExternalIp on the project
    • To specify a subnet for the VM: compute.subnetworks.use on the project or on the chosen subnet
    • To assign an external IP address to the VM when using a VPC network: compute.subnetworks.useExternalIp on the project or on the chosen subnet
    • To set VM instance metadata for the VM: compute.instances.setMetadata on the project
    • To set tags for the VM: compute.instances.setTags on the VM
    • To set labels for the VM: compute.instances.setLabels on the VM
    • To set a service account for the VM to use: compute.instances.setServiceAccount on the VM
    • To create a new disk for the VM: compute.disks.create on the project
    • To attach an existing disk in read-only or read-write mode: compute.disks.use on the disk
    • To attach an existing disk in read-only mode: compute.disks.useReadOnly on the disk
  • To expose the host ID when you create an instance template: compute.instanceTemplates.create
  • To expose or hide the host ID in an existing compute instance: compute.instances.update

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

Expose or hide host ID

Unless a compute instance meets specific requirements, its host ID is hidden by default. You can expose the host ID when you create or update compute instances. When you view the details of your compute instances, you can see their host IDs specific to your Google Cloud organization. You can't see the IDs of the block, sub-block, or cluster for the compute instances.

To expose or hide the host ID in a compute instance, use one of the following methods:

If you want to prevent host ID exposure for one or more projects in your organization, then you can create a custom constraint. This constraint is useful when, for example, you want to run security-sensitive workloads. For more information, see Custom constraints.

Expose or hide host ID in an existing compute instance

You can expose or hide the host ID in an existing compute instance without a restart. If you disable the setting that exposes the host ID for a compute instance that shows the host ID by default, then one of the following occurs:

  • If the compute instance specifies a compact placement policy or a workload policy, then you see the project-specific host ID and related physical location information.

  • If the compute instance uses an H4D machine type or an A3 High machine type with 8 GPUs (or later generations), then Compute Engine ignores the request.

To expose or hide the host ID of an existing compute instance, select one of the following options:

gcloud

To expose or hide the host ID for an existing compute instance, use the gcloud compute instances update command with one of the following flags:

  • To expose the host ID, include the --expose-host-topology flag:

    gcloud compute instances update INSTANCE_NAME \
    --expose-host-topology \
    --zone=ZONE

  • To hide the host ID, include the --no-expose-host-topology flag:

    gcloud compute instances update INSTANCE_NAME \
    --no-expose-host-topology \
    --zone=ZONE

Replace the following:

  • INSTANCE_NAME: the name of the compute instance.

  • ZONE: the zone where the compute instance exists.

REST

  1. To view the properties for an existing compute instance, make a GET request to the instances.get method:

    GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME

    Replace the following:

    • PROJECT_ID: the ID of the project where you created the compute instance.

    • ZONE: the zone where the compute instance exists.

    • INSTANCE_NAME: the name of the compute instance.

  2. To update a compute instance to expose or hide the host ID, make a PUT request to the instances.update method. In the request body, use the GET request output from the previous step. However, in the scheduling field, you must add the exposeHostTopology field to expose or hide the host ID. If the scheduling field doesn't exist in the request output, then add it as well.

    The PUT request is similar to the following:

    PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME?mostDisruptiveAllowedAction=REFRESH

{
  "scheduling": {
    "exposeHostTopology": EXPOSE_HOST_ID
  },
  ...
}

    Replace EXPOSE_HOST_ID with one of the following values:

    • To expose the host ID: true

    • To hide the host ID: false

Expose host ID in a new compute instance

To expose the host ID while you create a compute instance, select one of the following options:

gcloud

To expose the host ID while you create a compute instance, use the gcloud compute instances create command with the --expose-host-topology flag:

gcloud compute instances create INSTANCE_NAME \
    --machine-type=MACHINE_TYPE \
    --expose-host-topology \
    --zone=ZONE

Replace the following:

  • INSTANCE_NAME: the name of the compute instance.

  • MACHINE_TYPE: the machine type that you want your compute instance to use.

  • ZONE: the zone in which you want to create the compute instance.

REST

To expose the host ID while you create a compute instance, make a POST request to the instances.insert method. In the request body, include the scheduling.exposeHostTopology field set to true.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances

{
  "name": "INSTANCE_NAME",
  "machineType": "zones/ZONE/machineTypes/MACHINE_TYPE",
  "disks": [
    {
      "boot": true,
      "initializeParams": {
        "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"
      }
    }
  ],
  "networkInterfaces": [
    {
      "network": "global/networks/default"
    }
  ],
  "scheduling": {
    "exposeHostTopology": true
  }
}

Replace the following:

  • PROJECT_ID: the ID of the project in which to create the compute instance.

  • ZONE: the zone in which you want to create the compute instance.

  • INSTANCE_NAME: the name for the compute instance.

  • MACHINE_TYPE: the machine type that you want your compute instance to use.

  • IMAGE_PROJECT: the image project that contains the image—for example, debian-cloud. For more information about the supported image projects, see Public OS images.

  • IMAGE: specify one of the following:

    • A specific version of the OS image—for example, debian-12-bookworm-v20240617.

    • An image family, which must be formatted as family/IMAGE_FAMILY. This specifies the most recent, non-deprecated OS image. For example, if you specify family/debian-12, then the latest version in the Debian 12 image family is used. For more information about using image families, see Image families best practices.

Expose host ID in new compute instances in bulk

To expose the host ID when you create compute instances in bulk, select one of the following options:

gcloud

To expose the host ID when you create compute instances in bulk, run the gcloud compute instances create-bulk command with the --expose-host-topology flag.

For example, to create compute instances in bulk in a single zone and specify to expose their host ID, run the following command:

gcloud compute instances create-bulk \
    --count=COUNT \
    --machine-type=MACHINE_TYPE \
    --name-pattern="NAME_PATTERN" \
    --expose-host-topology \
    --zone=ZONE

Replace the following:

  • COUNT: the number of compute instances to create.

  • MACHINE_TYPE: the machine type that you want your compute instances to use.

  • NAME_PATTERN: the name pattern for the compute instances. To replace a sequence of numbers in a compute instance name, use a sequence of hash (#) characters. For example, using instance-# for the name pattern generates compute instances with names starting with instance-1, instance-2, and continuing up to the number of compute instances specified by COUNT.

  • ZONE: the zone in which you want to create compute instances in bulk.

REST

To expose the host ID when you create compute instances in bulk, make a POST request to the instances.bulkInsert method. In the request body, include the instanceProperties.scheduling.exposeHostTopology field set to true.

For example, to create compute instances in bulk in a single zone and specify to expose their host ID, make a POST request as follows:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/bulkInsert

{
  "count": "COUNT",
  "namePattern": "NAME_PATTERN",
  "instanceProperties": {
    "machineType": "MACHINE_TYPE",
    "disks": [
      {
        "boot": true,
        "initializeParams": {
          "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"
        }
      }
    ],
    "networkInterfaces": [
      {
        "network": "global/networks/default"
      }
    ],
    "scheduling": {
      "exposeHostTopology": true
    }
  }
}

Replace the following:

  • PROJECT_ID: the ID of the project in which to create the compute instances.

  • ZONE: the zone in which you want to create the compute instances.

  • COUNT: the number of compute instances to create.

  • NAME_PATTERN: the name pattern for the compute instances. To replace a sequence of numbers in a compute instance name, use a sequence of hash (#) characters. For example, using instance-# for the name pattern generates compute instances with names starting with instance-1, instance-2, and continuing up to the number of compute instances specified by COUNT.

  • MACHINE_TYPE: the machine type that you want your compute instances to use.

  • IMAGE_PROJECT: the image project that contains the image—for example, debian-cloud. For more information about the supported image projects, see Public OS images.

  • IMAGE: specify one of the following:

    • A specific version of the OS image—for example, debian-12-bookworm-v20240617.

    • An image family, which must be formatted as family/IMAGE_FAMILY. This specifies the most recent, non-deprecated OS image. For example, if you specify family/debian-12, then the latest version in the Debian 12 image family is used. For more information about using image families, see Image families best practices.

Expose host ID in a new instance template

After you create an instance template that specifies to expose the host ID, you can use the instance template to do the following:

To expose the host ID while you create an instance template, select one of the following options:

gcloud

To expose the host ID while you create an instance template, use the gcloud compute instance-templates create command with the --expose-host-topology flag.

For example, use the following command to create a regional instance template. If you want to create a global instance template, then use the same command without the --instance-template-region flag.

gcloud compute instance-templates create INSTANCE_TEMPLATE_NAME \
    --expose-host-topology \
    --instance-template-region=REGION \
    --machine-type=MACHINE_TYPE

Replace the following:

  • INSTANCE_TEMPLATE_NAME: the name for the instance template.

  • REGION: the region in which to create the instance template.

  • MACHINE_TYPE: the machine type that you want your compute instances to use.

REST

To expose the host ID while you create an instance template, make a POST request to one of the following methods. In the request body, include the properties.scheduling.exposeHostTopology field set to true.

For example, to create a regional instance template that exposes the host ID, make a POST request as follows:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/instanceTemplates

{
  "name": "INSTANCE_TEMPLATE_NAME",
  "properties": {
    "disks": [
      {
        "boot": true,
        "initializeParams": {
          "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"
        }
      }
    ],
    "machineType": "MACHINE_TYPE",
    "networkInterfaces": [
      {
        "network": "global/networks/default"
      }
    ],
    "scheduling": {
      "exposeHostTopology": true
    }
  }
}

Replace the following:

  • PROJECT_ID: the ID of the project in which to create the instance template.

  • REGION: the region in which you want to create the instance template.

  • INSTANCE_TEMPLATE_NAME: the name of the instance template.

  • IMAGE_PROJECT: the image project that contains the image—for example, debian-cloud. For more information about the supported image projects, see Public OS images.

  • IMAGE: specify one of the following:

    • A specific version of the OS image—for example, debian-12-bookworm-v20240617.

    • An image family, which must be formatted as family/IMAGE_FAMILY. This specifies the most recent, non-deprecated OS image. For example, if you specify family/debian-12, the latest version in the Debian 12 image family is used. For more information about using image families, see Image families best practices.

  • MACHINE_TYPE: the machine type that you want your compute instances to use.

Verify compute instance physical location

You can only view the physical location of your running compute instances if they meet specific requirements or you expose their host IDs.

To verify the physical location of the running compute instances in your organization, use one of the following methods:

Verify physical location by using the Google Cloud console, gcloud CLI, or REST

To view the physical location for multiple compute instances at once, use the REST API. Otherwise, select one of the following options:

Console

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

    Go to VM instances

  2. 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 instance appears and the Details tab is selected.

  3. 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 compute instance name.

  • ZONE: the zone where the compute instance exists.

The output is similar to one of 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:

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

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

    ---
block: null
cluster: null
host: 1215168a4ecdfb434fd4d28056589059
subBlock: null

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 limit the output to the name, machineType, and physicalHostTopology fields of a compute instance. You must also include the filter query parameter and limit the results to 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 one of 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. In the following example, the compute instances vm-01 and vm-02 are located in the same block.

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

  • If you can only view the ID 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": {
          "block": null,
          "cluster": null,
          "host": "1215168a4ecdfb434fd4d28056589059",
          "subBlock": null
        }
      }
    },
    {
      "name": "vm-02",
      "machineType": "https://www.googleapis.com/compute/v1/projects/example-project/zones/europe-west1-b/machineTypes/a3-ultragpu-8g",
      "resourceStatus": {
        "physicalHostTopology": {
          "block": null,
          "cluster": null,
          "host": "2326279b5ecdfc545fd5e39167698168",
          "subBlock": null
        }
      }
    },
    ...
  ]
}

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

Verify physical location 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:

Linux instances

  1. Connect to your Linux instance.

  2. Query the physical_host_topology metadata key by using curl:

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

    The output is similar to one of 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:

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

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

      {
  "block": null,
  "cluster": null,
  "host": "2326279b5ecdfc545fd5e39167698168",
  "subBlock": null
}

Windows instances

  1. Connect to your Windows instance.

  2. Query the physical_host_topology metadata key by using the Invoke-RestMethod 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 one of 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:

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

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

      {
  "block": null,
  "cluster": null,
  "host": "2326279b5ecdfc545fd5e39167698168",
  "subBlock": null
}

What's next