resourcegroup

API Reference: v1/resourcegroup.proto

Resource Groups manage power policies for temporary workload allocations on datacenter hardware. They provide ephemeral power management that overrides topology defaults during job execution.

A resource group is a collection of compute resources (nodes) allocated for a specific workload, such as a SLURM job or machine learning training run. Resource groups temporarily override the topology-specified power policies of their entities during workload execution, then restore topology defaults when the workload completes.

Resource groups follow a 5-step lifecycle:

1. CREATE - Create an empty, inactive resource group with optional default power policy
2. ADD - Add compute resources (nodes) to the group before activation
3. ACTIVATE - Apply power policies to hardware and mark the group as active
4. UPDATE (Optional) - Dynamically adjust power policies during workload execution
5. DELETE - Deactivate and cleanup, restoring topology defaults

Power Policy Hierarchy

Resource groups use a 3-level policy hierarchy to determine effective power settings:

1. Entity-level policy - Specific policy for individual nodes (highest priority)
2. Resource group policy - Default policy for all nodes in the group
3. Topology policy - Baseline policy from the datacenter topology (lowest priority)

Dynamic Power Management

Resource groups support dynamic power management (DPM) through:

• Power Reservation Steering (PRS) - Automatic power redistribution based on telemetry
• Policy Updates - Runtime policy adjustments for optimization
• GPU Workload Profiles - Hardware-specific power optimization for GPU workloads

Integration with Workload Schedulers

Resource groups are designed to integrate with workload schedulers like SLURM:

• Use external IDs to map to scheduler job IDs (e.g., SLURM_JOB_ID)
• Follow scheduler lifecycle events (job start/end)
• Support scheduler-driven power policy updates

Power policies are defined in policy.proto, and topology entities are defined in topology.proto. Workload-specific optimizations use telemetry data structures from common.proto.

Table of Contents

• Services

  • ResourceGroupManagementService

• Messages

  • ActivateResourceGroupRequest
  • ActivateResourceGroupResponse
  • ActivateResourceGroupResponse.NodeStatusesEntry
  • DeactivateResourceGroupRequest
  • DeactivateResourceGroupResponse
  • GPUWorkloadProfileResponse
  • GPUWorkloadProfileResponses
  • NodeStatusResponse
  • ResourceGroupAddResourcesRequest
  • ResourceGroupAddResourcesResponse
  • ResourceGroupAsyncOperationStatus
  • ResourceGroupAsyncOperationStatusRequest
  • ResourceGroupAsyncOperationStatusRequest.ResourceGroupStatusInfo
  • ResourceGroupAsyncStrategy
  • ResourceGroupCreateRequest
  • ResourceGroupCreateResponse
  • ResourceGroupDeleteRequest
  • ResourceGroupDeleteResponse
  • ResourceGroupListAllRequest
  • ResourceGroupListAllResponse
  • ResourceGroupListAllResponse.ResourceGroupInfo
  • ResourceGroupListAllResponse.ResourceGroupInfo.ResourcePolicy
  • ResourceGroupPartialActivation
  • ResourceGroupRemoveResourcesRequest
  • ResourceGroupRemoveResourcesResponse
  • ResourceGroupUpdateRequest
  • ResourceGroupUpdateResourcesRequest
  • ResourceGroupUpdateResourcesRequest.ResourcePolicy
  • ResourceGroupUpdateResourcesResponse
  • ResourceGroupUpdateResourcesResponse.NodeStatusesEntry
  • ResourceGroupUpdateResponse
  • ResourceGroupUpdateResponse.NodeStatusesEntry
  • UpdateGPUPoliciesRequest
  • UpdateGPUPoliciesRequest.NodeGpuPoliciesEntry
  • UpdateGPUPoliciesResponse
  • UpdateGPUPoliciesResponse.Result
  • WorkloadProfileIDs

• Scalar Value Types

Services

ResourceGroupManagementService

ResourceGroupManagementService manages ephemeral power policy allocations for workloads

This service provides APIs to create, manage, and monitor resource groups - collections of compute resources with customized power policies for specific workloads. Resource groups temporarily override topology-specified power policies during workload execution, enabling dynamic power management optimized for specific computational tasks.

The service integrates with workload schedulers like SLURM to provide power management throughout the workload lifecycle. It supports both static policy assignment and dynamic policy updates based on real-time telemetry data.

Resource groups must be created from an active topology. The topology defines the available entities and baseline power policies that resource groups can override.

ResourceGroupCreate

rpc ResourceGroupCreate(ResourceGroupCreateRequest) ResourceGroupCreateResponse

Create a new empty and inactive resource group.

This is the first step in the resource group lifecycle. The created resource group is initially empty (no resources) and inactive (no policies applied to hardware). Resources must be added and the group activated before power policies take effect.

ResourceGroupDelete

rpc ResourceGroupDelete(ResourceGroupDeleteRequest) ResourceGroupDeleteResponse

Deactivate and delete a given resource group

This permanently removes the resource group and restores all associated hardware resources to their topology-specified power policies. If the resource group is active, it is automatically deactivated before deletion. This is typically called when a workload completes.

