Update Deployment Target
const url = 'https://example.com/topology/v1/targets/example';const options = { method: 'PATCH', headers: {'Content-Type': 'application/json'}, body: '{"resource_pool_id":"example","name":"example","hostname":"example","os":{"family":"example","manufacturer":"example","version":"example","bitness":"OS_BITNESS_UNSPECIFIED"},"cpu_topology":{"byte_order":"BYTE_ORDER_UNSPECIFIED","vendor_id":"example","model_name":"example","model":1,"cpu_family_id":1,"stepping":1,"min_frequency_hz":"example","max_frequency_hz":"example","online_cpus":1,"threads_per_core":1,"cores_per_socket":1,"sockets":1,"architecture":"CPU_ARCHITECTURE_UNSPECIFIED","caches":[{"level":1,"size_bytes":"example"}],"numa":{"nodes":[{"id":1,"cpus":[1]}]}},"gpu_topology":[{"name":"example","device_id":"example","vendor":"example","base_clock_hz":"example","boost_clock_hz":"example","tflops":"example","vram":{"size_bytes":"example","type":"VRAM_TYPE_UNSPECIFIED","memory_bus_bits":"example"},"cores":1,"ai_features":{"tensor_cores":1,"rt_cores":1,"has_dlss_support":true,"has_fp16_support":true,"has_fp64_support":true},"memory_bandwidth_bps":"example"}],"memory_topology":{"available_memory_bytes":"example","free_memory_bytes":"example","total_memory_bytes":"example","type":"MEMORY_TYPE_UNSPECIFIED","ddr_generation":1},"disks":[{"name":"example","serial":"example","size_bytes":"example","free_space_bytes":"example","model":"example","type":"DISK_TYPE_UNSPECIFIED","throughput":{"read_speed_bps":"example","write_speed_bps":"example"},"iops":{"ips":{"value":1,"unit":"TOPOLOGY_DURATION_UNIT_UNSPECIFIED"},"ops":{"value":1,"unit":"TOPOLOGY_DURATION_UNIT_UNSPECIFIED"}}}],"network_info":{"host_name":"example","domain_name":"example","dns_servers":["example"],"mac_address":"example","interfaces":[{"ip_addresses":["example"],"type":1,"status":"NETWORK_STATUS_UNSPECIFIED","mtu":"example","name":"example","display_name":"example","bandwidth":{"download_speed_bps":"example","upload_speed_bps":"example","peak_download_speed_bps":"example","peak_upload_speed_bps":"example"}}],"ip_gateways":["example"]},"tags":[{"id":"example","key":"example","value":"example","type":"TOPOLOGY_TAG_TYPE_UNSPECIFIED","description":"example"}]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PATCH \ --url https://example.com/topology/v1/targets/example \ --header 'Content-Type: application/json' \ --data '{ "resource_pool_id": "example", "name": "example", "hostname": "example", "os": { "family": "example", "manufacturer": "example", "version": "example", "bitness": "OS_BITNESS_UNSPECIFIED" }, "cpu_topology": { "byte_order": "BYTE_ORDER_UNSPECIFIED", "vendor_id": "example", "model_name": "example", "model": 1, "cpu_family_id": 1, "stepping": 1, "min_frequency_hz": "example", "max_frequency_hz": "example", "online_cpus": 1, "threads_per_core": 1, "cores_per_socket": 1, "sockets": 1, "architecture": "CPU_ARCHITECTURE_UNSPECIFIED", "caches": [ { "level": 1, "size_bytes": "example" } ], "numa": { "nodes": [ { "id": 1, "cpus": [ 1 ] } ] } }, "gpu_topology": [ { "name": "example", "device_id": "example", "vendor": "example", "base_clock_hz": "example", "boost_clock_hz": "example", "tflops": "example", "vram": { "size_bytes": "example", "type": "VRAM_TYPE_UNSPECIFIED", "memory_bus_bits": "example" }, "cores": 1, "ai_features": { "tensor_cores": 1, "rt_cores": 1, "has_dlss_support": true, "has_fp16_support": true, "has_fp64_support": true }, "memory_bandwidth_bps": "example" } ], "memory_topology": { "available_memory_bytes": "example", "free_memory_bytes": "example", "total_memory_bytes": "example", "type": "MEMORY_TYPE_UNSPECIFIED", "ddr_generation": 1 }, "disks": [ { "name": "example", "serial": "example", "size_bytes": "example", "free_space_bytes": "example", "model": "example", "type": "DISK_TYPE_UNSPECIFIED", "throughput": { "read_speed_bps": "example", "write_speed_bps": "example" }, "iops": { "ips": { "value": 1, "unit": "TOPOLOGY_DURATION_UNIT_UNSPECIFIED" }, "ops": { "value": 1, "unit": "TOPOLOGY_DURATION_UNIT_UNSPECIFIED" } } } ], "network_info": { "host_name": "example", "domain_name": "example", "dns_servers": [ "example" ], "mac_address": "example", "interfaces": [ { "ip_addresses": [ "example" ], "type": 1, "status": "NETWORK_STATUS_UNSPECIFIED", "mtu": "example", "name": "example", "display_name": "example", "bandwidth": { "download_speed_bps": "example", "upload_speed_bps": "example", "peak_download_speed_bps": "example", "peak_upload_speed_bps": "example" } } ], "ip_gateways": [ "example" ] }, "tags": [ { "id": "example", "key": "example", "value": "example", "type": "TOPOLOGY_TAG_TYPE_UNSPECIFIED", "description": "example" } ] }'Updates an existing deployment target
Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The unique identifier of the deployment target to update
Query Parameters
Section titled “Query Parameters ”The set of fields to update. If omitted, all mutable fields are overwritten. See AIP-134 for field mask semantics.
Request Body required
Section titled “Request Body required ”object
The unique identifier of the deployment target
The unique identifier of the parent resource pool (optional: a deployment target can exist without belonging to a resource pool)
The handle of the deployment target, e.g. “node-01”. Lowercase letters, digits and hyphens; letter-initial; not itself an id.
The hostname of the physical host (RFC 1123 FQDN, max 253)
The operating system running on the host
object
The OS family (e.g., “Linux”, “Windows”)
The OS manufacturer (e.g., “Canonical”, “Microsoft”)
The OS version (e.g., “22.04”, “11”)
The bitness of the operating system
The CPU topology of the host
object
The byte order of the CPU
The CPU vendor identifier (e.g., “GenuineIntel”, “AuthenticAMD”)
The CPU model name (e.g., “Intel(R) Xeon(R) Gold 6248R”)
The CPU model number
The CPU family identifier
The CPU stepping (revision within a model)
The minimum clock frequency of the CPU Minimum core frequency, in hertz.
The maximum clock frequency of the CPU Maximum core frequency, in hertz.
The number of online (available) CPUs. In hybrid architectures this number won’t necessarily match the formula: threads_per_core x cores_per_socket x sockets
The number of threads per physical core
The number of physical cores per socket
The number of CPU sockets
The CPU architecture
The CPU caches (L1, L2, L3, etc.)
CPU Cache
Represents a single level of CPU cache (L1, L2, L3, etc.).
object
The cache level (1, 2, 3, etc.)
Cache size.
The NUMA topology of the CPU
object
The list of NUMA nodes
NUMA Node
Represents a single NUMA node with its associated CPUs.
object
The NUMA node identifier
The list of CPU identifiers belonging to this NUMA node
The GPU topology of the host (may have zero or more GPUs)
GPU Topology
Describes a GPU installed on the physical host, including clock speeds, VRAM, core count, and AI-specific features.
object
The GPU name (e.g., “NVIDIA A100”, “AMD Instinct MI300X”)
The GPU device identifier
The GPU vendor (e.g., “NVIDIA”, “AMD”, “Intel”)
The base clock speed of the GPU Base clock, in hertz.
The boost clock speed of the GPU Boost clock, in hertz.
The theoretical peak performance in TFLOPS
The GPU video RAM
object
The total VRAM size
The type of VRAM
The memory bus width Memory bus WIDTH, in bits — a bus width is not a quantity of data.
The number of GPU cores (CUDA cores, stream processors, etc.)
AI-specific features of the GPU
object
The number of tensor cores (NVIDIA) or equivalent
The number of ray tracing cores
Whether DLSS (Deep Learning Super Sampling) is supported
Whether FP16 (half-precision) is supported
Whether FP64 (double-precision) is supported
The memory bandwidth of the GPU Memory bandwidth, in bits per second.
The memory topology of the host
object
The available memory (usable without swapping)
The free memory (unused by the OS)
The total physical memory installed
The type of physical memory
The DDR generation (e.g., 4 for DDR4, 5 for DDR5). Only applicable when type is DDR.
The disk nodes attached to the deployment target
Disk Node
Describes a physical disk attached to the deployment target.
object
The disk device name (e.g., “/dev/sda”, “/dev/nvme0n1”)
The disk serial number
The total disk size
The free space available on the disk
The disk model name
The type of physical disk
The disk throughput (read/write speeds)
object
The sequential read speed Sequential read speed, in bits per second.
The sequential write speed Sequential write speed, in bits per second.
The disk IOPS (input/output operations per second)
object
Input operations per time unit (read IOPS)
object
The numerical value of operations
The time unit denominator
Output operations per time unit (write IOPS)
object
The numerical value of operations
The time unit denominator
The network information of the host
object
The hostname of the host
The domain name of the host
The DNS servers configured on the host
The primary MAC address of the host
The network interfaces available on the host
Network Interface
Describes a network interface on the physical host.
object
The IP addresses assigned to this interface
The interface type identifier
The operational status of the interface
The Maximum Transmission Unit (MTU) in bytes
The interface name (e.g., “eth0”, “ens3”)
The display name of the interface
The bandwidth of the interface
object
The current download speed Negotiated download speed, in bits per second.
The current upload speed Negotiated upload speed, in bits per second.
The peak download speed observed Peak download speed, in bits per second.
The peak upload speed observed Peak upload speed, in bits per second.
The IP gateways configured on the host
Tags associated with this deployment target for labeling and categorization
Topology Tag
A key-value pair used to label and categorize topology resources such as regions, zones, resource pools, and deployment targets.
object
The unique identifier of the tag
The key of the tag
The value of the tag
The type of the tag (system or user-defined)
An optional description for the tag
The timestamp when the deployment target was registered
The timestamp when the deployment target was last updated
Node Name
The Kubernetes Node name this deployment target projects (node.metadata.name).
Mutable on K8s rename. Used for human-friendly identification and filtering, NOT for
correlation; use node_uid for that.
Node Uid
The Kubernetes Node uid (node.metadata.uid): durable correlation key (AD-003
§Correlation). Immutable; a deleted-and-recreated Node yields a new uid, which
produces a new DeploymentTarget row rather than resurrecting the old one.
Status
Domain status of the deployment target: one of ready, not_ready,
maintenance, deleted. deleted is the terminal soft-delete state;
findAll listings exclude it by default. maintenance is preferred over
the K8s-specific “cordoned”; see AD-003 §Vocabulary.
Labels
The full Kubernetes Node label map. Powers ResourcePool selector matching.
object
Last Observed At
Last successful reconciler observation: freshness proof for the 5-second SLA.
Zone Id
The zone this deployment target belongs to (FK to topology.zones(id), denormalised onto the row so AIP-160 filters can scope by zone without a JOIN). Populated by the K8s reconciler from the standard topology.kubernetes.io/zone label; empty when the label is absent. Used by compute’s scheduler feasibility check.
Responses
Section titled “ Responses ”OK
Topology Operation
An acknowledgment of a mutation request, carrying tracking metadata, errors, and warnings. Follows GCP’s Operations pattern (AIP-151).
object
Operation ID
Unique identifier for this operation.
Resource ID
The ID of the resource affected by this operation. May be empty for async operations where the resource does not yet exist.
Resource Type
The type of resource (e.g., “com.qibdo.cloud.topology:zone”).
Operation Type
The kind of mutation that was requested.
Status
Current lifecycle state of the operation.
Insert Time
When the operation was first created.
Start Time
When the operation started executing.
End Time
When the operation completed (either successfully or with errors).
Errors
Business rule errors encountered during the operation.
Operation Error
A structured error returned inside an operation when a business rule fails.
object
Error Code
Numeric identifier following the S_SSS_EEE convention.
Description
Human-readable explanation of the error.
Reason
Machine-readable error identifier in UPPER_SNAKE form — the same dispatch
key google.rpc.ErrorInfo.reason carries on the synchronous error plane.
Warnings
Non-fatal notices about the operation.
Operation Warning
A non-fatal notice attached to an operation.
object
Warning Code
Numeric identifier following the S_SSS_EEE convention.
Description
Human-readable explanation of the warning.
Progress
Percentage of completion (0-100).
Scope Type
The category of scope the operation ran in or was triggered from. TOPOLOGY_SCOPE_TYPE_UNSPECIFIED when the operation is not scoped.
Scope ID
The resource this operation was scoped to — for example, when scope_type is TOPOLOGY_SCOPE_TYPE_WORKSPACE this is the workspace id. Empty for TOPOLOGY_SCOPE_TYPE_PLATFORM, which has no scoped resource, and when unscoped.
Principal ID
Who performed or triggered the operation, whether a person or a machine account. Always populated: platform-driven work records the reserved system principal, so every audit record names an actor.
Trace ID
W3C trace id, for correlating this operation with the traces and log lines of the request that caused it. Empty when the operation ran with no trace context — a scheduled or event-driven action rather than a request.
Example
{ "operation_type": "TOPOLOGY_OPERATION_TYPE_UNSPECIFIED", "status": "TOPOLOGY_OPERATION_STATUS_UNSPECIFIED", "scope_type": "TOPOLOGY_SCOPE_TYPE_UNSPECIFIED"}default
Section titled “default ”Default error response
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
object
The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
A list of messages that carry the error details. There is a common set of message types for APIs to use.
Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.
object
The type of the serialized message.
Example generated
{ "code": 1, "message": "example", "details": [ { "@type": "example" } ]}