View the topology and health status of All Capacity Mode reservations

You can retrieve topology and health information about your All Capacity Mode capacity using the Google Cloud console or the Google Cloud CLI before or after you provision TPU slices. You can also retrieve the physical location of a TPU VM instance through the Compute Engine Instance API or through a curl command from within the TPU VM's guest OS. Topology and health status information at the cluster, block, sub-block, host, and VM levels let you to make topology-aware placement decisions for your workloads, target specific blocks or sub-blocks for deployment, and understand the relative proximity between TPU VM instances.

View capacity topology in the Google Cloud console

To use the Google Cloud console to view the details of your reservation:

In the Google Cloud console, use the search bar to search for "reservations" and navigate to the reservation page .
Select the On-demand reservationstab and find your TPU All Capacity Mode reservation. Your account team will tell you the name of your reservation.
Select your reservation, a reservation details page is displayed.

For an All Capacity mode reservation, the Operational modeis set to All capacity. A list of blocks is displayed along with a summary of their utilization and health status.

Select a block from the list to see the block detail page. The block's topology is displayed in the Cluster Locationsection. This section displays the cluster name, the hashed ID of a block, and the hashed ID of a sub-block.

Cluster names are globally unique across all Google organizations. In other words, two different customers may see the same cluster name. Unlike cluster names, the hashed ID of blocks or sub-blocks are unique within your Google Cloud organization's projects.

You can select a sub-block to display the Sub-block detail page which only shows you physical hosts with active TPU VM instances. Unused physical hosts are not displayed.

View capacity topology using Google Cloud CLI

You can use the Google Cloud CLI list and describe commands on reservations, blocks, and sub-blocks to find topology and health information about your capacity.

You can use the information displayed by the commands in this section to determine the topology hierarchy of the physical capacity in your reservation.

Describe a reservation

You can use the gcloud compute reservations describe to see an overview of the capacity in your reservation. The following command displays a summary of an reservation called "example-reservation":

 gcloud  
compute  
reservations  
describe  
example-reservation  
 \ 
  
--project = 
example-project  
 \ 
  
--zone = 
us-central1-c

This command displays output similar to the following:

advancedDeploymentControl:  
 reservationOperationalMode:  
ALL_CAPACITY 
aggregateReservation:  
inUseResources:  
-  
accelerator:  
 acceleratorCount:  
 48 
 
  
 acceleratorType:  
projects/example-project/zones/us-central1-c/acceleratorTypes/tpu7x 
  
reservedResources:  
-  
accelerator:  
 acceleratorCount:  
 128 
 
  
acceleratorType:  
projects/example-project/zones/us-central1-c/acceleratorTypes/tpu7x  
vmFamily:  
VM_FAMILY_CLOUD_TPU_POD_SLICE_TPU7X  
workloadType:  
UNSPECIFIED
creationTimestamp:  
 '2025-11-05T14:16:30.571-08:00' 
deleteAtTime:  
 '2026-11-06T08:00:00Z' 
 deploymentType:  
DENSE  
 
enableEmergentMaintenance:  
 false 
id:  
 '8873145979824927313' 
kind:  
compute#reservation
linkedCommitments:
-  
https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1/commitments/example-cud
name:  
example-reservation
protectionTier:  
STANDARD
reservationSharingPolicy:  
 serviceShareType:  
ALLOW_ALL 
resourceStatus:  
 healthInfo:  
degradedBlockCount:  
 0 
  
healthStatus:  
HEALTHY  
healthyBlockCount:  
 1 
  
reservationBlockCount:  
 1 
  
reservationMaintenance:  
schedulingType:  
 
schedulingType:  
GROUPED
selfLink:  
https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-c/reservations/example-reservation
shareSettings:  
projectMap:  
 '111111111111' 
:  
 projectId:  
 '111111111111' 
 
  
shareType:  
SPECIFIC_PROJECTS
specificReservationRequired:  
 true 
status:  
READY
zone:  
https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-c

The following values from the output describe the reservation:

