v1/policy.proto#

Policy specifies the power policies for devices. Policies are defined within a topology with unique names describing the power min-max values.

Services#

PolicyService#

PolicyService manages policy bundles and their bindings.

GetBundle#

rpc GetBundle(PolicyBundleGetRequest) returns PolicyBundle

GetBundle retrieves one named policy bundle.

Upsert#

rpc Upsert(PolicyUpsertRequest) returns Status

Upsert creates a policy bundle or replaces its complete policy set.

Delete#

rpc Delete(PolicyBundleDeleteRequest) returns Status

Delete deletes a policy bundle and all of its bindings.

CreateBinding#

rpc CreateBinding(PolicyBindingCreateRequest) returns PolicyBindingCreateResponse

CreateBinding creates a user-owned policy bundle binding.

GetBinding#

rpc GetBinding(PolicyBindingGetRequest) returns PolicyBinding

GetBinding retrieves one policy binding by UUID.

UpdateBinding#

rpc UpdateBinding(PolicyBindingUpdateRequest) returns Status

UpdateBinding replaces the scope and level of a user-owned policy binding.

DeleteBinding#

rpc DeleteBinding(PolicyBindingDeleteRequest) returns Status

DeleteBinding deletes one user-owned policy binding.

DeleteAllBindings#

rpc DeleteAllBindings(PolicyBindingsDeleteAllRequest) returns Status

DeleteAllBindings deletes all user-owned bindings for a policy bundle.

ListBundles#

rpc ListBundles(PolicyBundleListRequest) returns PolicyBundleListResponse

ListBundles returns one bounded page of policy bundles.

ListBindings#

rpc ListBindings(PolicyBindingListRequest) returns PolicyBindingListResponse

ListBindings returns one bounded page of policy bindings.

Messages#

APPMPolicy#

An APPM.v1 policy type defines APPM settings.

Field

Type

Description

scope

PolicyScope

Defines which entities/resource groups the policy applies to.

spec

APPMSpec

Specifies the policy spec.

APPMSpec#

APPMSpec specifies the APPM policy values

Field

Type

Description

value

APPMSpec.Enabled

none

AggregatePowerLimitsPolicy#

An AggregatePowerLimits.v1 policy participates in per-entity effective-policy composition. Runtime validation groups complete compute nodes that carry the same composed effective policy and limits the sum of their SetPointWatts.

Field

Type

Description

scope

PolicyScope

Defines which entities/resource groups the policy applies to.

spec

AggregatePowerLimitsSpec

Specifies the policy spec.

AggregatePowerLimitsSpec#

AggregatePowerLimitsSpec specifies aggregate power limits for complete compute nodes that carry the same composed effective AggregatePowerLimits policy. Runtime validation sums the SetPointWatts of each node once within the effective policy group; TargetWatts and LoadWatts are not included. A proposed allocation is rejected when any group violates its floor or ceiling. Partial-node allocation is out of scope.

Field

Type

Description

ceiling_watts

double

Max power limit for the aggregate scope. Must be finite and greater than or equal to 0.

floor_watts

double

Min power limit for the aggregate scope. Must be finite and greater than or equal to 0.

ComputerSystemLimitsPolicy#

A ComputerSystemLimit.v1 policy type can be bound to any ComputerSystem type device or entity, as designated by the Scope field. Some ComputerSystem devices may be suited for a more specific policy (e.g. VeraRubinLimits.v1).

Field

Type

Description

scope

PolicyScope

Defines which entities/resource groups the policy applies to

spec

ComputerSystemLimitsSpec

Specifies the policy spec.

ComputerSystemLimitsSpec#

ComputerSystemLimitsSpec specifies the computer system operating range. Node, GPU, CPU, and memory ranges are independently optional, but at least one range value must be set.

Field

Type

Description

oneof range_spec.operating_range_watts

ComputerSystemLimitsSpec.OperatingRange

Node operating range in watts

oneof range_spec.operating_range_percent

ComputerSystemLimitsSpec.OperatingRange

Node operating range in percentages of device max

gpu_target_percent

double

Relative GPU target, as a percentage. This value represents a % of the node ceiling. Zero means no GPU target is set. Must be finite and between 0 and 100, inclusive.

cpu_target_percent

double

Relative CPU target, as a percentage. This value represents a % of the node ceiling. Zero means no CPU target is set. Must be finite and between 0 and 100, inclusive.

