Topologies

Overview

Topologies model the physical power distribution structure of your datacenter, defining how entities are connected and how power flows between them. They establish the hierarchical relationships between power sources, distribution units, and consuming devices.

When importing topologies, a topology file can consist of:

Entities - References to physical equipment instances
Topology - Parent-child connections showing power flow
Policies - Power management configurations

Multiple topologies can exist for different datacenter sections or configurations, however, DPS can manage only a single topology at a time.

Topology Definition

The topology is defined using a JSON file.

The file format follows DMTF/Redfish terminology and aligns with it whenever possible.

Import Structure

Each import file defines at most one topology, zero or more entities, and zero or more policies:

{
    "Entities": [
        // Entity definition
    ],
    "Topology": {
      "Name": "topologyName",
      "Entities": [
         // Topology entities
      ]
    },
    "Policies": [
        // Policy definition
    ]
}

Separate import files containing only entities, policies, or a topology can be used to build the inventory for a data center.

Note: Importing a topology validates that all entities referenced the topology are already defined, so entities must be imported before importing a topology using those entities.

Validation

File format is backed by the JSON schema. Developed schema is based on stripped down Redfish Schema definitions with DPS-specific additions. Latest schema files are available for external use and are embedded into DPS. Validation is performed on both client side (dpsctl) and server side (DPS-server). If client side validation fails (dpsctl topology import), an error message is printed and import request is not propagated to the server side. Similar validation is performed on the server side as it is required if DPS topology import API is directly used.

Available Schemas:

Schema Reference - Detailed schema documentation

Topology Entities

Topology entities (Entities) is a JSON array where each array element represents an instance of an entity within a topology, and connections from that entitie to one or more children entities (one to many):

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

Here, it is defined that entity with the name PD-A contains 3 child entities with the names PDU-A1, PDU-A2 and PDU-A3. From the power perspective, this relation should be understood as PDU-A1, PDU-A2 and PDU-A3 are all powered by PD-A. Each entity is referred by it’s Name property (name is an entity key). Each entity with specified Name must already be defined in the data center.

Each Name must be unique in Entities array. On the server side (dps-server), relation validations are performed to rule out invalid connectivity such as cycles and disconnected entities.

A topology does not have to include all defined entities of the data center. This allows defining topologies that use only a subset of the entities.

A topology entity may override properties of the entity defined at the datacenter level. For instance, the following topology entity overrides the Constraints while leaving all properties that are defined at the datacenter level unmodified:

"Topology": {
  "Name": "topologyA",
  "Entities" [
        {
            "Name": "PD-A",
            "Constraints": {
                "PowerValue": {
                    "Value": 1150000,
                    "Type": "W"
                },
                "PowerFactor": 0.9
            },
            "Children": [ ...]
        },
        ...
    ]
}

Example

A complete topology definition with one power domain, one PDU, one rack PDU and two computer systems, each using different power policies Node-Low and Node-High.

{
    "Entities": [
        {
            "Type": "PowerDomain",
            "Name": "PD-A",
            "Constraints": {
                "PowerValue": {
                    "Value": 1150000,
                    "Type": "W"
                },
                "PowerFactor": 0.9
            },
            "Redfish": {
                "@odata.type": "#PowerDomain.v1_2_2.PowerDomain",
                "@odata.id": "/PD-A",
                "Id": "PD-A"
            }
        },
        {
            "Type": "PowerDistribution",
            "Model": "PDU",
            "Name": "PDU-A1",
            "Redfish": {
                "@odata.type": "#PowerDistribution.v1_4_0.PowerDistribution",
                "@odata.id": "/PDU-A1",
                "Id": "PDU-A1",
                "EquipmentType": "FloorPDU"
            }
        },
        {
            "Type": "PowerDistribution",
            "Model": "Horizontal_rPDU",
            "Name": "rPDU-A1-001",
            "StaticLoad": {
                "Value": 3400,
                "Type": "W"
            },
            "Redfish": {
                "@odata.type": "#PowerDistribution.v1_4_0.PowerDistribution",
                "@odata.id": "/rPDU-A1-001",
                "Id": "rPDU-A1-001",
                "EquipmentType": "RackPDU"
            }
        },
        {
            "Type": "ComputerSystem",
            "Model": "DGX_H100",
            "Policy": "Node-Low",
            "Name": "viking001",
            "Redfish": {
                "@odata.type": "#ComputerSystem.v1_23_0.ComputerSystem",
                "@odata.id": "/viking001",
                "Id": "viking001",
                "URL": "https://viking001",
                "SecretName": "viking001"
            }
        },
        {
            "Type": "ComputerSystem",
            "Model": "DGX_H100",
            "Policy": "Node-High",
            "Name": "viking002",
            "Redfish": {
                "@odata.type": "#ComputerSystem.v1_23_0.ComputerSystem",
                "@odata.id": "/viking002",
                "Id": "viking002",
                "URL": "https://viking002",
                "SecretName": "viking002"
            }
        }
    ],
    "Topology": {
       "Name": "pdn",
       "Entities": [
           {
               "Name": "PD-A",
               "Children": [
                   "PDU-A1"
               ]
           },
           {
               "Name": "PDU-A1",
               "Children": [
                   "rPDU-A1-001"
               ]
           },
           {
               "Name": "rPDU-A1-001",
               "Children": [
                   "viking001",
                   "viking002"
               ]
           },
           {
               "Name": "viking001"
           },
           {
               "Name": "viking002"
           }
       ]
    },
    "Policies": [
        {
            "Name": "Node-Low",
            "Description": "Low power profile configuration",
            "Limits": [
                {
                    "ElementType": "Node",
                    "PowerLimit": { "Watts": 5250 }
                },
                {
                    "ElementType": "GPU",
                    "PowerLimit": { "Watts": 2800 }
                },
                {
                    "ElementType": "CPU",
                    "PowerLimit": { "Watts": 720 }
                },
                {
                    "ElementType": "Memory",
                    "PowerLimit": { "Watts": 480 }
                }
            ]
        },
        {
            "Name": "Node-High",
            "Description": "High power profile configuration",
            "Limits": [
                {
                    "ElementType": "Node",
                    "PowerLimit": { "Watts": 10200 }
                },
                {
                    "ElementType": "GPU",
                    "PowerLimit": { "Watts": 800 }
                },
                {
                    "ElementType": "CPU",
                    "PowerLimit": { "Watts": 500 }
                },
                {
                    "ElementType": "Memory",
                    "PowerLimit": { "Watts": 1200 }
                }
            ]
        }
    ]
}

Usage

Topologies are imported and managed through dpsctl:

# Import topology from JSON file
dpsctl topology import datacenter.json

# List available topologies
dpsctl topology list

# Activate topology for power management
dpsctl topology activate pdn

Topologies

Topologies

Overview

Topology Definition

Import Structure

Validation

Topology Entities

Example

Usage

Further Reading

Products