advancedDeploymentControl.reservationOperationalMode - the capacity mode for the reservation
aggregateReservation.inUseResources.accelerator.acceleratorCount - the number of TPU chips in use
aggregateReservation.inUseResources.accelerator.acceleratorType - the TPU version
reservedResources.accelerator.acceleratorCount - the number of TPU chips in the reservation
deploymentType - the deployment type (will always be DENSE for TPUs)
reservationSharingPolicy.serviceShareType - the service share type
resourceStatus.healthInfo.healthStatus - overall health of the capacity
resourceStatus.healthInfo.healthyBlockCount - the number of healthy blocks in the reservation
resourceStatus.reservationBlockCount - the number of blocks in the reservation

List all reservation blocks

You can use the gcloud compute reservations blocks list command to display capacity, topology and health information for all the blocks in a reservation. In the following example, the reservation "example-reservation" has 2 blocks, "example-reservation-block-0001" and "example-reservation-block-0002". Both blocks reside in the cluster "example-cluster".

Each block, sub-block, and Host object is identified by a hash ID. The ID of the parent object is displayed in the physical topology fields of child objects. You can use the hash IDs to construct a topology hierarchy view of the capacity.

 gcloud compute reservations blocks list example-reservation \
  --project=example-project \
  --zone=us-central1-c

The command displays the following output:

 count:  
 32 
 
creationTimestamp:  
 '2025-11-05T15:00:15.223-08:00' 
 healthInfo:  
degradedSubBlockCount:  
 0 
  
healthStatus:  
HEALTHY  
healthySubBlockCount:  
 2 
  
id:  
 '2996501069483632657' 
 
 inUseCount:  
 12 
 
 kind:  
compute#reservationBlock 
 name:  
example-reservation-block-0001 
 physicalTopology:  
block:  
9a0e671424e45fd480ca172ad7a4e25d  
cluster:  
example-cluster 
reservationMaintenance:  
schedulingType:  
GROUPED
reservationSubBlockCount:  
 2 
reservationSubBlockInUseCount:  
 1 
selfLink:  
https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-c/reservations/example-reservation/reservationBlocks/example-reservation-block-0001
selfLinkWithId:  
https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-c/reservations/example-reservation/reservationBlocks/2996501069483632657
status:  
READY
zone:  
https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-c count:  
 128 
 
creationTimestamp:  
 '2025-08-19T18:23:32.825-07:00' 
 healthInfo: 
  
 degradedSubBlockCount:  
 0 
 
  
 healthStatus:  
HEALTHY 
  
 healthySubBlockCount:  
 4 
 
 id:  
 '9a0e671424e45fd480ca172ad7a4e25d' 
 
 inUseCount:  
 64 
 
 kind:  
compute#reservationBlock 
 name:  
example-reservation-block-0002 
 physicalTopology: 
  
 block:  
3feffcdeb6434d68bb818a836f75c1b8 
  
 cluster:  
example-cluster 
reservationMaintenance:  
schedulingType:  
GROUPED
reservationSubBlockCount:  
 2 
reservationSubBlockInUseCount:  
 1 
selfLink:  
https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-c/reservations/example-reservation/reservationBlocks/example-reservation-block-0001
selfLinkWithId:  
https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-c/reservations/example-reservation/reservationBlocks/2996501069483632657
status:  
READY
zone:  
https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-c

The following values from the output describe the blocks in the reservation:

count - the number of physical hosts
healthInfo.healthStatus - the overall health of the block
healthInfo.healthySubblockCount - the number of healthy sub-blocks in the block
id - the block's ID
inUseCount - the number of physical hosts in use
kind - the kind of object described
name - the name of the block
physicalTopology.block - the block ID
physicalTopology.cluster - the cluster where the block is located
reservationSubBlockCount - the number of sub-blocks in this block
reservationSubBlockInUseCount - the number of sub-blocks in use

Describe a reservation block

You can use the gcloud compute reservations blocks describe command on a specific block to display information for the block you specify.

 gcloud compute reservations blocks describe example-reservation \
  --block-name=example-reservation-block-0001 \
  --project=example-project \
  --zone=us-central1-c

This command displays the following output:

resource:  
 count:  
 32 
 
  
creationTimestamp:  
 '2025-11-05T15:00:15.223-08:00' 
  