memory_target_percent

double

Relative Memory target, as a percentage. This value represents a % of the node ceiling. Zero means no memory target is set. Must be finite and between 0 and 100, inclusive.

gpu_ceiling_percent

double

Relative GPU ceiling, as a percentage. This value represents a % of the node ceiling. Zero means no GPU ceiling is set. Must be finite and between 0 and 100, inclusive.

gpu_floor_percent

double

Relative GPU floor, as a percentage. This value represents a % of the node ceiling. Zero means no GPU floor is set. Must be finite and between 0 and 100, inclusive.

cpu_ceiling_percent

double

Relative CPU ceiling, as a percentage. This value represents a % of the node ceiling. Zero means no CPU ceiling is set. Must be finite and between 0 and 100, inclusive.

cpu_floor_percent

double

Relative CPU floor, as a percentage. This value represents a % of the node ceiling. Zero means no CPU floor is set. Must be finite and between 0 and 100, inclusive.

memory_ceiling_percent

double

Relative memory ceiling, as a percentage. This value represents a % of the node ceiling. Zero means no memory ceiling is set. Must be finite and between 0 and 100, inclusive.

memory_floor_percent

double

Relative memory floor, as a percentage. This value represents a % of the node ceiling. Zero means no memory floor is set. Must be finite and between 0 and 100, inclusive.

gpu_target_watts

double

GPU target in watts. Zero means no GPU target is set. Must be finite and greater than or equal to 0.

cpu_target_watts

double

CPU target in watts. Zero means no CPU target is set. Must be finite and greater than or equal to 0.

memory_target_watts

double

Memory target in watts. Zero means no memory target is set. Must be finite and greater than or equal to 0.

gpu_ceiling_watts

double

GPU ceiling in watts. Zero means no GPU ceiling is set. Must be finite and greater than or equal to 0.

gpu_floor_watts

double

GPU floor in watts. Zero means no GPU floor is set. Must be finite and greater than or equal to 0.

cpu_ceiling_watts

double

CPU ceiling in watts. Zero means no CPU ceiling is set. Must be finite and greater than or equal to 0.

cpu_floor_watts

double

CPU floor in watts. Zero means no CPU floor is set. Must be finite and greater than or equal to 0.

memory_ceiling_watts

double

Memory ceiling in watts. Zero means no memory ceiling is set. Must be finite and greater than or equal to 0.

memory_floor_watts

double

Memory floor in watts. Zero means no memory floor is set. Must be finite and greater than or equal to 0.

ComputerSystemLimitsSpec.OperatingRange#

Field

Type

Description

ceiling

double

Operating range ceiling. Zero means no upper bound. Must be finite and greater than or equal to 0.

target

double

Operating range target. Zero means unspecified. Must be finite and greater than or equal to 0.

floor

double

Operating range floor. Zero means no lower bound. Must be finite and greater than or equal to 0.

DPMPolicy#

A DPM.v1 policy type defines dynamic power management settings.

Field

Type

Description

scope

PolicyScope

Defines which entities/resource groups the policy applies to.

spec

DPMSpec

Specifies the policy spec.

DPMSpec#

DPMSpec specifies dynamic power management policy settings.

Field

Type

Description

oneof _strategy.strategy

optional DPMSpec.Strategy

Strategy selects the dynamic power management optimization strategy.

oneof _power_shift.power_shift

optional DPMSpec.Shift

PowerShift selects the power-shift behavior.

oneof _grid_shift.grid_shift

optional DPMSpec.Shift

GridShift selects the grid-shift behavior.

oneof _real_time_shift.real_time_shift

optional DPMSpec.Shift

RealTimeShift selects the real-time-shift behavior.

EPDPolicy#

An EPD.v1 policy type defines EPD settings.

Field

Type

Description

scope

PolicyScope

Defines which entities/resource groups the policy applies to.

spec

EPDSpec

Specifies the policy spec.

EPDSpec#

EPDSpec specifies the EPD policy values

Field

Type

Description

value

EPDSpec.Enabled

none

GPUPolicies#

GPUPolicies is a list of GPUPolicy objects. Each policy in the list should address a unique GPU.

Field

Type

Description

policies

repeated GPUPolicy

The GPU policies. Each policy should address a distinct GPU

GPUPolicy#

