Import a Topology#

Use this workflow to load a clean topology from a JSON file into DPS. The procedure covers schema-backed validation, CLI import, direct API composition, and how to confirm that the imported inventory matches the file.

Import registers entities and topology relationships. It does not activate the topology or apply power policies to BMCs.

Prerequisites#

Confirm the following before you import:

  • The DPS server is running and reachable.

  • dpsctl is installed and you are authenticated. Refer to Installing dpsctl.

  • Device specifications for every entity Type and Model already exist. Refer to Managing Devices.

  • The environment is a clean install, or you have exported any topology you need to keep. Refer to export.

  • Typed policy bundles already exist if you will bind a bundle at resource-group creation or through the CreateUpdateTopology create request. Create bundles with dpsctl policy bundle upsert. Do not embed a top-level Policies array in the topology file.

Schema#

Topology files validate against the JSON schema embedded in the current DPS release. The published schema reference is generated from that artifact. The schema $id is dcpower_0.1, a schema document identifier rather than a product version. The gRPC API package is nvidia.dcpower.v1.

Refer to Schema Reference for the schema and downloadable JSON.

Each file is a JSON object with these top-level members:

  • Entities — optional array of data center entity definitions

  • Topology — required for import; name plus parent-child power relationships

  • Policies — retained in the schema for compatibility. A non-empty array is rejected by dpsctl topology validate and dpsctl topology import

The topology must contain at least one topology entity. Entity Name values are unique keys. Every name referenced in Topology.Entities must appear in the file or already exist in the inventory.

Power-domain caps use OperatingLimit, not Constraints. The Go topology model does not load Constraints as a typed power cap. The extra field can pass schema validation and remain in the entity’s untyped JSON, but it does not configure operating-limit behavior.

The entity Policy string is a legacy field. Typed policy activation binds a named bundle on the topology (CreateUpdateTopologyRequest.CreateRequest.policy_bundle) or on a resource group (--policy-bundle). Upserting a bundle that happens to share an entity Policy name does not apply that bundle.

The topology JSON model does not serialize a topology-level policy bundle (PolicyBundle is omitted from JSON). dpsctl topology import therefore cannot bind a bundle from the file. The server resolves an empty create value to the current global_policy_bundle setting and persists that selection. Direct API clients can set the create RPC policy_bundle field explicitly. Resource groups select their bundle separately with --policy-bundle.

Example File#

The following file defines one power domain and one compute node. It omits Policies.

{
  "Entities": [
    {
      "Type": "PowerDomain",
      "Name": "PD-A",
      "OperatingLimit": {
        "PowerValue": {"Value": 1150000, "Type": "W"},
        "PowerFactor": 0.9
      }
    },
    {
      "Type": "ComputerSystem",
      "Model": "DGX_H100",
      "Name": "node001",
      "Redfish": {
        "URL": "https://node001-bmc.example.com",
        "SecretName": "node001"
      }
    }
  ],
  "Topology": {
    "Name": "pdn",
    "Entities": [
      {
        "Name": "PD-A",
        "Children": ["node001"]
      },
      {
        "Name": "node001"
      }
    ]
  }
}

For the file model and relationship rules, refer to Topologies.

Validate Before Import#

Validation does not write entities or topologies. Use it to catch errors before you mutate the database.

dpsctl topology validate runs two layers:

  1. Local schema validation against the embedded JSON schema. Syntax errors report file, line, column, and offset. Schema errors report instance location and a sanitized message.

  2. Server semantic validation through the TopologyManagementService.ValidateTopology stream. The server combines the uploaded model with existing inventory and checks names, device models, connectivity, cycles, and disconnected entities. Closing the stream starts validation. The call does not modify the database.

dpsctl topology validate topology.json

Successful server validation returns:

{
  "status": {
    "ok": true,
    "diag_msg": "Topology validation passed"
  }
}

If semantic validation fails, status.ok is false, diag_msg reports the error count, and validation_errors lists each object name, object type, error code, and message. Server error codes are snake_case values such as device_not_found, invalid_model, and circular_dependency.

A non-empty Policies array fails before the server call:

legacy topology policies are not supported; create policy bundles with dpsctl policy bundle upsert

Command reference: validate.

Import with dpsctl#

Go dpsctl is the operator CLI. Import is client-side orchestration, not a single ImportTopology RPC.

dpsctl topology import topology.json

Successful import returns:

{
  "status": {
    "ok": true,
    "diag_msg": "Success"
  }
}

The CLI performs these steps:

  1. Reads and schema-validates the JSON file.

  2. Rejects a missing topology, a topology with no entities, or a non-empty Policies array.

  3. Calls ListTopologies and fails if the topology name already exists. This check is not a lock; a concurrent create can still collide on the server.

  4. Calls GetEntities and CreateEntities for entity names that are not already present. Existing names are left unchanged.

  5. Streams CreateUpdateTopology with a create operation. The created topology is inactive.

If entity creation succeeds and topology creation then fails, the new entities remain. Fix the file or inventory, then retry. Import does not roll back earlier writes.

