Entities

Overview

Entities represent actual physical equipment instances in your datacenter - specific servers, power distribution units, GPUs, switches, and other hardware components. Each entity is a concrete instantiation of a device specification, configured with real-world details like BMC endpoints and site-specific constraints.

Entity Structure

Each entity defines:

Name - Unique identifier (e.g., “node001”, “rack-pdu-a1”)
Type - Device category from device specification
Model - Specific device model from device specification
Redfish - BMC endpoint configuration for management
Policy - Default power policy (optional)
Constraints - Site-specific power limits (optional)
StaticLoad - Fixed power consumption (optional)
TelemetryID - Sensor ID for obtaining telemetry data (optional)

Entity Types and Examples

Compute Entities

Compute Nodes (ComputerSystem):

{
  "Type": "ComputerSystem",
  "Model": "DGX_H100",
  "Name": "node001",
  "Policy": "Node-High",
  "Redfish": {
    "URL": "https://node001-bmc.example.com",
    "SecretName": "node001"
  },
  "TelemetryID": "sensor-node001"
}

Power Distribution Entities

Power Domains (top-level power sources):

{
  "Type": "PowerDomain",
  "Name": "PD-A",
  "Constraints": {
    "PowerValue": {"Value": 1150000, "Type": "W"},
    "PowerFactor": 0.9
  }
}

Rack PDUs (power distribution units):

{
  "Type": "PowerDistribution",
  "Model": "RackPDU95_57500W",
  "Name": "rPDU-A1-001",
  "StaticLoad": {"Value": 3400, "Type": "W"}
}

Redfish Integration

Compute entities include Redfish configuration for BMC communication:

"Redfish": {
  "URL": "https://node001-bmc.example.com",
  "SecretName": "node001"
}

URL - BMC endpoint address (hostname or IP)
SecretName - Reference to stored authentication credentials

Power Configuration

Constraints

Specify power limitations and efficiency:

"Constraints": {
  "PowerValue": {"Value": 1150000, "Type": "W"},
  "PowerFactor": 0.9
}

Static Load

Add fixed power consumption from unmanaged devices:

"StaticLoad": {"Value": 3400, "Type": "W"}

Example: Complete Entity Definition

{
  "Entities": [
    {
      "Type": "PowerDomain",
      "Name": "PD-A",
      "Constraints": {
        "PowerValue": {"Value": 1150000, "Type": "W"},
        "PowerFactor": 0.9
      }
    },
    {
      "Type": "PowerDistribution",
      "Model": "RackPDU95_57500W",
      "Name": "rPDU-A1-001",
      "StaticLoad": {"Value": 3400, "Type": "W"}
    },
    {
      "Type": "ComputerSystem",
      "Model": "DGX_H100",
      "Name": "node001",
      "Policy": "Node-High",
      "Redfish": {
        "URL": "https://node001-bmc.example.com",
        "SecretName": "node001"
      },
      "TelemetryID": "sensor-node001"
    }
  ]
}

BMC Credentials

Entity BMC access requires secure credential management through secrets:

# Store BMC credentials
kubectl create secret generic node001 \
  --namespace=dps \
  --type=Opaque \
  --from-literal='bmc={"username":"admin","password":"secret123"}'

# Add Label to BMC credential
kubectl label secret node001 \
  --namespace=dps \
  app=bmc-secret

# Entity references the secret
"Redfish": {
  "URL": "https://node001-bmc.example.com",
  "SecretName": "node001"
}

Entity Generation

There are multiple ways that entities can be imported into DPS.

Manual Definition

Define entities explicitly in topology JSON files:

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

BCM Integration

For Base Command Manager (BCM) environments, DPS can auto-generate entities using an asynchronous import workflow:

# Step 1: Start entity generation from BCM (returns a request ID)
dpsctl import entity --source bcm \
  --url https://bcm-headnode:8443 \
  --username admin \
  --password secret123

# Sample Output:
{
  "request_id": "4826e1b3-cb36-42eb-97d5-0eaa9e9ee346"
}

# Step 2: Retrieve generated entities using the request ID
dpsctl import entity-status --request-id <request-id>

# Sample Output:
[
  {
    "Type": "ComputerSystem",
    "Model": "DGX_H100",
    "Name": "node002",
    "Redfish": {
      "SecretName": "node002",
      "URL": "https://node002"
    },
    "UpdatedAt": "0001-01-01T00:00:00Z"
  },
  {
    "Type": "ComputerSystem",
    "Model": "DGX_H100",
    "Name": "node003",
    "Redfish": {
      "SecretName": "node003",
      "URL": "https://node003"
    },
    "UpdatedAt": "0001-01-01T00:00:00Z"
  },
  {
    "Type": "ComputerSystem",
    "Model": "DGX_H100",
    "Name": "node004",
    "Redfish": {
      "SecretName": "node004",
      "URL": "https://node004"
    },
    "UpdatedAt": "0001-01-01T00:00:00Z"
  }
]

Nautobot Integration

Similar to BCM Environments, DPS can auto-generate entities from Nautobot’s DCIM Inventory using an asynchronous import workflow:

# Step 1: Start entity generation from Nautobot (returns a request ID)
dpsctl import entity --source nautobot \
  --locations "DC-1" \
  --racks "Rack-A1,Rack-A2" \
  --device-types "DGX_H100"

# Sample Output:
{
  "request_id": "b12d520d-f3e6-4603-b2bf-74dd55617888"
}

# Step 2: Retrieve generated entities using the request ID
dpsctl import entity-status --request-id <request-id>

# Sample Output:
[
  {
    "Type": "ComputerSystem",
    "Model": "DGX_B200",
    "Name": "computerSystem001",
    "UpdatedAt": "0001-01-01T00:00:00Z"
  },
  {
    "Type": "ComputerSystem",
    "Model": "DGX_B200",
    "Name": "computerSystem002",
    "UpdatedAt": "0001-01-01T00:00:00Z"
  },
  {
    "Type": "ComputerSystem",
    "Model": "DGX_B200",
    "Name": "computerSystem003",
    "UpdatedAt": "0001-01-01T00:00:00Z"
  }
]

See the import entity command reference for full details.

Usage

Entities are imported as part of topology files and can be queried through dpsctl:

# Import entities and topology
dpsctl topology import datacenter.json

# List entities
dpsctl topology list-entities

# Show entity details
dpsctl topology list-entities node001