v1/topology.proto#
Topology defines the entities in a data center (PDUs, PSUs, nodes, etc.) and how they are connected.
A topology can be created in one of two ways:
(Preferred method) Import a topology JSON file. This process creates the data center and the entities in the data center.
Create a data center, and a topology. Then use the functions of the topology service to add entities and entity relationships.
A newly created topology is not active. You have to explicitly “activate” it using the topology service. Activation validates the topology connectivity and policies before activating the topology and applying policies.
Topology entities (Entity, TopologyEntity) are defined in this file.
Policy definitions are in policy.proto
Power policies associated with topology entities can be overridden by resource groups, defined in resourcegroup.proto
Services#
TopologyManagementService#
TopologyManagementService manages the entities and topologies in a data center.
ValidateTopology#
rpc ValidateTopology(ValidateTopologyRequest) returns ValidateTopologyResponse
Validates a topology
The purpose of this API is to aid the topology editing process. It is designed to provide user-friendly feedback without altering the database.
The topology is uploaded as a stream of ValidateTopologyRequest objects. Once all the entities and topology entities are uploaded, the client closes the stream to start validation. The validation takes into account existing entities and combines them with the provided entities. It returns a detailed validation report if it encounters any errors.
This call does not modify any existing entities or topologies in the database.
CreateEntities#
rpc CreateEntities(Entity) returns .google.protobuf.Empty
Creates new datacenter entities. These entities are not part of any topology. The provided entities must be all new entities.
UpsertEntities#
rpc UpsertEntities(Entity) returns .google.protobuf.Empty
Retained for API compatibility. Entity upsert is not supported; the server returns UNIMPLEMENTED without modifying entity or topology state.
GetEntities#
rpc GetEntities(GetEntitiesRequest) returns Entity
Returns all entities or selected entities
DeleteEntities#
rpc DeleteEntities(DeleteEntitiesRequest) returns DeleteEntitiesResponse
Deletes given entities. The call will either fail without any change, or will successfully delete all given entities. If an entity is part of a topology, deletion will fail.
CreateUpdateTopology#
rpc CreateUpdateTopology(CreateUpdateTopologyRequest) returns CreateUpdateTopologyResponse
Creates or updates a topology.
A topology describes a particular power connection layout using the existing entities in a datacenter. A topology may define entity specific default policies and/or entity properties.
Before creating a topology, all the entities and power policies referred in that policy must be created.
When the topology is created, it is inactive. Activating a topology will activate default policies on topology entities and provide power allocation services using the constraints and connections defined in the topology.
The topology is uploaded as a stream of CreateUpdateTopologyRequest objects. The first object in the stream must specify whether this is a create or update operation, and provide the necessary flags for the chosen operation. Each element of the stream provides zero or more topology entities. These entities must refer to already existing datacenter entities.
After all the topology is uploaded, the client closes the stream to start topology validation and actual database modifications. Any failure at this stage will be returned in the response.
TopologyDelete#
rpc TopologyDelete(TopologyDeleteRequest) returns TopologyDeleteResponse
Deletes an inactive topology
GetTopologyModel#
rpc GetTopologyModel(GetTopologyModelRequest) returns GetTopologyModelResponse
GetTopologyModel streams the entities and relationships in a topology
ActivateTopology#
rpc ActivateTopology(ActivateTopologyRequest) returns ActivateTopologyResponse
Activate a given topology.
This call first validates topology connectivity. It then validates the power policies, and then applies those power policies to the topology entities and marks the topology as active.
If another topology is already active, this call can be used to switch to a new topology. This can be useful when sections of the datacenter are enabled/disabled.
DeactivateTopology#
rpc DeactivateTopology(DeactivateTopologyRequest) returns DeactivateTopologyResponse
Deactivate a given topology
Deactivating an active topology will remove existing power policies.
ListTopologies#
rpc ListTopologies(TopologyListRequest) returns TopologyListResponse
List existing topologies
NodeConnectionCheck#
rpc NodeConnectionCheck(TopologyNodeConnectionCheckRequest) returns TopologyNodeConnectionCheckResponse
Perform a node connection check
Performing a node connection check verifies that a connection can be established between DPS and the topology-specified nodes for policy configuration.
UpsertDevices#
rpc UpsertDevices(Devices) returns .google.protobuf.Empty
Insert or update a device definitions in the db.
Each datacenter entity refers to a device definition that specifies the power characteristics of that device.
ListDevices#
rpc ListDevices(.google.protobuf.Empty) returns Device
List all known devices in the database
GetNodesStatus#
rpc GetNodesStatus(GetNodesStatusRequest) returns GetNodesStatusResponse
Get last known status on specified nodes
ValidateAllocation#
rpc ValidateAllocation(ValidateAllocationRequest) returns ValidateAllocationResponse
Validate allocation (dry-run allocation feasibility analysis without persisting state)
Validates whether devices can be allocated without creating a resource group or modifying hardware. Returns power impact analysis, policy selection prediction, and per-device allocation results. Streams response: first message contains overall validation result, subsequent messages contain per-device details. Use this for pre-flight checks and “what-if” allocation feasibility analysis before resource group activation.
GenerateEntities#
rpc GenerateEntities(GenerateEntitiesRequest) returns GenerateEntitiesResponse
GenerateEntities validates auth and config and asynchronously queries the BCM or Nautobot for datacenter entities. Returns a request_id for streaming results.
GetGenerateEntitiesStatus#
rpc GetGenerateEntitiesStatus(GetGenerateEntitiesStatusRequest) returns Entity
GetGenerateEntitiesStatus streams the generated entities for the given request_id. Use the request_id returned by GenerateEntities. Streams Entity messages, not status.
CancelGenerateEntitiesRequest#
rpc CancelGenerateEntitiesRequest(CancelGenerateEntitiesRequestRequest) returns CancelGenerateEntitiesRequestResponse
CancelGenerateEntitiesRequest cancels an async generate entities request.
DeleteGenerateEntitiesRequest#
rpc DeleteGenerateEntitiesRequest(DeleteGenerateEntitiesRequestRequest) returns DeleteGenerateEntitiesRequestResponse
DeleteGenerateEntitiesRequest deletes a generate entities request and any stored results.
Messages#
ActivateTopologyRequest#
ActivateTopologyRequest is used by TopologyManagementService.ActivateTopology.
Activating an inactive topology involves validating connectivity and policy consistency. After topology is validated, the power policies for those entities that have a default power policy assigned will be activated. If an entity does not have a default power policy assigned, then the entity will be capped at its idle power policy if one exists. Otherwise, the entity will be “ping”ed if ping_hosts is set, and the result of the ping will be included in the return status. If ping_hosts is not set, entities with no power policies will not be pinged and they may be inaccessible when the topology starts.
If all hosts are to be pinged, it is also possible to specify a failure tolerance for activation by setting atleast_frac_hosts, which defaults to 0.5. That means, if half of the entities are accessible (either via a ping or by setting entity default policy), then topology activation is deemed successful.
If there is already an active topology when another topology is activated, the second activation request fails. Topology switching is currently disabled; deactivate the active topology before activating another.
Field |
Type |
Description |
|---|---|---|
topology_name |
|
Name of topology to activate. Must not be empty. |
switch_if_active |
|
Retained for API compatibility. Topology switching is currently disabled, so setting this field while another topology is active returns InvalidOperation. Deactivate first. |
ping_hosts |
|
Ping all hosts |
atleast_frac_hosts |
|
At least this fraction of hosts must be accessible to activate the topology. Must be finite and between 0 and 1, inclusive. |
ActivateTopologyResponse#
ActivateTopologyResponse will be returned if topology activation was successful
Field |
Type |
Description |
|---|---|---|
node_statuses |
map |
Status a map where key is entity name and value is a struct with activation status and actual policy |
status |
|
Operation status |
ActivateTopologyResponse.NodeStatusesEntry#
Field |
Type |
Description |
|---|---|---|
key |
|
none |
value |
|
none |
CancelGenerateEntitiesRequestRequest#
CancelGenerateEntitiesRequestRequest is used by TopologyManagementService.CancelGenerateEntitiesRequest. It contains the request id returned by GenerateEntities.
Field |
Type |
Description |
|---|---|---|
request_id |
|
none |
CancelGenerateEntitiesRequestResponse#
CancelGenerateEntitiesRequestResponse contains the cancellation status.
Field |
Type |
Description |
|---|---|---|
status |
|
none |
CreateUpdateTopologyRequest#
CreateUpdateTopologyRequest is used to stream the elements of a topology to the server. The same stream element is used for both creation of a new topology, or update of an existing one. Updating an existing topology requires sending the complete topology (i.e. it is not an incremental update).
The first message in the stream specifies whether it is for creating a new topology, or updating it using the Operation field. The subsequent messages should omit this field. The topology name and topology properties must be given in the first message.
A topology update operation implements an optimistic locking scheme to prevent unintended overwrites. The GetTopologyModel API returns a topology hash computed by alphabetically sorting JSON serialization of the topology. The CreateUpdateTopologyRequest must include this hash, meaning that this update request is for the update of the topology with that hash, and if the topology stored in the database has a different hash (that is, if the topology in the database was modified after GetTopologyModel was called), then the update is rejected. It is expected that the client will refetch the topology and reapply the changes. Setting the force_update field disables this behavior and overwrites the topology without first checking for modifications.
Each entity and policy referenced in CreateUpdateTopologyRequest.entities must already be defined in the database.
The actual topology validation and creation/update happens after the client sends all topology entities and closes the stream.
Field |
Type |
Description |
|---|---|---|
oneof Operation.create_topology |
|
Create a new topology |
oneof Operation.update_topology |
|
Update an existing topology |
entities |
repeated |
Zero or more topology entities. |
CreateUpdateTopologyRequest.CreateRequest#
CreateRequest describes the topology to create.
The created topology will be inactive.
Field |
Type |
Description |
|---|---|---|
topology_name |
|
Name of topology to create. The topology name must be unique. Must not be empty. |
properties |
|
Optional topology properties. |
policy_bundle |
|
Policy bundle configured for the complete topology. Empty inherits global_policy_bundle; if that global setting is empty, no bundle is configured. |
CreateUpdateTopologyRequest.UpdateRequest#
UpdateRequest describes the topology to update.
Field |
Type |
Description |
|---|---|---|
topology_name |
|
Name of the existing topology to update. Must not be empty. |
new_topology_name |
|
If topology is to be renamed, the new name of the topology. If the topology name is not to be changed, this field should be left empty. |
topology_hash |
|
The hash of the topology to update. The update will fail if the topology hash doesn’t match what’s in the db. The hash is the SHA256 hash of the unindented topology JSON constructed by recursively ordering JSON objects within the topology model. |
properties |
|
Topology properties |
force_update |
|
Force update. Update the topology even if the topology was modified by someone else |
oneof _policy_bundle.policy_bundle |
optional |
Optional policy bundle update for the complete topology. Omitted preserves the current bundle configuration; an explicitly empty value inherits global_policy_bundle, or resolves to no bundle when that global setting is empty. |
CreateUpdateTopologyResponse#
CreateUpdateTopologyResponse will be returned if adding relations to the topology was successful
Field |
Type |
Description |
|---|---|---|
status |
|
none |
DeactivateTopologyRequest#
DeactivateTopologyRequest is used by TopologyManagementService.DeactivateTopology.
Deactivating the topology removes the policies applied to the policy entities and marks the topology as inactive. All power caps will be removed.
Field |
Type |
Description |
|---|---|---|
topology_name |
|
Name of topology to deactivate. Must not be empty. |
DeactivateTopologyResponse#
DeactivateTopologyResponse will be returned if topology deactivation was successful
Field |
Type |
Description |
|---|---|---|
status |
|
Operation status |
DeleteEntitiesRequest#
DeleteEntitiesRequest contains a list of entities to delete
Field |
Type |
Description |
|---|---|---|
entities |
repeated |
The list of entities to delete. Must contain at least one item, and each entry must not be empty. If there are any references to the entity from any topology, the deletion will fail. |
DeleteEntitiesResponse#
DeleteEntitiesResponse contains the status of the delete operation
Field |
Type |
Description |
|---|---|---|
status |
|
Status of the operation |
entity_topologies |
map |
If entities cannot be deleted because they are used in topologies, map of entity -> []topology |
DeleteEntitiesResponse.EntityTopologiesEntry#
Field |
Type |
Description |
|---|---|---|
key |
|
none |
value |
|
none |
DeleteEntitiesResponse.Topologies#
Field |
Type |
Description |
|---|---|---|
topologies |
repeated |
none |
DeleteGenerateEntitiesRequestRequest#
DeleteGenerateEntitiesRequestRequest is used by TopologyManagementService.DeleteGenerateEntitiesRequest. It contains the request id returned by GenerateEntities.
Field |
Type |
Description |
|---|---|---|
request_id |
|
none |
DeleteGenerateEntitiesRequestResponse#
DeleteGenerateEntitiesRequestResponse contains the delete status.
Field |
Type |
Description |
|---|---|---|
status |
|
none |
Entity#
Entity represents a topology entity matching the Entity JSON schema specification.
Field |
Type |
Description |
|---|---|---|
entity |
|
none |
GenerateEntitiesFromBCMRequest#
GenerateEntitiesFromBCMRequest contains connection parameters for querying BCM to retrieve datacenter entities. Used as the source in GenerateEntitiesRequest. Results are streamed via GetGenerateEntitiesStatus using the request_id from GenerateEntitiesResponse.
Field |
Type |
Description |
|---|---|---|
username |
|
Username for BCM authentication. Must not be empty. |
password |
|
Password for BCM authentication |
GenerateEntitiesFromNautobotRequest#
GenerateEntitiesFromNautobotRequest is used by GenerateEntitiesRequest. It contains filters to query and generate specific entities from Nautobot. Note: Nautobot generation is reserved and may be unimplemented on the server.
Field |
Type |
Description |
|---|---|---|
locations |
repeated |
none |
racks |
repeated |
none |
device_types |
repeated |
none |
oneof _request_string.request_string |
optional |
Optional free-form query string passed to the Nautobot API for additional filtering. |
GenerateEntitiesRequest#
GenerateEntitiesRequest is used by TopologyManagementService.GenerateEntities. It contains either Nautobot or BCM request messages to use as a source to query and generate entities from either.
Field |
Type |
Description |
|---|---|---|
oneof source.bcm |
|
none |
oneof source.nautobot |
|
none |
timeout |
|
Optional timeout for the generation operation. If unset or zero, the server uses its default (10 minutes). Clamped to a server-defined maximum (30 minutes). |
GenerateEntitiesResponse#
GenerateEntitiesResponse is used by TopologyManagementService.GenerateEntities. It contains the validation status and a request id for async retrieval.
Field |
Type |
Description |
|---|---|---|
status |
|
The validation status. The status will be ok only if there are no validation errors |
request_id |
|
The actual import will be async and need to return an id for which the response can be checked |
GetEntitiesRequest#
GetEntitiesRequest specifies the entities to fetch
Field |
Type |
Description |
|---|---|---|
names |
repeated |
If nonempty, entities matching these names will be returned. If empty, all entities will be returned. Each name must not be empty. |
GetGenerateEntitiesStatusRequest#
GetGenerateEntitiesStatusRequest is used by TopologyManagementService.GetGenerateEntitiesStatus. It contains the request id returned by GenerateEntities.
Field |
Type |
Description |
|---|---|---|
request_id |
|
Request id returned by GenerateEntities. Must not be empty. |
GetNodesStatusRequest#
GetNodesStatusRequest contains a list of nodes to retrieve status
Field |
Type |
Description |
|---|---|---|
nodes |
repeated |
List of nodes to query. Each node name must not be empty. |
GetNodesStatusResponse#
GetNodesStatusResponse contains the last known node status
Field |
Type |
Description |
|---|---|---|
node_statuses |
map |
Map of node statuses by entity name |
GetNodesStatusResponse.NodeState#
Contains node state
Field |
Type |
Description |
|---|---|---|
resource_group |
|
Resource group name |
allocated_policy_name |
|
Allocated policy name |
GetNodesStatusResponse.NodeStatus#
node status contains the latest node status
Field |
Type |
Description |
|---|---|---|
inaccessible_since |
|
Inaccessible since timestamp |
last_successful_access_time |
|
Last successful access timestamp |
last_access_error |
|
Last error message |
current_state |
|
Node state |
last_policy_error |
|
Last policy error (e.g., idle policy application failure) |
cleanup_warnings |
repeated |
Best-effort cleanup warnings recorded during topology/entity changes |
GetNodesStatusResponse.NodeStatusesEntry#
Field |
Type |
Description |
|---|---|---|
key |
|
none |
value |
|
none |
GetTopologyModelRequest#
GetTopologyModelRequest specifies the topology name whose model will be returned
Field |
Type |
Description |
|---|---|---|
topology_name |
|
Name of the topology model to retrieve. Must not be empty. |
GetTopologyModelResponse#
GetTopologyModelResponse is a stream element containing topology entities and relations. The first message in the stream will contain the header field giving topology hash and topology properties. The topology hash is a hash computed from the alphabetically sorted JSON representation of the topology, and should be used when updating the returned topology to prevent unintentional overwrites.
Field |
Type |
Description |
|---|---|---|
header |
|
The header is sent once as the first message in the stream. The header should be ignored in subsequent messages. |
entities |
repeated |
One or more topology connections |
GetTopologyModelResponse.Header#
Field |
Type |
Description |
|---|---|---|
topology_name |
|
Name of the topology |
properties |
|
Topology properties |
topology_hash |
|
SHA256 hash of the topology. This value should be sent in update topology request to make sure the topology was not changed since the caller retrieved the topology |
policy_bundle |
|
Policy bundle configured for the complete topology. Empty means no bundle. |
TopologyDeleteRequest#
TopologyDeleteRequest is used to delete a topology
Field |
Type |
Description |
|---|---|---|
topology_name |
|
Name of the topology to delete. Must not be empty. |
TopologyDeleteResponse#
TopologyDeleteResponse has the topology deletion response
Field |
Type |
Description |
|---|---|---|
status |
|
none |
TopologyEntity#
TopologyEntity defines a reference to an entity, and the relation between topology entities
Field |
Type |
Description |
|---|---|---|
entity |
|
The entity reference. The struct elements match the definition of TopologyEntity in the topology schema, so it must include the Name field that identifies the datacenter entity already existing in the database. The topology entity may include other properties, and these properties will be merged with the properties of the existing entity. This allows the topology entity to override matching values of an existing entity. |
children |
repeated |
The child entity ids of this entity |
TopologyListRequest#
TopologyListRequest is used by TopologyManagementService.ListTopologies.
Field |
Type |
Description |
|---|---|---|
oneof _is_active.is_active |
optional |
Filter by active status. If non-nil, only active or inactive topologies will be returned. If nil, all topologies will be returned regardless of activation status. |
TopologyListResponse#
TopologyListResponse contains the topology list specified by TopologyListRequest.
Field |
Type |
Description |
|---|---|---|
status |
|
Operation status |
topologies |
repeated |
List of all Topologies matching the TopologyListRequest specification |
TopologyListResponse.TopologyInfo#
Fields pertaining to topologies returned from listing
Field |
Type |
Description |
|---|---|---|
topology_name |
|
Name of Topology |
is_active |
|
Is Topology active/inactive |
leaf_node_names |
repeated |
Names of configurable leaf entities in Topology |
policy_bundle |
|
Policy bundle configured for the complete topology. Empty means no bundle. |
TopologyNodeConnectionCheckRequest#
TopologyNodeConnectionCheckRequest is used by TopologyManagementService.NodeConnectionCheck.
Field |
Type |
Description |
|---|---|---|
topology_name |
|
Name of topology to perform check. Note: no buf.validate annotation here because empty topology_name is valid. When empty, the server pings all entities regardless of topology (used for health checks and pinging nodes without an active topology). |
nodes |
repeated |
Optional names of nodes to check. If none specified, all nodes will be checked. |
oneof _attempts.attempts |
optional |
Optional number of connection attempts (default 1). Must be at least 1 when set. |
TopologyNodeConnectionCheckResponse#
TopologyNodeConnectionCheckResponse contains a message about node connection health.
Field |
Type |
Description |
|---|---|---|
total_nodes |
|
Total number of nodes in the topology |
success_nodes |
|
Number of successful node checks |
failure_nodes |
repeated |
Failed nodes with error message |
TopologyNodeConnectionCheckResponse.TopologyNodeConnectionCheckFailure#
Fields pertaining to a connection check failure on a node
Field |
Type |
Description |
|---|---|---|
node_name |
|
Name of the failed node |
error_msg |
|
Error message |
ValidateTopologyRequest#
ValidateTopologyRequest is used to stream the elements of a topology to the server for validation.
No part of the topology will be stored.
Each element of the stream contains zero or more entities and topology entities.
The first message must set header; subsequent messages must omit it.
The topology validation happens after all requests are sent and the stream is closed by the client.
The purpose of this request is to break a topology definition into gRPC-friendly messages instead of uploading a large topology file that may exceed gRPC message length limits.
Field |
Type |
Description |
|---|---|---|
oneof _header.header |
optional |
none |
entities |
repeated |
Zero or more entities that would replace existing datacenter entities in the database, or new entities that would be defined if the topology is saved. Topology validation takes into account existing database entities merged with the entities specified in ValidateTopologyRequests. |
topology_entities |
repeated |
Zero or more topology entities. Each topology entity must refer to an existing entity already stored in the database or specified in one of the ValidateTopologyRequest.entities fields. Since the actual validation takes place after all topology is uploaded via the stream, topology entities of an individual request may refer to entities that will be defined in later instances of ValidateTopologyRequests |
ValidateTopologyRequest.Header#
Field |
Type |
Description |
|---|---|---|
topology_name |
|
none |
ValidateTopologyResponse#
ValidateTopologyResponse contains topology validation results
Field |
Type |
Description |
|---|---|---|
status |
|
The validation status. The status will be ok only if there are no validation errors |
validation_errors |
repeated |
Zero or more validation errors. |
Scalar Value Types#
.proto Type |
Notes |
C++ Type |
Java Type |
Python Type |
|---|---|---|---|---|
double |
double |
double |
float |
|
float |
float |
float |
float |
|
int32 |
Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. |
int32 |
int |
int |
int64 |
Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. |
int64 |
long |
int/long |
uint32 |
Uses variable-length encoding. |
uint32 |
int |
int/long |
uint64 |
Uses variable-length encoding. |
uint64 |
long |
int/long |
sint32 |
Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. |
int32 |
int |
int |
sint64 |
Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. |
int64 |
long |
int/long |
fixed32 |
Always four bytes. More efficient than uint32 if values are often greater than 2^28. |
uint32 |
int |
int |
fixed64 |
Always eight bytes. More efficient than uint64 if values are often greater than 2^56. |
uint64 |
long |
int/long |
sfixed32 |
Always four bytes. |
int32 |
int |
int |
sfixed64 |
Always eight bytes. |
int64 |
long |
int/long |
bool |
bool |
boolean |
boolean |
|
string |
A string must always contain UTF-8 encoded or 7-bit ASCII text. |
string |
String |
str/unicode |
bytes |
May contain any arbitrary sequence of bytes. |
string |
ByteString |
str |