Managing Topologies#

Overview#

This guide covers the command-line workflow for validating, importing, and activating a topology. For the topology data model, refer to Topologies.

Prerequisites#

DPS server running and accessible.
dpsctl installed and authenticated.
Required device specifications available. Refer to Managing Devices.

Step 1: Prepare the Topology JSON File#

A topology import file contains entity definitions and topology relationships. Do not put policy definitions or policy assignments in this file.

If you enabled a DPS Agent, assign managed devices to it in Topology.Entities. An AgentId assigns the entity and is inherited by descendants that do not set their own value. For example, set it on a shared parent:

{
  "Name": "PD-A",
  "AgentId": "data-hall-a-agent",
  "Children": ["node001"]
}

Set AgentId to the agent.agentID configured for that data hall.

A nonempty top-level Policies array is rejected. A legacy Policy value on an entity does not assign a policy during activation.

Step 2: Validate the File#

Validate the topology before importing it:

dpsctl topology validate topology.json

Resolve schema, reference, duplicate-name, cycle, and connectivity errors before continuing.

Step 3: Select the Policy Bundle#

The Go CLI topology file has no policy-bundle field. Before importing, store any custom bundle and set the global default that the new topology should use:

dpsctl policy bundle upsert site-balanced.yaml
dpsctl policy bundle list
dpsctl settings update --set global_policy_bundle=site-balanced

Use an installed bundle name, and omit the upsert command when selecting a built-in bundle. An API client can instead provide an explicit policy_bundle in the topology create request.

Step 4: Import the Topology#

Import the validated file:

dpsctl topology import topology.json

Import creates missing inventory entities and a new inactive topology. An existing topology with the same name causes the import to fail; use the update command for that topology. Import does not apply a policy to hardware.

The Go import request leaves CreateUpdateTopologyRequest.policy_bundle empty, so the server resolves and persists the current global_policy_bundle as the topology selection.

For default selection and lifecycle behavior, refer to Power Policies.

Step 5: List Topologies#

List stored topologies and review the selected policy bundle and active state:

dpsctl topology list

Step 6: Activate a Topology#

Only one topology can be active. If another topology is active, deactivate it before activating the candidate:

dpsctl topology activate --topology pdn

Activation applies the topology-wide effective policy to matching power-managed devices. Without an effective policy, activation invokes the device unset path, which can apply an idle policy or a plugin-specific fallback.

Host reachability checks are enabled by default. To set the minimum acceptable reachability percentage explicitly:

dpsctl topology activate \
  --topology pdn \
  --ping-hosts \
  --at-least-percent-hosts 80

Step 7: Deactivate a Topology#

Deactivate the topology before removing it or activating a different one:

dpsctl topology deactivate --topology pdn

Deactivation marks the topology inactive and performs best-effort cleanup on managed devices. A successful response does not confirm that every BMC accepted the cleanup request, so verify the resulting power limits.

For details about idle policies, BMC defaults, and service outages, refer to Topology Deactivation and Loss of DPS Control.

Prepare Nodes for Maintenance#

Before you power down a managed node, restart its BMC, or update its firmware, remove the node from its active resource group. Removing a node from an active resource group reapplies the topology default policy, so the node remains power-managed by the active topology. After maintenance, add the node back to the resource group to reapply its resource-group policy.

For maintenance on selected nodes in an active resource group, use the following procedure:

Remove the affected nodes from the active resource group:

dpsctl resource-group remove \
  --resource-group <resource-group> \
  --entities <comma-separated-node-list>

Complete the maintenance and confirm that each BMC is reachable.

Add the nodes back to the active resource group. Adding a node to an active resource group applies its policy immediately:

dpsctl resource-group add \
  --resource-group <resource-group> \
  --entities <comma-separated-node-list> \
  --strict-policy \
  --allow-reprovision=false

Confirm the resource-group state and the effective node limits:

dpsctl resource-group list
dpsctl check status --nodes <comma-separated-node-list>

For topology-wide maintenance, record the configuration of every active resource group, delete those groups, and deactivate the topology. After maintenance, activate the topology, recreate the resource groups, and activate them to reapply their policies.

DPS does not provide a standalone resource-group deactivate command. Deleting an active resource group deactivates it as part of the delete operation.

Step 8: Update a Topology#

After editing the topology JSON, update the stored topology:

dpsctl topology update updated-topology.json

Use --force only to bypass the optimistic topology-hash conflict check. Schema and server validation still run.

This Go command preserves the topology’s current policy-bundle selection. API clients can explicitly change the selection only while the topology is inactive.

Step 9: Remove a Topology#

A topology must be inactive before removal:

dpsctl topology remove --topology pdn

Step 10: Manage Inventory Entities#

List all inventory entities or request specific names:

dpsctl topology list-entities
dpsctl topology list-entities node001

Remove entities only when active topology and resource-group state no longer depends on them:

dpsctl topology remove-entities node001 node002