GPUPolicy specifies the power policy for a single GPU in a node.

Field

Type

Description

oneof _gpu_id.gpu_id

optional uint32

The zero-based GPU index within the node. The gpu_id name is retained for API compatibility. UpdateGPUPolicies requests must provide gpu_id or gpu_uuid; when both are provided, they must identify the same GPU.

oneof _power_limit.power_limit

optional PowerLimit

The power limit. Null value means the GPU does not have a set policy. Use null to remove GPU-specific policy assignment

oneof _gpu_uuid.gpu_uuid

optional string

Hardware-backed Redfish Processor UUID. UpdateGPUPolicies requests may use this as the GPU selector instead of gpu_id. Other request paths do not use UUID selection. Responses include both identifiers when known.

PRSPolicy#

A PRS.v1 policy type defines PRS settings.

Field

Type

Description

scope

PolicyScope

Defines which entities/resource groups the policy applies to.

spec

PRSSpec

Specifies the policy spec.

PRSSpec#

PRSSpec specifies the PRS policy values

Field

Type

Description

value

PRSSpec.Enabled

none

Policy#

Policy combines all known policy types

Field

Type

Description

oneof Policy.computer_system_limits

ComputerSystemLimitsPolicy

none

oneof Policy.dpm

DPMPolicy

none

oneof Policy.prs

PRSPolicy

none

oneof Policy.appm

APPMPolicy

none

oneof Policy.epd

EPDPolicy

none

oneof Policy.aggregate_power_limits

AggregatePowerLimitsPolicy

none

oneof Policy.wpps

WPPSPolicy

none

PolicyApplyStatus#

Policy application status including applied policy details

Field

Type

Description

policy

PolicyObject

The policy that was applied

status

Status

Operation status

PolicyBinding#

PolicyBinding describes one persisted policy bundle binding.

Field

Type

Description

binding_id

string

UUID identifier of the binding.

policy_bundle

string

Name of the bound policy bundle.

scope

PolicyScope

Scope to which the policy bundle is bound.

created_by

PolicyBindingCreatedBy

Subsystem that owns the binding. Only user-created bindings may be modified through PolicyService binding mutation APIs.

policy_level

PolicyLevel

Composition precedence for this binding. Policy level does not constrain the scope.

PolicyBindingCreateRequest#

PolicyBindingCreateRequest creates a user-owned policy binding.

Field

Type

Description

policy_bundle

string

Unique policy bundle name.

scope

PolicyScope

Scope to which the policy bundle is bound.

policy_level

PolicyLevel

Composition precedence for the binding. Policy level does not constrain the scope.

PolicyBindingCreateResponse#

PolicyBindingCreateResponse identifies the newly created binding.

Field

Type

Description

status

Status

Operation status.

binding_id

string

UUID identifier for the new binding.

PolicyBindingDeleteRequest#

PolicyBindingDeleteRequest identifies a user-owned binding to delete.

Field

Type

Description

binding_id

string

UUID identifier of the binding.

PolicyBindingGetRequest#

PolicyBindingGetRequest identifies a policy binding to retrieve.

Field

Type

Description

binding_id

string

UUID identifier of the binding.

PolicyBindingListRequest#

PolicyBindingListRequest requests one page of policy bindings.

Field

Type

Description

page_size

int32

Maximum number of bindings to return. Zero uses the server default of 50; values greater than 100 are reduced to 100.

page_token

string

Opaque token returned by a previous ListBindings call.

PolicyBindingListResponse#

PolicyBindingListResponse contains one page of policy bindings.

Field

Type

Description

policy_bindings

repeated PolicyBinding

Policy bindings in ascending binding ID order.

next_page_token

string

Opaque token for the next page. Empty when no more bindings remain.

PolicyBindingUpdateRequest#

PolicyBindingUpdateRequest replaces a user-owned binding’s scope and level.

Field

Type

Description

binding_id

string

UUID identifier of the binding.

scope

PolicyScope

Replacement binding scope.

policy_level

PolicyLevel

Replacement composition precedence. Policy level does not constrain the scope.

PolicyBindingsDeleteAllRequest#

PolicyBindingsDeleteAllRequest removes every user-owned binding for a bundle.

Field

Type

Description

policy_bundle

string

Unique policy bundle name.

PolicyBundle#

A PolicyBundle groups policies

Field

