The topology hierarchy

Topology describes where resources can be placed in two complementary ways. A location names a place in provider-agnostic terms; the inventory hierarchy is the physical structure underneath it. Most callers work with locations, while operators and the platform’s own discovery keep the inventory current.

Locations and their kinds

A location is the single reference the rest of the platform uses to say where a resource lives. Every location is one of four kinds, from broadest to most specific:

• Global: one always-available location meaning “no particular place.” It is the default when a resource does not name one, and it is always usable.
• Region: a geographic area, each backed by a physical cluster. Regions are discovered from the fleet, never created by hand.
• Multi-region: an administrator-defined grouping of regions, for resources meant to span more than one. A region belongs to at most one multi-region, and a multi-region with no regions yet is allowed.
• Zone: a failure domain within a region, the concrete place a workload lands. Zones in a region are expected to fail independently, which is why resilient placement spreads across them.

Reading a location tells you its kind and its usability in one step, without having to know which underlying resource backs it.

The inventory hierarchy

Underneath the locations sits the physical inventory: a set of nested containers, each one a subset of the one above it.

flowchart TB
  classDef mrC fill:#ececf1,stroke:#302e45,color:#0e0d1a
  classDef rgC fill:#e8e8ff,stroke:#1100ff,color:#0e0d1a
  classDef znC fill:#e2faec,stroke:#00e64d,color:#0e0d1a
  classDef rpC fill:#f3ecfb,stroke:#9333ea,color:#0e0d1a
  classDef dtC fill:#ffffff,stroke:#0e0d1a,color:#0e0d1a

  subgraph mr["Multi-region"]
    subgraph rgA["Region A (cluster A)"]
      subgraph znA1["Zone A1"]
        subgraph rpA1["Resource pool"]
          dtA1["Host"]
        end
        subgraph rpA2["Resource pool"]
          dtA2["Host"]
        end
      end
      subgraph znA2["Zone A2"]
        subgraph rpA3["Resource pool"]
          dtA3["Host"]
        end
      end
    end
    subgraph rgB["Region B (cluster B)"]
      subgraph znB1["Zone B1"]
        subgraph rpB1["Resource pool"]
          dtB1["Host"]
        end
      end
    end
  end

  class mr mrC
  class rgA,rgB rgC
  class znA1,znA2,znB1 znC
  class rpA1,rpA2,rpA3,rpB1 rpC
  class dtA1,dtA2,dtA3,dtB1 dtC

• A multi-region groups regions. It is optional: a region need not belong to one.
• A region is backed by a physical cluster and groups zones.
• A zone groups resource pools.
• A resource pool groups deployment targets for scheduling. Membership is by labels, not a hand-kept list: a host belongs to a pool when its labels match the pool’s selector, so membership follows the labels rather than an enrolment step.
• A deployment target is one physical host, described by its CPU, memory, GPU, disks, network, and operating system. It may belong to a resource pool, and its zone follows from where the host sits rather than from a value you set.

Status and the approval lifecycle

Every location other than global carries a status that gates whether it can be used:

• Pending approval: discovered or created, waiting for an administrator.
• Active: approved and usable. Only active locations accept new placements.
• Disabled: taken out of service; an administrator can re-enable it.

Regions arrive already discovered and wait for approval; zones and multi-regions are created by an administrator and start pending as well. Once a zone is enabled its shape is fixed, so it does not drift after workloads rely on it. Placing a resource onto anything that is not active is refused, and when a region is chosen the platform narrows it to one of that region’s active zones.

Identity and freshness of hosts

Deployment targets are projected from the underlying fleet, so each host has two names with different guarantees. A durable identifier stays stable for the life of the host and is what you use to correlate a target over time; a friendly name is for display and filtering and can change. Each target also reports a health status and the time it was last observed, which is your freshness proof for the data on it.