Topologies#

Overview#

Topologies model the physical power-distribution structure of a data center. They define the equipment in a managed area and the parent-child relationships that describe power flow.

A topology import file can contain:

Entities: Physical equipment instances.
Topology: Parent-child connections between those instances.

Multiple topologies can describe different data center sections or configurations, but DPS can manage only one active topology at a time.

A topology also has one persisted topology-wide policy-bundle selection. The selection is not stored in topology JSON and is not assigned per entity. Refer to Power Policies for selection, activation, and fallback behavior.

Topology Deactivation and Loss of DPS Control#

Topology deactivation and a DPS service outage have different effects on the policies that a Baseboard Management Controller (BMC) enforces. The following table summarizes the operator-visible behavior:

Table 1 Policy Behavior When DPS Stops Applying Policies#
Event	DPS behavior	BMC behavior
Explicit topology deactivation	DPS marks the topology inactive and sends an `UnsetPolicy` request to each managed node. Active resource groups prevent topology deactivation.	The device plugin applies the configured idle policy. If no idle policy is configured, the plugin restores the BMC defaults or removes the DPS-managed policy, depending on the platform.
Planned DPS shutdown, accidental DPS server or agent pod deletion, or temporary DPS outage	DPS sends no deactivation or policy-change request while it is unavailable.	If the BMC remains operational, it continues enforcing the last successfully applied power limits.
Node restart, BMC restart, or firmware maintenance	DPS cannot guarantee that a policy survives a reset of the system that enforces it.	The BMC can return to its default limits. Reintroduce the node through a topology or resource-group policy operation to put it back under DPS control.

A topology-deactivation response confirms that the topology is inactive. Device cleanup is best effort, so the response does not guarantee that every BMC accepted the UnsetPolicy request. Verify the power limits when maintenance or another operational requirement depends on a specific hardware state.

For the maintenance workflow, refer to Prepare Nodes for Maintenance.

Topology Definition#

Topology import files use JSON and follow DMTF Redfish terminology where possible.

Import Structure#

Each topology import file defines one topology with at least one topology entity, plus zero or more data center inventory entities:

{
  "Entities": [
    // Entity definitions
  ],
  "Topology": {
    "Name": "topologyName",
    "Entities": [
      // Topology relationships
    ]
  }
}

A topology-only file can be imported when every referenced entity already exists. Include missing entities in the same JSON file, or create them through the CreateEntities API stream before you create the topology.

Topology Policy Selection#

The topology import format does not contain a policy-bundle field. Consequently, dpsctl topology import sends an empty CreateUpdateTopologyRequest.CreateRequest.policy_bundle, and the server resolves and persists the current global_policy_bundle value. API clients that create or update a topology can provide an explicit policy_bundle value in the corresponding nested request instead.

Importing or creating a topology does not change hardware. The selected bundle takes effect when the topology activates. For the full lifecycle, refer to Policy Lifecycle and Fallback.

Validation#

The file format is backed by the topology JSON schema, which is based on a reduced Redfish schema with DPS additions. dpsctl topology validate performs local schema validation and then calls the server’s non-mutating ValidateTopology RPC. During import, the server performs semantic validation as part of the mutating CreateUpdateTopology RPC.

Refer to Topology Schema Reference for the detailed format.

Topology Entities#

The topology’s Entities array represents entity instances and their one-to-many child connections:

{
  "Name": "PD-A",
  "Children": [
    "PDU-A1",
    "PDU-A2",
    "PDU-A3"
  ]
}

This relationship means that PD-A powers the three child PDUs. Each Name refers to an entity in the data center inventory and must be unique within the topology array. Server validation rejects invalid connectivity such as cycles and disconnected entities.

A topology can include a subset of the defined inventory entities.

A topology entity can override supported properties of the inventory entity. For example, this topology entity overrides OperatingLimit without changing the other inventory properties:

{
  "Name": "PD-A",
  "OperatingLimit": {
    "PowerValue": {
      "Value": 1150000,
      "Type": "W"
    },
    "PowerFactor": 0.9
  },
  "Children": ["node001"]
}

Shared GPU Topology Constraints#

Shared-GPU resource groups still have to satisfy these topology relationships after a GPU policy update. DPS rejects a shared-GPU update whose post-clamp aggregate load would violate a non-compute ancestor such as a rack or PDN device, even when the resource-group GPU budget still has headroom. Refer to Shared GPU Budget.

Example#

A complete topology definition with one power domain, one PDU, one rack PDU, and two computer systems.

Usage#

Use dpsctl to validate, import, list, and activate topologies:

# Validate without mutating the database
dpsctl topology validate datacenter.json

# Import topology from JSON file (created topology is inactive)
dpsctl topology import datacenter.json
dpsctl topology list
dpsctl topology activate --topology pdn

An active topology must be deactivated before a different topology can be activated.