ResourceGroupList

rpc ResourceGroupList(ResourceGroupListAllRequest) ResourceGroupListAllResponse

List all available resource groups

Returns comprehensive information about all resource groups in the system, including their activation status, assigned resources, and power policies. This is used for monitoring, administration, and troubleshooting resource group state.

ResourceGroupAddResources

rpc ResourceGroupAddResources(ResourceGroupAddResourcesRequest) ResourceGroupAddResourcesResponse

Add resources to a given resource group. The resource group must be inactive.

This assigns compute resources (nodes) to the resource group before activation. Resources can be assigned group-level or entity-specific power policies. The resource group must be inactive - resources cannot be added to active resource groups.

ResourceGroupRemoveResources

rpc ResourceGroupRemoveResources(ResourceGroupRemoveResourcesRequest) ResourceGroupRemoveResourcesResponse

Remove resources from a given resource group. The resource group must be inactive.

This removes compute resources from the resource group before activation. Used to adjust resource allocation based on workload requirements. The resource group must be inactive - resources cannot be removed from active resource groups.

ActivateResourceGroup

rpc ActivateResourceGroup(ActivateResourceGroupRequest) ActivateResourceGroupResponse

Activate a given resource group. The resource group must be inactive.

This applies the resource group’s power policies to the assigned hardware resources and marks the group as active. The activation process validates power allocation constraints and applies policies to the hardware. Once active, the resource group manages power policies for its assigned resources until deactivation.

ResourceGroupUpdate

rpc ResourceGroupUpdate(ResourceGroupUpdateRequest) ResourceGroupUpdateResponse

Update a resource group policy. The new policy affects all entities in the resource group that does not have entity-level policies set. If the resource group is active, the policy is validated and applied immediately.

This changes the default power policy for the entire resource group. Entities with entity-specific policies are not affected. If the resource group is active, the new policy is immediately validated and applied to hardware. This enables dynamic power optimization during workload execution.

ResourceGroupUpdateResources

rpc ResourceGroupUpdateResources(ResourceGroupUpdateResourcesRequest) ResourceGroupUpdateResourcesResponse

Update policies for some of the resources in the resource group. If the resource group is active, the changes are applied immediately. This API may perform partial updates.

This updates entity-specific power policies for selected resources in the group. If the resource group is active, changes are immediately applied to hardware. The API supports partial updates - some policy changes may succeed while others fail, allowing for selective power optimization.

UpdateGPUPolicies

rpc UpdateGPUPolicies(UpdateGPUPoliciesRequest) UpdateGPUPoliciesResponse

UpdateGPUPolicies allows updating GPU policies without specifying the resource group. Because of this, a single call may end up updating multiple resource groups. If the resource groups are active, the changes are applied immediately.

This provides direct GPU power management without requiring knowledge of resource group assignments. It’s designed for telemetry-driven power optimization where external monitoring systems can adjust GPU power limits based on real-time performance data. A single call may affect multiple resource groups if GPUs span multiple groups.

AsyncOperationStatus

rpc AsyncOperationStatus(ResourceGroupAsyncOperationStatusRequest) ResourceGroupAsyncOperationStatus

Queries the server about the status of an asynchronous operation started by one of the service APIs

Resource group operations (especially activation) can be performed asynchronously for better scalability. This API allows clients to check the progress and results of these asynchronous operations. The operation results are available until explicitly queried and forgotten.

Messages

ActivateResourceGroupRequest

ActivateResourceGroupRequest is used by ResourceGroupManagementService.ActivateResourceGroup.

Validates and applies power policies to all hardware resources in the resource group. Resource group must be inactive with resources added. After activation, workload can start.

Examples: dpsctl resource-group activate –resource-group “rg_$SLURM_JOB_ID” –sync # Synchronous activation dpsctl resource-group activate –resource-group “rg_$SLURM_JOB_ID” # Asynchronous activation dpsctl resource-group activate –resource-group “rg_$SLURM_JOB_ID” –partial-n-hosts 8 # Succeed if ≥8 hosts activate

ActivateResourceGroupResponse

ActivateResourceGroupResponse is returned if resource group activation was successful.

ActivateResourceGroupResponse.NodeStatusesEntry

DeactivateResourceGroupRequest

DeactivateResourceGroupRequest is used to deactivate a resource group and remove applied policies from physical entities.

Removes power policies from hardware resources and returns them to topology defaults. Typically called automatically during resource group deletion. Resource group must be active. After deactivation, resources return to topology defaults.

DeactivateResourceGroupResponse

Empty response from deactivating a resource group

GPUWorkloadProfileResponse

GPUWorkloadProfileResponse describes the result of setting workload profile on one GPU

GPUWorkloadProfileResponses

GPUWorkloadProfileResponse describes the result of setting workload profile on one GPU

NodeStatusResponse

NodeStatusResponse combines the node status and workload profile results

ResourceGroupAddResourcesRequest

ResourceGroupAddResourcesRequest is used by ResourceGroupManagementService.ResourceGroupAddResources.

Adds compute resources (nodes) to an existing inactive resource group before activation. Resource group must be inactive. Resources cannot be added to active resource groups.

