Entities#

Overview#

Entities represent physical equipment instances in your data center, such as servers, power distribution units, GPUs, switches, and other hardware components. Each entity instantiates a device specification and provides deployment details such as BMC endpoints and site-specific operating limits.

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 - Optional legacy entity policy name retained for compatibility. It does not select a policy bundle.

  • OperatingLimit - Optional site-specific power cap for PowerDomain, PowerDistribution, and PowerSupply entities

  • 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",
  "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",
  "OperatingLimit": {
    "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#

Operating Limit#

Specify an operating cap on a PowerDomain, PowerDistribution, or PowerSupply entity:

"OperatingLimit": {
  "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",
      "OperatingLimit": {
        "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",
      "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. Refer to Import a Topology.

# 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 \
  --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

Further Reading#