Command reference: import.

Import through the API#

API consumers compose import from multiple RPCs. Do not send the CLI JSON file as a single RPC payload.

The release-supported service is nvidia.dcpower.v1.TopologyManagementService. Refer to APIs.

The following table lists the recommended sequence:

Step

RPC

Mutates State

Role

1

ValidateTopology (client stream)

No

Schema-valid payload plus semantic checks against existing inventory

2

ListTopologies

No

Detect a topology-name collision before creating entities

3

GetEntities

No

Detect which entity names already exist

4

CreateEntities (client stream)

Yes

Create only missing entities; error if any streamed name already exists

5

CreateUpdateTopology (client stream)

Yes

Create the named topology. The first message is a create request. Referenced entities must already exist. Set CreateUpdateTopologyRequest.CreateRequest.policy_bundle to bind a typed bundle. The new topology is inactive

6

ListTopologies or GetTopologyModel

No

Inspect names, is_active, leaf nodes, and exported model

dpsctl topology import performs local schema validation but does not call ValidateTopology before it starts the mutation sequence. The server performs semantic validation when it receives CreateUpdateTopology. Direct API clients should call ValidateTopology first to detect semantic errors before creating inventory entities.

UpsertEntities is retained for compatibility and returns UNIMPLEMENTED without changing state.

The Python api.topology_import.import_from_json helper follows the create-missing-entities then create-topology sequence and rejects a nonempty Policies array. Unlike the Go CLI, it does not call ListTopologies before entity creation, so check for a topology-name collision separately. The helper does not set CreateUpdateTopologyRequest.CreateRequest.policy_bundle. The libdpsapi topology import path uses the same policy-array rejection.

Python import composition
import json

from dpsapi import DpsApi

api = DpsApi(
    dps_host="api.dps.example.com",
    dps_port=443,
).with_username("alice").with_password("<password>")

with open("bundle.json", encoding="utf-8") as fh:
    api.policies.upsert_bundle(json.load(fh))

with open("topology.json", encoding="utf-8") as fh:
    topology_data = json.load(fh)

topology = topology_data["Topology"]
validation = api.topology.validate_topology(
    topology_name=topology["Name"],
    entities=topology_data.get("Entities"),
    topology_entities=topology.get("Entities"),
)
print(validation)

imported = api.topology_import.import_from_json(topology_data)
print(imported)

listed = api.topology.list_topologies(is_active=False)
print(listed)

After authentication, list topologies through TopologyManagementService:

grpcurl -H "authorization: Bearer $DPS_ACCESS_TOKEN" \
  api.dps.your.domain:443 \
  nvidia.dcpower.v1.TopologyManagementService/ListTopologies

Verify the Import#

Compare the loaded inventory with the input file. Import success does not mean the topology is active.

dpsctl topology list
dpsctl topology list --active=false
dpsctl topology list --active=true
dpsctl topology list-entities
dpsctl topology export --topology pdn

Confirm the following:

  • topology list includes the imported name.

  • dpsctl topology list --active=false lists the topology.

  • dpsctl topology list --active=true does not list it. JSON output omits is_active when the value is false.

  • Leaf node names match the compute entities in the file.

  • list-entities returns every imported Name, Type, and Model.

  • export hierarchy and entity identities match the input. Export sanitization omits the runtime-only topologyHash.

Command references: list, list-entities, and export.

Activation Is Separate#

Power policy application and BMC connectivity checks run during activation, not import. Deactivate the currently active topology before you activate another. The --replace-topology flag is retained for compatibility and is currently rejected.

dpsctl topology activate --topology pdn

Refer to activate and Managing Topologies.

Troubleshoot and Recover#

The following table maps common failures to a corrective action:

Symptom

Likely Cause

Action

Invalid JSON syntax at line, column, offset

Malformed file

Fix the reported location and re-run validate

topology schema validation failed with instance paths

Field type, required member, or uniqueness

Correct the named instance path against the schema

legacy topology policies are not supported

Non-empty top-level Policies array

Remove Policies. Upsert typed bundles with dpsctl policy bundle upsert

no topology in the input file or topology has no entities defined

Missing Topology or empty Topology.Entities

Add a named topology with at least one entity

failed to create topology during import preflight

Topology name already exists

Choose a new name, or use the API-only CreateUpdateTopology update operation. Refer to update

device_not_found in validation_errors

Missing device specification

Register the device, then validate again

circular_dependency, disconnected_graph, or referenced_entity_not_found

Invalid hierarchy

Fix Children references and unique Name values

Entity create succeeded, topology create failed

Partial write

Inspect list-entities, fix the topology, then retry import or remove unused entities

Authentication or connectivity errors

Session, TLS, or endpoint

Re-authenticate and confirm --host and --port

Validate remains safe to retry. Import can encounter partial prior writes after entity creation.

Next Steps#

After the imported topology matches the file and remains inactive:

  1. Activate it when you are ready to apply policies. Refer to Managing Topologies.

  2. Create resource groups for workloads. Refer to Managing Resource Groups.