Examples: dpsctl resource-group add –resource-group “rg_$SLURM_JOB_ID” –entities “node001,node002” –policy “Node-High” # Add nodes with policy

ResourceGroupAddResourcesResponse

ResourceGroupAddResourcesResponse is returned if adding resources to a resource group was successful.

ResourceGroupAsyncOperationStatus

ResourceGroupAsyncOperationStatus returns the status of an asynchronous resource group operation. After it returns that the operation was completed, the results are forgotten.

ResourceGroupAsyncOperationStatusRequest

ResourceGroupAsyncOperationStatusRequest is used to query the status of an asynchronous operation.

Checks the progress and result of asynchronous resource group operations like activation or updates. Returns operation progress including success count, failure count, and completion status.

ResourceGroupAsyncOperationStatusRequest.ResourceGroupStatusInfo

Resource group information

ResourceGroupAsyncStrategy

ResourceGroupAsyncStrategy specifies the asynchronous resource group activation strategy

ResourceGroupCreateRequest

ResourceGroupCreateRequest is used by the ResourceGroupManagementService.ResourceGroupCreate.

Creates a new, empty, and inactive resource group for managing power policies during workload execution. A resource group must be identified by a unique name, such as slurm job id. When created, the resource group does not have any resources and it is not active.

Examples: dpsctl resource-group create –resource-group “rg_$SLURM_JOB_ID” –external-id “$SLURM_JOB_ID” –policy “Node-Med”

ResourceGroupCreateResponse

ResourceGroupCreateResponse is returned if the resource group is created successfully.

ResourceGroupDeleteRequest

ResourceGroupDeleteRequest is used by ResourceGroupManagementService.ResourceGroupDelete.

Deactivates and deletes a resource group, returning all hardware resources to their topology defaults. The resource group is automatically deactivated if active before deletion.

ResourceGroupDeleteResponse

ResourceGroupDeleteResponse is returned if the resource group deletion was successful.

ResourceGroupListAllRequest

ResourceGroupListAllRequest is used to list resource groups.

Queries all resource groups in the system with optional filtering by activation status. Used for monitoring, administration, and troubleshooting resource group state. Returns comprehensive information including policies, resources, and status for each resource group.

ResourceGroupListAllResponse

Response containing all (filtered) resource group information

ResourceGroupListAllResponse.ResourceGroupInfo

ResourceGroupListAllResponse.ResourceGroupInfo.ResourcePolicy

Define policy for a resource

ResourceGroupPartialActivation

ResourceGroupPartialActivation specifies the parameters for acceptable level of failure during host configuration

ResourceGroupRemoveResourcesRequest

ResourceGroupRemoveResourcesRequest is used by ResourceGroupManagementService.ResourceGroupRemoveResources.

Removes compute resources (nodes) from an existing inactive resource group before activation. Used to adjust resource allocation before the workload starts. Resource group must be inactive. Resources cannot be removed from active resource groups.

ResourceGroupRemoveResourcesResponse

ResourceGroupRemoveResourcesResponse is returned if entity removal was successful.

ResourceGroupUpdateRequest

ResourceGroupUpdateRequest is used by ResourceGroupManagementService.ResourceGroupUpdate to modify the resource group level policy setting.

Updates the default power policy for the entire resource group. Can be used on active or inactive resource groups. If resource group is active, changes are applied immediately to hardware.

Examples: dpsctl resource-group update –resource-group “rg_$SLURM_JOB_ID” –policy “Node-High” –sync # Synchronous update

ResourceGroupUpdateResourcesRequest

ResourceGroupUpdateResourcesRequest is used by ResourceGroupManagementService.ResourceGroupUpdateResources.

Updates power policies for individual entities (nodes) within the resource group. If resource group is active, changes are applied immediately to hardware.

ResourceGroupUpdateResourcesRequest.ResourcePolicy

Specifies the resource and the policy to apply to that resource. To remove a policy from a resource, don’t include optional policy

ResourceGroupUpdateResourcesResponse

Empty response from updating resources for a resource group

ResourceGroupUpdateResourcesResponse.NodeStatusesEntry

ResourceGroupUpdateResponse

ResourceGroupUpdateResponse is returned if resource group update was successful.

ResourceGroupUpdateResponse.NodeStatusesEntry

UpdateGPUPoliciesRequest

UpdateGPUPoliciesRequest is used by ResourceGroupManagementService.UpdateGPUPolicies to update GPU power policies without a reference to the resource group.

Updates individual GPU power limits based on real-time telemetry data from external monitoring systems. Used for dynamic power optimization during workload execution without knowing resource group details. All GPUs in a node must be specified or the update fails. Updates node-level policy to satisfy aggregate GPU requirements.

UpdateGPUPoliciesRequest.NodeGpuPoliciesEntry

UpdateGPUPoliciesResponse

UpdateGPUPoliciesResponse describes the result of each update operation

UpdateGPUPoliciesResponse.Result

Result describes the result of setting the power limit of one GPU

WorkloadProfileIDs

WorkloadProfileIDs is a wrapper around an array of workload profile IDs

Scalar Value Types