healthInfo:  
degradedSubBlockCount:  
 0 
  
 healthStatus:  
HEALTHY 
  
 healthySubBlockCount:  
 2 
 
  
 id:  
 '2996501069483632657' 
 
  
 inUseCount:  
 12 
 
  
 kind:  
compute#reservationBlock 
  
 name:  
example-reservation-block-0001 
  
 physicalTopology:  
block:  
9a0e671424e45fd480ca172ad7a4e25d  
cluster:  
example-cluster 
  
reservationMaintenance:  
schedulingType:  
GROUPED  
 reservationSubBlockCount:  
 2 
 
  
 reservationSubBlockInUseCount:  
 1 
 
  
selfLink:  
https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-c/reservations/example-reservation/reservationBlocks/example-reservation-block-0001  
selfLinkWithId:  
https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-c/reservations/example-reservation/reservationBlocks/2996501069483632657  
status:  
READY  
zone:  
https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-c

The following values from the output describe the blocks in the reservation:

count - the number of hosts in the block
healthInfo.healthStatus - the overall health of the block
healthInfo.healthySubblockCount - the number of healthy sub-blocks in the block
id - the block's ID
inUseCount - the number of hosts in use
kind - the kind of object described
name - the name of the block
physicalTopology.block - the block ID
physicalTopology.cluster - the cluster where the block is located
reservationSubBlockCount - the number of sub-blocks in this block
reservationSubBlockInUseCount - the number of sub-blocks in use

List all sub-blocks of a block

You can list the sub-blocks in a block to display information for each sub-block:

 gcloud compute reservations sub-blocks list example-reservation \
  --block-name=example-reservation-block-0001 \
  --project=example-project \
  --zone=us-central1-c

This command displays the following information:

 count:  
 16 
 
creationTimestamp:  
 '2025-11-05T15:00:16.738-08:00' 
healthInfo:  
degradedHostCount:  
 0 
  
 degradedInfraCount:  
 0 
 
  
 healthStatus:  
HEALTHY 
  
 healthyHostCount:  
 16 
 
  
healthyInfraCount:  
 1 
 id:  
 '8309376980435233263' 
 
 inUseCount:  
 0 
 
 kind:  
compute#reservationSubBlock 
 name:  
example-reservation-block-0001-subblock-0001 
 physicalTopology:  
block:  
9a0e671424e45fd480ca172ad7a4e25d  
cluster:  
example-cluster  
subBlock:  
a0122935eb54d02750b65eef2d4f0366 
reservationSubBlockMaintenance:  
schedulingType:  
GROUPED
selfLink:  
https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-c/reservations/example-reservation/reservationBlocks/example-reservation-block-0001/reservationSubBlocks/example-reservation-block-0001-subblock-0001
selfLinkWithId:  
https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-c/reservations/example-reservation/reservationBlocks/example-reservation-block-0001/reservationSubBlocks/8309376980435233263
status:  
READY
zone:  
https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-c
--- count:  
 16 
 
creationTimestamp:  
 '2025-11-05T15:00:16.736-08:00' 
 healthInfo:  
degradedHostCount:  
 0 
  
degradedInfraCount:  
 0 
  
healthStatus:  
HEALTHY  
healthyHostCount:  
 16 
  
healthyInfraCount:  
 1 
 
 id:  
 '5629213080155482607' 
 
 inUseCount:  
 12 
 
 kind:  
compute#reservationSubBlock 
 name:  
example-reservation-block-0001-subblock-0002 
 physicalTopology:  
block:  
9a0e671424e45fd480ca172ad7a4e25d  
cluster:  
example-cluster  
subBlock:  
7aca49831e54d32970631524bc060d9c 
reservationSubBlockMaintenance:  
schedulingType:  
GROUPED
selfLink:  
https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-c/reservations/example-reservation/reservationBlocks/example-reservation-block-0001/reservationSubBlocks/example-reservation-block-0001-subblock-0002
selfLinkWithId:  
https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-c/reservations/example-reservation/reservationBlocks/example-reservation-block-0001/reservationSubBlocks/5629213080155482607
status:  
READY
zone:  
https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-c