Type

Description

name

string

Optional bundle name. A bundle name is required if the PolicyBundle is used as an input from the end-user or when it is stored in to a db, but it does not need a name when the policy bundle is used simply as a set of policies.

policies

repeated Policy

Polymorphic policy list contained in the bundle

updated_at

google.protobuf.Timestamp

The timestamp policy bundle was last updated at

PolicyBundleDeleteRequest#

PolicyBundleDeleteRequest identifies a policy bundle to delete.

Field

Type

Description

policy_bundle

string

Unique policy bundle name.

PolicyBundleGetRequest#

PolicyBundleGetRequest identifies a policy bundle to retrieve.

Field

Type

Description

policy_bundle

string

Unique policy bundle name.

PolicyBundleListRequest#

PolicyBundleListRequest requests one page of policy bundles.

Field

Type

Description

page_size

int32

Maximum number of bundles to return. Zero uses the server default of 50; values greater than 100 are reduced to 100.

page_token

string

Opaque token returned by a previous ListBundles call.

PolicyBundleListResponse#

PolicyBundleListResponse contains one page of policy bundles.

Field

Type

Description

policy_bundles

repeated PolicyBundle

Policy bundles in ascending name order.

next_page_token

string

Opaque token for the next page. Empty when no more bundles remain.

PolicyLimit#

PolicyLimit specifies a power limit for a specific entity type.

Field

Type

Description

element_type

PolicyElementType

The entity type to which the power limit applies. A valid PolicyObject must include at least one limit with POLICY_ELEMENT_TYPE_NODE (Node). Must be a defined enum value.

power_limit

PowerLimit

The power limit value

PolicyObject#

PolicyObject specifies a topology or resource group entity power policy.

Field

Type

Description

name

string

Name of the policy. The name must be unique within a topology.

limits

repeated PolicyLimit

Limits for the policy. Must contain at least one item and include at least one limit with element_type NODE.

properties

google.protobuf.Struct

Properties for the policy

PolicyScope#

PolicyScope selects the entities to which a policy applies. It is the sole binding selector; PolicyLevel controls precedence only. Entities are selected by:

  • entity name, or other entity properties

  • entity device properties

  • entity membership in a resource group

  • go-expr expression that selects entities

Structured resource-group scopes also participate in parent-to-child policy inheritance when used by the effective-policy resolver.

Field

Type

Description

oneof scope.entities

PolicyScope.Entities

none

oneof scope.devices

PolicyScope.Devices

none

oneof scope.resource_groups

PolicyScope.ResourceGroups

none

oneof scope.expr

string

none

PolicyScope.Device#

Device message type contains the device type and model. Both fields are optional, but at least one must be present

Field

Type

Description

type

string

none

model

string

none

PolicyScope.Devices#

Devices message type contains a list of entity devices

Field

Type

Description

devices

repeated PolicyScope.Device

Entity devices in scope. Must contain at least one item.

PolicyScope.Entities#

Entities message type contains entity names

Field

Type

Description

entities

repeated string

Entity names in scope. Each entity name must not be empty.

PolicyScope.ResourceGroups#

ResourceGroups message type contains resource groups by id

Field

Type

Description

resource_groups

repeated string

Resource group ids in scope. Each resource group id must not be empty.

PolicyUpsertRequest#

PolicyUpsertRequest creates or replaces a named policy bundle.

Field

Type

Description

policy_bundle

PolicyBundle

Policy bundle to create or replace.

PowerLimit#

PowerLimit specifies a power limit for a specific entity

Field

Type

Description

oneof power_limit.watts

double

Power limit in watts. Must be finite and greater than 0.

oneof power_limit.percentage

double

Power limit as a percentage. Must be finite and greater than 0 and no more than 100.

WPPSPolicy#

A WPPS.v1 policy type defines workload profile settings.

Field

Type

Description

scope

PolicyScope

Defines which entities/resource groups the policy applies to.

spec

WPPSSpec

Specifies the complete desired workload profile set. Omitted and empty repeated values both mean an empty desired set and explicitly clear all workload profiles.

WPPSSpec#

WPPSSpec specifies the complete desired workload profile set.

Field

Type

Description

profile_ids

repeated int32

Profile IDs are the complete desired set. Omitted and empty repeated values both mean an empty desired set and explicitly clear all workload profiles.

Enums#

