diff --git a/rest-api/api/pkg/api/model/taskrun.go b/rest-api/api/pkg/api/model/taskrun.go
index a33e72afe7..bdd2042e30 100644
--- a/rest-api/api/pkg/api/model/taskrun.go
+++ b/rest-api/api/pkg/api/model/taskrun.go
@@ -586,9 +586,9 @@ func (atrcr *APITaskRunCancelRequest) Validate() error {
// ~~~~~ Create ~~~~~ //
// APITaskRunCreateRequest is the JSON body for POST /task/run. A run executes
-// exactly one operation (currently firmware) across a candidate set of racks,
-// narrowed by an optional selector and divided into phases by an optional phase
-// policy. operationType is inferred from the operation and is not accepted here.
+// exactly one operation across a candidate set of racks, narrowed by an
+// optional selector and divided into phases by an optional phase policy.
+// operationType is inferred from the operation and is not accepted here.
type APITaskRunCreateRequest struct {
SiteID string `json:"siteId"`
Name string `json:"name"`
diff --git a/rest-api/api/pkg/api/pagination/pagination.go b/rest-api/api/pkg/api/pagination/pagination.go
index d77f1dfe73..4e7f6cfa2b 100644
--- a/rest-api/api/pkg/api/pagination/pagination.go
+++ b/rest-api/api/pkg/api/pagination/pagination.go
@@ -5,6 +5,7 @@ package pagination
import (
"fmt"
+ "math"
"regexp"
"strings"
@@ -19,6 +20,13 @@ const (
// MaxPageSize is the maximum page size allowed
MaxPageSize = 100
+ // MaxPageNumber is the maximum page number allowed. It bounds PageNumber so
+ // that the largest offset Validate can derive, (MaxPageNumber-1) *
+ // MaxPageSize, still fits the int32 every consumer narrows Offset to. Past
+ // that the narrowed offset wraps to an unrelated or negative value and the
+ // response reports a page it does not contain.
+ MaxPageNumber = math.MaxInt32 / MaxPageSize
+
// ResponseHeaderName describes the header name for the pagination response
ResponseHeaderName = "X-Pagination"
)
@@ -50,10 +58,11 @@ func (pr *PageRequest) Validate(orderByFields []string) error {
err := validation.ValidateStruct(pr,
validation.Field(&pr.PageNumber,
validation.Min(1).Error("must be greater than 0"),
+ validation.Max(MaxPageNumber).Error(fmt.Sprintf("must be less than or equal to: %v", MaxPageNumber)),
),
validation.Field(&pr.PageSize,
validation.Min(1).Error("must be greater than 0"),
- validation.Max(MaxPageSize).Error(fmt.Sprintf("must be less that or equal to: %v", MaxPageSize)),
+ validation.Max(MaxPageSize).Error(fmt.Sprintf("must be less than or equal to: %v", MaxPageSize)),
),
validation.Field(&pr.OrderByStr,
validation.Match(regexp.MustCompile(OrderByRegex)).Error(fmt.Sprintf("must be in the format of field_%v or field_%v", cdbp.OrderAscending, cdbp.OrderDescending)),
diff --git a/rest-api/api/pkg/api/pagination/pagination_test.go b/rest-api/api/pkg/api/pagination/pagination_test.go
index d016baa3dc..7ec56d96b7 100644
--- a/rest-api/api/pkg/api/pagination/pagination_test.go
+++ b/rest-api/api/pkg/api/pagination/pagination_test.go
@@ -4,6 +4,7 @@
package pagination
import (
+ "math"
"testing"
cutil "github.com/NVIDIA/infra-controller/rest-api/common/pkg/util"
@@ -89,6 +90,32 @@ func TestPageRequest_Validate(t *testing.T) {
},
wantErr: true,
},
+ {
+ name: "test Page Request validate success, largest page number and size",
+ fields: fields{
+ PageNumber: cutil.GetPtr(MaxPageNumber),
+ PageSize: cutil.GetPtr(MaxPageSize),
+ },
+ args: args{
+ orderByFields: []string{"name"},
+ },
+ want: &PageRequest{
+ Offset: cutil.GetPtr((MaxPageNumber - 1) * MaxPageSize),
+ Limit: cutil.GetPtr(MaxPageSize),
+ },
+ wantErr: false,
+ },
+ {
+ name: "test Page Request validate error, page number too large",
+ fields: fields{
+ PageNumber: cutil.GetPtr(MaxPageNumber + 1),
+ PageSize: cutil.GetPtr(MaxPageSize),
+ },
+ args: args{
+ orderByFields: []string{"name"},
+ },
+ wantErr: true,
+ },
{
name: "test Page Request validate error, invalid order by",
fields: fields{
@@ -139,6 +166,10 @@ func TestPageRequest_Validate(t *testing.T) {
assert.Equal(t, *tt.want.Offset, *pr.Offset)
assert.Equal(t, *tt.want.Limit, *pr.Limit)
+ // Consumers narrow Offset to int32; MaxPageNumber exists to keep
+ // every accepted request inside that range.
+ assert.LessOrEqual(t, *pr.Offset, math.MaxInt32)
+
if tt.want.OrderBy != nil {
assert.Equal(t, tt.want.OrderBy.Field, pr.OrderBy.Field)
assert.Equal(t, tt.want.OrderBy.Order, pr.OrderBy.Order)
diff --git a/rest-api/docs/index.html b/rest-api/docs/index.html
index 475ab771dc..6e6b9df4e1 100644
--- a/rest-api/docs/index.html
+++ b/rest-api/docs/index.html
@@ -958,7 +958,7 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Search string to filter Tenant Accounts by account number, tenant org, or tenant org display name
includeRelation
string
Enum:"InfrastructureProvider""Tenant"
Related entity to expand
-
pageNumber
integer >= 1
Default: 1
Example: pageNumber=1
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Default: 1
Example: pageNumber=1
Page number for pagination query
pageSize
integer [ 1 .. 100 ]
Example: pageSize=20
Page size for pagination query
@@ -1376,7 +1376,7 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Search for matches across all Sites. Input will be matched against name, description, location, contact, and status fields
includeRelation
string
Value:"InfrastructureProvider"
Related entity to expand
-
pageNumber
integer >= 1
Default: 1
Example: pageNumber=1
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Default: 1
Example: pageNumber=1
Page number for pagination query
pageSize
integer [ 1 .. 100 ]
Example: pageSize=20
Page size for pagination query
@@ -2032,9 +2032,9 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Name of the Org
siteId
required
string <uuid>
ID of the Site
-
query Parameters
pageNumber
integer
query Parameters
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Page number for pagination query
-
pageSize
integer
pageSize
integer [ 1 .. 100 ]
Page size for pagination query
orderBy
string
Ordering for pagination query
@@ -2454,9 +2454,9 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Name of the Org
query Parameters
siteId
required
string <uuid>
ID of the Site
-
pageNumber
integer
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Page number of results returned
-
pageSize
integer
pageSize
integer [ 1 .. 100 ]
Number of results per page
orderBy
string
Default: "ID_ASC"
Enum:"ID_ASC""ID_DESC"
Order results by endpoint ID
@@ -2602,7 +2602,7 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Search for matches across all Allocations. Input will be matched against name, description, and status fields
includeRelation
string
Enum:"InfrastructureProvider""Tenant""Site"
Related entity to expand
-
pageNumber
integer >= 1
Default: 1
Example: pageNumber=1
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Default: 1
Example: pageNumber=1
Page number for pagination query
pageSize
integer [ 1 .. 100 ]
Example: pageSize=20
Page size for pagination query
@@ -3032,7 +3032,7 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Search for matches across all VPCs. Input will be matched against name, description, labels, and status fields
Optional Site ID filter. If provided, caller must have access to the specified Site.
-
pageNumber
integer >= 1
Default: 1
Example: pageNumber=1
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Default: 1
Example: pageNumber=1
Page number for pagination query
pageSize
integer [ 1 .. 100 ]
Example: pageSize=20
Page size for pagination query
@@ -4150,7 +4150,7 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Related entity to expand
includeUsageStats
boolean
When true, each VPC Prefix object includes usage statistics using the same structure as IP Block usage. Prefix and IP usage data is derived by evaluating associated Ethernet interfaces. Each Interface associated with a VPC Prefix consumes a /31 prefix.
-
pageNumber
integer >= 1
Default: 1
Example: pageNumber=1
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Default: 1
Example: pageNumber=1
Page number for pagination query
pageSize
integer [ 1 .. 100 ]
Example: pageSize=20
Page size for pagination query
@@ -4430,7 +4430,7 @@
Typical API Call Flow for Tenant
Prefix and IP usage data is derived by evaluating associated Ethernet interfaces. Each Interface associated with a Subnet consumes a single IP. In addition, one gateway and one broadcast IP address are reserved per Subnet.</p>
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
When true, each Subnet object includes usage statistics using the same structure as IP Block usage.
Prefix and IP usage data is derived by evaluating associated Ethernet interfaces. Each Interface associated with a Subnet consumes a single IP. In addition, one gateway and one broadcast IP address are reserved per Subnet.
-
pageNumber
integer >= 1
Default: 1
Example: pageNumber=1
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Default: 1
Example: pageNumber=1
Page number for pagination query
pageSize
integer [ 1 .. 100 ]
Example: pageSize=20
Page size for pagination query
@@ -4928,7 +4928,7 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
ID of the Site to filter Expected Machines by
includeRelation
string
Enum:"Site""Sku"
Related entity to expand
-
pageNumber
integer >= 1
Default: 1
Example: pageNumber=1
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Default: 1
Example: pageNumber=1
Page number for pagination query
pageSize
integer [ 1 .. 100 ]
Example: pageSize=20
Page size for pagination query
@@ -5714,7 +5714,7 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
ID of the Site to filter Expected Power Shelves by
includeRelation
string
Value:"Site"
Related entity to expand
-
pageNumber
integer >= 1
Default: 1
Example: pageNumber=1
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Default: 1
Example: pageNumber=1
Page number for pagination query
pageSize
integer [ 1 .. 100 ]
Example: pageSize=20
Page size for pagination query
@@ -6006,7 +6006,7 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
ID of the Site to filter Expected Racks by
includeRelation
string
Value:"Site"
Related entity to expand
-
pageNumber
integer >= 1
Default: 1
Example: pageNumber=1
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Default: 1
Example: pageNumber=1
Page number for pagination query
pageSize
integer [ 1 .. 100 ]
Example: pageSize=20
Page size for pagination query
@@ -6336,7 +6336,7 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
ID of the Site to filter Expected Switches by
includeRelation
string
Value:"Site"
Related entity to expand
-
pageNumber
integer >= 1
Default: 1
Example: pageNumber=1
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Default: 1
Example: pageNumber=1
Page number for pagination query
pageSize
integer [ 1 .. 100 ]
Example: pageSize=20
Page size for pagination query
@@ -6582,7 +6582,7 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Name of the Org
query Parameters
siteId
required
string <uuid>
ID of the Site to retrieve SKUs from
-
pageNumber
integer >= 1
Default: 1
Example: pageNumber=1
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Default: 1
Example: pageNumber=1
Page number for pagination query
pageSize
integer [ 1 .. 100 ]
Example: pageSize=20
Page size for pagination query
@@ -7150,7 +7150,7 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Search for matches across all InfiniBand Partitions. Input will be matched against name, description, and status fields
includeRelation
string
Enum:"Site""VPC""Tenant"
Related entity to expand
-
pageNumber
integer >= 1
Default: 1
Example: pageNumber=1
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Default: 1
Example: pageNumber=1
Page number for pagination query
pageSize
integer [ 1 .. 100 ]
Example: pageSize=20
Page size for pagination query
@@ -7428,7 +7428,7 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Filter InfiniBand Interfaces by Status. Can be specified multiple times to filter on more than one status.
includeRelation
string
Enum:"Instance""InfiniBandPartition""Site"
Related entity to expand
-
pageNumber
integer >= 1
Default: 1
Example: pageNumber=1
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Default: 1
Example: pageNumber=1
Page number for pagination query
pageSize
integer [ 1 .. 100 ]
Example: pageSize=20
Page size for pagination query
@@ -7496,7 +7496,7 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Include VPCs in response.
includeRelation
string
Enum:"Site""Tenant"
Related entity to expand
-
pageNumber
integer >= 1
Default: 1
Example: pageNumber=1
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Default: 1
Example: pageNumber=1
Page number for pagination query
pageSize
integer [ 1 .. 100 ]
Example: pageSize=20
Page size for pagination query
@@ -7732,7 +7732,7 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Filter NVLink Interfaces by NVLink Domain ID. Can be specified multiple times to filter on more than one ID.
includeRelation
string
Enum:"Instance""NVLinkLogicalPartition"
Related entity to expand
-
pageNumber
integer >= 1
Default: 1
Example: pageNumber=1
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Default: 1
Example: pageNumber=1
Page number for pagination query
pageSize
integer [ 1 .. 100 ]
Example: pageSize=20
Page size for pagination query
@@ -7814,7 +7814,7 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Provide query to search for matches. Input will be matched against name, description and status fields
includeRelation
string
Enum:"InfrastructureProvider""Tenant"
Related entity to expand
-
pageNumber
integer >= 1
Default: 1
Example: pageNumber=1
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Default: 1
Example: pageNumber=1
Page number for pagination query
pageSize
integer [ 1 .. 100 ]
Example: pageSize=20
Page size for pagination query
@@ -8386,7 +8386,7 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Name of the Org
query Parameters
siteId
Array of strings <uuid> [ items <uuid > ]
Optional site ID(s); may be repeated to restrict results to templates available at any of the sites
-
pageNumber
integer >= 1
Default: 1
Example: pageNumber=1
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Default: 1
Example: pageNumber=1
Page number for pagination query
pageSize
integer [ 1 .. 100 ]
Example: pageSize=20
Page size for pagination query
@@ -8472,7 +8472,7 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Include Allocation stats.
excludeUnallocated
boolean
Excludes Instance Type records that have no allocations from being returned in the result set. Currently can only be requested by Tenant.
-
pageNumber
integer >= 1
Default: 1
Example: pageNumber=1
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Default: 1
Example: pageNumber=1
Page number for pagination query
pageSize
integer [ 1 .. 100 ]
Example: pageSize=20
Page size for pagination query
@@ -9002,7 +9002,7 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Name of the Org
instanceTypeId
required
string <uuid>
ID of the Instance Type
-
query Parameters
pageNumber
integer >= 1
Default: 1
Example: pageNumber=1
query Parameters
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Default: 1
Example: pageNumber=1
Page number for pagination query
pageSize
integer [ 1 .. 100 ]
Example: pageSize=20
Page size for pagination query
@@ -9132,7 +9132,7 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Search for matches across all Instances. Input will be matched against name, description, status, and labels fields
Filter NVLink Interfaces by Status. Can be specified multiple times to filter on more than one status.
includeRelation
string
Enum:"Instance""NVLinkLogicalPartition"
Related entity to expand
-
pageNumber
integer >= 1
Default: 1
Example: pageNumber=1
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Default: 1
Example: pageNumber=1
Page number for pagination query
pageSize
integer [ 1 .. 100 ]
Example: pageSize=20
Page size for pagination query
@@ -10852,7 +10852,7 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Provide query to search for matches. Input will be matched against Machine ID, vendor, product name, hostname and status
includeRelation
string
Enum:"InfrastructureProvider""Site""InstanceType"
Related entity to expand
-
pageNumber
integer >= 1
Default: 1
Example: pageNumber=1
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Default: 1
Example: pageNumber=1
Page number for pagination query
pageSize
integer [ 1 .. 100 ]
Example: pageSize=20
Page size for pagination query
@@ -11578,9 +11578,9 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Name of the Org
machineId
required
string
ID of the Machine
-
query Parameters
pageNumber
integer
query Parameters
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Page number for pagination query
-
pageSize
integer
pageSize
integer [ 1 .. 100 ]
Page size for pagination query
orderBy
string
Ordering for pagination query
@@ -11944,7 +11944,7 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Filter Capabilities by Inactive Devices value. Since the value is an array, multiple query parameters should be specified in the correct order. For example, to filter for [1, 3], specify inactiveDevices=1&inactiveDevices=3
count
string
Filter Capabilities by Count
-
pageNumber
integer >= 1
Default: 1
Example: pageNumber=1
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Default: 1
Example: pageNumber=1
Page number for pagination query
pageSize
integer [ 1 .. 100 ]
Example: pageSize=20
Page size for pagination query
@@ -12334,7 +12334,7 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Filter by rack name
manufacturer
string
Filter by manufacturer
-
pageNumber
integer >= 1
Default: 1
Example: pageNumber=1
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Default: 1
Example: pageNumber=1
Page number for pagination query
pageSize
integer [ 1 .. 100 ]
Example: pageSize=20
Page size for pagination query
@@ -12976,7 +12976,7 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Restrict results to non-terminal Tasks.
includeReport
boolean
Default: false
Include the per-task execution report on each returned task.
-
pageNumber
integer >= 1
Default: 1
Example: pageNumber=1
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Default: 1
Example: pageNumber=1
Page number for pagination query
pageSize
integer [ 1 .. 100 ]
Example: pageSize=20
Page size for pagination query
@@ -13070,7 +13070,7 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Filter by tray UUID. Can be specified multiple times to filter on more than one tray ID.
slotId
integer <int32> >= 0
Restrict to trays at this rack slot (matches position.slotId). Requires rackId or rackName. Composes with the rest of the filter via AND.
-
pageNumber
integer >= 1
Default: 1
Example: pageNumber=1
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Default: 1
Example: pageNumber=1
Page number for pagination query
pageSize
integer [ 1 .. 100 ]
Example: pageSize=20
Page size for pagination query
@@ -13696,7 +13696,7 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Restrict results to non-terminal Tasks.
includeReport
boolean
Default: false
Include the per-task execution report on each returned task.
-
pageNumber
integer >= 1
Default: 1
Example: pageNumber=1
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Default: 1
Example: pageNumber=1
Page number for pagination query
pageSize
integer [ 1 .. 100 ]
Example: pageSize=20
Page size for pagination query
@@ -13930,14 +13930,28 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Optional free-form description.
operationType
required
string
Enum:"PowerControl""FirmwareControl"
Operation type the rule applies to.
-
operationCode
required
string
Operation code within the operation type (e.g. power_on).
-
required
object (RuleDefinition)
Executable definition of a rule. Mirrors Flow's wire schema 1:1 so existing
-YAML rule files can be converted to JSON without any key renaming
-(nested fields use snake_case).
+
operationCode
required
string
Operation code within the operation type. For PowerControl, accepted
+values are power_on, force_power_on, power_off, force_power_off,
+restart, force_restart, warm_reset, and cold_reset. For
+FirmwareControl, accepted values are upgrade, downgrade, and
+rollback. The server validates the code against the selected type.
+
required
object (RuleDefinition)
Executable definition of a rule. Structurally identical to Flow's own rule
+schema, so an existing YAML rule file maps across field for field. The
+fields declared here use camelCase (componentType, mainOperation,
+pollInterval) rather than the snake_case of Flow's YAML; keys inside
+the free-form parameters map pass through unchanged and stay
+snake_case (expected_status, component_types).
version
required
string
Value:"v1"
Schema version. Currently always v1.
Array of objects (SequenceStep)
Typical API Call Flow for Tenant
stages run sequentially in ascending numerical order. May be empty for
operations whose sequencing is hardcoded in Flow (e.g. bring-up,
firmware update).
-
Array
componentType
required
string
Component type this step targets (e.g. Compute, NVLSwitch,
-PowerShelf). Validated against Flow's component-type set.
+
Array
componentType
required
string
Component type this step targets. Validated against Flow's
+component-type set: Compute, NVSwitch, PowerShelf,
+ToRSwitch, UMS, CDU. Matched case-insensitively.
stage
required
integer >= 1
Stage number; steps with the same stage run in parallel, lower stages run
@@ -13988,18 +14004,30 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Optional free-form description.
operationType
required
string
Enum:"PowerControl""FirmwareControl"
Type of operation this rule applies to. Immutable after creation.
-
operationCode
required
string
operationCode
required
string
Operation code within the operation type (e.g. power_on, power_off,
-upgrade). Server-side validated against Flow's allow-list for the type.
+" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Operation code within the operation type. For PowerControl, accepted
+values are power_on, force_power_on, power_off, force_power_off,
+restart, force_restart, warm_reset, and cold_reset. For
+FirmwareControl, accepted values are upgrade, downgrade, and
+rollback. The server validates the code against the selected type.
Immutable after creation.
-
required
object (RuleDefinition)
Executable definition of a rule. Mirrors Flow's wire schema 1:1 so existing
-YAML rule files can be converted to JSON without any key renaming
-(nested fields use snake_case).
+
required
object (RuleDefinition)
Executable definition of a rule. Structurally identical to Flow's own rule
+schema, so an existing YAML rule file maps across field for field. The
+fields declared here use camelCase (componentType, mainOperation,
+pollInterval) rather than the snake_case of Flow's YAML; keys inside
+the free-form parameters map pass through unchanged and stay
+snake_case (expected_status, component_types).
version
required
string
Value:"v1"
Schema version. Currently always v1.
Array of objects (SequenceStep)
Typical API Call Flow for Tenant
stages run sequentially in ascending numerical order. May be empty for
operations whose sequencing is hardcoded in Flow (e.g. bring-up,
firmware update).
-
Array
componentType
required
string
Component type this step targets (e.g. Compute, NVLSwitch,
-PowerShelf). Validated against Flow's component-type set.
+
Array
componentType
required
string
Component type this step targets. Validated against Flow's
+component-type set: Compute, NVSwitch, PowerShelf,
+ToRSwitch, UMS, CDU. Matched case-insensitively.
stage
required
integer >= 1
Stage number; steps with the same stage run in parallel, lower stages run
@@ -14062,7 +14092,7 @@
Typical API Call Flow for Tenant
create or update resources may succeed even if timeout is returned.
"name": "Power on - shelves, then switches, then compute",
"description": "Verifies each component type reached the on state before the next stage starts.",
"operationType": "PowerControl",
"operationCode": "power_on",
"ruleDefinition": {
"version": "v1",
"steps": [
{
"componentType": "PowerShelf",
"stage": 1,
"maxParallel": 0,
"timeout": "15m",
"retry": {
"maxAttempts": 3,
"initialInterval": "5s",
"backoffCoefficient": 2,
"maxInterval": "1m"
},
"mainOperation": {
"name": "PowerControl"
},
"postOperation": [
{
"name": "VerifyPowerStatus",
"timeout": "5m",
"pollInterval": "10s",
"parameters": {
"expected_status": "on"
}
}
]
},
{
"componentType": "NVSwitch",
"stage": 2,
"maxParallel": 0,
"timeout": "15m",
"retry": {
"maxAttempts": 3,
"initialInterval": "5s",
"backoffCoefficient": 2
},
"mainOperation": {
"name": "PowerControl"
},
"postOperation": [
{
"name": "VerifyPowerStatus",
"timeout": "5m",
"pollInterval": "10s",
"parameters": {
"expected_status": "on"
}
}
]
},
{
"componentType": "Compute",
"stage": 3,
"maxParallel": 8,
"timeout": "20m",
"retry": {
"maxAttempts": 3,
"initialInterval": "1s",
"backoffCoefficient": 2
},
"mainOperation": {
"name": "PowerControl"
},
"postOperation": [
{
"name": "VerifyReachability",
"timeout": "10m",
"pollInterval": "30s",
"parameters": {
"component_types": [
"Compute"
],
"require_all": true
}
}
]
}
]
}
}
Response samples
201
400
403
504
Content type
application/json
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"description": "string",
"operationType": "PowerControl",
"operationCode": "string",
"ruleDefinition": {
"version": "v1",
"steps": [
{
"componentType": "string",
"stage": 1,
"maxParallel": 0,
"timeout": "string",
"retry": {
"maxAttempts": 1,
"initialInterval": "string",
"backoffCoefficient": 1,
"maxInterval": "string"
},
"preOperation": [
{
"name": "Sleep",
"timeout": "string",
"pollInterval": "string",
"parameters": { }
}
],
"mainOperation": {
"name": "Sleep",
"timeout": "string",
"pollInterval": "string",
"parameters": { }
},
"postOperation": [
{
"name": "Sleep",
"timeout": "string",
"pollInterval": "string",
"parameters": { }
}
],
"delayAfter": "string"
}
]
},
"isDefault": true,
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z"
}
List Operation Rules
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
ID of the Site that owns the rules (rules are site-scoped).
operationType
string
Enum:"PowerControl""FirmwareControl"
Filter by operation type.
-
pageNumber
integer >= 1
pageNumber
integer (PageNumber) [ 1 .. 21474836 ]
Page number of results returned (1-indexed).
-
pageSize
integer >= 1
pageSize
integer [ 1 .. 100 ]
Number of results per page.
Responses
operationType
required
string
Enum:"PowerControl""FirmwareControl"
Type of operation this rule applies to. Immutable after creation.
-
operationCode
required
string
operationCode
required
string
Operation code within the operation type (e.g. power_on, power_off,
-upgrade). Server-side validated against Flow's allow-list for the type.
+" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Operation code within the operation type. For PowerControl, accepted
+values are power_on, force_power_on, power_off, force_power_off,
+restart, force_restart, warm_reset, and cold_reset. For
+FirmwareControl, accepted values are upgrade, downgrade, and
+rollback. The server validates the code against the selected type.
Immutable after creation.
-
required
object (RuleDefinition)
Executable definition of a rule. Mirrors Flow's wire schema 1:1 so existing
-YAML rule files can be converted to JSON without any key renaming
-(nested fields use snake_case).
+
required
object (RuleDefinition)
Executable definition of a rule. Structurally identical to Flow's own rule
+schema, so an existing YAML rule file maps across field for field. The
+fields declared here use camelCase (componentType, mainOperation,
+pollInterval) rather than the snake_case of Flow's YAML; keys inside
+the free-form parameters map pass through unchanged and stay
+snake_case (expected_status, component_types).
version
required
string
Value:"v1"
Schema version. Currently always v1.
Array of objects (SequenceStep)
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Optional free-form description.
operationType
required
string
Enum:"PowerControl""FirmwareControl"
Type of operation this rule applies to. Immutable after creation.
-
operationCode
required
string
operationCode
required
string
Operation code within the operation type (e.g. power_on, power_off,
-upgrade). Server-side validated against Flow's allow-list for the type.
+" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Operation code within the operation type. For PowerControl, accepted
+values are power_on, force_power_on, power_off, force_power_off,
+restart, force_restart, warm_reset, and cold_reset. For
+FirmwareControl, accepted values are upgrade, downgrade, and
+rollback. The server validates the code against the selected type.
Immutable after creation.
-
required
object (RuleDefinition)
Executable definition of a rule. Mirrors Flow's wire schema 1:1 so existing
-YAML rule files can be converted to JSON without any key renaming
-(nested fields use snake_case).
+
required
object (RuleDefinition)
Executable definition of a rule. Structurally identical to Flow's own rule
+schema, so an existing YAML rule file maps across field for field. The
+fields declared here use camelCase (componentType, mainOperation,
+pollInterval) rather than the snake_case of Flow's YAML; keys inside
+the free-form parameters map pass through unchanged and stay
+snake_case (expected_status, component_types).
version
required
string
Value:"v1"
Schema version. Currently always v1.
Array of objects (SequenceStep)
Typical API Call Flow for Tenant
stages run sequentially in ascending numerical order. May be empty for
operations whose sequencing is hardcoded in Flow (e.g. bring-up,
firmware update).
-
Array
componentType
required
string
Component type this step targets (e.g. Compute, NVLSwitch,
-PowerShelf). Validated against Flow's component-type set.
+
Array
componentType
required
string
Component type this step targets. Validated against Flow's
+component-type set: Compute, NVSwitch, PowerShelf,
+ToRSwitch, UMS, CDU. Matched case-insensitively.
stage
required
integer >= 1
Stage number; steps with the same stage run in parallel, lower stages run
@@ -14236,7 +14292,7 @@
Typical API Call Flow for Tenant
create or update resources may succeed even if timeout is returned.
"name": "Power on - shelves, then switches, then compute",
"description": "Verifies each component type reached the on state before the next stage starts.",
"operationType": "PowerControl",
"operationCode": "power_on",
"isDefault": true,
"created": "2026-07-02T09:14:37Z",
"updated": "2026-08-05T11:20:05Z",
"ruleDefinition": {
"version": "v1",
"steps": [
{
"componentType": "PowerShelf",
"stage": 1,
"maxParallel": 0,
"timeout": "15m",
"retry": {
"maxAttempts": 3,
"initialInterval": "5s",
"backoffCoefficient": 2,
"maxInterval": "1m"
},
"mainOperation": {
"name": "PowerControl"
},
"postOperation": [
{
"name": "VerifyPowerStatus",
"timeout": "5m",
"pollInterval": "10s",
"parameters": {
"expected_status": "on"
}
}
]
},
{
"componentType": "Compute",
"stage": 2,
"maxParallel": 8,
"timeout": "20m",
"retry": {
"maxAttempts": 3,
"initialInterval": "1s",
"backoffCoefficient": 2
},
"mainOperation": {
"name": "PowerControl"
},
"postOperation": [
{
"name": "VerifyReachability",
"timeout": "10m",
"pollInterval": "30s",
"parameters": {
"component_types": [
"Compute"
],
"require_all": true
}
}
]
}
]
}
}
Update an Operation Rule
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
New rule name. Must be non-empty when provided.
description
string
New free-form description.
-
object (RuleDefinition)
Executable definition of a rule. Mirrors Flow's wire schema 1:1 so existing
-YAML rule files can be converted to JSON without any key renaming
-(nested fields use snake_case).
+
object (RuleDefinition)
Executable definition of a rule. Structurally identical to Flow's own rule
+schema, so an existing YAML rule file maps across field for field. The
+fields declared here use camelCase (componentType, mainOperation,
+pollInterval) rather than the snake_case of Flow's YAML; keys inside
+the free-form parameters map pass through unchanged and stay
+snake_case (expected_status, component_types).
version
required
string
Value:"v1"
Schema version. Currently always v1.
Array of objects (SequenceStep)
Typical API Call Flow for Tenant
stages run sequentially in ascending numerical order. May be empty for
operations whose sequencing is hardcoded in Flow (e.g. bring-up,
firmware update).
-
Array
componentType
required
string
Component type this step targets (e.g. Compute, NVLSwitch,
-PowerShelf). Validated against Flow's component-type set.
+
Array
componentType
required
string
Component type this step targets. Validated against Flow's
+component-type set: Compute, NVSwitch, PowerShelf,
+ToRSwitch, UMS, CDU. Matched case-insensitively.
stage
required
integer >= 1
Stage number; steps with the same stage run in parallel, lower stages run
@@ -14326,7 +14390,7 @@
Typical API Call Flow for Tenant
create or update resources may succeed even if timeout is returned.
A Task Run is a phased, policy-gated execution of one operation (currently firmware) across many Racks. A Task Run narrows a candidate set of Racks with an optional selector, divides the selected Racks into phases, and drives one execution target per Rack; each target in turn drives at most one Task. Safety gates pause the Task Run when failures exceed a threshold, and phase gates hold each phase until an operator advances it. This tag exposes creation, retrieval, target listing, and the pause / resume / advance / cancel lifecycle actions; drill into per-Rack execution detail via the Task tag using each target's taskId.
A Task Run is a phased, policy-gated execution of one operation across many Racks. A Task Run narrows a candidate set of Racks with an optional selector, divides the selected Racks into phases, and drives one execution target per Rack; each target in turn drives at most one Task. Safety gates pause the Task Run when failures exceed a threshold, and phase gates hold each phase until an operator advances it. This tag exposes creation, retrieval, target listing, and the pause / resume / advance / cancel lifecycle actions; drill into per-Rack execution detail via the Task tag using each target's taskId.
Create a Task Run
Create a Task Run: a phased, policy-gated execution of one operation across
many Racks. The configuration is validated server-side by Flow; on
validation failure no state changes.
-
A Task Run executes exactly one operation (currently firmware) over a
-candidate set of Racks, narrowed by an optional selector and divided
-into phases by an optional options.phasePolicy. The response echoes the
-assigned id; the Task Run always starts in the Pending state. Poll
+
A Task Run executes exactly one operation over a candidate set of Racks,
+narrowed by an optional selector and divided into phases by an
+optional options.phasePolicy. The response echoes the assigned id;
+the Task Run always starts in the Pending state. Poll
GET /task/run/{id} for progress.
Org must have an Infrastructure Provider entity. User must have
authorization role with PROVIDER_ADMIN suffix.
@@ -14404,7 +14468,7 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
Selects a percentage of the candidate Racks. seed is optional; when
omitted Flow generates and stores one so the cohort is deterministic and
auditable.
-
percent
required
integer [ 0 .. 100 ]
percent
required
integer [ 1 .. 100 ]
Percentage of candidate Racks to select.
seed
string
Optional seed for the deterministic selection.
@@ -14446,8 +14510,8 @@
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
When true, phases advance automatically as long as safety gates are
not tripped. When false (default) each completed phase pauses at a
phase gate until advanced explicitly.
-
required
object (TaskRunOperation)
The operation the Task Run executes. Firmware is the only supported operation today.
+
required
object (TaskRunOperation)
The operation the Task Run executes. Firmware is the only supported operation.
required
object (TaskRunFirmwareOperation)
Configures a firmware rollout.
version
required
string
Typical API Call Flow for Tenant
Flow's default rule resolution pick one.
overrideReadinessCheck
boolean
Default: false
Skip the pre-flight readiness check when true.
-
subTargets
Array of strings
Optional subset of firmware sub-targets to update.
+
subTargets
Array of strings
Optional subset of firmware sub-parts to update within each targeted
+tray, using the same lowercase names as the Tray firmware endpoint's
+targets (e.g. bmc, bios). Omitted or empty means update
+everything in the bundle. Unknown names are rejected.
excludeRunIds
Array of strings <uuid> [ items <uuid > ]
Excludes Racks materialized by prior Task Runs from this Task Run's
@@ -14530,7 +14600,13 @@
Typical API Call Flow for Tenant
create or update resources may succeed even if timeout is returned.
Takes a deterministic 10% of the Site's candidate Racks, splits
+the cohort into two equal phases, and holds at a phase gate
+between them because autoAdvance is false.
+
{
"siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
"name": "Compute firmware 25.03 - 10% cohort",
"description": "Canary cohort ahead of the fleet-wide rollout.",
"selector": {
"percentage": {
"percent": 10,
"seed": "fw-25-03-canary"
}
},
"options": {
"maxConcurrentTargets": 4,
"safetyPolicy": {
"gates": [
{
"failureRate": {
"scope": "currentPhase",
"thresholdPercent": 10
}
},
{
"failureCount": {
"scope": "cumulativeRun",
"thresholdCount": 5
}
}
]
},
"conflictPolicy": {
"retry": {
"retryTimeout": "30m",
"initialRetryDelay": "10s",
"maxRetryDelay": "5m"
}
},
"orderingPolicy": {
"random": {
"seed": "fw-25-03-canary"
}
},
"phasePolicy": {
"equal": {
"phaseCount": 2
},
"autoAdvance": false
}
},
"operation": {
"firmware": {
"version": "25.03.1",
"subTargets": [
"bmc",
"bios"
]
}
}
}
Response samples
201
400
403
504
Content type
application/json
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"description": "string",
"operationType": "PowerControl",
"operationCode": "string",
"status": "Unknown",
"statusReason": "Unknown",
"statusMessage": "string",
"totalPhases": 0,
"created": "2019-08-24T14:15:22Z",
"updated": "2019-08-24T14:15:22Z",
"started": "2019-08-24T14:15:22Z",
"finished": "2019-08-24T14:15:22Z",
"stats": {
"currentPhase": {
"phaseIndex": 0,
"selectedTargets": 0,
"outcomeCounts": {
"completed": 0,
"failed": 0,
"terminated": 0,
"skipped": 0
}
},
"cumulativePhase": {
"phaseIndex": 0,
"selectedTargets": 0,
"outcomeCounts": {
"completed": 0,
"failed": 0,
"terminated": 0,
"skipped": 0
}
}
}
}
Retrieve all Task Runs
Typical API Call Flow for Tenant
" class="sc-iJSMbW sc-cBEgGa fiNpIH bAoMjv">
stats is present because the request set
+includeStats=true. statusReason is PhaseGate, so the
+first phase finished and the Task Run is waiting for an
+explicit advance.
+
{
"id": "7a4c1e88-3d21-4f9b-b0c5-2e6d9f1a4b73",
"name": "Compute firmware 25.03 - 10% cohort",
"description": "Canary cohort ahead of the fleet-wide rollout.",