topology

API Reference: 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, the power policies, 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, entity relationships, and policies.

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 are defined in entity.proto

Policy definitions are in policy.proto

Power policies associates with topology entities can be overridden by resource groups, defined in resourcegroup.proto

Table of Contents

• Services

  • TopologyManagementService

• Messages

  • ActivateTopologyRequest
  • ActivateTopologyResponse
  • ActivateTopologyResponse.NodeStatusesEntry
  • CreateUpdateTopologyRequest
  • CreateUpdateTopologyRequest.CreateRequest
  • CreateUpdateTopologyRequest.UpdateRequest
  • CreateUpdateTopologyResponse
  • DeactivateTopologyRequest
  • DeactivateTopologyResponse
  • DeleteEntitiesRequest
  • DeleteEntitiesResponse
  • DeleteEntitiesResponse.EntityTopologiesEntry
  • DeleteEntitiesResponse.Topologies
  • Entity
  • GenerateEntitiesFromBCMRequest
  • GetEntitiesRequest
  • GetNodesStatusRequest
  • GetNodesStatusResponse
  • GetNodesStatusResponse.NodeState
  • GetNodesStatusResponse.NodeStatus
  • GetNodesStatusResponse.NodeStatusesEntry
  • GetTopologyModelRequest
  • GetTopologyModelResponse
  • GetTopologyModelResponse.Header
  • TopologyDeleteRequest
  • TopologyDeleteResponse
  • TopologyEntity
  • TopologyListRequest
  • TopologyListResponse
  • TopologyListResponse.TopologyInfo
  • TopologyNodeConnectionCheckRequest
  • TopologyNodeConnectionCheckResponse
  • TopologyNodeConnectionCheckResponse.TopologyNodeConnectionCheckFailure
  • ValidateTopologyRequest
  • ValidateTopologyResponse

• Scalar Value Types

Services

TopologyManagementService

TopologyManagementService manages the entities in a data center, power policy definitions, and topologies

ValidateTopology

rpc ValidateTopology(ValidateTopologyRequest) 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, topology entities, and power policies are uploaded, the client closes the stream to start the validation process. The validation takes into account existing entities and policies, combines them with the provided entities and policies, and then validates the topology. It returns a detailed validation report if it encounters any errors.

This call does not modify any existing entities, policies, or topologies in the database.

CreateEntities

rpc CreateEntities(Entity) .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) .google.protobuf.Empty

Upserts entities.

This API is used to define the entities in a datacenter before creating topologies using those entities.

These entities are not part of any topology. If an entity already exists, the entity is updated to what’s provided. If an entity does not exist, it is created.

If one or more of the updated entities belong to an active topology, the modifications for those entities are applied to the active topology.

GetEntities

rpc GetEntities(GetEntitiesRequest) Entity

Returns all entities or selected entities

DeleteEntities

rpc DeleteEntities(DeleteEntitiesRequest) 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) CreateUpdateTopologyResponse

Creates or updates a topology.

A topology descibes 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 chose 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) TopologyDeleteResponse

Deletes an inactive topology

PolicyCreate

rpc PolicyCreate(PolicyCreateRequest) PolicyCreateResponse

Create a new power policy.

ListPolicies

rpc ListPolicies(.google.protobuf.Empty) PolicyObject

ListPolicies streams all policies

GenerateEntitiesFromBCM

rpc GenerateEntitiesFromBCM(GenerateEntitiesFromBCMRequest) Entity

GenerateEntitiesFromBCM queries the BCM for datacenter entities and returns a stream of entity structs

GetTopologyModel

rpc GetTopologyModel(GetTopologyModelRequest) GetTopologyModelResponse

GetTopologyModel streams the entities and relationships in a topology

ActivateTopology

rpc ActivateTopology(ActivateTopologyRequest) 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) DeactivateTopologyResponse

Deactivate a given topology

Deactivating an active topology will remove existing power policies.

ListTopologies

rpc ListTopologies(TopologyListRequest) TopologyListResponse

List existing topologies

NodeConnectionCheck

rpc NodeConnectionCheck(TopologyNodeConnectionCheckRequest) 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) .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) Device

List all known devices in the database

GetNodesStatus

rpc GetNodesStatus(GetNodesStatusRequest) GetNodesStatusResponse

Get last known status on specified nodes

Messages

ActivateTopologyRequest

ActivateTopologyRequest is used by TopologyManagementService.ActivateTopology.

Activating an inactive topology involves validating connectivity and validation 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 will fail, unless switch_if_active is set. If switch_is_active is set, then existing resource groups will be ported to the new topology and validated. If the new topology power allocation is invalid, topology switching will fail.

ActivateTopologyResponse

ActivateTopologyResponse will be returned if topology activation was successful

ActivateTopologyResponse.NodeStatusesEntry

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 unintented 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 chaning 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.

CreateUpdateTopologyRequest.CreateRequest

CreateRequest describes the topology to create.

The created topology will be inactive.

CreateUpdateTopologyRequest.UpdateRequest

UpdateRequest describes the topology to update.

CreateUpdateTopologyResponse

CreateUpdateTopologyResponse will be returned if adding relations to the topology was successful

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.

DeactivateTopologyResponse

DeactivateTopologyResponse will be returned if topology deactivation was successful

DeleteEntitiesRequest

DeleteEntitiesRequest contains a list of entities to delete

DeleteEntitiesResponse

DeleteEntitiesResponse contains the status of the delete operation

DeleteEntitiesResponse.EntityTopologiesEntry

DeleteEntitiesResponse.Topologies

Entity

Entity represents a topology entity matching the Entity JSON schema specification.

GenerateEntitiesFromBCMRequest

GenerateEntitiesFromBCMRequest is used by TopologyManagementService.GenerateEntitiesFromBCM. It retrieves the datacenter entities by querying the BCM, then streams those entities to the caller.

GetEntitiesRequest

GetEntitiesRequest specifies the entities to fetch

GetNodesStatusRequest

GetNodesStatusRequest contains a list of nodes to retrieve status

GetNodesStatusResponse

GetNodesStatusResponse contains the last known node status

GetNodesStatusResponse.NodeState

Contains node state

GetNodesStatusResponse.NodeStatus

node status contains the latest node status

GetNodesStatusResponse.NodeStatusesEntry

GetTopologyModelRequest

GetTopologyModelRequest specifies the topology name whose model will be returned

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.

GetTopologyModelResponse.Header

TopologyDeleteRequest

TopologyDeleteRequest is used to delete a topology

TopologyDeleteResponse

TopologyDeleteResponse has the topology deletion response

TopologyEntity

TopologyEntity defines a reference to an entity, and the relation between topology entities

TopologyListRequest

TopologyListRequest is used by TopologyManagementService.ListTopologies.

TopologyListResponse

TopologyListResponse contains the topology list specified by TopologyListRequest.

TopologyListResponse.TopologyInfo

Fields pertaining to topologies returned from listing

TopologyNodeConnectionCheckRequest

TopologyNodeConnectionCheckRequest is used by TopologyManagementService.NodeConnectionCheck.

TopologyNodeConnectionCheckResponse

TopologyNodeConnectionCheckResponse contains a message about node connection health.

TopologyNodeConnectionCheckResponse.TopologyNodeConnectionCheckFailure

Fields pertaining to a connection check failure on a node

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, topology entities, and policies. The topology_name should be specified in the first request, and may be omitted in the subsequent requests.

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.

ValidateTopologyResponse

ValidateTopologyResponse contains topology validation results

Scalar Value Types