APPMSpec.Enabled#

Name

Number

Description

UNSPECIFIED

0

none

DISABLED

1

none

ENABLED

2

none

DPMSpec.Shift#

Shift controls an individual DPM adjustment path, such as power, grid, or real-time shifting. Disabled/enabled values express normal policy intent; force values make that intent restrictive for lower-priority policies.

Name

Number

Description

SHIFT_UNSPECIFIED

0

none

SHIFT_DISABLED

1

none

SHIFT_ENABLED

2

none

SHIFT_FORCE_DISABLED

3

none

SHIFT_FORCE_ENABLED

4

none

DPMSpec.Strategy#

Strategy selects the dynamic power management optimization strategy.

Name

Number

Description

STRATEGY_UNSPECIFIED

0

none

STRATEGY_UNIFORM

1

DPS allocates power uniformly across the specified policy scope

Example: Nodes in a resource group. * Scope: Nodes in an RG * Previous Node Policies: 5600W, 4300W, 3200W, 5600W * New Node Policies (stealing 800W total power, 200W per node): 5400W, 4100W, 3000W, 5400W | | STRATEGY_PROPORTIONAL | 2 | none | | STRATEGY_GREEDY | 3 | DPS allocates power according to highest & lowest policy. Here, the highest power jobs will be stolen from first, and lowest power jobs given back to first. This strategy should be used to decrease the number of policy allocations.

Example: High power job * Scope: Topology * Previous Job Policies Job 1: 10kW, Job 2: 2kW, Job 3: 8kW * New Job Policies (stealing 1.5kW of power) Job 1: 8.5kw, Job 2: 2kW, Job 3: 8kW |

EPDSpec.Enabled#

Name

Number

Description

UNSPECIFIED

0

none

DISABLED

1

none

ENABLED

2

none

PRSSpec.Enabled#

Name

Number

Description

UNSPECIFIED

0

none

DISABLED

1

none

ENABLED

2

none

FORCE_DISABLED

3

none

FORCE_ENABLED

4

none

PolicyBindingCreatedBy#

PolicyBindingCreatedBy identifies the subsystem that owns a binding.

Name

Number

Description

POLICY_BINDING_CREATED_BY_UNSPECIFIED

0

none

POLICY_BINDING_CREATED_BY_USER

1

none

POLICY_BINDING_CREATED_BY_TOPOLOGY

2

none

POLICY_BINDING_CREATED_BY_RESOURCE_GROUP

3

none

PolicyElementType#

PolicyElementType specifies the type of entity to which the power limit applies

Name

Number

Description

POLICY_ELEMENT_TYPE_NODE

0

none

POLICY_ELEMENT_TYPE_GPU

1

none

POLICY_ELEMENT_TYPE_CPU

2

none

POLICY_ELEMENT_TYPE_MEMORY

3

none

PolicyLevel#

PolicyLevel determines policy precedence during effective-policy composition. A binding’s scope selects which entities receive that binding; individual policy types may further scope their own applicability. This enum does not constrain where a binding applies. Precedence increases from global through entity.

Name

Number

Description

POLICY_LEVEL_UNSPECIFIED

0

none

POLICY_LEVEL_GLOBAL

1

none

POLICY_LEVEL_TOPOLOGY

2

none

POLICY_LEVEL_RESOURCE_GROUP

3

none

POLICY_LEVEL_ENTITY

4

none

Scalar Value Types#

.proto Type

Notes

C++ Type

Java Type

Python Type

double

double

double

float

float

float

float

float

int32

Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.

int32

int

int

int64

Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.

int64

long

int/long

uint32

Uses variable-length encoding.

uint32

int

int/long

uint64

Uses variable-length encoding.

uint64

long

int/long

sint32

Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.

int32

int

int

sint64

Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.

int64

long

int/long

fixed32

Always four bytes. More efficient than uint32 if values are often greater than 2^28.

uint32

int

int

fixed64

Always eight bytes. More efficient than uint64 if values are often greater than 2^56.

uint64

long

int/long

sfixed32

Always four bytes.

int32

int

int

sfixed64

Always eight bytes.

int64

long

int/long

bool

bool

boolean

boolean

string

A string must always contain UTF-8 encoded or 7-bit ASCII text.

string

String

str/unicode

bytes

May contain any arbitrary sequence of bytes.

string

ByteString

str