The following values from the output describe the sub-blocks in the reservation:

count - the number of hosts
healthInfo.degradedInfraCount - the healthy state of an Ironwood cube's Optical Circuit Switch (OCS). If this value is 1, it indicates the Ironwood cube's OCS has degraded. This value does not apply to Trillium
healthInfo.healthStatus - the overall health of the sub-block
healthInfo.healthyHostCount - the number of healthy hosts in the sub-block
id - the block's ID
inUseCount - the number of hosts in use
kind - the kind of object described
name - the name of the sub-block
physicalTopology.block - the ID of the block that contains this sub-block
physicalTopology.cluster - the cluster where the block is located
physicalTopology.subblock - the sub-block's ID

Describe a reservation sub-block

You can use the gcloud compute sub-blocks describe to see information about a sub-block:

 gcloud  
compute  
reservations  
sub-blocks  
describe  
example-reservation  
 \ 
  
--block-name = 
example-reservation-block-0001  
 \ 
  
--sub-block-name = 
example-reservation-block-0001-subblock-0002  
 \ 
  
--project = 
example-project  
 \ 
  
--zone = 
us-central1-c

This command displays the following information:

resource:  
 count:  
 16 
 
  
creationTimestamp:  
 '2025-11-05T15:00:16.736-08:00' 
  
 healthInfo: 
  
 degradedHostCount:  
 0 
 
  
 degradedInfraCount:  
 0 
 
  
 healthStatus:  
HEALTHY 
  
 healthyHostCount:  
 16 
 
  
 healthyInfraCount:  
 1 
 
  
 id:  
 '5629213080155482607' 
 
  
 inUseCount:  
 12 
 
  
 kind:  
compute#reservationSubBlock 
  
 name:  
example-reservation-block-0001-subblock-0002 
  
 physicalTopology: 
  
 block:  
9a0e671424e45fd480ca172ad7a4e25d 
  
 cluster:  
example-cluster 
  
 subBlock:  
7aca49831e54d32970631524bc060d9c 
  
reservationSubBlockMaintenance:  
schedulingType:  
GROUPED  
selfLink:  
https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-c/reservations/example-reservation/reservationBlocks/example-reservation-block-0001/reservationSubBlocks/example-reservation-block-0001-subblock-0002  
selfLinkWithId:  
https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-c/reservations/example-reservation/reservationBlocks/example-reservation-block-0001/reservationSubBlocks/5629213080155482607  
status:  
READY  
zone:  
https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-c

The following values from the output describe the sub-blocks in the reservation:

count - the number of hosts
healthInfo.degradedInfraCount - the healthy state of an Ironwood cube's Optical Circuit Switch (OCS). If this value is 1, it indicates the Ironwood cube's OCS has degraded. This value does not apply to Trillium
healthInfo.healthStatus - the overall health of the sub-block
healthInfo.healthyHostCount - the number of healthy hosts in the sub-block
id - the block's ID
inUseCount - the number of hosts in use
kind - the kind of object described
name - the name of the sub-block
physicalTopology.block - the ID of the block that contains this sub-block
physicalTopology.cluster - the cluster where the block is located
physicalTopology.subblock - the sub-block's ID

Find the physical location of a TPU VM instance

Once you provision TPU slices, you can retrieve the physical location of your TPU VM instances. This lets you understand the relative distances between TPU VM instances for workload scheduling optimization.

You can find the physical location of a TPU VM instance using curl or the Google Cloud CLI. The following example shows the physical location of the TPU VM instances in the example reservation "example-reservation".

curl

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

gcloud

 gcloud compute instances describe vm-1 \
--format="table[box,title=VM-Position](resourceStatus.physical_host_topology:label=location)" \
  --zone=ZONE

Both of these commands display information about the cluster, block, sub-block, and host of the TPU VM you specify:

 block:  
3feffcdeb6434d68bb818a836f75c1b8
cluster:  
southamerica-west1-cluster-njga
subblock:  
cbee689cb721abdb0c7f80a4f2d0c1c7
host:  
36b2d9731c1e1cf8594a759c8c4178f0