From 4bf79bb5780c81c1542cab9e36ec4d69607a37fe Mon Sep 17 00:00:00 2001 From: Hitesh Wadekar Date: Mon, 4 May 2026 12:23:54 -0700 Subject: [PATCH 01/16] feat: Support IP Usage stats in VpcPrefix --- api/pkg/api/handler/vpcprefix.go | 80 +++++++++++++++++++++--- api/pkg/api/handler/vpcprefix_test.go | 34 +++++++++- api/pkg/api/model/vpcprefix.go | 15 ++++- api/pkg/api/model/vpcprefix_test.go | 2 +- db/pkg/db/ipam/ipam.go | 63 +++++++++++++++++++ db/pkg/db/ipam/ipam_test.go | 90 +++++++++++++++++++++++++++ openapi/spec.yaml | 20 ++++++ 7 files changed, 294 insertions(+), 10 deletions(-) diff --git a/api/pkg/api/handler/vpcprefix.go b/api/pkg/api/handler/vpcprefix.go index 04d61d29a..daa98aefe 100644 --- a/api/pkg/api/handler/vpcprefix.go +++ b/api/pkg/api/handler/vpcprefix.go @@ -24,6 +24,7 @@ import ( "fmt" "net/http" "slices" + "strconv" "github.com/labstack/echo/v4" @@ -49,6 +50,8 @@ import ( cwssaws "github.com/NVIDIA/infra-controller-rest/workflow-schema/schema/site-agent/workflows/v1" "github.com/NVIDIA/infra-controller-rest/workflow/pkg/queue" + + cip "github.com/NVIDIA/infra-controller-rest/ipam" ) // ~~~~~ Create Handler ~~~~~ // @@ -325,7 +328,7 @@ func (csh CreateVpcPrefixHandler) Handle(c echo.Context) error { } // create response - apiVpcPrefix := model.NewAPIVpcPrefix(createdVpcPrefix, []cdbm.StatusDetail{*ssd}) + apiVpcPrefix := model.NewAPIVpcPrefix(createdVpcPrefix, []cdbm.StatusDetail{*ssd}, nil) logger.Info().Msg("finishing API handler") return c.JSON(http.StatusCreated, apiVpcPrefix) } @@ -361,7 +364,8 @@ func NewGetAllVpcPrefixHandler(dbSession *cdb.Session, tc temporalClient.Client, // @Param siteId query string false "Site ID" // @Param vpcId query string true "ID of Vpc" // @Param query query string false "Query input for full text search" -// @Param includeRelation query string false "Related entities to include in response e.g. 'Site', 'Vpc', 'IPv4Block'" +// @Param includeRelation query string false "Related entities to include in response e.g. 'Site', 'Vpc', 'IPBlock'" +// @Param includeUsageStats query boolean false "VPC prefix IPAM usage stats (same shape as IP Block usage)" // @Param pageNumber query integer false "Page number of results returned" // @Param pageSize query integer false "Number of results per page" // @Param orderBy query string false "Order by field" @@ -424,6 +428,20 @@ func (gash GetAllVpcPrefixHandler) Handle(c echo.Context) error { return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, errMsg, nil) } + includeUsageStats := false + qius := c.QueryParam("includeUsageStats") + if qius != "" { + includeUsageStats, err = strconv.ParseBool(qius) + if err != nil { + return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, "Invalid value specified for `includeUsageStats` query param", nil) + } + } + + queryIncludeRelations := slices.Clone(qIncludeRelations) + if includeUsageStats && !slices.Contains(queryIncludeRelations, cdbm.IPBlockRelationName) { + queryIncludeRelations = append(queryIncludeRelations, cdbm.IPBlockRelationName) + } + // Get site ID from query param tsDAO := cdbm.NewTenantSiteDAO(gash.dbSession) var siteIDs []uuid.UUID @@ -485,13 +503,31 @@ func (gash GetAllVpcPrefixHandler) Handle(c echo.Context) error { Limit: pageRequest.Limit, OrderBy: pageRequest.OrderBy, }, - qIncludeRelations, + queryIncludeRelations, ) if err != nil { logger.Error().Err(err).Msg("error getting VPC Prefixes from db") return cutil.NewAPIErrorResponse(c, http.StatusInternalServerError, "Failed to retrieve VPC Prefixes", nil) } + puVpMap := map[uuid.UUID]*cip.Usage{} + if includeUsageStats { + ipamStorage := ipam.NewIpamStorage(gash.dbSession.DB, nil) + for i := range vpcPrefixes { + vp := &vpcPrefixes[i] + if vp.IPBlock == nil { + logger.Error().Str("vpcPrefixId", vp.ID.String()).Msg("VPC prefix missing IP Block relation for usage stats") + continue + } + prefixUsage, serr := ipam.GetIpamUsageForVpcPrefix(ctx, ipamStorage, vp, vp.IPBlock) + if serr != nil { + logger.Error().Err(serr).Msg("error retrieving ipam usage stats for VPC prefix") + continue + } + puVpMap[vp.ID] = prefixUsage + } + } + // Get status details sdDAO := cdbm.NewStatusDetailDAO(gash.dbSession) @@ -516,7 +552,8 @@ func (gash GetAllVpcPrefixHandler) Handle(c echo.Context) error { // get status details for _, sn := range vpcPrefixes { cursn := sn - apiVpcPrefix := model.NewAPIVpcPrefix(&cursn, ssdMap[sn.ID.String()]) + cipu := puVpMap[sn.ID] + apiVpcPrefix := model.NewAPIVpcPrefix(&cursn, ssdMap[sn.ID.String()], cipu) apiVpcPrefixes = append(apiVpcPrefixes, apiVpcPrefix) } @@ -565,6 +602,7 @@ func NewGetVpcPrefixHandler(dbSession *cdb.Session, tc temporalClient.Client, cf // @Param org path string true "Name of NGC organization" // @Param id path string true "ID of VPC prefix" // @Param includeRelation query string false "Related entities to include in response e.g. 'Site', 'Vpc', 'Tenant', 'IPv4Block', 'IPv6Block'" +// @Param includeUsageStats query boolean false "VPC prefix IPAM usage stats (same shape as IP Block usage)" // @Success 200 {object} model.APIVpcPrefix // @Router /v2/org/{org}/nico/vpcprefix/{id} [get] func (gsh GetVpcPrefixHandler) Handle(c echo.Context) error { @@ -602,6 +640,20 @@ func (gsh GetVpcPrefixHandler) Handle(c echo.Context) error { return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, errMsg, nil) } + includeUsageStats := false + qius := c.QueryParam("includeUsageStats") + if qius != "" { + includeUsageStats, err = strconv.ParseBool(qius) + if err != nil { + return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, "Invalid value specified for `includeUsageStats` query param", nil) + } + } + + queryIncludeRelations := slices.Clone(qIncludeRelations) + if includeUsageStats && !slices.Contains(queryIncludeRelations, cdbm.IPBlockRelationName) { + queryIncludeRelations = append(queryIncludeRelations, cdbm.IPBlockRelationName) + } + // Get VPC prefix ID from URL param sStrID := c.Param("id") @@ -623,7 +675,7 @@ func (gsh GetVpcPrefixHandler) Handle(c echo.Context) error { } // Check that VPC prefix exists - vpcPrefix, err := vpDAO.GetByID(ctx, nil, sID, qIncludeRelations) + vpcPrefix, err := vpDAO.GetByID(ctx, nil, sID, queryIncludeRelations) if err != nil { logger.Error().Err(err).Msg("error retrieving VPC prefix DB entity") if err == cdb.ErrDoesNotExist { @@ -646,8 +698,22 @@ func (gsh GetVpcPrefixHandler) Handle(c echo.Context) error { return cutil.NewAPIErrorResponse(c, http.StatusInternalServerError, "Failed to retrieve Status Details for VPC prefix", nil) } + var puVPC *cip.Usage + if includeUsageStats { + if vpcPrefix.IPBlock == nil { + logger.Error().Str("vpcPrefixId", vpcPrefix.ID.String()).Msg("VPC prefix missing IP Block relation for usage stats") + return cutil.NewAPIErrorResponse(c, http.StatusInternalServerError, "Failed to retrieve Usage Stats for VPC prefix", nil) + } + ipamStorage := ipam.NewIpamStorage(gsh.dbSession.DB, nil) + puVPC, err = ipam.GetIpamUsageForVpcPrefix(ctx, ipamStorage, vpcPrefix, vpcPrefix.IPBlock) + if err != nil { + logger.Error().Err(err).Msg("error retrieving ipam usage stats details for VPC prefix") + return cutil.NewAPIErrorResponse(c, http.StatusInternalServerError, "Failed to retrieve Usage Stats for VPC prefix", nil) + } + } + // Send response - apiVpcPrefix := model.NewAPIVpcPrefix(vpcPrefix, ssds) + apiVpcPrefix := model.NewAPIVpcPrefix(vpcPrefix, ssds, puVPC) logger.Info().Msg("finishing API handler") return c.JSON(http.StatusOK, apiVpcPrefix) } @@ -866,7 +932,7 @@ func (ush UpdateVpcPrefixHandler) Handle(c echo.Context) error { } // Send response - apiVpcPrefix := model.NewAPIVpcPrefix(updatedVpcPrefix, ssds) + apiVpcPrefix := model.NewAPIVpcPrefix(updatedVpcPrefix, ssds, nil) logger.Info().Msg("finishing API handler") return c.JSON(http.StatusOK, apiVpcPrefix) } diff --git a/api/pkg/api/handler/vpcprefix_test.go b/api/pkg/api/handler/vpcprefix_test.go index cbc135e0c..ce5cd0f7a 100644 --- a/api/pkg/api/handler/vpcprefix_test.go +++ b/api/pkg/api/handler/vpcprefix_test.go @@ -1106,8 +1106,10 @@ func TestVpcPrefixHandler_Get(t *testing.T) { queryIncludeRelations1 *string queryIncludeRelations2 *string queryIncludeRelations3 *string + queryIncludeUsageStats *string expectedVpcName *string expectetIPName *string + expectUsageStatsNonNil bool verifyChildSpanner bool }{ { @@ -1187,6 +1189,25 @@ func TestVpcPrefixHandler_Get(t *testing.T) { queryIncludeRelations1: cdb.GetStrPtr(cdbm.IPBlockRelationName), expectetIPName: &ipb1.Name, }, + { + name: "error when includeUsageStats query invalid", + reqOrgName: tnOrg1, + user: tnu, + id: vpcprefix.ID, + expectedErr: true, + expectedStatus: http.StatusBadRequest, + queryIncludeUsageStats: cdb.GetStrPtr("not-a-bool"), + }, + { + name: "success case when includeUsageStats true", + reqOrgName: tnOrg1, + user: tnu, + id: vpcprefix.ID, + expectedErr: false, + expectedStatus: http.StatusOK, + queryIncludeUsageStats: cdb.GetStrPtr("true"), + expectUsageStatsNonNil: true, + }, } for _, tc := range tests { t.Run(tc.name, func(t *testing.T) { @@ -1195,6 +1216,9 @@ func TestVpcPrefixHandler_Get(t *testing.T) { e := echo.New() q := url.Values{} + if tc.queryIncludeUsageStats != nil { + q.Set("includeUsageStats", *tc.queryIncludeUsageStats) + } if tc.queryIncludeRelations1 != nil { q.Add("includeRelation", *tc.queryIncludeRelations1) } @@ -1236,17 +1260,25 @@ func TestVpcPrefixHandler_Get(t *testing.T) { // validate response fields assert.Equal(t, 1, len(rsp.StatusHistory)) - if tc.queryIncludeRelations1 != nil || tc.queryIncludeRelations2 != nil || tc.queryIncludeRelations3 != nil { + expanded := tc.queryIncludeRelations1 != nil || tc.queryIncludeRelations2 != nil || tc.queryIncludeRelations3 != nil || tc.expectUsageStatsNonNil + if expanded { if tc.expectedVpcName != nil { assert.Equal(t, *tc.expectedVpcName, rsp.Vpc.Name) } if tc.expectetIPName != nil { assert.Equal(t, *tc.expectetIPName, rsp.IPBlock.Name) } + if tc.expectUsageStatsNonNil { + require.NotNil(t, rsp.IPBlock) + require.NotNil(t, rsp.UsageStats) + } } else { assert.Nil(t, rsp.Vpc) assert.Nil(t, rsp.IPBlock) } + if !expanded && !tc.expectedErr { + assert.Nil(t, rsp.UsageStats) + } } if tc.verifyChildSpanner { diff --git a/api/pkg/api/model/vpcprefix.go b/api/pkg/api/model/vpcprefix.go index e38ed4f36..56556ac19 100644 --- a/api/pkg/api/model/vpcprefix.go +++ b/api/pkg/api/model/vpcprefix.go @@ -26,6 +26,7 @@ import ( "github.com/NVIDIA/infra-controller-rest/api/pkg/api/model/util" cdbm "github.com/NVIDIA/infra-controller-rest/db/pkg/db/model" + ipam "github.com/NVIDIA/infra-controller-rest/ipam" ) const ( @@ -134,6 +135,8 @@ type APIVpcPrefix struct { Status string `json:"status"` // StatusHistory is the history of statuses for the VpcPrefix StatusHistory []APIStatusDetail `json:"statusHistory"` + // UsageStats reports IP usage within this VPC Prefix (from IPAM) when requested via includeUsageStats + UsageStats *APIIPBlockUsageStats `json:"usageStats,omitempty"` // CreatedAt indicates the ISO datetime string for when the entity was created Created time.Time `json:"created"` // UpdatedAt indicates the ISO datetime string for when the entity was last updated @@ -141,7 +144,7 @@ type APIVpcPrefix struct { } // NewAPIVpcPrefix accepts a DB layer objects and returns an API layer object -func NewAPIVpcPrefix(dbvp *cdbm.VpcPrefix, dbsds []cdbm.StatusDetail) *APIVpcPrefix { +func NewAPIVpcPrefix(dbvp *cdbm.VpcPrefix, dbsds []cdbm.StatusDetail, dbpu *ipam.Usage) *APIVpcPrefix { apiVpcPrefix := APIVpcPrefix{ ID: dbvp.ID.String(), Name: dbvp.Name, @@ -155,6 +158,16 @@ func NewAPIVpcPrefix(dbvp *cdbm.VpcPrefix, dbsds []cdbm.StatusDetail) *APIVpcPre Updated: dbvp.Updated, } + if dbpu != nil { + apiVpcPrefix.UsageStats = &APIIPBlockUsageStats{ + AvailableIPs: dbpu.AvailableIPs, + AcquiredIPs: dbpu.AcquiredIPs, + AvailablePrefixes: dbpu.AvailablePrefixes, + AcquiredPrefixes: dbpu.AcquiredPrefixes, + AvailableSmallestPrefixes: dbpu.AvailableSmallestPrefixes, + } + } + apiVpcPrefix.StatusHistory = []APIStatusDetail{} for _, dbsd := range dbsds { apiVpcPrefix.StatusHistory = append(apiVpcPrefix.StatusHistory, NewAPIStatusDetail(dbsd)) diff --git a/api/pkg/api/model/vpcprefix_test.go b/api/pkg/api/model/vpcprefix_test.go index e02156643..9d1d847bc 100644 --- a/api/pkg/api/model/vpcprefix_test.go +++ b/api/pkg/api/model/vpcprefix_test.go @@ -210,7 +210,7 @@ func TestAPIVpcPrefixNew(t *testing.T) { for _, tc := range tests { t.Run(tc.desc, func(t *testing.T) { - got := NewAPIVpcPrefix(tc.dbObj, tc.sdObj) + got := NewAPIVpcPrefix(tc.dbObj, tc.sdObj, nil) assert.Equal(t, tc.dbObj.ID.String(), got.ID) assert.NotNil(t, tc.dbObj.SiteID) assert.NotNil(t, tc.dbObj.VpcID) diff --git a/db/pkg/db/ipam/ipam.go b/db/pkg/db/ipam/ipam.go index cb6ad0dcc..31ac2d884 100644 --- a/db/pkg/db/ipam/ipam.go +++ b/db/pkg/db/ipam/ipam.go @@ -36,6 +36,8 @@ var ( ErrPrefixDoesNotExistForIPBlock = errors.New("prefix does not exist for IPBlock in ipam db") // ErrNilIPBlock is the error when a nil IPBlock was passed ErrNilIPBlock = errors.New("ipblock parameter is nil") + // ErrNilVpcPrefix is the error when a nil VpcPrefix was passed + ErrNilVpcPrefix = errors.New("vpcPrefix parameter is nil") ) // ~~~~~ IPAM Utilities ~~~~~ // @@ -75,6 +77,28 @@ func GetCidrForIPBlock(ctx context.Context, prefix string, blockSize int) string return fmt.Sprintf("%s/%d", prefix, blockSize) } +func getVpcPrefixCidr(ctx context.Context, vpcPrefix *cdbm.VpcPrefix) string { + if vpcPrefix != nil && strings.Contains(vpcPrefix.Prefix, "/") { + return vpcPrefix.Prefix + } + if vpcPrefix == nil { + return "" + } + return GetCidrForIPBlock(ctx, vpcPrefix.Prefix, vpcPrefix.PrefixLength) +} + +func cidrPrefixesEqual(a, b string) bool { + pa, err := netip.ParsePrefix(a) + if err != nil { + return false + } + pb, err := netip.ParsePrefix(b) + if err != nil { + return false + } + return pa == pb +} + // CreateIpamEntryForIPBlock will create an ipam entry in the ipam DB for the IPBlock // will error if there is a prefix clash in that same namespace func CreateIpamEntryForIPBlock(ctx context.Context, ipamDB cipam.Storage, prefix string, blockSize int, routingType string, infrastructureProviderID, siteID string) (*cipam.Prefix, error) { @@ -145,6 +169,45 @@ func GetIpamUsageForIPBlock(ctx context.Context, ipamDB cipam.Storage, ipBlock * } } +// GetIpamUsageForVpcPrefix returns IPAM usage for the VPC Prefix CIDR subtree within the parent IP Block namespace (same source as allocations for Instances on this prefix). +func GetIpamUsageForVpcPrefix(ctx context.Context, ipamDB cipam.Storage, vpcPrefix *cdbm.VpcPrefix, ipBlock *cdbm.IPBlock) (*cipam.Usage, error) { + if vpcPrefix == nil { + return nil, ErrNilVpcPrefix + } + if ipBlock == nil { + return nil, ErrNilIPBlock + } + + vpcCidr := getVpcPrefixCidr(ctx, vpcPrefix) + parentCidr := GetCidrForIPBlock(ctx, ipBlock.Prefix, ipBlock.PrefixLength) + + if ipBlock.FullGrant && cidrPrefixesEqual(vpcCidr, parentCidr) { + return &cipam.Usage{ + AvailableIPs: 0, + AcquiredIPs: 0, + AvailableSmallestPrefixes: 0, + AvailablePrefixes: nil, + AcquiredPrefixes: 1, + }, nil + } + + ipamer := cipam.NewWithStorage(ipamDB) + namespace := GetIpamNamespaceForIPBlock(ctx, ipBlock.RoutingType, ipBlock.InfrastructureProviderID.String(), ipBlock.SiteID.String()) + ipamer.SetNamespace(namespace) + ipamPrefix := ipamer.PrefixFrom(ctx, vpcCidr) + if ipamPrefix == nil { + return nil, fmt.Errorf("did not find prefix for VPC prefix: %s", vpcPrefix.ID.String()) + } + u := ipamPrefix.Usage() + return &cipam.Usage{ + AvailableIPs: u.AvailableIPs, + AcquiredIPs: u.AcquiredIPs, + AvailableSmallestPrefixes: u.AvailableSmallestPrefixes, + AvailablePrefixes: u.AvailablePrefixes, + AcquiredPrefixes: u.AcquiredPrefixes, + }, nil +} + // CreateChildIpamEntryForIPBlock will create an child ipam entry in the ipam DB for the given parent IP Block, with a given child block size // Note: FullGrant is a special case when the childBlockSize matches the parentIPBlock, and the parentIPBlock has no // child prefixes, then, the parentIPBlock is updated as a full grant in db, and its prefix is diff --git a/db/pkg/db/ipam/ipam_test.go b/db/pkg/db/ipam/ipam_test.go index 255480168..46a5e18c6 100644 --- a/db/pkg/db/ipam/ipam_test.go +++ b/db/pkg/db/ipam/ipam_test.go @@ -846,3 +846,93 @@ func TestGetFirstIPFromCidr(t *testing.T) { }) } } + +func TestGetIpamUsageForVpcPrefix(t *testing.T) { + dbSession := cdbutil.GetTestDBSession(t, false) + defer dbSession.Close() + ipamDB := getTestIpamDB(t, dbSession, true) + ctx := context.Background() + testIpamSetupSchema(t, dbSession) + + ip := testIpamBuildInfrastructureProvider(t, dbSession, "testvpcprefixip") + site := testIpamBuildSite(t, dbSession, ip, "testvpcprefixsite") + + parent := &cdbm.IPBlock{ + ID: uuid.New(), + Name: "parent", + RoutingType: cdbm.IPBlockRoutingTypeDatacenterOnly, + InfrastructureProviderID: ip.ID, + SiteID: site.ID, + Prefix: "10.88.0.0", + PrefixLength: 16, + ProtocolVersion: cdbm.IPBlockProtocolVersionV4, + Status: cdbm.IPBlockStatusReady, + CreatedBy: cdb.GetUUIDPtr(uuid.New()), + } + testIpamBuildIPBlock(t, dbSession, parent) + + _, err := CreateIpamEntryForIPBlock(ctx, ipamDB, parent.Prefix, parent.PrefixLength, parent.RoutingType, parent.InfrastructureProviderID.String(), parent.SiteID.String()) + assert.Nil(t, err) + + childPrefix, err := CreateChildIpamEntryForIPBlock(ctx, nil, dbSession, ipamDB, parent, 24) + assert.Nil(t, err) + + ipamer := cipam.NewWithStorage(ipamDB) + ns := GetIpamNamespaceForIPBlock(ctx, parent.RoutingType, parent.InfrastructureProviderID.String(), parent.SiteID.String()) + ipamer.SetNamespace(ns) + _, err = ipamer.AcquireIP(ctx, childPrefix.Cidr) + assert.Nil(t, err) + + pfxNet, bits, parseErr := ParseCidrIntoPrefixAndBlockSize(childPrefix.Cidr) + assert.Nil(t, parseErr) + + vpFullCidr := &cdbm.VpcPrefix{ + ID: uuid.New(), + Prefix: childPrefix.Cidr, + PrefixLength: bits, + } + vpBareNetwork := &cdbm.VpcPrefix{ + ID: uuid.New(), + Prefix: pfxNet, + PrefixLength: bits, + } + + uNil, err := GetIpamUsageForVpcPrefix(ctx, ipamDB, nil, parent) + assert.Nil(t, uNil) + assert.ErrorIs(t, err, ErrNilVpcPrefix) + + u1, err := GetIpamUsageForVpcPrefix(ctx, ipamDB, vpFullCidr, parent) + assert.Nil(t, err) + assert.NotNil(t, u1) + assert.GreaterOrEqual(t, u1.AcquiredIPs, uint64(1)) + + u2, err := GetIpamUsageForVpcPrefix(ctx, ipamDB, vpBareNetwork, parent) + assert.Nil(t, err) + assert.Equal(t, u1.AcquiredIPs, u2.AcquiredIPs) + + fullGrantParent := &cdbm.IPBlock{ + ID: uuid.New(), + Name: "fullgrant", + RoutingType: cdbm.IPBlockRoutingTypeDatacenterOnly, + InfrastructureProviderID: ip.ID, + SiteID: site.ID, + Prefix: "10.87.10.0", + PrefixLength: 24, + ProtocolVersion: cdbm.IPBlockProtocolVersionV4, + Status: cdbm.IPBlockStatusReady, + CreatedBy: cdb.GetUUIDPtr(uuid.New()), + FullGrant: true, + } + testIpamBuildIPBlock(t, dbSession, fullGrantParent) + _, err = CreateIpamEntryForIPBlock(ctx, ipamDB, fullGrantParent.Prefix, fullGrantParent.PrefixLength, fullGrantParent.RoutingType, fullGrantParent.InfrastructureProviderID.String(), fullGrantParent.SiteID.String()) + assert.Nil(t, err) + vpFullGrant := &cdbm.VpcPrefix{ + ID: uuid.New(), + Prefix: fmt.Sprintf("%s/%d", fullGrantParent.Prefix, fullGrantParent.PrefixLength), + PrefixLength: fullGrantParent.PrefixLength, + } + uFg, err := GetIpamUsageForVpcPrefix(ctx, ipamDB, vpFullGrant, fullGrantParent) + assert.Nil(t, err) + assert.Equal(t, uint64(1), uFg.AcquiredPrefixes) + assert.Equal(t, uint64(0), uFg.AcquiredIPs) +} diff --git a/openapi/spec.yaml b/openapi/spec.yaml index afd01e65f..62eb49b50 100644 --- a/openapi/spec.yaml +++ b/openapi/spec.yaml @@ -2929,6 +2929,13 @@ paths: in: query name: includeRelation description: Related entity to expand + - schema: + type: boolean + in: query + name: includeUsageStats + description: >- + When true, includes IPAM usage for each VPC prefix (`usageStats`), same shape as IP Block usage + (available/acquired IPs and child prefixes). Loads the parent IP Block relation internally if needed. - schema: type: integer example: 1 @@ -3027,6 +3034,13 @@ paths: in: query name: includeRelation description: Related entity to expand + - schema: + type: boolean + in: query + name: includeUsageStats + description: >- + When true, includes IPAM usage for this VPC prefix (`usageStats`), same shape as IP Block usage. + Loads the parent IP Block relation internally if needed. delete: summary: Delete VPC Prefix operationId: delete-vpc-prefix @@ -13994,6 +14008,12 @@ components: $ref: '#/components/schemas/VpcPrefixStatus' readOnly: true description: Status of the VPC Prefix + usageStats: + $ref: '#/components/schemas/IpBlockUsageStats' + readOnly: true + description: >- + Present when query param `includeUsageStats=true`. IPAM usage within this VPC prefix + (available/acquired IPs and child prefixes consumed by Instances and other allocations). statusHistory: type: array items: From ee371561ab221c1f95eced822d0f8d2ed05d7de7 Mon Sep 17 00:00:00 2001 From: Hitesh Wadekar Date: Mon, 4 May 2026 12:29:53 -0700 Subject: [PATCH 02/16] Added sdk --- sdk/standard/api_vpc_prefix.go | 52 ++++++++++++++++++++++---------- sdk/standard/model_vpc_prefix.go | 37 +++++++++++++++++++++++ 2 files changed, 73 insertions(+), 16 deletions(-) diff --git a/sdk/standard/api_vpc_prefix.go b/sdk/standard/api_vpc_prefix.go index 0a034c602..84280cc42 100644 --- a/sdk/standard/api_vpc_prefix.go +++ b/sdk/standard/api_vpc_prefix.go @@ -283,17 +283,18 @@ func (a *VPCPrefixAPIService) DeleteVpcPrefixExecute(r ApiDeleteVpcPrefixRequest } type ApiGetAllVpcPrefixRequest struct { - ctx context.Context - ApiService *VPCPrefixAPIService - org string - siteId *string - vpcId *string - status *string - query *string - includeRelation *string - pageNumber *int32 - pageSize *int32 - orderBy *string + ctx context.Context + ApiService *VPCPrefixAPIService + org string + siteId *string + vpcId *string + status *string + query *string + includeRelation *string + includeUsageStats *bool + pageNumber *int32 + pageSize *int32 + orderBy *string } // Filter VPC Prefixes by Site, required if vpcId query param is not specified @@ -326,6 +327,12 @@ func (r ApiGetAllVpcPrefixRequest) IncludeRelation(includeRelation string) ApiGe return r } +// When true, includes IPAM usage for each VPC prefix (`usageStats`), same shape as IP Block usage (available/acquired IPs and child prefixes). Loads the parent IP Block relation internally if needed. +func (r ApiGetAllVpcPrefixRequest) IncludeUsageStats(includeUsageStats bool) ApiGetAllVpcPrefixRequest { + r.includeUsageStats = &includeUsageStats + return r +} + // Page number for pagination query func (r ApiGetAllVpcPrefixRequest) PageNumber(pageNumber int32) ApiGetAllVpcPrefixRequest { r.pageNumber = &pageNumber @@ -405,6 +412,9 @@ func (a *VPCPrefixAPIService) GetAllVpcPrefixExecute(r ApiGetAllVpcPrefixRequest if r.includeRelation != nil { parameterAddToHeaderOrQuery(localVarQueryParams, "includeRelation", r.includeRelation, "form", "") } + if r.includeUsageStats != nil { + parameterAddToHeaderOrQuery(localVarQueryParams, "includeUsageStats", r.includeUsageStats, "form", "") + } if r.pageNumber != nil { parameterAddToHeaderOrQuery(localVarQueryParams, "pageNumber", r.pageNumber, "form", "") } else { @@ -483,11 +493,12 @@ func (a *VPCPrefixAPIService) GetAllVpcPrefixExecute(r ApiGetAllVpcPrefixRequest } type ApiGetVpcPrefixRequest struct { - ctx context.Context - ApiService *VPCPrefixAPIService - org string - vpcPrefixId string - includeRelation *string + ctx context.Context + ApiService *VPCPrefixAPIService + org string + vpcPrefixId string + includeRelation *string + includeUsageStats *bool } // Related entity to expand @@ -496,6 +507,12 @@ func (r ApiGetVpcPrefixRequest) IncludeRelation(includeRelation string) ApiGetVp return r } +// When true, includes IPAM usage for this VPC prefix (`usageStats`), same shape as IP Block usage. Loads the parent IP Block relation internally if needed. +func (r ApiGetVpcPrefixRequest) IncludeUsageStats(includeUsageStats bool) ApiGetVpcPrefixRequest { + r.includeUsageStats = &includeUsageStats + return r +} + func (r ApiGetVpcPrefixRequest) Execute() (*VpcPrefix, *http.Response, error) { return r.ApiService.GetVpcPrefixExecute(r) } @@ -548,6 +565,9 @@ func (a *VPCPrefixAPIService) GetVpcPrefixExecute(r ApiGetVpcPrefixRequest) (*Vp if r.includeRelation != nil { parameterAddToHeaderOrQuery(localVarQueryParams, "includeRelation", r.includeRelation, "form", "") } + if r.includeUsageStats != nil { + parameterAddToHeaderOrQuery(localVarQueryParams, "includeUsageStats", r.includeUsageStats, "form", "") + } // to determine the Content-Type header localVarHTTPContentTypes := []string{} diff --git a/sdk/standard/model_vpc_prefix.go b/sdk/standard/model_vpc_prefix.go index 2041b538a..a7b2f2042 100644 --- a/sdk/standard/model_vpc_prefix.go +++ b/sdk/standard/model_vpc_prefix.go @@ -54,6 +54,8 @@ type VpcPrefix struct { PrefixLength *int32 `json:"prefixLength,omitempty"` // Status of the VPC Prefix Status *VpcPrefixStatus `json:"status,omitempty"` + // Present when query param `includeUsageStats=true`. IPAM usage within this VPC prefix (available/acquired IPs and child prefixes consumed by Instances and other allocations). + UsageStats *IpBlockUsageStats `json:"usageStats,omitempty"` // Details of 20 most recent status changes StatusHistory []StatusDetail `json:"statusHistory,omitempty"` // Date and time when the VPC Prefix was created @@ -389,6 +391,38 @@ func (o *VpcPrefix) SetStatus(v VpcPrefixStatus) { o.Status = &v } +// GetUsageStats returns the UsageStats field value if set, zero value otherwise. +func (o *VpcPrefix) GetUsageStats() IpBlockUsageStats { + if o == nil || IsNil(o.UsageStats) { + var ret IpBlockUsageStats + return ret + } + return *o.UsageStats +} + +// GetUsageStatsOk returns a tuple with the UsageStats field value if set, nil otherwise +// and a boolean to check if the value has been set. +func (o *VpcPrefix) GetUsageStatsOk() (*IpBlockUsageStats, bool) { + if o == nil || IsNil(o.UsageStats) { + return nil, false + } + return o.UsageStats, true +} + +// HasUsageStats returns a boolean if a field has been set. +func (o *VpcPrefix) HasUsageStats() bool { + if o != nil && !IsNil(o.UsageStats) { + return true + } + + return false +} + +// SetUsageStats gets a reference to the given IpBlockUsageStats and assigns it to the UsageStats field. +func (o *VpcPrefix) SetUsageStats(v IpBlockUsageStats) { + o.UsageStats = &v +} + // GetStatusHistory returns the StatusHistory field value if set, zero value otherwise. func (o *VpcPrefix) GetStatusHistory() []StatusDetail { if o == nil || IsNil(o.StatusHistory) { @@ -522,6 +556,9 @@ func (o VpcPrefix) ToMap() (map[string]interface{}, error) { if !IsNil(o.Status) { toSerialize["status"] = o.Status } + if !IsNil(o.UsageStats) { + toSerialize["usageStats"] = o.UsageStats + } if !IsNil(o.StatusHistory) { toSerialize["statusHistory"] = o.StatusHistory } From 9aab199e587e277367f9a0920e37cccc0d6aeb8a Mon Sep 17 00:00:00 2001 From: Hitesh Wadekar Date: Mon, 4 May 2026 13:11:29 -0700 Subject: [PATCH 03/16] Added IP usage stats support for Subnet --- api/pkg/api/handler/subnet.go | 78 +++++++++++++++++++++++-- api/pkg/api/handler/subnet_test.go | 35 ++++++++++- api/pkg/api/model/subnet.go | 15 ++++- api/pkg/api/model/subnet_test.go | 2 +- db/pkg/db/ipam/ipam.go | 60 +++++++++++++++++++ db/pkg/db/ipam/ipam_test.go | 93 ++++++++++++++++++++++++++++++ openapi/spec.yaml | 20 +++++++ 7 files changed, 294 insertions(+), 9 deletions(-) diff --git a/api/pkg/api/handler/subnet.go b/api/pkg/api/handler/subnet.go index 915bca518..4b59afdda 100644 --- a/api/pkg/api/handler/subnet.go +++ b/api/pkg/api/handler/subnet.go @@ -25,9 +25,12 @@ import ( "fmt" "net/http" "slices" + "strconv" "github.com/labstack/echo/v4" + cip "github.com/NVIDIA/ncx-infra-controller-rest/ipam" + "go.opentelemetry.io/otel/attribute" temporalClient "go.temporal.io/sdk/client" tp "go.temporal.io/sdk/temporal" @@ -399,7 +402,7 @@ func (csh CreateSubnetHandler) Handle(c echo.Context) error { txCommitted = true // create response - apiInstance := model.NewAPISubnet(subnet, []cdbm.StatusDetail{*ssd}) + apiInstance := model.NewAPISubnet(subnet, []cdbm.StatusDetail{*ssd}, nil) logger.Info().Msg("finishing API handler") return c.JSON(http.StatusCreated, apiInstance) } @@ -437,6 +440,7 @@ func NewGetAllSubnetHandler(dbSession *cdb.Session, tc temporalClient.Client, cf // @Param status query string false "Filter by status" e.g. 'Pending', 'Error'" // @Param query query string false "Query input for full text search" // @Param includeRelation query string false "Related entities to include in response e.g. 'Site', 'Vpc', 'Tenant', 'IPv4Block', 'IPv6Block'" +// @Param includeUsageStats query boolean false "Subnet IPv4 IPAM usage stats (same shape as IP Block usage)" // @Param pageNumber query integer false "Page number of results returned" // @Param pageSize query integer false "Number of results per page" // @Param orderBy query string false "Order by field" @@ -501,6 +505,20 @@ func (gash GetAllSubnetHandler) Handle(c echo.Context) error { return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, errMsg, nil) } + includeUsageStats := false + qius := c.QueryParam("includeUsageStats") + if qius != "" { + includeUsageStats, err = strconv.ParseBool(qius) + if err != nil { + return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, "Invalid value specified for `includeUsageStats` query param", nil) + } + } + + queryIncludeRelations := slices.Clone(qIncludeRelations) + if includeUsageStats && !slices.Contains(queryIncludeRelations, cdbm.IPv4BlockRelationName) { + queryIncludeRelations = append(queryIncludeRelations, cdbm.IPv4BlockRelationName) + } + // Get site ID from query param tsDAO := cdbm.NewTenantSiteDAO(gash.dbSession) var siteID *uuid.UUID @@ -570,12 +588,30 @@ func (gash GetAllSubnetHandler) Handle(c echo.Context) error { Limit: pageRequest.Limit, Offset: pageRequest.Offset, OrderBy: pageRequest.OrderBy, - }, qIncludeRelations) + }, queryIncludeRelations) if err != nil { logger.Error().Err(err).Msg("error getting subnets from db") return cutil.NewAPIErrorResponse(c, http.StatusInternalServerError, "Failed to retrieve Subnets", nil) } + puSubnetMap := map[uuid.UUID]*cip.Usage{} + if includeUsageStats { + ipamStorage := ipam.NewIpamStorage(gash.dbSession.DB, nil) + for i := range subnets { + sn := &subnets[i] + if sn.IPv4Block == nil { + logger.Error().Str("subnetId", sn.ID.String()).Msg("Subnet missing IPv4 Block relation for usage stats") + continue + } + prefixUsage, serr := ipam.GetIpamUsageForSubnet(ctx, ipamStorage, sn, sn.IPv4Block) + if serr != nil { + logger.Error().Err(serr).Str("subnetId", sn.ID.String()).Msg("error retrieving ipam usage stats for Subnet") + continue + } + puSubnetMap[sn.ID] = prefixUsage + } + } + // Get status details sdDAO := cdbm.NewStatusDetailDAO(gash.dbSession) @@ -600,7 +636,8 @@ func (gash GetAllSubnetHandler) Handle(c echo.Context) error { // get status details for _, sn := range subnets { cursn := sn - apiSubnet := model.NewAPISubnet(&cursn, ssdMap[sn.ID.String()]) + cipu := puSubnetMap[sn.ID] + apiSubnet := model.NewAPISubnet(&cursn, ssdMap[sn.ID.String()], cipu) apiSubnets = append(apiSubnets, apiSubnet) } @@ -649,6 +686,7 @@ func NewGetSubnetHandler(dbSession *cdb.Session, tc temporalClient.Client, cfg * // @Param org path string true "Name of NGC organization" // @Param id path string true "ID of Subnet" // @Param includeRelation query string false "Related entities to include in response e.g. 'Site', 'Vpc', 'Tenant', 'IPv4Block', 'IPv6Block'" +// @Param includeUsageStats query boolean false "Subnet IPv4 IPAM usage stats (same shape as IP Block usage)" // @Success 200 {object} model.APISubnet // @Router /v2/org/{org}/nico/subnet/{id} [get] func (gsh GetSubnetHandler) Handle(c echo.Context) error { @@ -686,6 +724,20 @@ func (gsh GetSubnetHandler) Handle(c echo.Context) error { return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, errMsg, nil) } + includeUsageStats := false + qius := c.QueryParam("includeUsageStats") + if qius != "" { + includeUsageStats, err = strconv.ParseBool(qius) + if err != nil { + return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, "Invalid value specified for `includeUsageStats` query param", nil) + } + } + + queryIncludeRelations := slices.Clone(qIncludeRelations) + if includeUsageStats && !slices.Contains(queryIncludeRelations, cdbm.IPv4BlockRelationName) { + queryIncludeRelations = append(queryIncludeRelations, cdbm.IPv4BlockRelationName) + } + // Get subnet ID from URL param sStrID := c.Param("id") @@ -707,7 +759,7 @@ func (gsh GetSubnetHandler) Handle(c echo.Context) error { } // Check that subnet exists - subnet, err := sDAO.GetByID(ctx, nil, sID, qIncludeRelations) + subnet, err := sDAO.GetByID(ctx, nil, sID, queryIncludeRelations) if err != nil { logger.Error().Err(err).Msg("error retrieving Subnet DB entity") if err == cdb.ErrDoesNotExist { @@ -730,8 +782,22 @@ func (gsh GetSubnetHandler) Handle(c echo.Context) error { return cutil.NewAPIErrorResponse(c, http.StatusInternalServerError, "Failed to retrieve Status Details for subnet", nil) } + var puSubnet *cip.Usage + if includeUsageStats { + if subnet.IPv4Block == nil { + logger.Error().Str("subnetId", subnet.ID.String()).Msg("Subnet missing IPv4 Block relation for usage stats") + return cutil.NewAPIErrorResponse(c, http.StatusInternalServerError, "Failed to retrieve Usage Stats for Subnet", nil) + } + ipamStorage := ipam.NewIpamStorage(gsh.dbSession.DB, nil) + puSubnet, err = ipam.GetIpamUsageForSubnet(ctx, ipamStorage, subnet, subnet.IPv4Block) + if err != nil { + logger.Error().Err(err).Msg("error retrieving ipam usage stats details for Subnet") + return cutil.NewAPIErrorResponse(c, http.StatusInternalServerError, "Failed to retrieve Usage Stats for Subnet", nil) + } + } + // Send response - apiInstance := model.NewAPISubnet(subnet, ssds) + apiInstance := model.NewAPISubnet(subnet, ssds, puSubnet) logger.Info().Msg("finishing API handler") return c.JSON(http.StatusOK, apiInstance) } @@ -890,7 +956,7 @@ func (ush UpdateSubnetHandler) Handle(c echo.Context) error { txCommitted = true // Send response - apiInstance := model.NewAPISubnet(subnet, ssds) + apiInstance := model.NewAPISubnet(subnet, ssds, nil) logger.Info().Msg("finishing API handler") return c.JSON(http.StatusOK, apiInstance) } diff --git a/api/pkg/api/handler/subnet_test.go b/api/pkg/api/handler/subnet_test.go index deddd1e11..cfccc0733 100644 --- a/api/pkg/api/handler/subnet_test.go +++ b/api/pkg/api/handler/subnet_test.go @@ -1161,9 +1161,11 @@ func TestSubnetHandler_Get(t *testing.T) { queryIncludeRelations1 *string queryIncludeRelations2 *string queryIncludeRelations3 *string + queryIncludeUsageStats *string expectedVpcName *string expectetIPv4Name *string expectedIPv6Name *string + expectUsageStatsNonNil bool verifyChildSpanner bool }{ { @@ -1243,6 +1245,25 @@ func TestSubnetHandler_Get(t *testing.T) { queryIncludeRelations1: cdb.GetStrPtr(cdbm.IPv4BlockRelationName), expectetIPv4Name: &ipb1.Name, }, + { + name: "error when includeUsageStats query invalid", + reqOrgName: tnOrg1, + user: tnu, + id: subnet.ID, + expectedErr: true, + expectedStatus: http.StatusBadRequest, + queryIncludeUsageStats: cdb.GetStrPtr("not-a-bool"), + }, + { + name: "success case when includeUsageStats true", + reqOrgName: tnOrg1, + user: tnu, + id: subnet.ID, + expectedErr: false, + expectedStatus: http.StatusOK, + queryIncludeUsageStats: cdb.GetStrPtr("true"), + expectUsageStatsNonNil: true, + }, } for _, tc := range tests { t.Run(tc.name, func(t *testing.T) { @@ -1251,6 +1272,9 @@ func TestSubnetHandler_Get(t *testing.T) { e := echo.New() q := url.Values{} + if tc.queryIncludeUsageStats != nil { + q.Set("includeUsageStats", *tc.queryIncludeUsageStats) + } if tc.queryIncludeRelations1 != nil { q.Add("includeRelation", *tc.queryIncludeRelations1) } @@ -1294,7 +1318,8 @@ func TestSubnetHandler_Get(t *testing.T) { assert.Equal(t, cdbm.IPBlockRoutingTypeDatacenterOnly, *rsp.RoutingType) - if tc.queryIncludeRelations1 != nil || tc.queryIncludeRelations2 != nil || tc.queryIncludeRelations3 != nil { + expanded := tc.queryIncludeRelations1 != nil || tc.queryIncludeRelations2 != nil || tc.queryIncludeRelations3 != nil || tc.expectUsageStatsNonNil + if expanded { if tc.expectedVpcName != nil { assert.Equal(t, *tc.expectedVpcName, rsp.Vpc.Name) } @@ -1304,11 +1329,19 @@ func TestSubnetHandler_Get(t *testing.T) { if tc.expectedIPv6Name != nil { assert.Equal(t, *tc.expectedIPv6Name, rsp.IPv6Block.Name) } + if tc.expectUsageStatsNonNil { + require.NotNil(t, rsp.IPv4Block) + } } else { assert.Nil(t, rsp.Vpc) assert.Nil(t, rsp.IPv4Block) assert.Nil(t, rsp.IPv6Block) } + if tc.expectUsageStatsNonNil { + require.NotNil(t, rsp.UsageStats) + } else { + assert.Nil(t, rsp.UsageStats) + } } if tc.verifyChildSpanner { diff --git a/api/pkg/api/model/subnet.go b/api/pkg/api/model/subnet.go index b38d05bea..58c605542 100644 --- a/api/pkg/api/model/subnet.go +++ b/api/pkg/api/model/subnet.go @@ -25,6 +25,7 @@ import ( "github.com/NVIDIA/infra-controller-rest/api/pkg/api/model/util" cdbm "github.com/NVIDIA/infra-controller-rest/db/pkg/db/model" + ipam "github.com/NVIDIA/infra-controller-rest/ipam" ) const ( @@ -156,6 +157,8 @@ type APISubnet struct { MTU *int `json:"mtu"` // StatusHistory is the history of statuses for the Subnet StatusHistory []APIStatusDetail `json:"statusHistory"` + // UsageStats reports IPv4 IP usage within this Subnet (from IPAM) when requested via includeUsageStats + UsageStats *APIIPBlockUsageStats `json:"usageStats,omitempty"` // CreatedAt indicates the ISO datetime string for when the entity was created Created time.Time `json:"created"` // UpdatedAt indicates the ISO datetime string for when the entity was last updated @@ -163,7 +166,7 @@ type APISubnet struct { } // NewAPISubnet accepts a DB layer objects and returns an API layer object -func NewAPISubnet(dbs *cdbm.Subnet, dbsds []cdbm.StatusDetail) *APISubnet { +func NewAPISubnet(dbs *cdbm.Subnet, dbsds []cdbm.StatusDetail, dbpu *ipam.Usage) *APISubnet { apiSubnet := APISubnet{ ID: dbs.ID.String(), Name: dbs.Name, @@ -184,6 +187,16 @@ func NewAPISubnet(dbs *cdbm.Subnet, dbsds []cdbm.StatusDetail) *APISubnet { MTU: dbs.MTU, } + if dbpu != nil { + apiSubnet.UsageStats = &APIIPBlockUsageStats{ + AvailableIPs: dbpu.AvailableIPs, + AcquiredIPs: dbpu.AcquiredIPs, + AvailablePrefixes: dbpu.AvailablePrefixes, + AcquiredPrefixes: dbpu.AcquiredPrefixes, + AvailableSmallestPrefixes: dbpu.AvailableSmallestPrefixes, + } + } + if dbs.ControllerNetworkSegmentID != nil { apiSubnet.ControllerNetworkSegmentID = util.GetUUIDPtrToStrPtr(dbs.ControllerNetworkSegmentID) } diff --git a/api/pkg/api/model/subnet_test.go b/api/pkg/api/model/subnet_test.go index d8770c3fa..b5cd261ff 100644 --- a/api/pkg/api/model/subnet_test.go +++ b/api/pkg/api/model/subnet_test.go @@ -254,7 +254,7 @@ func TestAPISubnetNew(t *testing.T) { for _, tc := range tests { t.Run(tc.desc, func(t *testing.T) { - got := NewAPISubnet(tc.dbObj, tc.sdObj) + got := NewAPISubnet(tc.dbObj, tc.sdObj, nil) assert.Equal(t, tc.dbObj.ID.String(), got.ID) assert.NotNil(t, tc.dbObj.SiteID) if tc.dbObj.ControllerNetworkSegmentID != nil { diff --git a/db/pkg/db/ipam/ipam.go b/db/pkg/db/ipam/ipam.go index 31ac2d884..a8aef12a4 100644 --- a/db/pkg/db/ipam/ipam.go +++ b/db/pkg/db/ipam/ipam.go @@ -38,6 +38,10 @@ var ( ErrNilIPBlock = errors.New("ipblock parameter is nil") // ErrNilVpcPrefix is the error when a nil VpcPrefix was passed ErrNilVpcPrefix = errors.New("vpcPrefix parameter is nil") + // ErrNilSubnet is the error when a nil Subnet was passed + ErrNilSubnet = errors.New("subnet parameter is nil") + // ErrSubnetNoIPv4Prefix is returned when a Subnet has no IPv4 prefix to resolve IPAM CIDR + ErrSubnetNoIPv4Prefix = errors.New("subnet has no IPv4 prefix") ) // ~~~~~ IPAM Utilities ~~~~~ // @@ -208,6 +212,62 @@ func GetIpamUsageForVpcPrefix(ctx context.Context, ipamDB cipam.Storage, vpcPref }, nil } +func getSubnetIPv4Cidr(ctx context.Context, subnet *cdbm.Subnet) (string, error) { + if subnet == nil { + return "", ErrNilSubnet + } + if subnet.IPv4Prefix == nil || *subnet.IPv4Prefix == "" { + return "", ErrSubnetNoIPv4Prefix + } + p := *subnet.IPv4Prefix + if strings.Contains(p, "/") { + return p, nil + } + return GetCidrForIPBlock(ctx, p, subnet.PrefixLength), nil +} + +// GetIpamUsageForSubnet returns IPAM usage for the Subnet's IPv4 CIDR subtree within the parent IPv4 IP Block namespace. +func GetIpamUsageForSubnet(ctx context.Context, ipamDB cipam.Storage, subnet *cdbm.Subnet, ipBlock *cdbm.IPBlock) (*cipam.Usage, error) { + if subnet == nil { + return nil, ErrNilSubnet + } + if ipBlock == nil { + return nil, ErrNilIPBlock + } + + subnetCidr, err := getSubnetIPv4Cidr(ctx, subnet) + if err != nil { + return nil, err + } + parentCidr := GetCidrForIPBlock(ctx, ipBlock.Prefix, ipBlock.PrefixLength) + + if ipBlock.FullGrant && cidrPrefixesEqual(subnetCidr, parentCidr) { + return &cipam.Usage{ + AvailableIPs: 0, + AcquiredIPs: 0, + AvailableSmallestPrefixes: 0, + AvailablePrefixes: nil, + AcquiredPrefixes: 1, + }, nil + } + + ipamer := cipam.NewWithStorage(ipamDB) + namespace := GetIpamNamespaceForIPBlock(ctx, ipBlock.RoutingType, ipBlock.InfrastructureProviderID.String(), ipBlock.SiteID.String()) + ipamer.SetNamespace(namespace) + ipamPrefix := ipamer.PrefixFrom(ctx, subnetCidr) + if ipamPrefix == nil { + return nil, fmt.Errorf("did not find prefix for Subnet: %s", subnet.ID.String()) + } + u := ipamPrefix.Usage() + return &cipam.Usage{ + AvailableIPs: u.AvailableIPs, + AcquiredIPs: u.AcquiredIPs, + AvailableSmallestPrefixes: u.AvailableSmallestPrefixes, + AvailablePrefixes: u.AvailablePrefixes, + AcquiredPrefixes: u.AcquiredPrefixes, + }, nil +} + // CreateChildIpamEntryForIPBlock will create an child ipam entry in the ipam DB for the given parent IP Block, with a given child block size // Note: FullGrant is a special case when the childBlockSize matches the parentIPBlock, and the parentIPBlock has no // child prefixes, then, the parentIPBlock is updated as a full grant in db, and its prefix is diff --git a/db/pkg/db/ipam/ipam_test.go b/db/pkg/db/ipam/ipam_test.go index 46a5e18c6..f7839cd89 100644 --- a/db/pkg/db/ipam/ipam_test.go +++ b/db/pkg/db/ipam/ipam_test.go @@ -936,3 +936,96 @@ func TestGetIpamUsageForVpcPrefix(t *testing.T) { assert.Equal(t, uint64(1), uFg.AcquiredPrefixes) assert.Equal(t, uint64(0), uFg.AcquiredIPs) } + +func TestGetIpamUsageForSubnet(t *testing.T) { + dbSession := cdbutil.GetTestDBSession(t, false) + defer dbSession.Close() + ipamDB := getTestIpamDB(t, dbSession, true) + ctx := context.Background() + testIpamSetupSchema(t, dbSession) + + ip := testIpamBuildInfrastructureProvider(t, dbSession, "testsubnetip") + site := testIpamBuildSite(t, dbSession, ip, "testsubnetsite") + + parent := &cdbm.IPBlock{ + ID: uuid.New(), + Name: "parent", + RoutingType: cdbm.IPBlockRoutingTypeDatacenterOnly, + InfrastructureProviderID: ip.ID, + SiteID: site.ID, + Prefix: "10.99.0.0", + PrefixLength: 16, + ProtocolVersion: cdbm.IPBlockProtocolVersionV4, + Status: cdbm.IPBlockStatusReady, + CreatedBy: cdb.GetUUIDPtr(uuid.New()), + } + testIpamBuildIPBlock(t, dbSession, parent) + + _, err := CreateIpamEntryForIPBlock(ctx, ipamDB, parent.Prefix, parent.PrefixLength, parent.RoutingType, parent.InfrastructureProviderID.String(), parent.SiteID.String()) + assert.Nil(t, err) + + childPrefix, err := CreateChildIpamEntryForIPBlock(ctx, nil, dbSession, ipamDB, parent, 24) + assert.Nil(t, err) + + ipamer := cipam.NewWithStorage(ipamDB) + ns := GetIpamNamespaceForIPBlock(ctx, parent.RoutingType, parent.InfrastructureProviderID.String(), parent.SiteID.String()) + ipamer.SetNamespace(ns) + _, err = ipamer.AcquireIP(ctx, childPrefix.Cidr) + assert.Nil(t, err) + + pfxNet, bits, parseErr := ParseCidrIntoPrefixAndBlockSize(childPrefix.Cidr) + assert.Nil(t, parseErr) + + subFullCidr := &cdbm.Subnet{ + ID: uuid.New(), + IPv4Prefix: cdb.GetStrPtr(childPrefix.Cidr), + PrefixLength: bits, + } + subBare := &cdbm.Subnet{ + ID: uuid.New(), + IPv4Prefix: cdb.GetStrPtr(pfxNet), + PrefixLength: bits, + } + + uNil, err := GetIpamUsageForSubnet(ctx, ipamDB, nil, parent) + assert.Nil(t, uNil) + assert.ErrorIs(t, err, ErrNilSubnet) + + noPfx := &cdbm.Subnet{ID: uuid.New(), PrefixLength: 24} + uNo, err := GetIpamUsageForSubnet(ctx, ipamDB, noPfx, parent) + assert.Nil(t, uNo) + assert.ErrorIs(t, err, ErrSubnetNoIPv4Prefix) + + u1, err := GetIpamUsageForSubnet(ctx, ipamDB, subFullCidr, parent) + assert.Nil(t, err) + assert.GreaterOrEqual(t, u1.AcquiredIPs, uint64(1)) + + u2, err := GetIpamUsageForSubnet(ctx, ipamDB, subBare, parent) + assert.Nil(t, err) + assert.Equal(t, u1.AcquiredIPs, u2.AcquiredIPs) + + fullGrantParent := &cdbm.IPBlock{ + ID: uuid.New(), + Name: "fullgrantsn", + RoutingType: cdbm.IPBlockRoutingTypeDatacenterOnly, + InfrastructureProviderID: ip.ID, + SiteID: site.ID, + Prefix: "10.98.20.0", + PrefixLength: 24, + ProtocolVersion: cdbm.IPBlockProtocolVersionV4, + Status: cdbm.IPBlockStatusReady, + CreatedBy: cdb.GetUUIDPtr(uuid.New()), + FullGrant: true, + } + testIpamBuildIPBlock(t, dbSession, fullGrantParent) + _, err = CreateIpamEntryForIPBlock(ctx, ipamDB, fullGrantParent.Prefix, fullGrantParent.PrefixLength, fullGrantParent.RoutingType, fullGrantParent.InfrastructureProviderID.String(), fullGrantParent.SiteID.String()) + assert.Nil(t, err) + subFG := &cdbm.Subnet{ + ID: uuid.New(), + IPv4Prefix: cdb.GetStrPtr(fmt.Sprintf("%s/%d", fullGrantParent.Prefix, fullGrantParent.PrefixLength)), + PrefixLength: fullGrantParent.PrefixLength, + } + uFg, err := GetIpamUsageForSubnet(ctx, ipamDB, subFG, fullGrantParent) + assert.Nil(t, err) + assert.Equal(t, uint64(1), uFg.AcquiredPrefixes) +} diff --git a/openapi/spec.yaml b/openapi/spec.yaml index 62eb49b50..8c63ca06d 100644 --- a/openapi/spec.yaml +++ b/openapi/spec.yaml @@ -3176,6 +3176,13 @@ paths: in: query name: includeRelation description: Related entity to expand + - schema: + type: boolean + in: query + name: includeUsageStats + description: >- + When true, includes IPAM usage for each Subnet's IPv4 space (`usageStats`), same shape as IP Block usage. + Loads the parent IPv4 IP Block relation internally if needed. - schema: type: integer example: 1 @@ -3338,6 +3345,13 @@ paths: in: query name: includeRelation description: Related entity to expand + - schema: + type: boolean + in: query + name: includeUsageStats + description: >- + When true, includes IPAM usage for this Subnet's IPv4 space (`usageStats`), same shape as IP Block usage. + Loads the parent IPv4 IP Block relation internally if needed. delete: summary: Delete Subnet operationId: delete-subnet @@ -14188,6 +14202,12 @@ components: status: $ref: '#/components/schemas/SubnetStatus' readOnly: true + usageStats: + $ref: '#/components/schemas/IpBlockUsageStats' + readOnly: true + description: >- + Present when query param `includeUsageStats=true`. IPAM IPv4 usage within this Subnet (available/acquired + IPs and child prefixes used by Instances and other allocations). statusHistory: type: array items: From 47075831910a89b79aefdba04cea2fcc958edf21 Mon Sep 17 00:00:00 2001 From: Hitesh Wadekar Date: Mon, 4 May 2026 14:10:18 -0700 Subject: [PATCH 04/16] Restructred code based on review comments by codeRabbit --- api/pkg/api/handler/subnet.go | 32 ++--------- api/pkg/api/handler/subnet_test.go | 7 ++- api/pkg/api/handler/util/common/common.go | 18 ++++++ api/pkg/api/handler/vpcprefix.go | 32 ++--------- api/pkg/api/model/subnet.go | 4 +- api/pkg/api/model/vpcprefix_test.go | 69 +++++++++++++++++++++++ db/pkg/db/ipam/ipam.go | 6 +- 7 files changed, 108 insertions(+), 60 deletions(-) diff --git a/api/pkg/api/handler/subnet.go b/api/pkg/api/handler/subnet.go index 4b59afdda..444154bb8 100644 --- a/api/pkg/api/handler/subnet.go +++ b/api/pkg/api/handler/subnet.go @@ -24,8 +24,6 @@ import ( "errors" "fmt" "net/http" - "slices" - "strconv" "github.com/labstack/echo/v4" @@ -505,18 +503,9 @@ func (gash GetAllSubnetHandler) Handle(c echo.Context) error { return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, errMsg, nil) } - includeUsageStats := false - qius := c.QueryParam("includeUsageStats") - if qius != "" { - includeUsageStats, err = strconv.ParseBool(qius) - if err != nil { - return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, "Invalid value specified for `includeUsageStats` query param", nil) - } - } - - queryIncludeRelations := slices.Clone(qIncludeRelations) - if includeUsageStats && !slices.Contains(queryIncludeRelations, cdbm.IPv4BlockRelationName) { - queryIncludeRelations = append(queryIncludeRelations, cdbm.IPv4BlockRelationName) + includeUsageStats, queryIncludeRelations, err := common.ParseIncludeUsageStats(c, qIncludeRelations, cdbm.IPv4BlockRelationName) + if err != nil { + return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, "Invalid value specified for `includeUsageStats` query param", nil) } // Get site ID from query param @@ -724,18 +713,9 @@ func (gsh GetSubnetHandler) Handle(c echo.Context) error { return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, errMsg, nil) } - includeUsageStats := false - qius := c.QueryParam("includeUsageStats") - if qius != "" { - includeUsageStats, err = strconv.ParseBool(qius) - if err != nil { - return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, "Invalid value specified for `includeUsageStats` query param", nil) - } - } - - queryIncludeRelations := slices.Clone(qIncludeRelations) - if includeUsageStats && !slices.Contains(queryIncludeRelations, cdbm.IPv4BlockRelationName) { - queryIncludeRelations = append(queryIncludeRelations, cdbm.IPv4BlockRelationName) + includeUsageStats, queryIncludeRelations, err := common.ParseIncludeUsageStats(c, qIncludeRelations, cdbm.IPv4BlockRelationName) + if err != nil { + return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, "Invalid value specified for `includeUsageStats` query param", nil) } // Get subnet ID from URL param diff --git a/api/pkg/api/handler/subnet_test.go b/api/pkg/api/handler/subnet_test.go index cfccc0733..f22e2d99e 100644 --- a/api/pkg/api/handler/subnet_test.go +++ b/api/pkg/api/handler/subnet_test.go @@ -1318,8 +1318,9 @@ func TestSubnetHandler_Get(t *testing.T) { assert.Equal(t, cdbm.IPBlockRoutingTypeDatacenterOnly, *rsp.RoutingType) - expanded := tc.queryIncludeRelations1 != nil || tc.queryIncludeRelations2 != nil || tc.queryIncludeRelations3 != nil || tc.expectUsageStatsNonNil - if expanded { + hasRelations := tc.queryIncludeRelations1 != nil || tc.queryIncludeRelations2 != nil || tc.queryIncludeRelations3 != nil + hasUsageStats := tc.expectUsageStatsNonNil + if hasRelations || hasUsageStats { if tc.expectedVpcName != nil { assert.Equal(t, *tc.expectedVpcName, rsp.Vpc.Name) } @@ -1329,7 +1330,7 @@ func TestSubnetHandler_Get(t *testing.T) { if tc.expectedIPv6Name != nil { assert.Equal(t, *tc.expectedIPv6Name, rsp.IPv6Block.Name) } - if tc.expectUsageStatsNonNil { + if hasUsageStats { require.NotNil(t, rsp.IPv4Block) } } else { diff --git a/api/pkg/api/handler/util/common/common.go b/api/pkg/api/handler/util/common/common.go index 92c295e0e..d6aa5e7c8 100644 --- a/api/pkg/api/handler/util/common/common.go +++ b/api/pkg/api/handler/util/common/common.go @@ -28,6 +28,7 @@ import ( "net/url" "reflect" "slices" + "strconv" "strings" "sync" @@ -622,6 +623,23 @@ func HandleTxError(c echo.Context, logger zerolog.Logger, err error, fallback st return cutil.NewAPIErrorResponse(c, http.StatusInternalServerError, fallback, nil) } +// ParseIncludeUsageStats reads includeUsageStats from the request; when true, clones relations and appends relationForStats +// if absent (Subnet: IPv4Block; VPC prefix: IPBlock). +func ParseIncludeUsageStats(c echo.Context, relations []string, relationForStats string) (includeUsageStats bool, augmented []string, err error) { + includeUsageStats = false + if qius := c.QueryParam("includeUsageStats"); qius != "" { + includeUsageStats, err = strconv.ParseBool(qius) + if err != nil { + return false, nil, err + } + } + augmented = slices.Clone(relations) + if includeUsageStats && relationForStats != "" && !slices.Contains(augmented, relationForStats) { + augmented = append(augmented, relationForStats) + } + return includeUsageStats, augmented, nil +} + // GetAndValidateQueryRelations is a utility function to get and validate the query parameters for include relations get/getall request func GetAndValidateQueryRelations(qParams url.Values, relatedEntities map[string]bool) ([]string, string) { qIncludeRelations := qParams["includeRelation"] diff --git a/api/pkg/api/handler/vpcprefix.go b/api/pkg/api/handler/vpcprefix.go index daa98aefe..52d29aad3 100644 --- a/api/pkg/api/handler/vpcprefix.go +++ b/api/pkg/api/handler/vpcprefix.go @@ -23,8 +23,6 @@ import ( "errors" "fmt" "net/http" - "slices" - "strconv" "github.com/labstack/echo/v4" @@ -428,18 +426,9 @@ func (gash GetAllVpcPrefixHandler) Handle(c echo.Context) error { return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, errMsg, nil) } - includeUsageStats := false - qius := c.QueryParam("includeUsageStats") - if qius != "" { - includeUsageStats, err = strconv.ParseBool(qius) - if err != nil { - return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, "Invalid value specified for `includeUsageStats` query param", nil) - } - } - - queryIncludeRelations := slices.Clone(qIncludeRelations) - if includeUsageStats && !slices.Contains(queryIncludeRelations, cdbm.IPBlockRelationName) { - queryIncludeRelations = append(queryIncludeRelations, cdbm.IPBlockRelationName) + includeUsageStats, queryIncludeRelations, err := common.ParseIncludeUsageStats(c, qIncludeRelations, cdbm.IPBlockRelationName) + if err != nil { + return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, "Invalid value specified for `includeUsageStats` query param", nil) } // Get site ID from query param @@ -640,18 +629,9 @@ func (gsh GetVpcPrefixHandler) Handle(c echo.Context) error { return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, errMsg, nil) } - includeUsageStats := false - qius := c.QueryParam("includeUsageStats") - if qius != "" { - includeUsageStats, err = strconv.ParseBool(qius) - if err != nil { - return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, "Invalid value specified for `includeUsageStats` query param", nil) - } - } - - queryIncludeRelations := slices.Clone(qIncludeRelations) - if includeUsageStats && !slices.Contains(queryIncludeRelations, cdbm.IPBlockRelationName) { - queryIncludeRelations = append(queryIncludeRelations, cdbm.IPBlockRelationName) + includeUsageStats, queryIncludeRelations, err := common.ParseIncludeUsageStats(c, qIncludeRelations, cdbm.IPBlockRelationName) + if err != nil { + return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, "Invalid value specified for `includeUsageStats` query param", nil) } // Get VPC prefix ID from URL param diff --git a/api/pkg/api/model/subnet.go b/api/pkg/api/model/subnet.go index 58c605542..aa95a0072 100644 --- a/api/pkg/api/model/subnet.go +++ b/api/pkg/api/model/subnet.go @@ -25,7 +25,7 @@ import ( "github.com/NVIDIA/infra-controller-rest/api/pkg/api/model/util" cdbm "github.com/NVIDIA/infra-controller-rest/db/pkg/db/model" - ipam "github.com/NVIDIA/infra-controller-rest/ipam" + cipam "github.com/NVIDIA/infra-controller-rest/ipam" ) const ( @@ -166,7 +166,7 @@ type APISubnet struct { } // NewAPISubnet accepts a DB layer objects and returns an API layer object -func NewAPISubnet(dbs *cdbm.Subnet, dbsds []cdbm.StatusDetail, dbpu *ipam.Usage) *APISubnet { +func NewAPISubnet(dbs *cdbm.Subnet, dbsds []cdbm.StatusDetail, dbpu *cipam.Usage) *APISubnet { apiSubnet := APISubnet{ ID: dbs.ID.String(), Name: dbs.Name, diff --git a/api/pkg/api/model/vpcprefix_test.go b/api/pkg/api/model/vpcprefix_test.go index 9d1d847bc..b4caa2611 100644 --- a/api/pkg/api/model/vpcprefix_test.go +++ b/api/pkg/api/model/vpcprefix_test.go @@ -24,6 +24,7 @@ import ( cdb "github.com/NVIDIA/infra-controller-rest/db/pkg/db" cdbm "github.com/NVIDIA/infra-controller-rest/db/pkg/db/model" + ipam "github.com/NVIDIA/infra-controller-rest/ipam" "github.com/google/uuid" "github.com/stretchr/testify/assert" ) @@ -216,6 +217,74 @@ func TestAPIVpcPrefixNew(t *testing.T) { assert.NotNil(t, tc.dbObj.VpcID) assert.Equal(t, tc.dbObj.Prefix, *got.Prefix) assert.Equal(t, tc.dbObj.PrefixLength, got.PrefixLength) + assert.Nil(t, got.UsageStats) + }) + } +} + +func TestNewAPIVpcPrefix_UsageStats(t *testing.T) { + dbObj := &cdbm.VpcPrefix{ + ID: uuid.New(), + Name: "vpc-prefix-stats", + SiteID: uuid.New(), + VpcID: uuid.New(), + IPBlockID: cdb.GetUUIDPtr(uuid.New()), + Prefix: "10.1.0.0", + PrefixLength: 24, + Created: cdb.GetCurTime(), + Updated: cdb.GetCurTime(), + } + tests := []struct { + desc string + usage *ipam.Usage + want *APIIPBlockUsageStats + }{ + { + desc: "non-nil empty usage yields zero-valued UsageStats", + usage: &ipam.Usage{}, + want: &APIIPBlockUsageStats{ + AvailablePrefixes: []string(nil), + }, + }, + { + desc: "partial usage copies only populated fields", + usage: &ipam.Usage{ + AvailableIPs: 100, + AvailablePrefixes: []string{"10.1.1.0/26"}, + }, + want: &APIIPBlockUsageStats{ + AvailableIPs: 100, + AvailablePrefixes: []string{"10.1.1.0/26"}, + }, + }, + { + desc: "full usage maps all fields", + usage: &ipam.Usage{ + AvailableIPs: 50, + AcquiredIPs: 14, + AvailableSmallestPrefixes: 200, + AvailablePrefixes: []string{"10.2.0.0/26", "10.2.0.64/26"}, + AcquiredPrefixes: 8, + }, + want: &APIIPBlockUsageStats{ + AvailableIPs: 50, + AcquiredIPs: 14, + AvailableSmallestPrefixes: 200, + AvailablePrefixes: []string{"10.2.0.0/26", "10.2.0.64/26"}, + AcquiredPrefixes: 8, + }, + }, + } + for _, tc := range tests { + t.Run(tc.desc, func(t *testing.T) { + got := NewAPIVpcPrefix(dbObj, nil, tc.usage) + req := assert.New(t) + req.NotNil(got.UsageStats) + req.Equal(tc.want.AvailableIPs, got.UsageStats.AvailableIPs) + req.Equal(tc.want.AcquiredIPs, got.UsageStats.AcquiredIPs) + req.Equal(tc.want.AvailablePrefixes, got.UsageStats.AvailablePrefixes) + req.Equal(tc.want.AvailableSmallestPrefixes, got.UsageStats.AvailableSmallestPrefixes) + req.Equal(tc.want.AcquiredPrefixes, got.UsageStats.AcquiredPrefixes) }) } } diff --git a/db/pkg/db/ipam/ipam.go b/db/pkg/db/ipam/ipam.go index a8aef12a4..64a00e6e7 100644 --- a/db/pkg/db/ipam/ipam.go +++ b/db/pkg/db/ipam/ipam.go @@ -82,12 +82,12 @@ func GetCidrForIPBlock(ctx context.Context, prefix string, blockSize int) string } func getVpcPrefixCidr(ctx context.Context, vpcPrefix *cdbm.VpcPrefix) string { - if vpcPrefix != nil && strings.Contains(vpcPrefix.Prefix, "/") { - return vpcPrefix.Prefix - } if vpcPrefix == nil { return "" } + if strings.Contains(vpcPrefix.Prefix, "/") { + return vpcPrefix.Prefix + } return GetCidrForIPBlock(ctx, vpcPrefix.Prefix, vpcPrefix.PrefixLength) } From 03d700dee6d1527596a38eade8f7ed60dd99f5de Mon Sep 17 00:00:00 2001 From: Hitesh Wadekar Date: Mon, 4 May 2026 15:25:15 -0700 Subject: [PATCH 05/16] Addressed review comments by cr --- db/pkg/db/ipam/ipam.go | 2 +- db/pkg/db/ipam/ipam_test.go | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/db/pkg/db/ipam/ipam.go b/db/pkg/db/ipam/ipam.go index 64a00e6e7..0d2474d49 100644 --- a/db/pkg/db/ipam/ipam.go +++ b/db/pkg/db/ipam/ipam.go @@ -100,7 +100,7 @@ func cidrPrefixesEqual(a, b string) bool { if err != nil { return false } - return pa == pb + return pa.Masked() == pb.Masked() } // CreateIpamEntryForIPBlock will create an ipam entry in the ipam DB for the IPBlock diff --git a/db/pkg/db/ipam/ipam_test.go b/db/pkg/db/ipam/ipam_test.go index f7839cd89..8de52995f 100644 --- a/db/pkg/db/ipam/ipam_test.go +++ b/db/pkg/db/ipam/ipam_test.go @@ -909,6 +909,8 @@ func TestGetIpamUsageForVpcPrefix(t *testing.T) { u2, err := GetIpamUsageForVpcPrefix(ctx, ipamDB, vpBareNetwork, parent) assert.Nil(t, err) assert.Equal(t, u1.AcquiredIPs, u2.AcquiredIPs) + assert.Equal(t, u1.AcquiredPrefixes, u2.AcquiredPrefixes) + assert.Equal(t, u1.AvailableSmallestPrefixes, u2.AvailableSmallestPrefixes) fullGrantParent := &cdbm.IPBlock{ ID: uuid.New(), @@ -1003,6 +1005,8 @@ func TestGetIpamUsageForSubnet(t *testing.T) { u2, err := GetIpamUsageForSubnet(ctx, ipamDB, subBare, parent) assert.Nil(t, err) assert.Equal(t, u1.AcquiredIPs, u2.AcquiredIPs) + assert.Equal(t, u1.AcquiredPrefixes, u2.AcquiredPrefixes) + assert.Equal(t, u1.AvailableSmallestPrefixes, u2.AvailableSmallestPrefixes) fullGrantParent := &cdbm.IPBlock{ ID: uuid.New(), From fedab5bad1cbf0b21c8c1d860eb237173e9537d7 Mon Sep 17 00:00:00 2001 From: Hitesh Wadekar Date: Mon, 4 May 2026 17:29:46 -0700 Subject: [PATCH 06/16] Addressed review comments --- api/pkg/api/handler/subnet.go | 1 + api/pkg/api/handler/vpcprefix.go | 1 + 2 files changed, 2 insertions(+) diff --git a/api/pkg/api/handler/subnet.go b/api/pkg/api/handler/subnet.go index 444154bb8..caba9f98d 100644 --- a/api/pkg/api/handler/subnet.go +++ b/api/pkg/api/handler/subnet.go @@ -24,6 +24,7 @@ import ( "errors" "fmt" "net/http" + "slices" "github.com/labstack/echo/v4" diff --git a/api/pkg/api/handler/vpcprefix.go b/api/pkg/api/handler/vpcprefix.go index 52d29aad3..dcb5296a0 100644 --- a/api/pkg/api/handler/vpcprefix.go +++ b/api/pkg/api/handler/vpcprefix.go @@ -23,6 +23,7 @@ import ( "errors" "fmt" "net/http" + "slices" "github.com/labstack/echo/v4" From 60802a07ce2650e2c22efac82fc46ae1f71f91e1 Mon Sep 17 00:00:00 2001 From: Hitesh Wadekar Date: Wed, 6 May 2026 16:39:32 -0700 Subject: [PATCH 07/16] IP Usage based on Instance and Interface count --- api/pkg/api/handler/subnet.go | 47 ++++--- api/pkg/api/handler/util/common/common.go | 18 --- api/pkg/api/handler/vpcprefix.go | 48 +++++--- api/pkg/api/model/subnet.go | 2 +- api/pkg/api/model/util/util.go | 144 ++++++++++++++++++++++ api/pkg/api/model/util/util_test.go | 56 +++++++++ api/pkg/api/model/vpcprefix.go | 2 +- 7 files changed, 268 insertions(+), 49 deletions(-) create mode 100644 api/pkg/api/model/util/util_test.go diff --git a/api/pkg/api/handler/subnet.go b/api/pkg/api/handler/subnet.go index caba9f98d..5343f92eb 100644 --- a/api/pkg/api/handler/subnet.go +++ b/api/pkg/api/handler/subnet.go @@ -25,10 +25,11 @@ import ( "fmt" "net/http" "slices" + "strconv" "github.com/labstack/echo/v4" - cip "github.com/NVIDIA/ncx-infra-controller-rest/ipam" + cip "github.com/NVIDIA/infra-controller-rest/ipam" "go.opentelemetry.io/otel/attribute" temporalClient "go.temporal.io/sdk/client" @@ -40,6 +41,7 @@ import ( "github.com/NVIDIA/infra-controller-rest/api/internal/config" "github.com/NVIDIA/infra-controller-rest/api/pkg/api/handler/util/common" "github.com/NVIDIA/infra-controller-rest/api/pkg/api/model" + modelutil "github.com/NVIDIA/infra-controller-rest/api/pkg/api/model/util" "github.com/NVIDIA/infra-controller-rest/api/pkg/api/pagination" sc "github.com/NVIDIA/infra-controller-rest/api/pkg/client/site" auth "github.com/NVIDIA/infra-controller-rest/auth/pkg/authorization" @@ -439,7 +441,7 @@ func NewGetAllSubnetHandler(dbSession *cdb.Session, tc temporalClient.Client, cf // @Param status query string false "Filter by status" e.g. 'Pending', 'Error'" // @Param query query string false "Query input for full text search" // @Param includeRelation query string false "Related entities to include in response e.g. 'Site', 'Vpc', 'Tenant', 'IPv4Block', 'IPv6Block'" -// @Param includeUsageStats query boolean false "Subnet IPv4 IPAM usage stats (same shape as IP Block usage)" +// @Param includeUsageStats query boolean false "Subnet IPv4 usage (interface/instance-derived; same shape as IP Block usage)" // @Param pageNumber query integer false "Page number of results returned" // @Param pageSize query integer false "Number of results per page" // @Param orderBy query string false "Order by field" @@ -504,9 +506,17 @@ func (gash GetAllSubnetHandler) Handle(c echo.Context) error { return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, errMsg, nil) } - includeUsageStats, queryIncludeRelations, err := common.ParseIncludeUsageStats(c, qIncludeRelations, cdbm.IPv4BlockRelationName) - if err != nil { - return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, "Invalid value specified for `includeUsageStats` query param", nil) + includeUsageStats := false + qius := c.QueryParam("includeUsageStats") + if qius != "" { + includeUsageStats, err = strconv.ParseBool(qius) + if err != nil { + return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, "Invalid value specified for `includeUsageStats` query param", nil) + } + } + queryIncludeRelations := slices.Clone(qIncludeRelations) + if includeUsageStats && !slices.Contains(queryIncludeRelations, cdbm.IPv4BlockRelationName) { + queryIncludeRelations = append(queryIncludeRelations, cdbm.IPv4BlockRelationName) } // Get site ID from query param @@ -586,16 +596,15 @@ func (gash GetAllSubnetHandler) Handle(c echo.Context) error { puSubnetMap := map[uuid.UUID]*cip.Usage{} if includeUsageStats { - ipamStorage := ipam.NewIpamStorage(gash.dbSession.DB, nil) for i := range subnets { sn := &subnets[i] if sn.IPv4Block == nil { logger.Error().Str("subnetId", sn.ID.String()).Msg("Subnet missing IPv4 Block relation for usage stats") continue } - prefixUsage, serr := ipam.GetIpamUsageForSubnet(ctx, ipamStorage, sn, sn.IPv4Block) + prefixUsage, serr := modelutil.GetInterfaceBasedUsageForSubnet(ctx, gash.dbSession.DB, sn) if serr != nil { - logger.Error().Err(serr).Str("subnetId", sn.ID.String()).Msg("error retrieving ipam usage stats for Subnet") + logger.Error().Err(serr).Str("subnetId", sn.ID.String()).Msg("error retrieving usage stats for Subnet") continue } puSubnetMap[sn.ID] = prefixUsage @@ -676,7 +685,7 @@ func NewGetSubnetHandler(dbSession *cdb.Session, tc temporalClient.Client, cfg * // @Param org path string true "Name of NGC organization" // @Param id path string true "ID of Subnet" // @Param includeRelation query string false "Related entities to include in response e.g. 'Site', 'Vpc', 'Tenant', 'IPv4Block', 'IPv6Block'" -// @Param includeUsageStats query boolean false "Subnet IPv4 IPAM usage stats (same shape as IP Block usage)" +// @Param includeUsageStats query boolean false "Subnet IPv4 usage (interface/instance-derived; same shape as IP Block usage)" // @Success 200 {object} model.APISubnet // @Router /v2/org/{org}/nico/subnet/{id} [get] func (gsh GetSubnetHandler) Handle(c echo.Context) error { @@ -714,9 +723,18 @@ func (gsh GetSubnetHandler) Handle(c echo.Context) error { return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, errMsg, nil) } - includeUsageStats, queryIncludeRelations, err := common.ParseIncludeUsageStats(c, qIncludeRelations, cdbm.IPv4BlockRelationName) - if err != nil { - return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, "Invalid value specified for `includeUsageStats` query param", nil) + includeUsageStats := false + qius := c.QueryParam("includeUsageStats") + if qius != "" { + includeUsageStats, err = strconv.ParseBool(qius) + if err != nil { + return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, "Invalid value specified for `includeUsageStats` query param", nil) + } + } + + queryIncludeRelations := slices.Clone(qIncludeRelations) + if includeUsageStats && !slices.Contains(queryIncludeRelations, cdbm.IPv4BlockRelationName) { + queryIncludeRelations = append(queryIncludeRelations, cdbm.IPv4BlockRelationName) } // Get subnet ID from URL param @@ -769,10 +787,9 @@ func (gsh GetSubnetHandler) Handle(c echo.Context) error { logger.Error().Str("subnetId", subnet.ID.String()).Msg("Subnet missing IPv4 Block relation for usage stats") return cutil.NewAPIErrorResponse(c, http.StatusInternalServerError, "Failed to retrieve Usage Stats for Subnet", nil) } - ipamStorage := ipam.NewIpamStorage(gsh.dbSession.DB, nil) - puSubnet, err = ipam.GetIpamUsageForSubnet(ctx, ipamStorage, subnet, subnet.IPv4Block) + puSubnet, err = modelutil.GetInterfaceBasedUsageForSubnet(ctx, gsh.dbSession.DB, subnet) if err != nil { - logger.Error().Err(err).Msg("error retrieving ipam usage stats details for Subnet") + logger.Error().Err(err).Msg("error retrieving usage stats for Subnet") return cutil.NewAPIErrorResponse(c, http.StatusInternalServerError, "Failed to retrieve Usage Stats for Subnet", nil) } } diff --git a/api/pkg/api/handler/util/common/common.go b/api/pkg/api/handler/util/common/common.go index d6aa5e7c8..92c295e0e 100644 --- a/api/pkg/api/handler/util/common/common.go +++ b/api/pkg/api/handler/util/common/common.go @@ -28,7 +28,6 @@ import ( "net/url" "reflect" "slices" - "strconv" "strings" "sync" @@ -623,23 +622,6 @@ func HandleTxError(c echo.Context, logger zerolog.Logger, err error, fallback st return cutil.NewAPIErrorResponse(c, http.StatusInternalServerError, fallback, nil) } -// ParseIncludeUsageStats reads includeUsageStats from the request; when true, clones relations and appends relationForStats -// if absent (Subnet: IPv4Block; VPC prefix: IPBlock). -func ParseIncludeUsageStats(c echo.Context, relations []string, relationForStats string) (includeUsageStats bool, augmented []string, err error) { - includeUsageStats = false - if qius := c.QueryParam("includeUsageStats"); qius != "" { - includeUsageStats, err = strconv.ParseBool(qius) - if err != nil { - return false, nil, err - } - } - augmented = slices.Clone(relations) - if includeUsageStats && relationForStats != "" && !slices.Contains(augmented, relationForStats) { - augmented = append(augmented, relationForStats) - } - return includeUsageStats, augmented, nil -} - // GetAndValidateQueryRelations is a utility function to get and validate the query parameters for include relations get/getall request func GetAndValidateQueryRelations(qParams url.Values, relatedEntities map[string]bool) ([]string, string) { qIncludeRelations := qParams["includeRelation"] diff --git a/api/pkg/api/handler/vpcprefix.go b/api/pkg/api/handler/vpcprefix.go index dcb5296a0..363c0104b 100644 --- a/api/pkg/api/handler/vpcprefix.go +++ b/api/pkg/api/handler/vpcprefix.go @@ -24,6 +24,7 @@ import ( "fmt" "net/http" "slices" + "strconv" "github.com/labstack/echo/v4" @@ -34,9 +35,12 @@ import ( validation "github.com/go-ozzo/ozzo-validation/v4" "github.com/google/uuid" + cip "github.com/NVIDIA/infra-controller-rest/ipam" + "github.com/NVIDIA/infra-controller-rest/api/internal/config" "github.com/NVIDIA/infra-controller-rest/api/pkg/api/handler/util/common" "github.com/NVIDIA/infra-controller-rest/api/pkg/api/model" + modelutil "github.com/NVIDIA/infra-controller-rest/api/pkg/api/model/util" "github.com/NVIDIA/infra-controller-rest/api/pkg/api/pagination" sc "github.com/NVIDIA/infra-controller-rest/api/pkg/client/site" auth "github.com/NVIDIA/infra-controller-rest/auth/pkg/authorization" @@ -364,7 +368,7 @@ func NewGetAllVpcPrefixHandler(dbSession *cdb.Session, tc temporalClient.Client, // @Param vpcId query string true "ID of Vpc" // @Param query query string false "Query input for full text search" // @Param includeRelation query string false "Related entities to include in response e.g. 'Site', 'Vpc', 'IPBlock'" -// @Param includeUsageStats query boolean false "VPC prefix IPAM usage stats (same shape as IP Block usage)" +// @Param includeUsageStats query boolean false "IPv4 usage (interface/instance-derived; same shape as IP Block usage)" // @Param pageNumber query integer false "Page number of results returned" // @Param pageSize query integer false "Number of results per page" // @Param orderBy query string false "Order by field" @@ -427,9 +431,18 @@ func (gash GetAllVpcPrefixHandler) Handle(c echo.Context) error { return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, errMsg, nil) } - includeUsageStats, queryIncludeRelations, err := common.ParseIncludeUsageStats(c, qIncludeRelations, cdbm.IPBlockRelationName) - if err != nil { - return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, "Invalid value specified for `includeUsageStats` query param", nil) + includeUsageStats := false + qius := c.QueryParam("includeUsageStats") + if qius != "" { + includeUsageStats, err = strconv.ParseBool(qius) + if err != nil { + return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, "Invalid value specified for `includeUsageStats` query param", nil) + } + } + + queryIncludeRelations := slices.Clone(qIncludeRelations) + if includeUsageStats && !slices.Contains(queryIncludeRelations, cdbm.IPBlockRelationName) { + queryIncludeRelations = append(queryIncludeRelations, cdbm.IPBlockRelationName) } // Get site ID from query param @@ -502,16 +515,15 @@ func (gash GetAllVpcPrefixHandler) Handle(c echo.Context) error { puVpMap := map[uuid.UUID]*cip.Usage{} if includeUsageStats { - ipamStorage := ipam.NewIpamStorage(gash.dbSession.DB, nil) for i := range vpcPrefixes { vp := &vpcPrefixes[i] if vp.IPBlock == nil { logger.Error().Str("vpcPrefixId", vp.ID.String()).Msg("VPC prefix missing IP Block relation for usage stats") continue } - prefixUsage, serr := ipam.GetIpamUsageForVpcPrefix(ctx, ipamStorage, vp, vp.IPBlock) + prefixUsage, serr := modelutil.GetInterfaceBasedUsageForVpcPrefix(ctx, gash.dbSession.DB, vp) if serr != nil { - logger.Error().Err(serr).Msg("error retrieving ipam usage stats for VPC prefix") + logger.Error().Err(serr).Msg("error retrieving usage stats for VPC prefix") continue } puVpMap[vp.ID] = prefixUsage @@ -592,7 +604,7 @@ func NewGetVpcPrefixHandler(dbSession *cdb.Session, tc temporalClient.Client, cf // @Param org path string true "Name of NGC organization" // @Param id path string true "ID of VPC prefix" // @Param includeRelation query string false "Related entities to include in response e.g. 'Site', 'Vpc', 'Tenant', 'IPv4Block', 'IPv6Block'" -// @Param includeUsageStats query boolean false "VPC prefix IPAM usage stats (same shape as IP Block usage)" +// @Param includeUsageStats query boolean false "IPv4 usage (interface/instance-derived; same shape as IP Block usage)" // @Success 200 {object} model.APIVpcPrefix // @Router /v2/org/{org}/nico/vpcprefix/{id} [get] func (gsh GetVpcPrefixHandler) Handle(c echo.Context) error { @@ -630,9 +642,18 @@ func (gsh GetVpcPrefixHandler) Handle(c echo.Context) error { return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, errMsg, nil) } - includeUsageStats, queryIncludeRelations, err := common.ParseIncludeUsageStats(c, qIncludeRelations, cdbm.IPBlockRelationName) - if err != nil { - return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, "Invalid value specified for `includeUsageStats` query param", nil) + includeUsageStats := false + qius := c.QueryParam("includeUsageStats") + if qius != "" { + includeUsageStats, err = strconv.ParseBool(qius) + if err != nil { + return cutil.NewAPIErrorResponse(c, http.StatusBadRequest, "Invalid value specified for `includeUsageStats` query param", nil) + } + } + + queryIncludeRelations := slices.Clone(qIncludeRelations) + if includeUsageStats && !slices.Contains(queryIncludeRelations, cdbm.IPBlockRelationName) { + queryIncludeRelations = append(queryIncludeRelations, cdbm.IPBlockRelationName) } // Get VPC prefix ID from URL param @@ -685,10 +706,9 @@ func (gsh GetVpcPrefixHandler) Handle(c echo.Context) error { logger.Error().Str("vpcPrefixId", vpcPrefix.ID.String()).Msg("VPC prefix missing IP Block relation for usage stats") return cutil.NewAPIErrorResponse(c, http.StatusInternalServerError, "Failed to retrieve Usage Stats for VPC prefix", nil) } - ipamStorage := ipam.NewIpamStorage(gsh.dbSession.DB, nil) - puVPC, err = ipam.GetIpamUsageForVpcPrefix(ctx, ipamStorage, vpcPrefix, vpcPrefix.IPBlock) + puVPC, err = modelutil.GetInterfaceBasedUsageForVpcPrefix(ctx, gsh.dbSession.DB, vpcPrefix) if err != nil { - logger.Error().Err(err).Msg("error retrieving ipam usage stats details for VPC prefix") + logger.Error().Err(err).Msg("error retrieving usage stats for VPC prefix") return cutil.NewAPIErrorResponse(c, http.StatusInternalServerError, "Failed to retrieve Usage Stats for VPC prefix", nil) } } diff --git a/api/pkg/api/model/subnet.go b/api/pkg/api/model/subnet.go index aa95a0072..7c6ada28f 100644 --- a/api/pkg/api/model/subnet.go +++ b/api/pkg/api/model/subnet.go @@ -157,7 +157,7 @@ type APISubnet struct { MTU *int `json:"mtu"` // StatusHistory is the history of statuses for the Subnet StatusHistory []APIStatusDetail `json:"statusHistory"` - // UsageStats reports IPv4 IP usage within this Subnet (from IPAM) when requested via includeUsageStats + // UsageStats reports IPv4 usage (derived from interface count, distinct instance count, and CIDR size) when requested via includeUsageStats UsageStats *APIIPBlockUsageStats `json:"usageStats,omitempty"` // CreatedAt indicates the ISO datetime string for when the entity was created Created time.Time `json:"created"` diff --git a/api/pkg/api/model/util/util.go b/api/pkg/api/model/util/util.go index 911cbe408..32f2e590f 100644 --- a/api/pkg/api/model/util/util.go +++ b/api/pkg/api/model/util/util.go @@ -18,9 +18,17 @@ package util import ( + "context" "errors" "fmt" + "net/netip" + "strings" + cipam "github.com/NVIDIA/infra-controller-rest/ipam" + "github.com/google/uuid" + "github.com/uptrace/bun" + + cdbm "github.com/NVIDIA/infra-controller-rest/db/pkg/db/model" cwssaws "github.com/NVIDIA/infra-controller-rest/workflow-schema/schema/site-agent/workflows/v1" "gopkg.in/yaml.v3" ) @@ -174,3 +182,139 @@ func ProtobufLabelsFromAPILabels(labels map[string]string) []*cwssaws.Label { } return protoLabels } + +// ipv4UsableHostAddressesForPrefixBits returns assignable IPv4 host count for a prefix length (/32 and /31 special-cased). +func ipv4UsableHostAddressesForPrefixBits(prefixBits int) uint64 { + if prefixBits < 0 || prefixBits > 32 { + return 0 + } + hostBits := 32 - prefixBits + switch { + case hostBits == 0: + return 1 + case prefixBits == 31: + return 2 + default: + total := uint64(1) << uint(hostBits) + if total >= 2 { + return total - 2 + } + return total + } +} + +// IPv4UsableHostAddrsFromCidr returns usable IPv4 host addresses for the given CIDR for interface/instance usage stats. +func IPv4UsableHostAddrsFromCidr(cidr string) (uint64, error) { + p, err := netip.ParsePrefix(cidr) + if err != nil { + return 0, err + } + if !p.Addr().Is4() { + return 0, fmt.Errorf("usage stats support IPv4 only, got %s", cidr) + } + return ipv4UsableHostAddressesForPrefixBits(int(p.Bits())), nil +} + +func vpcPrefixIPv4Cidr(vp *cdbm.VpcPrefix) string { + if vp == nil { + return "" + } + if strings.Contains(vp.Prefix, "/") { + return vp.Prefix + } + return fmt.Sprintf("%s/%d", vp.Prefix, vp.PrefixLength) +} + +func subnetIPv4Cidr(sn *cdbm.Subnet) (string, error) { + if sn == nil { + return "", fmt.Errorf("subnet is nil") + } + if sn.IPv4Prefix == nil || *sn.IPv4Prefix == "" { + return "", fmt.Errorf("subnet has no IPv4 prefix") + } + p := *sn.IPv4Prefix + if strings.Contains(p, "/") { + return p, nil + } + return fmt.Sprintf("%s/%d", p, sn.PrefixLength), nil +} + +func countInterfacesAndDistinctInstances(ctx context.Context, db bun.IDB, subnetID *uuid.UUID, vpcPrefixID *uuid.UUID) (ifaceCount, instCount uint64, err error) { + var row struct { + Iface int64 `bun:"iface_count"` + Inst int64 `bun:"inst_count"` + } + switch { + case subnetID != nil: + err = db.NewRaw( + `SELECT count(*) AS iface_count, count(distinct instance_id) AS inst_count FROM "interface" AS ifc WHERE ifc.subnet_id = ? AND ifc.deleted IS NULL`, + *subnetID, + ).Scan(ctx, &row) + case vpcPrefixID != nil: + err = db.NewRaw( + `SELECT count(*) AS iface_count, count(distinct instance_id) AS inst_count FROM "interface" AS ifc WHERE ifc.vpc_prefix_id = ? AND ifc.deleted IS NULL`, + *vpcPrefixID, + ).Scan(ctx, &row) + default: + return 0, 0, fmt.Errorf("usage stats: need subnet or vpc prefix id") + } + if err != nil { + return 0, 0, err + } + return uint64(row.Iface), uint64(row.Inst), nil +} + +func ipamUsageFromInterfaceTelemetry(usableHosts, ifaceCount, instCount uint64) *cipam.Usage { + var available uint64 + if usableHosts > ifaceCount { + available = usableHosts - ifaceCount + } + return &cipam.Usage{ + AvailableIPs: available, + AcquiredIPs: ifaceCount, + AvailableSmallestPrefixes: 0, + AvailablePrefixes: nil, + AcquiredPrefixes: instCount, + } +} + +// GetInterfaceBasedUsageForVpcPrefix returns ipam.Usage-shaped stats from VPC prefix IPv4 size and +// interface/instance rows for this vpc_prefix_id (Core allocates instance IPs; not the IPAM subtree). +func GetInterfaceBasedUsageForVpcPrefix(ctx context.Context, db bun.IDB, vp *cdbm.VpcPrefix) (*cipam.Usage, error) { + if vp == nil { + return nil, fmt.Errorf("vpc prefix is nil") + } + cidr := vpcPrefixIPv4Cidr(vp) + if cidr == "" { + return nil, fmt.Errorf("vpc prefix has no IPv4 CIDR") + } + usable, err := IPv4UsableHostAddrsFromCidr(cidr) + if err != nil { + return nil, err + } + ifaceCount, instCount, err := countInterfacesAndDistinctInstances(ctx, db, nil, &vp.ID) + if err != nil { + return nil, err + } + return ipamUsageFromInterfaceTelemetry(usable, ifaceCount, instCount), nil +} + +// GetInterfaceBasedUsageForSubnet returns ipam.Usage-shaped stats from subnet IPv4 CIDR and interface/instance rows for subnet_id. +func GetInterfaceBasedUsageForSubnet(ctx context.Context, db bun.IDB, sn *cdbm.Subnet) (*cipam.Usage, error) { + if sn == nil { + return nil, fmt.Errorf("subnet is nil") + } + cidr, err := subnetIPv4Cidr(sn) + if err != nil { + return nil, err + } + usable, err := IPv4UsableHostAddrsFromCidr(cidr) + if err != nil { + return nil, err + } + ifaceCount, instCount, err := countInterfacesAndDistinctInstances(ctx, db, &sn.ID, nil) + if err != nil { + return nil, err + } + return ipamUsageFromInterfaceTelemetry(usable, ifaceCount, instCount), nil +} diff --git a/api/pkg/api/model/util/util_test.go b/api/pkg/api/model/util/util_test.go new file mode 100644 index 000000000..ed022ca8d --- /dev/null +++ b/api/pkg/api/model/util/util_test.go @@ -0,0 +1,56 @@ +/* + * SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + * SPDX-License-Identifier: Apache-2.0 + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package util + +import ( + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestIPv4UsableHostAddrsFromCidr(t *testing.T) { + t.Parallel() + cases := []struct { + name string + cidr string + want uint64 + wantErrMsg string + }{ + {"/24", "192.168.0.0/24", 254, ""}, + {"/16", "10.0.0.0/16", 65534, ""}, + {"/32", "10.1.2.3/32", 1, ""}, + {"/31", "10.1.2.0/31", 2, ""}, + {"IPv6", "2001:db8::/64", 0, "usage stats support IPv4 only"}, + } + for _, tc := range cases { + tc := tc + t.Run(tc.name, func(t *testing.T) { + t.Parallel() + got, err := IPv4UsableHostAddrsFromCidr(tc.cidr) + if tc.wantErrMsg != "" { + require.Error(t, err) + assert.Contains(t, err.Error(), tc.wantErrMsg) + assert.Equal(t, uint64(0), got) + return + } + require.NoError(t, err) + assert.Equal(t, tc.want, got) + }) + } +} diff --git a/api/pkg/api/model/vpcprefix.go b/api/pkg/api/model/vpcprefix.go index 56556ac19..df1a1e1bc 100644 --- a/api/pkg/api/model/vpcprefix.go +++ b/api/pkg/api/model/vpcprefix.go @@ -135,7 +135,7 @@ type APIVpcPrefix struct { Status string `json:"status"` // StatusHistory is the history of statuses for the VpcPrefix StatusHistory []APIStatusDetail `json:"statusHistory"` - // UsageStats reports IP usage within this VPC Prefix (from IPAM) when requested via includeUsageStats + // UsageStats reports IPv4 usage (derived from interface count, distinct instance count, and CIDR size) when requested via includeUsageStats UsageStats *APIIPBlockUsageStats `json:"usageStats,omitempty"` // CreatedAt indicates the ISO datetime string for when the entity was created Created time.Time `json:"created"` From 59b7b6bbde487b3ac99101870351a5e92debddc4 Mon Sep 17 00:00:00 2001 From: Hitesh Wadekar Date: Thu, 14 May 2026 16:36:20 -0700 Subject: [PATCH 08/16] Implemented based on Interface count and reserved IPs --- api/pkg/api/model/subnet.go | 2 +- api/pkg/api/model/util/util.go | 180 +++++++++++++-- api/pkg/api/model/util/util_test.go | 37 ++++ api/pkg/api/model/vpcprefix.go | 2 +- docs/index.html | 244 ++++++++++++++++++--- openapi/spec.yaml | 9 +- sdk/standard/api_subnet.go | 52 +++-- sdk/standard/model_ip_block_usage_stats.go | 4 +- sdk/standard/model_subnet.go | 51 ++++- 9 files changed, 498 insertions(+), 83 deletions(-) diff --git a/api/pkg/api/model/subnet.go b/api/pkg/api/model/subnet.go index 7c6ada28f..2c23b0a9f 100644 --- a/api/pkg/api/model/subnet.go +++ b/api/pkg/api/model/subnet.go @@ -157,7 +157,7 @@ type APISubnet struct { MTU *int `json:"mtu"` // StatusHistory is the history of statuses for the Subnet StatusHistory []APIStatusDetail `json:"statusHistory"` - // UsageStats reports IPv4 usage (derived from interface count, distinct instance count, and CIDR size) when requested via includeUsageStats + // UsageStats reports IPv4 usage derived from Ethernet interface count and IPv4 CIDR (see GetInterfaceBasedUsageForSubnet) when requested via includeUsageStats UsageStats *APIIPBlockUsageStats `json:"usageStats,omitempty"` // CreatedAt indicates the ISO datetime string for when the entity was created Created time.Time `json:"created"` diff --git a/api/pkg/api/model/util/util.go b/api/pkg/api/model/util/util.go index 32f2e590f..3836656e9 100644 --- a/api/pkg/api/model/util/util.go +++ b/api/pkg/api/model/util/util.go @@ -27,6 +27,7 @@ import ( cipam "github.com/NVIDIA/infra-controller-rest/ipam" "github.com/google/uuid" "github.com/uptrace/bun" + "go4.org/netipx" cdbm "github.com/NVIDIA/infra-controller-rest/db/pkg/db/model" cwssaws "github.com/NVIDIA/infra-controller-rest/workflow-schema/schema/site-agent/workflows/v1" @@ -40,6 +41,9 @@ const ( SitePhoneHomePostAll = "all" SitePhoneHomeUrl = "url" SiteCloudConfig = "#cloud-config" + + // maxInterfaceUsagePreviewPrefixes caps AvailablePrefixes samples for interface-derived Subnet/VPC Prefix usage. + maxInterfaceUsagePreviewPrefixes = 10 ) // Walks through the yaml nodes looking for a cloud-init phone-home block @@ -239,47 +243,177 @@ func subnetIPv4Cidr(sn *cdbm.Subnet) (string, error) { return fmt.Sprintf("%s/%d", p, sn.PrefixLength), nil } -func countInterfacesAndDistinctInstances(ctx context.Context, db bun.IDB, subnetID *uuid.UUID, vpcPrefixID *uuid.UUID) (ifaceCount, instCount uint64, err error) { +func subSatUint64(a, b uint64) uint64 { + if a > b { + return a - b + } + return 0 +} + +// countInterfacesForSubnetOrVpc counts Instance Ethernet interface rows (logical `interface` table; InfiniBand/NVLink use other tables). +func countInterfacesForSubnetOrVpc(ctx context.Context, db bun.IDB, subnetID *uuid.UUID, vpcPrefixID *uuid.UUID) (uint64, error) { var row struct { Iface int64 `bun:"iface_count"` - Inst int64 `bun:"inst_count"` } switch { case subnetID != nil: - err = db.NewRaw( - `SELECT count(*) AS iface_count, count(distinct instance_id) AS inst_count FROM "interface" AS ifc WHERE ifc.subnet_id = ? AND ifc.deleted IS NULL`, + err := db.NewRaw( + `SELECT count(*) AS iface_count FROM "interface" AS ifc WHERE ifc.subnet_id = ? AND ifc.deleted IS NULL`, *subnetID, ).Scan(ctx, &row) + if err != nil { + return 0, err + } case vpcPrefixID != nil: - err = db.NewRaw( - `SELECT count(*) AS iface_count, count(distinct instance_id) AS inst_count FROM "interface" AS ifc WHERE ifc.vpc_prefix_id = ? AND ifc.deleted IS NULL`, + err := db.NewRaw( + `SELECT count(*) AS iface_count FROM "interface" AS ifc WHERE ifc.vpc_prefix_id = ? AND ifc.deleted IS NULL`, *vpcPrefixID, ).Scan(ctx, &row) + if err != nil { + return 0, err + } + default: + return 0, fmt.Errorf("usage stats: need subnet or vpc prefix id") + } + return uint64(row.Iface), nil +} + +func forEachIPv4UsableHost(p netip.Prefix, fn func(addr netip.Addr) bool) { + ipp := p.Masked() + bits := int(ipp.Bits()) + if bits < 0 || bits > 32 || !ipp.Addr().Is4() { + return + } + hostBits := 32 - bits + switch { + case hostBits == 0: + fn(ipp.Addr()) + case bits == 31: + r := netipx.RangeOfPrefix(ipp) + if !fn(r.From()) { + return + } + fn(r.To()) default: - return 0, 0, fmt.Errorf("usage stats: need subnet or vpc prefix id") + r := netipx.RangeOfPrefix(ipp) + first := r.From().Next() + last := r.To().Prev() + for a := first; a.Compare(last) <= 0; a = a.Next() { + if !fn(a) { + return + } + } } +} + +// firstIPv432HostPreview returns up to limit IPv4 /32 strings from usable hosts, skipping the first skipHosts usable addresses in enumeration order. +func firstIPv432HostPreview(cidr string, skipHosts uint64, limit int) ([]string, error) { + if limit <= 0 { + return nil, nil + } + p, err := netip.ParsePrefix(cidr) if err != nil { - return 0, 0, err + return nil, err } - return uint64(row.Iface), uint64(row.Inst), nil + if !p.Addr().Is4() { + return nil, nil + } + var out []string + var idx uint64 + forEachIPv4UsableHost(p, func(addr netip.Addr) bool { + if idx >= skipHosts { + px, err := addr.Prefix(32) + if err == nil { + out = append(out, px.String()) + } + if len(out) >= limit { + return false + } + } + idx++ + return true + }) + return out, nil } -func ipamUsageFromInterfaceTelemetry(usableHosts, ifaceCount, instCount uint64) *cipam.Usage { - var available uint64 - if usableHosts > ifaceCount { - available = usableHosts - ifaceCount +// firstIPv431PrefixPreview returns up to limit IPv4 /31 prefixes inside parentCidr, skipping the first skipBlocks aligned /31 blocks. +func firstIPv431PrefixPreview(parentCidr string, skipBlocks uint64, limit int) ([]string, error) { + if limit <= 0 { + return nil, nil + } + p, err := netip.ParsePrefix(parentCidr) + if err != nil { + return nil, err + } + if !p.Addr().Is4() { + return nil, nil + } + var out []string + var blockIdx uint64 + first := netipx.RangeOfPrefix(p).From() + for p.Contains(first) { + second := first.Next() + if !p.Contains(second) { + break + } + if blockIdx >= skipBlocks { + p31, err := first.Prefix(31) + if err == nil { + out = append(out, p31.String()) + } + if len(out) >= limit { + break + } + } + blockIdx++ + first = second.Next() + } + return out, nil +} + +func subnetUsageFromInterfaceCounts(totalUsableIPv4Hosts, ifaceCount uint64, cidr string) (*cipam.Usage, error) { + acquiredIPs := ifaceCount + 2 + availableIPs := subSatUint64(totalUsableIPv4Hosts, ifaceCount+2) + var prefixes []string + if availableIPs > 0 { + var err error + prefixes, err = firstIPv432HostPreview(cidr, ifaceCount+2, maxInterfaceUsagePreviewPrefixes) + if err != nil { + return nil, err + } } return &cipam.Usage{ - AvailableIPs: available, - AcquiredIPs: ifaceCount, + AvailableIPs: availableIPs, + AcquiredIPs: acquiredIPs, AvailableSmallestPrefixes: 0, - AvailablePrefixes: nil, - AcquiredPrefixes: instCount, + AvailablePrefixes: prefixes, + AcquiredPrefixes: ifaceCount, + }, nil +} + +func vpcPrefixUsageFromInterfaceCounts(totalUsableIPv4Hosts, ifaceCount uint64, cidr string) (*cipam.Usage, error) { + acquiredIPs := ifaceCount * 2 + availableIPs := subSatUint64(totalUsableIPv4Hosts, ifaceCount*2) + availableSmallest := availableIPs / 2 + var prefixes []string + if availableIPs > 0 { + var err error + prefixes, err = firstIPv431PrefixPreview(cidr, ifaceCount, maxInterfaceUsagePreviewPrefixes) + if err != nil { + return nil, err + } } + return &cipam.Usage{ + AvailableIPs: availableIPs, + AcquiredIPs: acquiredIPs, + AvailableSmallestPrefixes: availableSmallest, + AvailablePrefixes: prefixes, + AcquiredPrefixes: ifaceCount, + }, nil } // GetInterfaceBasedUsageForVpcPrefix returns ipam.Usage-shaped stats from VPC prefix IPv4 size and -// interface/instance rows for this vpc_prefix_id (Core allocates instance IPs; not the IPAM subtree). +// Ethernet interface rows for this vpc_prefix_id (Core allocates instance IPs; not the IPAM subtree). func GetInterfaceBasedUsageForVpcPrefix(ctx context.Context, db bun.IDB, vp *cdbm.VpcPrefix) (*cipam.Usage, error) { if vp == nil { return nil, fmt.Errorf("vpc prefix is nil") @@ -292,14 +426,14 @@ func GetInterfaceBasedUsageForVpcPrefix(ctx context.Context, db bun.IDB, vp *cdb if err != nil { return nil, err } - ifaceCount, instCount, err := countInterfacesAndDistinctInstances(ctx, db, nil, &vp.ID) + ifaceCount, err := countInterfacesForSubnetOrVpc(ctx, db, nil, &vp.ID) if err != nil { return nil, err } - return ipamUsageFromInterfaceTelemetry(usable, ifaceCount, instCount), nil + return vpcPrefixUsageFromInterfaceCounts(usable, ifaceCount, cidr) } -// GetInterfaceBasedUsageForSubnet returns ipam.Usage-shaped stats from subnet IPv4 CIDR and interface/instance rows for subnet_id. +// GetInterfaceBasedUsageForSubnet returns ipam.Usage-shaped stats from subnet IPv4 CIDR and Ethernet `interface` rows for subnet_id. func GetInterfaceBasedUsageForSubnet(ctx context.Context, db bun.IDB, sn *cdbm.Subnet) (*cipam.Usage, error) { if sn == nil { return nil, fmt.Errorf("subnet is nil") @@ -312,9 +446,9 @@ func GetInterfaceBasedUsageForSubnet(ctx context.Context, db bun.IDB, sn *cdbm.S if err != nil { return nil, err } - ifaceCount, instCount, err := countInterfacesAndDistinctInstances(ctx, db, &sn.ID, nil) + ifaceCount, err := countInterfacesForSubnetOrVpc(ctx, db, &sn.ID, nil) if err != nil { return nil, err } - return ipamUsageFromInterfaceTelemetry(usable, ifaceCount, instCount), nil + return subnetUsageFromInterfaceCounts(usable, ifaceCount, cidr) } diff --git a/api/pkg/api/model/util/util_test.go b/api/pkg/api/model/util/util_test.go index ed022ca8d..0dc0162aa 100644 --- a/api/pkg/api/model/util/util_test.go +++ b/api/pkg/api/model/util/util_test.go @@ -54,3 +54,40 @@ func TestIPv4UsableHostAddrsFromCidr(t *testing.T) { }) } } + +func TestSubnetUsageFromInterfaceCounts(t *testing.T) { + t.Parallel() + u, err := subnetUsageFromInterfaceCounts(254, 0, "192.168.0.0/24") + require.NoError(t, err) + assert.Equal(t, uint64(252), u.AvailableIPs) + assert.Equal(t, uint64(2), u.AcquiredIPs) + assert.Equal(t, uint64(0), u.AvailableSmallestPrefixes) + assert.Equal(t, uint64(0), u.AcquiredPrefixes) + require.Len(t, u.AvailablePrefixes, 10) + assert.Equal(t, "192.168.0.3/32", u.AvailablePrefixes[0]) + + u3, err := subnetUsageFromInterfaceCounts(254, 3, "192.168.0.0/24") + require.NoError(t, err) + assert.Equal(t, uint64(249), u3.AvailableIPs) + assert.Equal(t, uint64(5), u3.AcquiredIPs) + assert.Equal(t, uint64(3), u3.AcquiredPrefixes) +} + +func TestVpcPrefixUsageFromInterfaceCounts(t *testing.T) { + t.Parallel() + u, err := vpcPrefixUsageFromInterfaceCounts(254, 1, "192.168.0.0/24") + require.NoError(t, err) + assert.Equal(t, uint64(252), u.AvailableIPs) + assert.Equal(t, uint64(2), u.AcquiredIPs) + assert.Equal(t, uint64(126), u.AvailableSmallestPrefixes) + assert.Equal(t, uint64(1), u.AcquiredPrefixes) + require.NotEmpty(t, u.AvailablePrefixes) + assert.Equal(t, "192.168.0.2/31", u.AvailablePrefixes[0]) + + u0, err := vpcPrefixUsageFromInterfaceCounts(254, 0, "192.168.0.0/24") + require.NoError(t, err) + assert.Equal(t, uint64(254), u0.AvailableIPs) + assert.Equal(t, uint64(0), u0.AcquiredIPs) + assert.Equal(t, uint64(127), u0.AvailableSmallestPrefixes) + assert.Equal(t, "192.168.0.0/31", u0.AvailablePrefixes[0]) +} diff --git a/api/pkg/api/model/vpcprefix.go b/api/pkg/api/model/vpcprefix.go index df1a1e1bc..2f2bb8f22 100644 --- a/api/pkg/api/model/vpcprefix.go +++ b/api/pkg/api/model/vpcprefix.go @@ -135,7 +135,7 @@ type APIVpcPrefix struct { Status string `json:"status"` // StatusHistory is the history of statuses for the VpcPrefix StatusHistory []APIStatusDetail `json:"statusHistory"` - // UsageStats reports IPv4 usage (derived from interface count, distinct instance count, and CIDR size) when requested via includeUsageStats + // UsageStats reports IPv4 usage derived from Ethernet interface count and IPv4 CIDR (see GetInterfaceBasedUsageForVpcPrefix) when requested via includeUsageStats UsageStats *APIIPBlockUsageStats `json:"usageStats,omitempty"` // CreatedAt indicates the ISO datetime string for when the entity was created Created time.Time `json:"created"` diff --git a/docs/index.html b/docs/index.html index f97df0215..8d8f24b8b 100644 --- a/docs/index.html +++ b/docs/index.html @@ -2438,6 +2438,8 @@

Typical API Call Flow for Tenant

" class="sc-iJuXkV sc-cBNeAB iNuSsz dyntKg">

Search for matches across all Sites. Input will be matched against name and status fields

includeRelation
string
Enum: "VPC" "Tenant" "IPBlock"

Related entity to expand

+
includeUsageStats
boolean

When true, includes IPAM usage for each VPC prefix (usageStats), same shape as IP Block usage (available/acquired IPs and child prefixes). Loads the parent IP Block relation internally if needed.

pageNumber
integer >= 1
Default: 1
Example: pageNumber=1

Page number for pagination query

pageSize
integer [ 1 .. 100 ]
Example: pageSize=20
Typical API Call Flow for Tenant " class="sc-iJuXkV sc-cBNeAB iNuSsz dyntKg">

Length of the prefix. Valid range is 8 to 31, and max usable value depends on prefix length of parent IP Block.

status
string (VpcPrefixStatus)
Enum: "Ready" "Deleting" "Error"

Status of the VPC Prefix

-
Array of objects (StatusDetail)
object (IpBlockUsageStats)

Present when query param includeUsageStats=true. IPAM usage within this VPC prefix (available/acquired IPs and child prefixes consumed by Instances and other allocations).

+
availableIPs
integer <int64>

Number of IP addresses available in the block

+
acquiredIPs
integer <int64>

Number of individual IP addresses acquired from the block

+
availablePrefixes
Array of strings

Example prefixes available to acquire. For IPBlocks this comes from IPAM. +For Subnets and VPC Prefixes with interface-derived usage, at most 10 sample prefixes are returned +(/32 host prefixes for Subnets; /31 prefixes for VPC Prefixes).

+
availableSmallestPrefixes
integer <int64>

Number of smallest prefixes available to acquire. For VPC Prefix interface-derived usage this is the count of remaining /31 interface slots (half of remaining IPs). +Subnet interface-derived usage leaves this as zero; IPBlocks use IPAM semantics.

+
acquiredPrefixes
integer <int64>

Number of prefixes acquired from this block

+
Array of objects (StatusDetail)

Details of 20 most recent status changes

Array
status
string
message
string or null
created
string <date-time>
updated
string <date-time>
created
string <date-time>

Date and time when the VPC Prefix was created

@@ -2506,7 +2526,25 @@

Typical API Call Flow for Tenant

" class="sc-iJuXkV sc-cBNeAB iNuSsz dyntKg">

Length of the prefix. Valid range is 8 to 31, and max usable value depends on prefix length of parent IP Block.

status
string (VpcPrefixStatus)
Enum: "Ready" "Deleting" "Error"

Status of the VPC Prefix

-
Array of objects (StatusDetail)
object (IpBlockUsageStats)

Present when query param includeUsageStats=true. IPAM usage within this VPC prefix (available/acquired IPs and child prefixes consumed by Instances and other allocations).

+
availableIPs
integer <int64>

Number of IP addresses available in the block

+
acquiredIPs
integer <int64>

Number of individual IP addresses acquired from the block

+
availablePrefixes
Array of strings

Example prefixes available to acquire. For IPBlocks this comes from IPAM. +For Subnets and VPC Prefixes with interface-derived usage, at most 10 sample prefixes are returned +(/32 host prefixes for Subnets; /31 prefixes for VPC Prefixes).

+
availableSmallestPrefixes
integer <int64>

Number of smallest prefixes available to acquire. For VPC Prefix interface-derived usage this is the count of remaining /31 interface slots (half of remaining IPs). +Subnet interface-derived usage leaves this as zero; IPBlocks use IPAM semantics.

+
acquiredPrefixes
integer <int64>

Number of prefixes acquired from this block

+
Array of objects (StatusDetail)

Details of 20 most recent status changes

Array
status
string
message
string or null
created
string <date-time>
updated
string <date-time>
created
string <date-time>

Date and time when the VPC Prefix was created

@@ -2526,8 +2564,10 @@

Typical API Call Flow for Tenant

" class="sc-iJuXkV sc-cBNeAB iNuSsz dyntKg">

Name of the Org

vpcPrefixId
required
string <uuid>

ID of the VPC Prefix

-
query Parameters
includeRelation
string
Enum: "VPC" "Tenant" "IPBlock"
query Parameters
includeRelation
string
Enum: "VPC" "Tenant" "IPBlock"

Related entity to expand

+
includeUsageStats
boolean

When true, includes IPAM usage for this VPC prefix (usageStats), same shape as IP Block usage. Loads the parent IP Block relation internally if needed.

Responses

Response Schema: application/json
id
string <uuid>
name
string [ 2 .. 256 ] characters
Typical API Call Flow for Tenant " class="sc-iJuXkV sc-cBNeAB iNuSsz dyntKg">

Length of the prefix. Valid range is 8 to 31, and max usable value depends on prefix length of parent IP Block.

status
string (VpcPrefixStatus)
Enum: "Ready" "Deleting" "Error"

Status of the VPC Prefix

-
Array of objects (StatusDetail)
object (IpBlockUsageStats)

Present when query param includeUsageStats=true. IPAM usage within this VPC prefix (available/acquired IPs and child prefixes consumed by Instances and other allocations).

+
availableIPs
integer <int64>

Number of IP addresses available in the block

+
acquiredIPs
integer <int64>

Number of individual IP addresses acquired from the block

+
availablePrefixes
Array of strings

Example prefixes available to acquire. For IPBlocks this comes from IPAM. +For Subnets and VPC Prefixes with interface-derived usage, at most 10 sample prefixes are returned +(/32 host prefixes for Subnets; /31 prefixes for VPC Prefixes).

+
availableSmallestPrefixes
integer <int64>

Number of smallest prefixes available to acquire. For VPC Prefix interface-derived usage this is the count of remaining /31 interface slots (half of remaining IPs). +Subnet interface-derived usage leaves this as zero; IPBlocks use IPAM semantics.

+
acquiredPrefixes
integer <int64>

Number of prefixes acquired from this block

+
Array of objects (StatusDetail)

Details of 20 most recent status changes

Array
status
string
message
string or null
created
string <date-time>
updated
string <date-time>
created
string <date-time>

Date and time when the VPC Prefix was created

@@ -2596,7 +2654,25 @@

Typical API Call Flow for Tenant

" class="sc-iJuXkV sc-cBNeAB iNuSsz dyntKg">

Length of the prefix. Valid range is 8 to 31, and max usable value depends on prefix length of parent IP Block.

status
string (VpcPrefixStatus)
Enum: "Ready" "Deleting" "Error"

Status of the VPC Prefix

-
Array of objects (StatusDetail)
object (IpBlockUsageStats)

Present when query param includeUsageStats=true. IPAM usage within this VPC prefix (available/acquired IPs and child prefixes consumed by Instances and other allocations).

+
availableIPs
integer <int64>

Number of IP addresses available in the block

+
acquiredIPs
integer <int64>

Number of individual IP addresses acquired from the block

+
availablePrefixes
Array of strings

Example prefixes available to acquire. For IPBlocks this comes from IPAM. +For Subnets and VPC Prefixes with interface-derived usage, at most 10 sample prefixes are returned +(/32 host prefixes for Subnets; /31 prefixes for VPC Prefixes).

+
availableSmallestPrefixes
integer <int64>

Number of smallest prefixes available to acquire. For VPC Prefix interface-derived usage this is the count of remaining /31 interface slots (half of remaining IPs). +Subnet interface-derived usage leaves this as zero; IPBlocks use IPAM semantics.

+
acquiredPrefixes
integer <int64>

Number of prefixes acquired from this block

+
Array of objects (StatusDetail)

Details of 20 most recent status changes

Array
status
string
message
string or null
created
string <date-time>
updated
string <date-time>
created
string <date-time>

Date and time when the VPC Prefix was created

@@ -2636,6 +2712,8 @@

Typical API Call Flow for Tenant

" class="sc-iJuXkV sc-cBNeAB iNuSsz dyntKg">

Search for matches across all Sites. Input will be matched against name, description and status fields

includeRelation
string
Enum: "VPC" "Tenant" "IPv4Block" "IPv6Block"

Related entity to expand

+
includeUsageStats
boolean

When true, includes IPAM usage for each Subnet's IPv4 space (usageStats), same shape as IP Block usage. Loads the parent IPv4 IP Block relation internally if needed.

pageNumber
integer >= 1
Default: 1
Example: pageNumber=1

Page number for pagination query

pageSize
integer [ 1 .. 100 ]
Example: pageSize=20
Typical API Call Flow for Tenant " class="sc-iJuXkV sc-cBNeAB iNuSsz dyntKg">

Max value depends on prefix length of parent IP Block

routingType
string or null
Enum: "Public" "DatacenterOnly"
status
string (SubnetStatus)
Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error"

Status values for Subnet objects

-
Array of objects (StatusDetail)
Array
status
string
message
string or null
created
string <date-time>
updated
string <date-time>
created
string <date-time>
updated
string <date-time>
Array of objects (Deprecation)
Array
attribute
string or null
queryParam
string or null
endpoint
string or null
replacedBy
string or null
takeActionBy
string <date-time>
notice
string
object (IpBlockUsageStats)

Present when query param includeUsageStats=true. IPAM IPv4 usage within this Subnet (available/acquired IPs and child prefixes used by Instances and other allocations).

+
availableIPs
integer <int64>

Number of IP addresses available in the block

+
acquiredIPs
integer <int64>

Number of individual IP addresses acquired from the block

+
availablePrefixes
Array of strings

Example prefixes available to acquire. For IPBlocks this comes from IPAM. +For Subnets and VPC Prefixes with interface-derived usage, at most 10 sample prefixes are returned +(/32 host prefixes for Subnets; /31 prefixes for VPC Prefixes).

+
availableSmallestPrefixes
integer <int64>

Number of smallest prefixes available to acquire. For VPC Prefix interface-derived usage this is the count of remaining /31 interface slots (half of remaining IPs). +Subnet interface-derived usage leaves this as zero; IPBlocks use IPAM semantics.

+
acquiredPrefixes
integer <int64>

Number of prefixes acquired from this block

+
Array of objects (StatusDetail)
Array
status
string
message
string or null
created
string <date-time>
updated
string <date-time>
created
string <date-time>
updated
string <date-time>
Array of objects (Deprecation)
Array
attribute
string or null
queryParam
string or null
endpoint
string or null
replacedBy
string or null
takeActionBy
string <date-time>
notice
string
routingType
string or null
Enum: "Public" "DatacenterOnly"
status
string (SubnetStatus)
Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error"

Status values for Subnet objects

-
Array of objects (StatusDetail)
Array
status
string
message
string or null
created
string <date-time>
updated
string <date-time>
created
string <date-time>
updated
string <date-time>
Array of objects (Deprecation)
Array
attribute
string or null
queryParam
string or null
endpoint
string or null
replacedBy
string or null
takeActionBy
string <date-time>
notice
string
object (IpBlockUsageStats)

Present when query param includeUsageStats=true. IPAM IPv4 usage within this Subnet (available/acquired IPs and child prefixes used by Instances and other allocations).

+
availableIPs
integer <int64>

Number of IP addresses available in the block

+
acquiredIPs
integer <int64>

Number of individual IP addresses acquired from the block

+
availablePrefixes
Array of strings

Example prefixes available to acquire. For IPBlocks this comes from IPAM. +For Subnets and VPC Prefixes with interface-derived usage, at most 10 sample prefixes are returned +(/32 host prefixes for Subnets; /31 prefixes for VPC Prefixes).

+
availableSmallestPrefixes
integer <int64>

Number of smallest prefixes available to acquire. For VPC Prefix interface-derived usage this is the count of remaining /31 interface slots (half of remaining IPs). +Subnet interface-derived usage leaves this as zero; IPBlocks use IPAM semantics.

+
acquiredPrefixes
integer <int64>

Number of prefixes acquired from this block

+
Array of objects (StatusDetail)
Array
status
string
message
string or null
created
string <date-time>
updated
string <date-time>
created
string <date-time>
updated
string <date-time>
Array of objects (Deprecation)
Array
attribute
string or null
queryParam
string or null
endpoint
string or null
replacedBy
string or null
takeActionBy
string <date-time>
notice
string
subnetId
required
string <uuid>

ID of the Subnet

-
query Parameters
includeRelation
string
Enum: "VPC" "Tenant" "IPv4Block" "IPv6Block"
query Parameters
includeRelation
string
Enum: "VPC" "Tenant" "IPv4Block" "IPv6Block"

Related entity to expand

+
includeUsageStats
boolean

When true, includes IPAM usage for this Subnet's IPv4 space (usageStats), same shape as IP Block usage. Loads the parent IPv4 IP Block relation internally if needed.

Responses

Response Schema: application/json
id
string <uuid>
name
string [ 2 .. 256 ] characters
description
string or null
siteId
string <uuid>
vpcId
string <uuid>
tenantId
string <uuid>
controllerNetworkSegmentId
string or null <uuid>
ipv4Prefix
string or null <ipv4>
Typical API Call Flow for Tenant " class="sc-iJuXkV sc-cBNeAB iNuSsz dyntKg">

Max value depends on prefix length of parent IP Block

routingType
string or null
Enum: "Public" "DatacenterOnly"
status
string (SubnetStatus)
Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error"

Status values for Subnet objects

-
Array of objects (StatusDetail)
Array
status
string
message
string or null
created
string <date-time>
updated
string <date-time>
created
string <date-time>
updated
string <date-time>
Array of objects (Deprecation)
Array
attribute
string or null
queryParam
string or null
endpoint
string or null
replacedBy
string or null
takeActionBy
string <date-time>
notice
string
object (IpBlockUsageStats)

Present when query param includeUsageStats=true. IPAM IPv4 usage within this Subnet (available/acquired IPs and child prefixes used by Instances and other allocations).

+
availableIPs
integer <int64>

Number of IP addresses available in the block

+
acquiredIPs
integer <int64>

Number of individual IP addresses acquired from the block

+
availablePrefixes
Array of strings

Example prefixes available to acquire. For IPBlocks this comes from IPAM. +For Subnets and VPC Prefixes with interface-derived usage, at most 10 sample prefixes are returned +(/32 host prefixes for Subnets; /31 prefixes for VPC Prefixes).

+
availableSmallestPrefixes
integer <int64>

Number of smallest prefixes available to acquire. For VPC Prefix interface-derived usage this is the count of remaining /31 interface slots (half of remaining IPs). +Subnet interface-derived usage leaves this as zero; IPBlocks use IPAM semantics.

+
acquiredPrefixes
integer <int64>

Number of prefixes acquired from this block

+
Array of objects (StatusDetail)
Array
status
string
message
string or null
created
string <date-time>
updated
string <date-time>
created
string <date-time>
updated
string <date-time>
Array of objects (Deprecation)
Array
attribute
string or null
queryParam
string or null
endpoint
string or null
replacedBy
string or null
takeActionBy
string <date-time>
notice
string
routingType
string or null
Enum: "Public" "DatacenterOnly"
status
string (SubnetStatus)
Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error"

Status values for Subnet objects

-
Array of objects (StatusDetail)
Array
status
string
message
string or null
created
string <date-time>
updated
string <date-time>
created
string <date-time>
updated
string <date-time>
Array of objects (Deprecation)
Array
attribute
string or null
queryParam
string or null
endpoint
string or null
replacedBy
string or null
takeActionBy
string <date-time>
notice
string
object (IpBlockUsageStats)

Present when query param includeUsageStats=true. IPAM IPv4 usage within this Subnet (available/acquired IPs and child prefixes used by Instances and other allocations).

+
availableIPs
integer <int64>

Number of IP addresses available in the block

+
acquiredIPs
integer <int64>

Number of individual IP addresses acquired from the block

+
availablePrefixes
Array of strings

Example prefixes available to acquire. For IPBlocks this comes from IPAM. +For Subnets and VPC Prefixes with interface-derived usage, at most 10 sample prefixes are returned +(/32 host prefixes for Subnets; /31 prefixes for VPC Prefixes).

+
availableSmallestPrefixes
integer <int64>

Number of smallest prefixes available to acquire. For VPC Prefix interface-derived usage this is the count of remaining /31 interface slots (half of remaining IPs). +Subnet interface-derived usage leaves this as zero; IPBlocks use IPAM semantics.

+
acquiredPrefixes
integer <int64>

Number of prefixes acquired from this block

+
Array of objects (StatusDetail)
Array
status
string
message
string or null
created
string <date-time>
updated
string <date-time>
created
string <date-time>
updated
string <date-time>
Array of objects (Deprecation)
Array
attribute
string or null
queryParam
string or null
endpoint
string or null
replacedBy
string or null
takeActionBy
string <date-time>
notice
string
acquiredIPs
integer <int64>

Number of individual IP addresses acquired from the block

-
availablePrefixes
Array of strings

Example prefixes available to acquire

-
availableSmallestPrefixes
integer <int64>

Number of smallest prefixes available to acquire

+
availablePrefixes
Array of strings

Example prefixes available to acquire. For IPBlocks this comes from IPAM. +For Subnets and VPC Prefixes with interface-derived usage, at most 10 sample prefixes are returned +(/32 host prefixes for Subnets; /31 prefixes for VPC Prefixes).

+
availableSmallestPrefixes
integer <int64>

Number of smallest prefixes available to acquire. For VPC Prefix interface-derived usage this is the count of remaining /31 interface slots (half of remaining IPs). +Subnet interface-derived usage leaves this as zero; IPBlocks use IPAM semantics.

acquiredPrefixes
integer <int64>

Number of prefixes acquired from this block

status
string (IpBlockStatus)
Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error"
Typical API Call Flow for Tenant " class="sc-iJuXkV sc-cBNeAB iNuSsz dyntKg">

Number of IP addresses available in the block

acquiredIPs
integer <int64>

Number of individual IP addresses acquired from the block

-
availablePrefixes
Array of strings

Example prefixes available to acquire

-
availableSmallestPrefixes
integer <int64>

Number of smallest prefixes available to acquire

+
availablePrefixes
Array of strings

Example prefixes available to acquire. For IPBlocks this comes from IPAM. +For Subnets and VPC Prefixes with interface-derived usage, at most 10 sample prefixes are returned +(/32 host prefixes for Subnets; /31 prefixes for VPC Prefixes).

+
availableSmallestPrefixes
integer <int64>

Number of smallest prefixes available to acquire. For VPC Prefix interface-derived usage this is the count of remaining /31 interface slots (half of remaining IPs). +Subnet interface-derived usage leaves this as zero; IPBlocks use IPAM semantics.

acquiredPrefixes
integer <int64>

Number of prefixes acquired from this block

status
string (IpBlockStatus)
Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error"
Typical API Call Flow for Tenant " class="sc-iJuXkV sc-cBNeAB iNuSsz dyntKg">

Number of IP addresses available in the block

acquiredIPs
integer <int64>

Number of individual IP addresses acquired from the block

-
availablePrefixes
Array of strings

Example prefixes available to acquire

-
availableSmallestPrefixes
integer <int64>

Number of smallest prefixes available to acquire

+
availablePrefixes
Array of strings

Example prefixes available to acquire. For IPBlocks this comes from IPAM. +For Subnets and VPC Prefixes with interface-derived usage, at most 10 sample prefixes are returned +(/32 host prefixes for Subnets; /31 prefixes for VPC Prefixes).

+
availableSmallestPrefixes
integer <int64>

Number of smallest prefixes available to acquire. For VPC Prefix interface-derived usage this is the count of remaining /31 interface slots (half of remaining IPs). +Subnet interface-derived usage leaves this as zero; IPBlocks use IPAM semantics.

acquiredPrefixes
integer <int64>

Number of prefixes acquired from this block

status
string (IpBlockStatus)
Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error"
Typical API Call Flow for Tenant " class="sc-iJuXkV sc-cBNeAB iNuSsz dyntKg">

Number of IP addresses available in the block

acquiredIPs
integer <int64>

Number of individual IP addresses acquired from the block

-
availablePrefixes
Array of strings

Example prefixes available to acquire

-
availableSmallestPrefixes
integer <int64>

Number of smallest prefixes available to acquire

+
availablePrefixes
Array of strings

Example prefixes available to acquire. For IPBlocks this comes from IPAM. +For Subnets and VPC Prefixes with interface-derived usage, at most 10 sample prefixes are returned +(/32 host prefixes for Subnets; /31 prefixes for VPC Prefixes).

+
availableSmallestPrefixes
integer <int64>

Number of smallest prefixes available to acquire. For VPC Prefix interface-derived usage this is the count of remaining /31 interface slots (half of remaining IPs). +Subnet interface-derived usage leaves this as zero; IPBlocks use IPAM semantics.

acquiredPrefixes
integer <int64>

Number of prefixes acquired from this block

status
string (IpBlockStatus)
Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error"
Typical API Call Flow for Tenant " class="sc-iJuXkV sc-cBNeAB iNuSsz dyntKg">

Number of IP addresses available in the block

acquiredIPs
integer <int64>

Number of individual IP addresses acquired from the block

-
availablePrefixes
Array of strings

Example prefixes available to acquire

-
availableSmallestPrefixes
integer <int64>

Number of smallest prefixes available to acquire

+
availablePrefixes
Array of strings

Example prefixes available to acquire. For IPBlocks this comes from IPAM. +For Subnets and VPC Prefixes with interface-derived usage, at most 10 sample prefixes are returned +(/32 host prefixes for Subnets; /31 prefixes for VPC Prefixes).

+
availableSmallestPrefixes
integer <int64>

Number of smallest prefixes available to acquire. For VPC Prefix interface-derived usage this is the count of remaining /31 interface slots (half of remaining IPs). +Subnet interface-derived usage leaves this as zero; IPBlocks use IPAM semantics.

acquiredPrefixes
integer <int64>

Number of prefixes acquired from this block

status
string (IpBlockStatus)
Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error"
Typical API Call Flow for Tenant
-
API docs by Redocly
API docs by Redocly

NVIDIA Infra Controller REST API (1.5.0)

Download OpenAPI specification:

License: Apache-2.0

NVIDIA Infra Controller REST API is the centralized RESTful gateway to access NVIDIA Infra Controller service

+ " fill="currentColor">

NVIDIA Infra Controller REST API (1.5.0)

Download OpenAPI specification:

License: Apache-2.0

NVIDIA Infra Controller REST API is the centralized RESTful gateway to access NVIDIA Infra Controller service

NVIDIA Infra Controller REST API allows users to create and manage resources e.g. VPC, Subnets, Instances across all connected NVIDIA Infra Controller datacenters, also referred to as Sites.

-

Getting Started

NVIDIA Infra Controller REST API allows users to create and manage resources e.g. VPC, Subnets, Instances across all connected NVIDIA Infra Controller datacenters, also referred to as Sites.

+

Getting Started

Typical API Call Flow for Tenant the Tenant has received a Compute Allocation from the Provider will be returned.
  • Create an Instance specifying the VPC, VPC Prefix or Subnet, Operating System, and Instance Type
    • -

    Service Account

    Service Account

    When API service is configured in Service Account mode, API users can act as both Provider and Tenant. For service accounts, the Tenant entity is initialized as a privileged Tenant with targetedInstanceCreation capability enabled.

    -

    Retrieve Service Account status for current org

    Retrieve Service Account status for current org

    Retrieve Service Account status for current org

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve Service Account status for current org

    API service must be configured for Service Account access at the time of deployment. It cannot be enabled or disabled via API.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -

    Responses

    Response Schema: application/json
    enabled
    boolean

    Indicates whether Service Account is enabled

    -
    infrastructureProviderId
    string or null <uuid>

    ID of the Infrastructure Provider associated with Service Account

    -
    tenantId
    string or null <uuid>

    ID of the Tenant associated with Service Account

    -

    Response samples

    Content type
    application/json
    {
    • "enabled": true,
    • "infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0"
    }

    Infrastructure Provider

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +

    Responses

    Response Schema: application/json
    enabled
    boolean

    Indicates whether Service Account is enabled

    +
    infrastructureProviderId
    string or null <uuid>

    ID of the Infrastructure Provider associated with Service Account

    +
    tenantId
    string or null <uuid>

    ID of the Tenant associated with Service Account

    +

    Response samples

    Content type
    application/json
    {
    • "enabled": true,
    • "infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0"
    }

    Infrastructure Provider

    Typical API Call Flow for Tenant
  • POST /org/:orgName/nico/infrastructure-provider endpoint was deprecated and was removed on August 17th, 2023 0:00 UTC. Infrastructure Providers are automatically created when retrieved by a Provider Admin.
  • PATCH /org/:orgName/nico/infrastructure-provider/current endpoint was deprecated and was removed on August 17th, 2023 0:00 UTC. Infrastructure Provider details are populated from Org information and cannot be updated by the user.
    • -

    Retrieve Infrastructure Provider for current Org

    Retrieve Infrastructure Provider for current Org

    Retrieve Infrastructure Provider entity for current Org.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve Infrastructure Provider entity for current Org.

    User must have authorization role with PROVIDER_ADMIN suffix.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -

    Responses

    Response Schema: application/json
    id
    string <uuid>
    org
    string
    orgDisplayName
    string or null
    created
    string <date-time>
    updated
    string <date-time>

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "org": "rf43bbtnb9c5",
    • "orgDisplayName": "Dell Corporation",
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Retrieve Stats for current Infrastructure Provider

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +

    Responses

    Response Schema: application/json
    id
    string <uuid>
    org
    string
    orgDisplayName
    string or null
    created
    string <date-time>
    updated
    string <date-time>

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "org": "rf43bbtnb9c5",
    • "orgDisplayName": "Dell Corporation",
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Retrieve Stats for current Infrastructure Provider

    Retrieve stats for current Infrastructure Provider.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve stats for current Infrastructure Provider.

    User must have authorization role with PROVIDER_ADMIN suffix.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -

    Responses

    Response Schema: application/json
    object (MachineCountByStatus)

    Describes count of Machines in various statuses

    -
    total
    integer
    initializing
    integer
    reset
    integer
    assigned
    integer
    ready
    integer
    error
    integer
    decommissioned
    integer
    unknown
    integer
    object (IpBlockCountByStatus)

    Describes counts of IP Blocks in various statuses

    -
    total
    integer
    pending
    integer
    provisioning
    integer
    ready
    integer
    deleting
    integer
    error
    integer
    object (TenantAccountCountByStatus)

    Describes counts of Tenant Accounts in various statuses

    -
    total
    integer
    pending
    integer
    invited
    integer
    ready
    integer
    error
    integer

    Response samples

    Content type
    application/json
    {
    • "machine": {
      },
    • "ipBlock": {
      },
    • "tenantAccount": {
      }
    }

    Tenant

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +

    Responses

    Response Schema: application/json
    object (MachineCountByStatus)

    Describes count of Machines in various statuses

    +
    total
    integer
    initializing
    integer
    reset
    integer
    assigned
    integer
    ready
    integer
    error
    integer
    decommissioned
    integer
    unknown
    integer
    object (IpBlockCountByStatus)

    Describes counts of IP Blocks in various statuses

    +
    total
    integer
    pending
    integer
    provisioning
    integer
    ready
    integer
    deleting
    integer
    error
    integer
    object (TenantAccountCountByStatus)

    Describes counts of Tenant Accounts in various statuses

    +
    total
    integer
    pending
    integer
    invited
    integer
    ready
    integer
    error
    integer

    Response samples

    Content type
    application/json
    {
    • "machine": {
      },
    • "ipBlock": {
      },
    • "tenantAccount": {
      }
    }

    Tenant

    Typical API Call Flow for Tenant
  • POST /org/:orgName/nico/tenant endpoint was deprecated and was removed on August 17th, 2023 0:00 UTC. Tenants are automatically created when retrieved by a Tenant Admin.
  • PATCH /org/:orgName/nico/tenant/current endpoint was deprecated and was removed on August 17th, 2023 0:00 UTC. Tenant details are populated from Org information and cannot be updated by the user.
    • -

    Retrieve Tenant for current Org

    Retrieve Tenant for current Org

    Retrieve Tenant entity for current Org.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve Tenant entity for current Org.

    User must have authorization role with TENANT_ADMIN suffix.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique ID of the Tenant

    -
    org
    string

    Name/external ID of Tenant's organization

    -
    orgDisplayName
    string or null

    Display name of Tenant's organization

    -
    created
    string <date-time>

    Date/time the Tenant was created

    -
    updated
    string <date-time>

    Date/time when Tenant was last updated

    -
    object (TenantCapabilities)

    Features that are enabled/disabled for Tenant

    -
    targetedInstanceCreation
    boolean <uuid>

    Indicates whether Tenant can create Instances by specifying Machine ID

    -

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "org": "qygdmg8oqik8",
    • "orgDisplayName": "Echo Corporation",
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z",
    • "capabilities": {
      }
    }

    Retrieve Stats for current Tenant

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique ID of the Tenant

    +
    org
    string

    Name/external ID of Tenant's organization

    +
    orgDisplayName
    string or null

    Display name of Tenant's organization

    +
    created
    string <date-time>

    Date/time the Tenant was created

    +
    updated
    string <date-time>

    Date/time when Tenant was last updated

    +
    object (TenantCapabilities)

    Features that are enabled/disabled for Tenant

    +
    targetedInstanceCreation
    boolean <uuid>

    Indicates whether Tenant can create Instances by specifying Machine ID

    +

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "org": "qygdmg8oqik8",
    • "orgDisplayName": "Echo Corporation",
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z",
    • "capabilities": {
      }
    }

    Retrieve Stats for current Tenant

    Retrieve stats for current Tenant.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve stats for current Tenant.

    User must have authorization role with TENANT_ADMIN suffix.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -

    Responses

    Response Schema: application/json
    object (InstanceCountByStatus)

    Describes count of Instances in various statuses

    -
    total
    integer
    pending
    integer
    provisioning
    integer
    ready
    integer
    terminating
    integer
    error
    integer
    object (VpcCountByStatus)

    Describes counts of VPCs in various statuses

    -
    total
    integer
    pending
    integer
    provisioning
    integer
    ready
    integer
    deleting
    integer
    error
    integer
    object (SubnetCountByStatus)

    Describes counts of Subnets in various statuses

    -
    total
    integer
    pending
    integer
    provisioning
    integer
    ready
    integer
    deleting
    integer
    error
    integer

    Response samples

    Content type
    application/json
    {
    • "instance": {
      },
    • "vpc": {
      },
    • "subnet": {
      }
    }

    Retrieve per-tenant instance type allocation stats for a site

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +

    Responses

    Response Schema: application/json
    object (InstanceCountByStatus)

    Describes count of Instances in various statuses

    +
    total
    integer
    pending
    integer
    provisioning
    integer
    ready
    integer
    terminating
    integer
    error
    integer
    object (VpcCountByStatus)

    Describes counts of VPCs in various statuses

    +
    total
    integer
    pending
    integer
    provisioning
    integer
    ready
    integer
    deleting
    integer
    error
    integer
    object (SubnetCountByStatus)

    Describes counts of Subnets in various statuses

    +
    total
    integer
    pending
    integer
    provisioning
    integer
    ready
    integer
    deleting
    integer
    error
    integer

    Response samples

    Content type
    application/json
    {
    • "instance": {
      },
    • "vpc": {
      },
    • "subnet": {
      }
    }

    Retrieve per-tenant instance type allocation stats for a site

    Returns instance type allocation stats grouped by tenant for the specified site.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Returns instance type allocation stats grouped by tenant for the specified site.

    User must have authorization role with PROVIDER_ADMIN suffix. The specified site must belong to the Provider.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    query Parameters
    siteId
    required
    string <uuid>

    ID of the Site

    -

    Responses

    Response Schema: application/json
    Array
    id
    string <uuid>

    Unique identifier for the Tenant

    -
    org
    string

    Organization name for the Tenant

    -
    orgDisplayName
    string

    Display name for the Tenant's organization

    -
    Array of objects (InstanceTypeStats)
    Array
    id
    string <uuid>
    name
    string
    allocated
    integer
    object (MachineStatusBreakdown)

    Machine counts broken down by status

    -
    maxAllocatable
    integer
    Array of objects (AllocationStats)

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Tenant Account

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    query Parameters
    siteId
    required
    string <uuid>

    ID of the Site

    +

    Responses

    Response Schema: application/json
    Array
    id
    string <uuid>

    Unique identifier for the Tenant

    +
    org
    string

    Organization name for the Tenant

    +
    orgDisplayName
    string

    Display name for the Tenant's organization

    +
    Array of objects (InstanceTypeStats)
    Array
    id
    string <uuid>
    name
    string
    allocated
    integer
    object (MachineStatusBreakdown)

    Machine counts broken down by status

    +
    maxAllocatable
    integer
    Array of objects (AllocationStats)

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Tenant Account

    Tenant Account connects a Tenant with an Infrastructure Provider. It represents/contains any information pertaining to their relationship.

    -

    Retrieve all Tenant Accounts

    Retrieve all Tenant Accounts

    Retrieve all Tenant Accounts.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve all Tenant Accounts.

    Either infrastructureProviderId or tenantId query param must be specified.

    If infrastructureProviderId query param is provided, then org must have an Infrastructure Provider entity and its ID should match the query param value. User must have authorization role with PROVIDER_ADMIN suffix.

    If tenantId query param is provided, then org must have a Tenant entity and its ID should match the query param value. User must have authorization role with TENANT_ADMIN suffix.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    query Parameters
    infrastructureProviderId
    string <uuid>

    Filter TenantAccounts by Infrastructure Provider ID

    -
    tenantId
    string <uuid>

    Filter TenantAccounts by Tenant ID

    -
    query
    string

    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

    Page number for pagination query

    -
    pageSize
    integer [ 1 .. 100 ]
    Example: pageSize=20

    Page size for pagination query

    -
    orderBy
    string
    Enum: "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" "ACCOUNT_NUMBER_ASC" "ACCOUNT_NUMBER_DESC" "TENANT_ORG_NAME_ASC" "TENANT_ORG_NAME_DESC" "TENANT_ORG_DISPLAY_NAME_ASC" "TENANT_ORG_DISPLAY_NAME_DESC" "TENANT_CONTACT_EMAIL_ASC" "TENANT_CONTACT_EMAIL_DESC" "TENANT_CONTACT_FULL_NAME_ASC" "TENANT_CONTACT_FULL_NAME_DESC"

    Ordering for pagination query

    -

    Responses

    Response Headers
    X-Pagination
    string
    Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}"

    Pagination result in JSON format

    -
    Response Schema: application/json
    Array
    id
    string <uuid>
    infrastructureProviderId
    string <uuid>
    infrastructureProviderOrg
    string
    tenantId
    string or null <uuid>
    tenantOrg
    string or null
    object (User)

    Details of the user collected from authentication tokens

    -
    id
    string <uuid>

    Unique identifier for the given user.

    -
    email
    string or null <email>
    firstName
    string or null
    lastName
    string or null
    created
    string <date-time>

    The date that the user was created.

    -
    updated
    string <date-time>
    allocationCount
    integer
    status
    string (TenantAccountStatus)
    Enum: "Pending" "Invited" "Ready" "Error"

    Status values for Tenant Account objects

    -
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Create Tenant Account

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    query Parameters
    infrastructureProviderId
    string <uuid>

    Filter TenantAccounts by Infrastructure Provider ID

    +
    tenantId
    string <uuid>

    Filter TenantAccounts by Tenant ID

    +
    query
    string

    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

    Page number for pagination query

    +
    pageSize
    integer [ 1 .. 100 ]
    Example: pageSize=20

    Page size for pagination query

    +
    orderBy
    string
    Enum: "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" "ACCOUNT_NUMBER_ASC" "ACCOUNT_NUMBER_DESC" "TENANT_ORG_NAME_ASC" "TENANT_ORG_NAME_DESC" "TENANT_ORG_DISPLAY_NAME_ASC" "TENANT_ORG_DISPLAY_NAME_DESC" "TENANT_CONTACT_EMAIL_ASC" "TENANT_CONTACT_EMAIL_DESC" "TENANT_CONTACT_FULL_NAME_ASC" "TENANT_CONTACT_FULL_NAME_DESC"

    Ordering for pagination query

    +

    Responses

    Response Headers
    X-Pagination
    string
    Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}"

    Pagination result in JSON format

    +
    Response Schema: application/json
    Array
    id
    string <uuid>
    infrastructureProviderId
    string <uuid>
    infrastructureProviderOrg
    string
    tenantId
    string or null <uuid>
    tenantOrg
    string or null
    object (User)

    Details of the user collected from authentication tokens

    +
    id
    string <uuid>

    Unique identifier for the given user.

    +
    email
    string or null <email>
    firstName
    string or null
    lastName
    string or null
    created
    string <date-time>

    The date that the user was created.

    +
    updated
    string <date-time>
    allocationCount
    integer
    status
    string (TenantAccountStatus)
    Enum: "Pending" "Invited" "Ready" "Error"

    Status values for Tenant Account objects

    +
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Create Tenant Account

    Create a Tenant Account.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Create a Tenant Account.

    Org must have an Infrastructure Provider entity and its ID must match the Infrastructure Provider ID in request data. User must have authorization role with PROVIDER_ADMIN suffix

    Infrastructure Provider can create a Tenant Account by specifying the Tenant's UUID or Tenant's org name. This will set the status of the Tenant Account to "Invited". Then the Tenant can view this account information and are able to confirm/accept the account by updating the Tenant Account.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    Request Body schema: application/json
    infrastructureProviderId
    required
    string <uuid>
    tenantOrg
    required
    string non-empty ^[A-Za-z0-9-_]+$

    Must be a valid Org name

    -

    Responses

    Response Schema: application/json
    id
    string <uuid>
    infrastructureProviderId
    string <uuid>
    infrastructureProviderOrg
    string
    tenantId
    string or null <uuid>
    tenantOrg
    string or null
    object (User)

    Details of the user collected from authentication tokens

    -
    id
    string <uuid>

    Unique identifier for the given user.

    -
    email
    string or null <email>
    firstName
    string or null
    lastName
    string or null
    created
    string <date-time>

    The date that the user was created.

    -
    updated
    string <date-time>
    allocationCount
    integer
    status
    string (TenantAccountStatus)
    Enum: "Pending" "Invited" "Ready" "Error"

    Status values for Tenant Account objects

    -
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>

    Request samples

    Content type
    application/json
    {
    • "infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
    • "tenantOrg": "rf43bbtnb9c5"
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
    • "infrastructureProviderOrg": "xskkpgqpeakn",
    • "tenantId": null,
    • "tenantOrg": "rf43bbtnb9c5",
    • "tenantContact": {
      },
    • "allocationCount": 0,
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Retrieve Tenant Account

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    Request Body schema: application/json
    infrastructureProviderId
    required
    string <uuid>
    tenantOrg
    required
    string non-empty ^[A-Za-z0-9-_]+$

    Must be a valid Org name

    +

    Responses

    Response Schema: application/json
    id
    string <uuid>
    infrastructureProviderId
    string <uuid>
    infrastructureProviderOrg
    string
    tenantId
    string or null <uuid>
    tenantOrg
    string or null
    object (User)

    Details of the user collected from authentication tokens

    +
    id
    string <uuid>

    Unique identifier for the given user.

    +
    email
    string or null <email>
    firstName
    string or null
    lastName
    string or null
    created
    string <date-time>

    The date that the user was created.

    +
    updated
    string <date-time>
    allocationCount
    integer
    status
    string (TenantAccountStatus)
    Enum: "Pending" "Invited" "Ready" "Error"

    Status values for Tenant Account objects

    +
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>

    Request samples

    Content type
    application/json
    {
    • "infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
    • "tenantOrg": "rf43bbtnb9c5"
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
    • "infrastructureProviderOrg": "xskkpgqpeakn",
    • "tenantId": null,
    • "tenantOrg": "rf43bbtnb9c5",
    • "tenantContact": {
      },
    • "allocationCount": 0,
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Retrieve Tenant Account

    Retrieve a Tenant Account by ID

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve a Tenant Account by ID

    Either infrastructureProviderId or tenantId query param must be specified.

    If infrastructureProviderId query param is provided, then org must have an Infrastructure Provider entity and its ID should match the query param value. User must have authorization role with PROVIDER_ADMIN suffix.

    If tenantId query param is provided, then org must have a Tenant entity and its ID should match the query param value. User must have authorization role with TENANT_ADMIN suffix.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    accountId
    required
    string <uuid>

    ID of the Tenant Account

    -
    query Parameters
    infrastructureProviderId
    string <uuid>

    Filter Tenant Accounts by Infrastructure Provider ID

    -
    tenantId
    string <uuid>

    Filter Tenant Accounts by Tenant ID

    -
    includeRelation
    string
    Enum: "InfrastructureProvider" "Tenant"

    Related entity to expand

    -

    Responses

    Response Schema: application/json
    id
    string <uuid>
    infrastructureProviderId
    string <uuid>
    infrastructureProviderOrg
    string
    tenantId
    string or null <uuid>
    tenantOrg
    string or null
    object (User)

    Details of the user collected from authentication tokens

    -
    id
    string <uuid>

    Unique identifier for the given user.

    -
    email
    string or null <email>
    firstName
    string or null
    lastName
    string or null
    created
    string <date-time>

    The date that the user was created.

    -
    updated
    string <date-time>
    allocationCount
    integer
    status
    string (TenantAccountStatus)
    Enum: "Pending" "Invited" "Ready" "Error"

    Status values for Tenant Account objects

    -
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
    • "infrastructureProviderOrg": "xskkpgqpeakn",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "tenantOrg": "rf43bbtnb9c5",
    • "tenantContact": {
      },
    • "allocationCount": 2,
    • "status": "Ready",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Update Tenant Account

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    accountId
    required
    string <uuid>

    ID of the Tenant Account

    +
    query Parameters
    infrastructureProviderId
    string <uuid>

    Filter Tenant Accounts by Infrastructure Provider ID

    +
    tenantId
    string <uuid>

    Filter Tenant Accounts by Tenant ID

    +
    includeRelation
    string
    Enum: "InfrastructureProvider" "Tenant"

    Related entity to expand

    +

    Responses

    Response Schema: application/json
    id
    string <uuid>
    infrastructureProviderId
    string <uuid>
    infrastructureProviderOrg
    string
    tenantId
    string or null <uuid>
    tenantOrg
    string or null
    object (User)

    Details of the user collected from authentication tokens

    +
    id
    string <uuid>

    Unique identifier for the given user.

    +
    email
    string or null <email>
    firstName
    string or null
    lastName
    string or null
    created
    string <date-time>

    The date that the user was created.

    +
    updated
    string <date-time>
    allocationCount
    integer
    status
    string (TenantAccountStatus)
    Enum: "Pending" "Invited" "Ready" "Error"

    Status values for Tenant Account objects

    +
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
    • "infrastructureProviderOrg": "xskkpgqpeakn",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "tenantOrg": "rf43bbtnb9c5",
    • "tenantContact": {
      },
    • "allocationCount": 2,
    • "status": "Ready",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Update Tenant Account

    Update a Tenant Account.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Update a Tenant Account.

    Can be used to accept an invitation sent by Infrastructure Provider.

    Org must have a tenant entity whose ID matches the tenantId of the Tenant Account object. User must have authorization role with TENANT_ADMIN suffix. Can only update a TenantAccount that has Invited status.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    accountId
    required
    string <uuid>

    ID of the Tenant Account

    -
    Request Body schema: application/json

    No params needed, an empty request body will suffice.

    -
    object (TenantAccountUpdateRequest)
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    accountId
    required
    string <uuid>

    ID of the Tenant Account

    +
    Request Body schema: application/json

    No params needed, an empty request body will suffice.

    +
    object (TenantAccountUpdateRequest)

    Request data to update a TenantAccount.

    +" class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

    Request data to update a TenantAccount.

    No params needed, an empty request will suffice.

    -

    Responses

    Response Schema: application/json
    id
    string <uuid>
    infrastructureProviderId
    string <uuid>
    infrastructureProviderOrg
    string
    tenantId
    string or null <uuid>
    tenantOrg
    string or null
    object (User)

    Details of the user collected from authentication tokens

    -
    id
    string <uuid>

    Unique identifier for the given user.

    -
    email
    string or null <email>
    firstName
    string or null
    lastName
    string or null
    created
    string <date-time>

    The date that the user was created.

    -
    updated
    string <date-time>
    allocationCount
    integer
    status
    string (TenantAccountStatus)
    Enum: "Pending" "Invited" "Ready" "Error"

    Status values for Tenant Account objects

    -
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>

    Request samples

    Content type
    application/json
    { }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
    • "infrastructureProviderOrg": "xskkpgqpeakn",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "tenantOrg": "rf43bbtnb9c5",
    • "tenantContact": {
      },
    • "allocationCount": 0,
    • "status": "Ready",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Delete Tenant Account

    Responses
    Response Schema: application/json
    id
    string <uuid>
    infrastructureProviderId
    string <uuid>
    infrastructureProviderOrg
    string
    tenantId
    string or null <uuid>
    tenantOrg
    string or null
    object (User)

    Details of the user collected from authentication tokens

    +
    id
    string <uuid>

    Unique identifier for the given user.

    +
    email
    string or null <email>
    firstName
    string or null
    lastName
    string or null
    created
    string <date-time>

    The date that the user was created.

    +
    updated
    string <date-time>
    allocationCount
    integer
    status
    string (TenantAccountStatus)
    Enum: "Pending" "Invited" "Ready" "Error"

    Status values for Tenant Account objects

    +
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>

    Request samples

    Content type
    application/json
    { }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
    • "infrastructureProviderOrg": "xskkpgqpeakn",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "tenantOrg": "rf43bbtnb9c5",
    • "tenantContact": {
      },
    • "allocationCount": 0,
    • "status": "Ready",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Delete Tenant Account

    Delete a Tenant Account by ID.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Delete a Tenant Account by ID.

    Org must have an Infrastructure Provider entity, specified Tenant Account must be created by said Provider. Requesting user must have PROVIDER_ADMIN role.

    Tenant cannot delete a Tenant Account.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    accountId
    required
    string <uuid>

    ID of the Tenant Account

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "source": "nico",
    • "message": "User is not allowed to perform this action",
    • "data": null
    }

    Site

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    accountId
    required
    string <uuid>

    ID of the Tenant Account

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "source": "nico",
    • "message": "User is not allowed to perform this action",
    • "data": null
    }

    Site

    Typical API Call Flow for Tenant
  • rackLevelAdministration capability attribute was deprecated in favor of flow and was removed on May 13th, 2026 0:00 UTC. Please use flow instead.
  • isRackLevelAdministrationEnabled query parameter was deprecated in favor of isFlowEnabled and was removed on May 13th, 2026 0:00 UTC. Please use isFlowEnabled instead.
    • -

    Retrieve all Sites

    Retrieve all Sites

    Retrieve all Sites for org.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve all Sites for org.

    User must have authorization role with PROVIDER_ADMIN or TENANT_ADMIN suffix. infrastructureProviderId or tenantId query param may be required for older API versions.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    query Parameters
    infrastructureProviderId
    string <uuid>

    Filter Sites by Infrastructure Provider ID

    -
    tenantId
    string <uuid>

    Filter Sites by Tenant ID

    -
    status
    string

    Filter Sites by Status. Can be specified multiple times to filter on more than one status

    -
    isNativeNetworkingEnabled
    boolean

    Filter Sites by native networking enabled flag. Requires Provider Admin role.

    -
    isNetworkSecurityGroupEnabled
    boolean

    Filter Sites by network security group enabled flag. Requires Provider Admin role.

    -
    isNVLinkPartitionEnabled
    boolean

    Filter Sites by NVLink partitioning enabled flag. Requires Provider Admin role.

    -
    isFlowEnabled
    boolean

    Filter Sites by NICo Flow enabled flag. Requires Provider Admin role.

    -
    includeMachineStats
    boolean

    Include a breakdown of Machine counts by life-cycle status and health. Requires Provider Admin role.

    -
    query
    string

    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

    Page number for pagination query

    -
    pageSize
    integer [ 1 .. 100 ]
    Example: pageSize=20

    Page size for pagination query

    -
    orderBy
    string
    Enum: "NAME_ASC" "NAME_DESC" "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" "DESCRIPTION_ASC" "DESCRIPTION_DESC" "LOCATION_ASC" "LOCATION_DESC" "CONTACT_ASC" "CONTACT_DESC"

    Ordering for pagination query

    -

    Responses

    Response Headers
    X-Pagination
    string
    Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}"

    Pagination result in JSON format

    -
    Response Schema: application/json
    Array
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters

    Name of the Site

    -
    description
    string or null

    Optional description for the Site

    -
    org
    string
    infrastructureProviderId
    string <uuid>
    siteControllerVersion
    string or null

    Version of the Site Controller software

    -
    siteAgentVersion
    string or null

    Version of the Site Agent software

    -
    registrationToken
    string or null

    Token that can be used to register a Site. Value only exposed to Provider

    -
    registrationTokenExpiration
    string or null <date-time>

    Date/time when registration token expires. Value only exposed to Provider

    -
    serialConsoleHostname
    string or null <hostname>
    isSerialConsoleEnabled
    boolean

    Indicates if Serial Console is enabled for the Site by the Provider

    -
    serialConsoleIdleTimeout
    integer or null

    Maximum idle time in seconds before Serial Console is disconnected

    -
    serialConsoleMaxSessionLength
    integer or null

    Maximum length of Serial Console session in seconds

    -
    isSerialConsoleSSHKeysEnabled
    boolean

    Only visible to Tenant retrieving the Site. Indicates if Serial Console access using SSH Keys is enabled by Tenant

    -
    isOnline
    boolean

    Indicates if the Site is currently reachable from Cloud

    -
    status
    string (SiteStatus)
    Enum: "Pending" "Registered" "Error"

    Status values for Site objects

    -
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>
    object (SiteLocation)

    Location of the Site

    -
    city
    string

    City where the site is located

    -
    state
    string

    State where the site is located

    -
    country
    string

    Country where the site is located

    -
    object (SiteContact)

    Contact for the Site

    -
    email
    string

    Email address of the Site contact

    -
    object (SiteCapabilities)

    Boolean flags to indicate features supported by a Site

    -
    nativeNetworking
    boolean
    networkSecurityGroup
    boolean
    nvLinkPartition
    boolean
    flow
    boolean
    imageBasedOperatingSystem
    boolean
    object (SiteMachineStats)

    Machine stats for a Site

    -
    total
    integer
    object (SiteMachineStatsByStatus)

    Machine stats for a Site by status

    -
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    -
    object (SiteMachineStatsByStatusAndHealth)

    Machine stats for a Site by status and health

    -
    object (SiteMachineStatsByAllocation)

    Machine stats for a Site by allocation

    -

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Create Site

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    query Parameters
    infrastructureProviderId
    string <uuid>

    Filter Sites by Infrastructure Provider ID

    +
    tenantId
    string <uuid>

    Filter Sites by Tenant ID

    +
    status
    string

    Filter Sites by Status. Can be specified multiple times to filter on more than one status

    +
    isNativeNetworkingEnabled
    boolean

    Filter Sites by native networking enabled flag. Requires Provider Admin role.

    +
    isNetworkSecurityGroupEnabled
    boolean

    Filter Sites by network security group enabled flag. Requires Provider Admin role.

    +
    isNVLinkPartitionEnabled
    boolean

    Filter Sites by NVLink partitioning enabled flag. Requires Provider Admin role.

    +
    isFlowEnabled
    boolean

    Filter Sites by NICo Flow enabled flag. Requires Provider Admin role.

    +
    includeMachineStats
    boolean

    Include a breakdown of Machine counts by life-cycle status and health. Requires Provider Admin role.

    +
    query
    string

    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

    Page number for pagination query

    +
    pageSize
    integer [ 1 .. 100 ]
    Example: pageSize=20

    Page size for pagination query

    +
    orderBy
    string
    Enum: "NAME_ASC" "NAME_DESC" "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" "DESCRIPTION_ASC" "DESCRIPTION_DESC" "LOCATION_ASC" "LOCATION_DESC" "CONTACT_ASC" "CONTACT_DESC"

    Ordering for pagination query

    +

    Responses

    Response Headers
    X-Pagination
    string
    Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}"

    Pagination result in JSON format

    +
    Response Schema: application/json
    Array
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters

    Name of the Site

    +
    description
    string or null

    Optional description for the Site

    +
    org
    string
    infrastructureProviderId
    string <uuid>
    siteControllerVersion
    string or null

    Version of the Site Controller software

    +
    siteAgentVersion
    string or null

    Version of the Site Agent software

    +
    registrationToken
    string or null

    Token that can be used to register a Site. Value only exposed to Provider

    +
    registrationTokenExpiration
    string or null <date-time>

    Date/time when registration token expires. Value only exposed to Provider

    +
    serialConsoleHostname
    string or null <hostname>
    isSerialConsoleEnabled
    boolean

    Indicates if Serial Console is enabled for the Site by the Provider

    +
    serialConsoleIdleTimeout
    integer or null

    Maximum idle time in seconds before Serial Console is disconnected

    +
    serialConsoleMaxSessionLength
    integer or null

    Maximum length of Serial Console session in seconds

    +
    isSerialConsoleSSHKeysEnabled
    boolean

    Only visible to Tenant retrieving the Site. Indicates if Serial Console access using SSH Keys is enabled by Tenant

    +
    isOnline
    boolean

    Indicates if the Site is currently reachable from Cloud

    +
    status
    string (SiteStatus)
    Enum: "Pending" "Registered" "Error"

    Status values for Site objects

    +
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>
    object (SiteLocation)

    Location of the Site

    +
    city
    string

    City where the site is located

    +
    state
    string

    State where the site is located

    +
    country
    string

    Country where the site is located

    +
    object (SiteContact)

    Contact for the Site

    +
    email
    string

    Email address of the Site contact

    +
    object (SiteCapabilities)

    Boolean flags to indicate features supported by a Site

    +
    nativeNetworking
    boolean
    networkSecurityGroup
    boolean
    nvLinkPartition
    boolean
    flow
    boolean
    imageBasedOperatingSystem
    boolean
    object (SiteMachineStats)

    Machine stats for a Site

    +
    total
    integer
    object (SiteMachineStatsByStatus)

    Machine stats for a Site by status

    +
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    +
    object (SiteMachineStatsByStatusAndHealth)

    Machine stats for a Site by status and health

    +
    object (SiteMachineStatsByAllocation)

    Machine stats for a Site by allocation

    +

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Create Site

    Create a Site for the org.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Create a Site for the org.

    Org must have an Infrastructure Provider entity. User must have authorization role with PROVIDER_ADMIN suffix.

    Tenants cannot create Sites.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    Request Body schema: application/json
    name
    required
    string [ 2 .. 256 ] characters

    Name for the Site

    -
    description
    string or null

    Description for the Site

    -
    serialConsoleHostname
    string or null <hostname>

    Hostname to reach Serial Console for the Site

    -
    object (SiteLocation)

    Location of the Site

    -
    city
    string

    City where the site is located

    -
    state
    string

    State where the site is located

    -
    country
    string

    Country where the site is located

    -
    object (SiteContact)

    Contact for the Site

    -
    email
    string

    Email address of the Site contact

    -

    Responses

    Response Schema: application/json
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters

    Name of the Site

    -
    description
    string or null

    Optional description for the Site

    -
    org
    string
    infrastructureProviderId
    string <uuid>
    siteControllerVersion
    string or null

    Version of the Site Controller software

    -
    siteAgentVersion
    string or null

    Version of the Site Agent software

    -
    registrationToken
    string or null

    Token that can be used to register a Site. Value only exposed to Provider

    -
    registrationTokenExpiration
    string or null <date-time>

    Date/time when registration token expires. Value only exposed to Provider

    -
    serialConsoleHostname
    string or null <hostname>
    isSerialConsoleEnabled
    boolean

    Indicates if Serial Console is enabled for the Site by the Provider

    -
    serialConsoleIdleTimeout
    integer or null

    Maximum idle time in seconds before Serial Console is disconnected

    -
    serialConsoleMaxSessionLength
    integer or null

    Maximum length of Serial Console session in seconds

    -
    isSerialConsoleSSHKeysEnabled
    boolean

    Only visible to Tenant retrieving the Site. Indicates if Serial Console access using SSH Keys is enabled by Tenant

    -
    isOnline
    boolean

    Indicates if the Site is currently reachable from Cloud

    -
    status
    string (SiteStatus)
    Enum: "Pending" "Registered" "Error"

    Status values for Site objects

    -
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>
    object (SiteLocation)

    Location of the Site

    -
    city
    string

    City where the site is located

    -
    state
    string

    State where the site is located

    -
    country
    string

    Country where the site is located

    -
    object (SiteContact)

    Contact for the Site

    -
    email
    string

    Email address of the Site contact

    -
    object (SiteCapabilities)

    Boolean flags to indicate features supported by a Site

    -
    nativeNetworking
    boolean
    networkSecurityGroup
    boolean
    nvLinkPartition
    boolean
    flow
    boolean
    imageBasedOperatingSystem
    boolean
    object (SiteMachineStats)

    Machine stats for a Site

    -
    total
    integer
    object (SiteMachineStatsByStatus)

    Machine stats for a Site by status

    -
    Decommissioned
    integer
    Error
    integer
    Initializing
    integer
    InUse
    integer
    Maintenance
    integer
    Ready
    integer
    Reset
    integer
    Unknown
    integer
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    -
    healthy
    integer
    unhealthy
    integer
    object (SiteMachineStatsByStatusAndHealth)

    Machine stats for a Site by status and health

    -
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    -
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    -
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    -
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    -
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    -
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    -
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    -
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    -
    object (SiteMachineStatsByAllocation)

    Machine stats for a Site by allocation

    -
    allocatedInUse
    integer
    allocatedNotInUse
    integer
    unallocated
    integer

    Request samples

    Content type
    application/json
    {
    • "name": "San Jose Central 4",
    • "description": "Datacenter serving San Jose central region",
    • "location": {
      },
    • "contact": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "San Jose Central 4",
    • "description": "Datacenter serving the San Jose central region",
    • "org": "qygdmg8oqik8",
    • "infrastructureProviderId": "5f2cc306-76e9-4fca-9186-950c9ef9a74e",
    • "siteControllerVersion": "0.1",
    • "siteAgentVersion": "0.1",
    • "registrationToken": "J7KO-89RR-Y7WQ-AD90",
    • "registrationTokenExpiration": "2019-08-25T12:00:00Z",
    • "serialConsoleHostname": "sjc.nico.acme.com",
    • "isSerialConsoleEnabled": true,
    • "serialConsoleIdleTimeout": 60,
    • "serialConsoleMaxSessionLength": 3600,
    • "isSerialConsoleSSHKeysEnabled": true,
    • "machineStats": {
      },
    • "capabilities": {
      },
    • "isOnline": false,
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z",
    • "location": {
      },
    • "contact": {
      }
    }

    Retrieve Site

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    Request Body schema: application/json
    name
    required
    string [ 2 .. 256 ] characters

    Name for the Site

    +
    description
    string or null

    Description for the Site

    +
    serialConsoleHostname
    string or null <hostname>

    Hostname to reach Serial Console for the Site

    +
    object (SiteLocation)

    Location of the Site

    +
    city
    string

    City where the site is located

    +
    state
    string

    State where the site is located

    +
    country
    string

    Country where the site is located

    +
    object (SiteContact)

    Contact for the Site

    +
    email
    string

    Email address of the Site contact

    +

    Responses

    Response Schema: application/json
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters

    Name of the Site

    +
    description
    string or null

    Optional description for the Site

    +
    org
    string
    infrastructureProviderId
    string <uuid>
    siteControllerVersion
    string or null

    Version of the Site Controller software

    +
    siteAgentVersion
    string or null

    Version of the Site Agent software

    +
    registrationToken
    string or null

    Token that can be used to register a Site. Value only exposed to Provider

    +
    registrationTokenExpiration
    string or null <date-time>

    Date/time when registration token expires. Value only exposed to Provider

    +
    serialConsoleHostname
    string or null <hostname>
    isSerialConsoleEnabled
    boolean

    Indicates if Serial Console is enabled for the Site by the Provider

    +
    serialConsoleIdleTimeout
    integer or null

    Maximum idle time in seconds before Serial Console is disconnected

    +
    serialConsoleMaxSessionLength
    integer or null

    Maximum length of Serial Console session in seconds

    +
    isSerialConsoleSSHKeysEnabled
    boolean

    Only visible to Tenant retrieving the Site. Indicates if Serial Console access using SSH Keys is enabled by Tenant

    +
    isOnline
    boolean

    Indicates if the Site is currently reachable from Cloud

    +
    status
    string (SiteStatus)
    Enum: "Pending" "Registered" "Error"

    Status values for Site objects

    +
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>
    object (SiteLocation)

    Location of the Site

    +
    city
    string

    City where the site is located

    +
    state
    string

    State where the site is located

    +
    country
    string

    Country where the site is located

    +
    object (SiteContact)

    Contact for the Site

    +
    email
    string

    Email address of the Site contact

    +
    object (SiteCapabilities)

    Boolean flags to indicate features supported by a Site

    +
    nativeNetworking
    boolean
    networkSecurityGroup
    boolean
    nvLinkPartition
    boolean
    flow
    boolean
    imageBasedOperatingSystem
    boolean
    object (SiteMachineStats)

    Machine stats for a Site

    +
    total
    integer
    object (SiteMachineStatsByStatus)

    Machine stats for a Site by status

    +
    Decommissioned
    integer
    Error
    integer
    Initializing
    integer
    InUse
    integer
    Maintenance
    integer
    Ready
    integer
    Reset
    integer
    Unknown
    integer
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    +
    healthy
    integer
    unhealthy
    integer
    object (SiteMachineStatsByStatusAndHealth)

    Machine stats for a Site by status and health

    +
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    +
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    +
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    +
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    +
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    +
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    +
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    +
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    +
    object (SiteMachineStatsByAllocation)

    Machine stats for a Site by allocation

    +
    allocatedInUse
    integer
    allocatedNotInUse
    integer
    unallocated
    integer

    Request samples

    Content type
    application/json
    {
    • "name": "San Jose Central 4",
    • "description": "Datacenter serving San Jose central region",
    • "location": {
      },
    • "contact": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "San Jose Central 4",
    • "description": "Datacenter serving the San Jose central region",
    • "org": "qygdmg8oqik8",
    • "infrastructureProviderId": "5f2cc306-76e9-4fca-9186-950c9ef9a74e",
    • "siteControllerVersion": "0.1",
    • "siteAgentVersion": "0.1",
    • "registrationToken": "J7KO-89RR-Y7WQ-AD90",
    • "registrationTokenExpiration": "2019-08-25T12:00:00Z",
    • "serialConsoleHostname": "sjc.nico.acme.com",
    • "isSerialConsoleEnabled": true,
    • "serialConsoleIdleTimeout": 60,
    • "serialConsoleMaxSessionLength": 3600,
    • "isSerialConsoleSSHKeysEnabled": true,
    • "machineStats": {
      },
    • "capabilities": {
      },
    • "isOnline": false,
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z",
    • "location": {
      },
    • "contact": {
      }
    }

    Retrieve Site

    Typical API Call Flow for Tenant <li>The org&#39;s Tenant has an Allocation for Site</li> <li>The org&#39;s Tenant is privileged and has Account with Site&#39;s Provider</li> </ul> -" class="sc-iJuXkV sc-cBNeAB iNuSsz jtfGmi">

    Retrieve a specific Site by ID.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve a specific Site by ID.

    User must have authorization role with PROVIDER_ADMIN or TENANT_ADMIN suffix.

    Access is granted if:

      @@ -1150,215 +1150,215 @@

      Typical API Call Flow for Tenant

    • The org's Tenant has an Allocation for Site
    • The org's Tenant is privileged and has Account with Site's Provider
    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    siteId
    required
    string <uuid>

    ID of the Site

    -

    Responses

    Response Schema: application/json
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters

    Name of the Site

    -
    description
    string or null

    Optional description for the Site

    -
    org
    string
    infrastructureProviderId
    string <uuid>
    siteControllerVersion
    string or null

    Version of the Site Controller software

    -
    siteAgentVersion
    string or null

    Version of the Site Agent software

    -
    registrationToken
    string or null

    Token that can be used to register a Site. Value only exposed to Provider

    -
    registrationTokenExpiration
    string or null <date-time>

    Date/time when registration token expires. Value only exposed to Provider

    -
    serialConsoleHostname
    string or null <hostname>
    isSerialConsoleEnabled
    boolean

    Indicates if Serial Console is enabled for the Site by the Provider

    -
    serialConsoleIdleTimeout
    integer or null

    Maximum idle time in seconds before Serial Console is disconnected

    -
    serialConsoleMaxSessionLength
    integer or null

    Maximum length of Serial Console session in seconds

    -
    isSerialConsoleSSHKeysEnabled
    boolean

    Only visible to Tenant retrieving the Site. Indicates if Serial Console access using SSH Keys is enabled by Tenant

    -
    isOnline
    boolean

    Indicates if the Site is currently reachable from Cloud

    -
    status
    string (SiteStatus)
    Enum: "Pending" "Registered" "Error"

    Status values for Site objects

    -
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>
    object (SiteLocation)

    Location of the Site

    -
    city
    string

    City where the site is located

    -
    state
    string

    State where the site is located

    -
    country
    string

    Country where the site is located

    -
    object (SiteContact)

    Contact for the Site

    -
    email
    string

    Email address of the Site contact

    -
    object (SiteCapabilities)

    Boolean flags to indicate features supported by a Site

    -
    nativeNetworking
    boolean
    networkSecurityGroup
    boolean
    nvLinkPartition
    boolean
    flow
    boolean
    imageBasedOperatingSystem
    boolean
    object (SiteMachineStats)

    Machine stats for a Site

    -
    total
    integer
    object (SiteMachineStatsByStatus)

    Machine stats for a Site by status

    -
    Decommissioned
    integer
    Error
    integer
    Initializing
    integer
    InUse
    integer
    Maintenance
    integer
    Ready
    integer
    Reset
    integer
    Unknown
    integer
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    -
    healthy
    integer
    unhealthy
    integer
    object (SiteMachineStatsByStatusAndHealth)

    Machine stats for a Site by status and health

    -
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    -
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    -
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    -
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    -
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    -
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    -
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    -
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    -
    object (SiteMachineStatsByAllocation)

    Machine stats for a Site by allocation

    -
    allocatedInUse
    integer
    allocatedNotInUse
    integer
    unallocated
    integer

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "San Jose Central 4",
    • "description": "Datacenter serving the San Jose central region",
    • "org": "qygdmg8oqik8",
    • "infrastructureProviderId": "5f2cc306-76e9-4fca-9186-950c9ef9a74e",
    • "siteControllerVersion": "0.1",
    • "siteAgentVersion": "0.1",
    • "registrationToken": "J7KO-89RR-Y7WQ-AD90",
    • "registrationTokenExpiration": "2019-08-25T12:00:00Z",
    • "serialConsoleHostname": "sjc.nico.acme.com",
    • "isSerialConsoleEnabled": true,
    • "serialConsoleIdleTimeout": 60,
    • "serialConsoleMaxSessionLength": 3600,
    • "isSerialConsoleSSHKeysEnabled": true,
    • "machineStats": {
      },
    • "capabilities": {
      },
    • "isOnline": false,
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z",
    • "location": {
      },
    • "contact": {
      }
    }

    Update Site

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    siteId
    required
    string <uuid>

    ID of the Site

    +

    Responses

    Response Schema: application/json
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters

    Name of the Site

    +
    description
    string or null

    Optional description for the Site

    +
    org
    string
    infrastructureProviderId
    string <uuid>
    siteControllerVersion
    string or null

    Version of the Site Controller software

    +
    siteAgentVersion
    string or null

    Version of the Site Agent software

    +
    registrationToken
    string or null

    Token that can be used to register a Site. Value only exposed to Provider

    +
    registrationTokenExpiration
    string or null <date-time>

    Date/time when registration token expires. Value only exposed to Provider

    +
    serialConsoleHostname
    string or null <hostname>
    isSerialConsoleEnabled
    boolean

    Indicates if Serial Console is enabled for the Site by the Provider

    +
    serialConsoleIdleTimeout
    integer or null

    Maximum idle time in seconds before Serial Console is disconnected

    +
    serialConsoleMaxSessionLength
    integer or null

    Maximum length of Serial Console session in seconds

    +
    isSerialConsoleSSHKeysEnabled
    boolean

    Only visible to Tenant retrieving the Site. Indicates if Serial Console access using SSH Keys is enabled by Tenant

    +
    isOnline
    boolean

    Indicates if the Site is currently reachable from Cloud

    +
    status
    string (SiteStatus)
    Enum: "Pending" "Registered" "Error"

    Status values for Site objects

    +
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>
    object (SiteLocation)

    Location of the Site

    +
    city
    string

    City where the site is located

    +
    state
    string

    State where the site is located

    +
    country
    string

    Country where the site is located

    +
    object (SiteContact)

    Contact for the Site

    +
    email
    string

    Email address of the Site contact

    +
    object (SiteCapabilities)

    Boolean flags to indicate features supported by a Site

    +
    nativeNetworking
    boolean
    networkSecurityGroup
    boolean
    nvLinkPartition
    boolean
    flow
    boolean
    imageBasedOperatingSystem
    boolean
    object (SiteMachineStats)

    Machine stats for a Site

    +
    total
    integer
    object (SiteMachineStatsByStatus)

    Machine stats for a Site by status

    +
    Decommissioned
    integer
    Error
    integer
    Initializing
    integer
    InUse
    integer
    Maintenance
    integer
    Ready
    integer
    Reset
    integer
    Unknown
    integer
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    +
    healthy
    integer
    unhealthy
    integer
    object (SiteMachineStatsByStatusAndHealth)

    Machine stats for a Site by status and health

    +
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    +
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    +
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    +
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    +
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    +
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    +
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    +
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    +
    object (SiteMachineStatsByAllocation)

    Machine stats for a Site by allocation

    +
    allocatedInUse
    integer
    allocatedNotInUse
    integer
    unallocated
    integer

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "San Jose Central 4",
    • "description": "Datacenter serving the San Jose central region",
    • "org": "qygdmg8oqik8",
    • "infrastructureProviderId": "5f2cc306-76e9-4fca-9186-950c9ef9a74e",
    • "siteControllerVersion": "0.1",
    • "siteAgentVersion": "0.1",
    • "registrationToken": "J7KO-89RR-Y7WQ-AD90",
    • "registrationTokenExpiration": "2019-08-25T12:00:00Z",
    • "serialConsoleHostname": "sjc.nico.acme.com",
    • "isSerialConsoleEnabled": true,
    • "serialConsoleIdleTimeout": 60,
    • "serialConsoleMaxSessionLength": 3600,
    • "isSerialConsoleSSHKeysEnabled": true,
    • "machineStats": {
      },
    • "capabilities": {
      },
    • "isOnline": false,
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z",
    • "location": {
      },
    • "contact": {
      }
    }

    Update Site

    Update a specific Site

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Update a specific Site

    User must have authorization role with PROVIDER_ADMIN suffix.

    Infrastructure Provider updating the Site must be the owner of the Site. At present, there are no other Site specific configurations modifiable by Tenant.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    siteId
    required
    string <uuid>

    ID of the Site

    -
    Request Body schema: application/json
    name
    string or null

    Update name of the Site. Can only be updated by Provider

    -
    description
    string or null

    Update description for the Site. Can only be updated by Provider

    -
    renewRegistrationToken
    boolean

    Set to true to issue a new registration token. Can only be updated by Provider

    -
    serialConsoleHostname
    string or null <hostname>

    Hostname to reach Serial Console for the Site. Can only be updated by Provider

    -
    isSerialConsoleEnabled
    boolean
    Deprecated

    Enable/disable Serial Console. Can only be updated by Provider. Modifying this attribute has no actual effect on SOL. It will be removed in a future API version.

    -
    serialConsoleIdleTimeout
    integer
    Deprecated

    Maximum idle time in seconds before Serial Console is disconnected. Can only be updated by Provider. Modifying this attribute has no actual effect on SOL. It will be removed in a future API version.

    -
    serialConsoleMaxSessionLength
    integer
    Deprecated

    Maximum length of Serial Console session in seconds. Can only be updated by Provider. Modifying this attribute has no actual effect on SOL. It will be removed in a future API version.

    -
    isSerialConsoleSSHKeysEnabled
    boolean
    Deprecated

    Enable/disable Serial Console access using SSH Keys. Previously updateable only by Tenants, modifying this value is no longer supported, update SSH Key Groups to remove Site instead.

    -
    object (SiteLocation)

    Location of the Site

    -
    city
    string

    City where the site is located

    -
    state
    string

    State where the site is located

    -
    country
    string

    Country where the site is located

    -
    object (SiteContact)

    Contact for the Site

    -
    email
    string

    Email address of the Site contact

    -
    object (SiteCapabilitiesUpdateRequest)

    Modify Site capabilities. Can only be updated by Provider. Partial update allowed, only specify capabilities that should be updated.

    -
    nativeNetworking
    boolean or null

    Enable or disable native networking for the Site

    -
    networkSecurityGroup
    boolean or null

    Enable or disable network security groups for the Site

    -
    nvLinkPartition
    boolean or null

    Enable or disable NVLink partition support for the Site

    -
    flow
    boolean or null

    Enable or disable NICo Flow for the Site

    -
    imageBasedOperatingSystem
    boolean or null

    Enable or disable image-based operating system support for the Site

    -

    Responses

    Response Schema: application/json
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters

    Name of the Site

    -
    description
    string or null

    Optional description for the Site

    -
    org
    string
    infrastructureProviderId
    string <uuid>
    siteControllerVersion
    string or null

    Version of the Site Controller software

    -
    siteAgentVersion
    string or null

    Version of the Site Agent software

    -
    registrationToken
    string or null

    Token that can be used to register a Site. Value only exposed to Provider

    -
    registrationTokenExpiration
    string or null <date-time>

    Date/time when registration token expires. Value only exposed to Provider

    -
    serialConsoleHostname
    string or null <hostname>
    isSerialConsoleEnabled
    boolean

    Indicates if Serial Console is enabled for the Site by the Provider

    -
    serialConsoleIdleTimeout
    integer or null

    Maximum idle time in seconds before Serial Console is disconnected

    -
    serialConsoleMaxSessionLength
    integer or null

    Maximum length of Serial Console session in seconds

    -
    isSerialConsoleSSHKeysEnabled
    boolean

    Only visible to Tenant retrieving the Site. Indicates if Serial Console access using SSH Keys is enabled by Tenant

    -
    isOnline
    boolean

    Indicates if the Site is currently reachable from Cloud

    -
    status
    string (SiteStatus)
    Enum: "Pending" "Registered" "Error"

    Status values for Site objects

    -
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>
    object (SiteLocation)

    Location of the Site

    -
    city
    string

    City where the site is located

    -
    state
    string

    State where the site is located

    -
    country
    string

    Country where the site is located

    -
    object (SiteContact)

    Contact for the Site

    -
    email
    string

    Email address of the Site contact

    -
    object (SiteCapabilities)

    Boolean flags to indicate features supported by a Site

    -
    nativeNetworking
    boolean
    networkSecurityGroup
    boolean
    nvLinkPartition
    boolean
    flow
    boolean
    imageBasedOperatingSystem
    boolean
    object (SiteMachineStats)

    Machine stats for a Site

    -
    total
    integer
    object (SiteMachineStatsByStatus)

    Machine stats for a Site by status

    -
    Decommissioned
    integer
    Error
    integer
    Initializing
    integer
    InUse
    integer
    Maintenance
    integer
    Ready
    integer
    Reset
    integer
    Unknown
    integer
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    -
    healthy
    integer
    unhealthy
    integer
    object (SiteMachineStatsByStatusAndHealth)

    Machine stats for a Site by status and health

    -
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    -
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    -
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    -
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    -
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    -
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    -
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    -
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    -
    object (SiteMachineStatsByAllocation)

    Machine stats for a Site by allocation

    -
    allocatedInUse
    integer
    allocatedNotInUse
    integer
    unallocated
    integer

    Request samples

    Content type
    application/json
    Example
    {
    • "name": "San Jose Central No.4",
    • "description": "Datacenter 4 serving central San Jose",
    • "renewRegistrationToken": true,
    • "serialConsoleHostname": "sol.nico.acme.com",
    • "location": {
      },
    • "contact": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "San Jose Central 4",
    • "description": "Datacenter serving the San Jose central region",
    • "org": "qygdmg8oqik8",
    • "infrastructureProviderId": "5f2cc306-76e9-4fca-9186-950c9ef9a74e",
    • "siteControllerVersion": "0.1",
    • "siteAgentVersion": "0.1",
    • "registrationToken": "J7KO-89RR-Y7WQ-AD90",
    • "registrationTokenExpiration": "2019-08-25T12:00:00Z",
    • "serialConsoleHostname": "sjc.nico.acme.com",
    • "isSerialConsoleEnabled": true,
    • "serialConsoleIdleTimeout": 60,
    • "serialConsoleMaxSessionLength": 3600,
    • "isSerialConsoleSSHKeysEnabled": true,
    • "machineStats": {
      },
    • "capabilities": {
      },
    • "isOnline": false,
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z",
    • "location": {
      },
    • "contact": {
      }
    }

    Delete Site

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    siteId
    required
    string <uuid>

    ID of the Site

    +
    Request Body schema: application/json
    name
    string or null

    Update name of the Site. Can only be updated by Provider

    +
    description
    string or null

    Update description for the Site. Can only be updated by Provider

    +
    renewRegistrationToken
    boolean

    Set to true to issue a new registration token. Can only be updated by Provider

    +
    serialConsoleHostname
    string or null <hostname>

    Hostname to reach Serial Console for the Site. Can only be updated by Provider

    +
    isSerialConsoleEnabled
    boolean
    Deprecated

    Enable/disable Serial Console. Can only be updated by Provider. Modifying this attribute has no actual effect on SOL. It will be removed in a future API version.

    +
    serialConsoleIdleTimeout
    integer
    Deprecated

    Maximum idle time in seconds before Serial Console is disconnected. Can only be updated by Provider. Modifying this attribute has no actual effect on SOL. It will be removed in a future API version.

    +
    serialConsoleMaxSessionLength
    integer
    Deprecated

    Maximum length of Serial Console session in seconds. Can only be updated by Provider. Modifying this attribute has no actual effect on SOL. It will be removed in a future API version.

    +
    isSerialConsoleSSHKeysEnabled
    boolean
    Deprecated

    Enable/disable Serial Console access using SSH Keys. Previously updateable only by Tenants, modifying this value is no longer supported, update SSH Key Groups to remove Site instead.

    +
    object (SiteLocation)

    Location of the Site

    +
    city
    string

    City where the site is located

    +
    state
    string

    State where the site is located

    +
    country
    string

    Country where the site is located

    +
    object (SiteContact)

    Contact for the Site

    +
    email
    string

    Email address of the Site contact

    +
    object (SiteCapabilitiesUpdateRequest)

    Modify Site capabilities. Can only be updated by Provider. Partial update allowed, only specify capabilities that should be updated.

    +
    nativeNetworking
    boolean or null

    Enable or disable native networking for the Site

    +
    networkSecurityGroup
    boolean or null

    Enable or disable network security groups for the Site

    +
    nvLinkPartition
    boolean or null

    Enable or disable NVLink partition support for the Site

    +
    flow
    boolean or null

    Enable or disable NICo Flow for the Site

    +
    imageBasedOperatingSystem
    boolean or null

    Enable or disable image-based operating system support for the Site

    +

    Responses

    Response Schema: application/json
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters

    Name of the Site

    +
    description
    string or null

    Optional description for the Site

    +
    org
    string
    infrastructureProviderId
    string <uuid>
    siteControllerVersion
    string or null

    Version of the Site Controller software

    +
    siteAgentVersion
    string or null

    Version of the Site Agent software

    +
    registrationToken
    string or null

    Token that can be used to register a Site. Value only exposed to Provider

    +
    registrationTokenExpiration
    string or null <date-time>

    Date/time when registration token expires. Value only exposed to Provider

    +
    serialConsoleHostname
    string or null <hostname>
    isSerialConsoleEnabled
    boolean

    Indicates if Serial Console is enabled for the Site by the Provider

    +
    serialConsoleIdleTimeout
    integer or null

    Maximum idle time in seconds before Serial Console is disconnected

    +
    serialConsoleMaxSessionLength
    integer or null

    Maximum length of Serial Console session in seconds

    +
    isSerialConsoleSSHKeysEnabled
    boolean

    Only visible to Tenant retrieving the Site. Indicates if Serial Console access using SSH Keys is enabled by Tenant

    +
    isOnline
    boolean

    Indicates if the Site is currently reachable from Cloud

    +
    status
    string (SiteStatus)
    Enum: "Pending" "Registered" "Error"

    Status values for Site objects

    +
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>
    object (SiteLocation)

    Location of the Site

    +
    city
    string

    City where the site is located

    +
    state
    string

    State where the site is located

    +
    country
    string

    Country where the site is located

    +
    object (SiteContact)

    Contact for the Site

    +
    email
    string

    Email address of the Site contact

    +
    object (SiteCapabilities)

    Boolean flags to indicate features supported by a Site

    +
    nativeNetworking
    boolean
    networkSecurityGroup
    boolean
    nvLinkPartition
    boolean
    flow
    boolean
    imageBasedOperatingSystem
    boolean
    object (SiteMachineStats)

    Machine stats for a Site

    +
    total
    integer
    object (SiteMachineStatsByStatus)

    Machine stats for a Site by status

    +
    Decommissioned
    integer
    Error
    integer
    Initializing
    integer
    InUse
    integer
    Maintenance
    integer
    Ready
    integer
    Reset
    integer
    Unknown
    integer
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    +
    healthy
    integer
    unhealthy
    integer
    object (SiteMachineStatsByStatusAndHealth)

    Machine stats for a Site by status and health

    +
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    +
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    +
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    +
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    +
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    +
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    +
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    +
    object (SiteMachineStatsByHealth)

    Machine stats for a Site by health

    +
    object (SiteMachineStatsByAllocation)

    Machine stats for a Site by allocation

    +
    allocatedInUse
    integer
    allocatedNotInUse
    integer
    unallocated
    integer

    Request samples

    Content type
    application/json
    Example
    {
    • "name": "San Jose Central No.4",
    • "description": "Datacenter 4 serving central San Jose",
    • "renewRegistrationToken": true,
    • "serialConsoleHostname": "sol.nico.acme.com",
    • "location": {
      },
    • "contact": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "San Jose Central 4",
    • "description": "Datacenter serving the San Jose central region",
    • "org": "qygdmg8oqik8",
    • "infrastructureProviderId": "5f2cc306-76e9-4fca-9186-950c9ef9a74e",
    • "siteControllerVersion": "0.1",
    • "siteAgentVersion": "0.1",
    • "registrationToken": "J7KO-89RR-Y7WQ-AD90",
    • "registrationTokenExpiration": "2019-08-25T12:00:00Z",
    • "serialConsoleHostname": "sjc.nico.acme.com",
    • "isSerialConsoleEnabled": true,
    • "serialConsoleIdleTimeout": 60,
    • "serialConsoleMaxSessionLength": 3600,
    • "isSerialConsoleSSHKeysEnabled": true,
    • "machineStats": {
      },
    • "capabilities": {
      },
    • "isOnline": false,
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z",
    • "location": {
      },
    • "contact": {
      }
    }

    Delete Site

    Delete a specific Site

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Delete a specific Site

    Org must have an Infrastructure Provider entity. User must have authorization role with PROVIDER_ADMIN suffix.

    Site can only be deleted if all Allocations have been deleted.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    siteId
    required
    string <uuid>

    ID of the Site

    -
    query Parameters
    purgeMachines
    boolean

    Scrub all Machine data associated with this Site to re-pair

    -

    Responses

    Retrieve Site status history

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    siteId
    required
    string <uuid>

    ID of the Site

    +
    query Parameters
    purgeMachines
    boolean

    Scrub all Machine data associated with this Site to re-pair

    +

    Responses

    Retrieve Site status history

    Typical API Call Flow for Tenant <li>The org&#39;s Tenant has an Allocation for Site</li> <li>The org&#39;s Tenant is privileged and has Account with Site&#39;s Provider</li> </ul> -" class="sc-iJuXkV sc-cBNeAB iNuSsz jtfGmi">

    Retrieve a specific Site status history

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve a specific Site status history

    User must have authorization role with PROVIDER_ADMIN or TENANT_ADMIN suffix.

    Access is granted if:

      @@ -1374,1325 +1374,1295 @@

      Typical API Call Flow for Tenant

    • The org's Tenant has an Allocation for Site
    • The org's Tenant is privileged and has Account with Site's Provider
    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    siteId
    required
    string <uuid>

    ID of the Site

    -
    query Parameters
    pageNumber
    integer

    Page number for pagination query

    -
    pageSize
    integer

    Page size for pagination query

    -
    orderBy
    string

    Ordering for pagination query

    -

    Responses

    Response Headers
    X-Pagination
    string

    Pagination result in JSON format

    -
    Response Schema: application/json
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Allocation

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    siteId
    required
    string <uuid>

    ID of the Site

    +
    query Parameters
    pageNumber
    integer

    Page number for pagination query

    +
    pageSize
    integer

    Page size for pagination query

    +
    orderBy
    string

    Ordering for pagination query

    +

    Responses

    Response Headers
    X-Pagination
    string

    Pagination result in JSON format

    +
    Response Schema: application/json
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Allocation

    Allocations are the mechanism by which Provider can delegate Network and Compute resources to Tenant.

    -

    Retrieve all Allocations

    Retrieve all Allocations

    Retrieve all Allocations for the org.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve all Allocations for the org.

    Provider and Tenant roles are inferred from the org's membership. User must have authorization role with PROVIDER_ADMIN or TENANT_ADMIN suffix.

    Results are returned from both Provider and Tenant perspectives when the org has both roles.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    query Parameters
    infrastructureProviderId
    string <uuid>
    Deprecated

    Filter Allocations by Infrastructure Provider ID.

    -
    tenantId
    string <uuid>

    Filter Allocations by Tenant ID.

    -
    siteId
    string <uuid>

    Filter Allocations by Site ID. Can be specified multiple times to filter on more than one Site ID.

    -
    id
    string

    Filter Allocations by ID. Can be specified multiple times to filter on more than one ID.

    -
    resourceType
    string
    Enum: "InstanceType" "IPBlock"

    Filter Allocations by Constraint Resource Type. Can be specified multiple times to filter on more than one Constraint Resource Type.

    -
    status
    string

    Filter Allocations by Status. Can be specified multiple times to filter on more than one Status.

    -
    resourceTypeId
    string

    Filter Allocations by Constraint Resource Type ID. Can be specified multiple times to filter on more than one Constraint Resource Type ID.

    -
    constraintType
    string
    Enum: "Reserved" "OnDemand" "Preemptible"

    Filter Allocations by Constraint Type. Can be specified multiple times to filter on more than one Constraint Type.

    -
    constraintValue
    integer

    Filter Allocations by Constraint Value. Can be specified multiple times to filter on more than one Constraint Value.

    -
    query
    string

    Search for matches across all Sites. 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

    Page number for pagination query

    -
    pageSize
    integer [ 1 .. 100 ]
    Example: pageSize=20

    Page size for pagination query

    -
    orderBy
    string
    Enum: "NAME_ASC" "NAME_DESC" "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" "SITE_NAME_ASC" "SITE_NAME_DESC" "TENANT_ORG_DISPLAY_NAME_ASC" "TENANT_ORG_DISPLAY_NAME_DESC" "INSTANCE_TYPE_NAME_ASC" "INSTANCE_TYPE_NAME_DESC" "IP_BLOCK_NAME_ASC" "IP_BLOCK_NAME_DESC" "CONSTRAINT_VALUE_ASC" "CONSTRAINT_VALUE_DESC"

    Ordering for pagination query

    -

    Responses

    Response Headers
    X-Pagination
    string
    Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}"

    Pagination result in JSON format

    -
    Response Schema: application/json
    Array
    id
    string <uuid>

    ID of the Allocation

    -
    name
    string [ 2 .. 256 ] characters

    Concise and descriptive name of the Allocation

    -
    description
    string or null

    Detailed description of the Allocation

    -
    infrastructureProviderId
    string <uuid>

    ID of the Infrastructure Provider that created the Allocation

    -
    tenantId
    string <uuid>

    ID of the Tenant that received the Allocation

    -
    siteId
    string <uuid>

    ID of the Site where resources are allocated

    -
    status
    string (AllocationStatus)
    Enum: "Pending" "Registered" "Deleting" "Error"

    Status values for Allocation objects

    -
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    Array of objects (AllocationConstraint)
    Array
    id
    string <uuid>

    ID of the Allocation Constraint

    -
    allocationId
    string <uuid>

    ID of the Allocation that contains the Allocation Constraint

    -
    resourceType
    string
    Enum: "InstanceType" "IPBlock"

    Type of the Resource that the Allocation Constraint applies to

    -
    resourceTypeId
    string <uuid>

    ID of the Resource Type that acts as the source of the Allocation. For resource type: InstanceType, this is the ID of the Instance Type whose associated Machines are allocated to the Tenant. For resource type IPBlock, this is the ID of the Site level IP Block from where a prefix is allocated to the Tenant.

    -
    constraintType
    string
    Enum: "Reserved" "OnDemand" "Preemptible"

    Type of the Allocation Constraint. Reserved is the only constraint type supported by current implementation.

    -
    constraintValue
    integer

    Value of the Allocation Constraint. For resource type: InstanceType, this value represents number of Machines associated with the Instance Type that is allocated to the Tenant. For resource type IPBlock, this value represents the prefix length of the IP Block allocated to the Tenant.

    -
    derivedResourceId
    string or null

    ID of the allocated Tenant IP Block when resource type is IPBlock

    -
    object (InstanceTypeSummary)

    Describes a subset of core attributes of an Instance Type

    -
    object (IpBlockSummary)

    Describes a subset of core attributes of an IP block

    -
    created
    string <date-time>

    Date/time when the Allocation Constraint was created

    -
    updated
    string <date-time>

    Date/time when the Allocation Constraint was last updated

    -
    created
    string <date-time>

    Date/time when the Allocation was created

    -
    updated
    string <date-time>

    Date/time when the Allocation was last updated

    -

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Create Allocation

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    query Parameters
    infrastructureProviderId
    string <uuid>
    Deprecated

    Filter Allocations by Infrastructure Provider ID.

    +
    tenantId
    string <uuid>

    Filter Allocations by Tenant ID.

    +
    siteId
    string <uuid>

    Filter Allocations by Site ID. Can be specified multiple times to filter on more than one Site ID.

    +
    id
    string

    Filter Allocations by ID. Can be specified multiple times to filter on more than one ID.

    +
    resourceType
    string
    Enum: "InstanceType" "IPBlock"

    Filter Allocations by Constraint Resource Type. Can be specified multiple times to filter on more than one Constraint Resource Type.

    +
    status
    string

    Filter Allocations by Status. Can be specified multiple times to filter on more than one Status.

    +
    resourceTypeId
    string

    Filter Allocations by Constraint Resource Type ID. Can be specified multiple times to filter on more than one Constraint Resource Type ID.

    +
    constraintType
    string
    Enum: "Reserved" "OnDemand" "Preemptible"

    Filter Allocations by Constraint Type. Can be specified multiple times to filter on more than one Constraint Type.

    +
    constraintValue
    integer

    Filter Allocations by Constraint Value. Can be specified multiple times to filter on more than one Constraint Value.

    +
    query
    string

    Search for matches across all Sites. 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

    Page number for pagination query

    +
    pageSize
    integer [ 1 .. 100 ]
    Example: pageSize=20

    Page size for pagination query

    +
    orderBy
    string
    Enum: "NAME_ASC" "NAME_DESC" "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" "SITE_NAME_ASC" "SITE_NAME_DESC" "TENANT_ORG_DISPLAY_NAME_ASC" "TENANT_ORG_DISPLAY_NAME_DESC" "INSTANCE_TYPE_NAME_ASC" "INSTANCE_TYPE_NAME_DESC" "IP_BLOCK_NAME_ASC" "IP_BLOCK_NAME_DESC" "CONSTRAINT_VALUE_ASC" "CONSTRAINT_VALUE_DESC"

    Ordering for pagination query

    +

    Responses

    Response Headers
    X-Pagination
    string
    Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}"

    Pagination result in JSON format

    +
    Response Schema: application/json
    Array
    id
    string <uuid>

    ID of the Allocation

    +
    name
    string [ 2 .. 256 ] characters

    Concise and descriptive name of the Allocation

    +
    description
    string or null

    Detailed description of the Allocation

    +
    infrastructureProviderId
    string <uuid>

    ID of the Infrastructure Provider that created the Allocation

    +
    tenantId
    string <uuid>

    ID of the Tenant that received the Allocation

    +
    siteId
    string <uuid>

    ID of the Site where resources are allocated

    +
    status
    string (AllocationStatus)
    Enum: "Pending" "Registered" "Deleting" "Error"

    Status values for Allocation objects

    +
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    Array of objects (AllocationConstraint)
    Array
    id
    string <uuid>

    ID of the Allocation Constraint

    +
    allocationId
    string <uuid>

    ID of the Allocation that contains the Allocation Constraint

    +
    resourceType
    string
    Enum: "InstanceType" "IPBlock"

    Type of the Resource that the Allocation Constraint applies to

    +
    resourceTypeId
    string <uuid>

    ID of the Resource Type that acts as the source of the Allocation. For resource type: InstanceType, this is the ID of the Instance Type whose associated Machines are allocated to the Tenant. For resource type IPBlock, this is the ID of the Site level IP Block from where a prefix is allocated to the Tenant.

    +
    constraintType
    string
    Enum: "Reserved" "OnDemand" "Preemptible"

    Type of the Allocation Constraint. Reserved is the only constraint type supported by current implementation.

    +
    constraintValue
    integer

    Value of the Allocation Constraint. For resource type: InstanceType, this value represents number of Machines associated with the Instance Type that is allocated to the Tenant. For resource type IPBlock, this value represents the prefix length of the IP Block allocated to the Tenant.

    +
    derivedResourceId
    string or null

    ID of the allocated Tenant IP Block when resource type is IPBlock

    +
    object (InstanceTypeSummary)

    Describes a subset of core attributes of an Instance Type

    +
    object (IpBlockSummary)

    Describes a subset of core attributes of an IP block

    +
    created
    string <date-time>

    Date/time when the Allocation Constraint was created

    +
    updated
    string <date-time>

    Date/time when the Allocation Constraint was last updated

    +
    created
    string <date-time>

    Date/time when the Allocation was created

    +
    updated
    string <date-time>

    Date/time when the Allocation was last updated

    +

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Create Allocation

    Create an Allocation for the org.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Create an Allocation for the org.

    Org must have an Infrastructure Provider entity. User must have authorization role with PROVIDER_ADMIN suffix.

    To successfully create a compute Allocation, there must be enough unallocated Machines associated with the Instance Type to satisfy the constraint value. For network Allocation, the source site-level IP Block must have an available prefix with length equal to constraint value.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    Request Body schema: application/json
    name
    required
    string [ 2 .. 256 ] characters

    Concise and descriptive name for the Allocation

    -
    description
    string or null

    Detailed description for the Allocation

    -
    tenantId
    required
    string <uuid>

    ID of the Tenant that should receive the Allocation

    -
    siteId
    required
    string <uuid>

    ID of the Site where resources should be allocated

    -
    Array of objects (AllocationConstraintCreateRequest)
    Array
    resourceType
    required
    string
    Enum: "InstanceType" "IPBlock"

    Type of the Resource that the Allocation Constraint applies to

    -
    resourceTypeId
    required
    string <uuid>

    ID of the Resource Type that the Allocation Constraint applies to. For InstanceType, this is the ID of the Instance Type. For IPBlock, this is the ID of the IP Block.

    -
    constraintType
    required
    string
    Enum: "Reserved" "OnDemand" "Preemptible"

    Type of the Allocation Constraint. Please note that OnDemand and Preemptible are not supported by current implementation.

    -
    constraintValue
    required
    integer

    Value of the Allocation Constraint. For InstanceType, this value represents number of Machines allocated for Tenant. For IPBlock, this value represents the prefix Length of the IP Block.

    -

    Responses

    Response Schema: application/json
    id
    string <uuid>

    ID of the Allocation

    -
    name
    string [ 2 .. 256 ] characters

    Concise and descriptive name of the Allocation

    -
    description
    string or null

    Detailed description of the Allocation

    -
    infrastructureProviderId
    string <uuid>

    ID of the Infrastructure Provider that created the Allocation

    -
    tenantId
    string <uuid>

    ID of the Tenant that received the Allocation

    -
    siteId
    string <uuid>

    ID of the Site where resources are allocated

    -
    status
    string (AllocationStatus)
    Enum: "Pending" "Registered" "Deleting" "Error"

    Status values for Allocation objects

    -
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    Array of objects (AllocationConstraint)
    Array
    id
    string <uuid>

    ID of the Allocation Constraint

    -
    allocationId
    string <uuid>

    ID of the Allocation that contains the Allocation Constraint

    -
    resourceType
    string
    Enum: "InstanceType" "IPBlock"

    Type of the Resource that the Allocation Constraint applies to

    -
    resourceTypeId
    string <uuid>

    ID of the Resource Type that acts as the source of the Allocation. For resource type: InstanceType, this is the ID of the Instance Type whose associated Machines are allocated to the Tenant. For resource type IPBlock, this is the ID of the Site level IP Block from where a prefix is allocated to the Tenant.

    -
    constraintType
    string
    Enum: "Reserved" "OnDemand" "Preemptible"

    Type of the Allocation Constraint. Reserved is the only constraint type supported by current implementation.

    -
    constraintValue
    integer

    Value of the Allocation Constraint. For resource type: InstanceType, this value represents number of Machines associated with the Instance Type that is allocated to the Tenant. For resource type IPBlock, this value represents the prefix length of the IP Block allocated to the Tenant.

    -
    derivedResourceId
    string or null

    ID of the allocated Tenant IP Block when resource type is IPBlock

    -
    object (InstanceTypeSummary)

    Describes a subset of core attributes of an Instance Type

    -
    object (IpBlockSummary)

    Describes a subset of core attributes of an IP block

    -
    created
    string <date-time>

    Date/time when the Allocation Constraint was created

    -
    updated
    string <date-time>

    Date/time when the Allocation Constraint was last updated

    -
    created
    string <date-time>

    Date/time when the Allocation was created

    -
    updated
    string <date-time>

    Date/time when the Allocation was last updated

    -

    Request samples

    Content type
    application/json
    {
    • "name": "Echo Studios",
    • "description": "Echo Studios resource allocation in SJC4",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
    • "allocationConstraints": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "Echo Studios",
    • "description": "Echo Studios resource allocation in SJC4",
    • "infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
    • "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z",
    • "allocationConstraints": [
      ]
    }

    Retrieve Allocation

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    Request Body schema: application/json
    name
    required
    string [ 2 .. 256 ] characters

    Concise and descriptive name for the Allocation

    +
    description
    string or null

    Detailed description for the Allocation

    +
    tenantId
    required
    string <uuid>

    ID of the Tenant that should receive the Allocation

    +
    siteId
    required
    string <uuid>

    ID of the Site where resources should be allocated

    +
    Array of objects (AllocationConstraintCreateRequest)
    Array
    resourceType
    required
    string
    Enum: "InstanceType" "IPBlock"

    Type of the Resource that the Allocation Constraint applies to

    +
    resourceTypeId
    required
    string <uuid>

    ID of the Resource Type that the Allocation Constraint applies to. For InstanceType, this is the ID of the Instance Type. For IPBlock, this is the ID of the IP Block.

    +
    constraintType
    required
    string
    Enum: "Reserved" "OnDemand" "Preemptible"

    Type of the Allocation Constraint. Please note that OnDemand and Preemptible are not supported by current implementation.

    +
    constraintValue
    required
    integer

    Value of the Allocation Constraint. For InstanceType, this value represents number of Machines allocated for Tenant. For IPBlock, this value represents the prefix Length of the IP Block.

    +

    Responses

    Response Schema: application/json
    id
    string <uuid>

    ID of the Allocation

    +
    name
    string [ 2 .. 256 ] characters

    Concise and descriptive name of the Allocation

    +
    description
    string or null

    Detailed description of the Allocation

    +
    infrastructureProviderId
    string <uuid>

    ID of the Infrastructure Provider that created the Allocation

    +
    tenantId
    string <uuid>

    ID of the Tenant that received the Allocation

    +
    siteId
    string <uuid>

    ID of the Site where resources are allocated

    +
    status
    string (AllocationStatus)
    Enum: "Pending" "Registered" "Deleting" "Error"

    Status values for Allocation objects

    +
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    Array of objects (AllocationConstraint)
    Array
    id
    string <uuid>

    ID of the Allocation Constraint

    +
    allocationId
    string <uuid>

    ID of the Allocation that contains the Allocation Constraint

    +
    resourceType
    string
    Enum: "InstanceType" "IPBlock"

    Type of the Resource that the Allocation Constraint applies to

    +
    resourceTypeId
    string <uuid>

    ID of the Resource Type that acts as the source of the Allocation. For resource type: InstanceType, this is the ID of the Instance Type whose associated Machines are allocated to the Tenant. For resource type IPBlock, this is the ID of the Site level IP Block from where a prefix is allocated to the Tenant.

    +
    constraintType
    string
    Enum: "Reserved" "OnDemand" "Preemptible"

    Type of the Allocation Constraint. Reserved is the only constraint type supported by current implementation.

    +
    constraintValue
    integer

    Value of the Allocation Constraint. For resource type: InstanceType, this value represents number of Machines associated with the Instance Type that is allocated to the Tenant. For resource type IPBlock, this value represents the prefix length of the IP Block allocated to the Tenant.

    +
    derivedResourceId
    string or null

    ID of the allocated Tenant IP Block when resource type is IPBlock

    +
    object (InstanceTypeSummary)

    Describes a subset of core attributes of an Instance Type

    +
    object (IpBlockSummary)

    Describes a subset of core attributes of an IP block

    +
    created
    string <date-time>

    Date/time when the Allocation Constraint was created

    +
    updated
    string <date-time>

    Date/time when the Allocation Constraint was last updated

    +
    created
    string <date-time>

    Date/time when the Allocation was created

    +
    updated
    string <date-time>

    Date/time when the Allocation was last updated

    +

    Request samples

    Content type
    application/json
    {
    • "name": "Echo Studios",
    • "description": "Echo Studios resource allocation in SJC4",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
    • "allocationConstraints": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "Echo Studios",
    • "description": "Echo Studios resource allocation in SJC4",
    • "infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
    • "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z",
    • "allocationConstraints": [
      ]
    }

    Retrieve Allocation

    Retrieve Allocation by ID

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve Allocation by ID

    Provider and Tenant roles are inferred from the org's membership. Allocation must belong to the Provider or Tenant associated with the org.

    User must have authorization role with PROVIDER_ADMIN or TENANT_ADMIN suffix.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    allocationId
    required
    string <uuid>

    ID of the Allocation

    -
    query Parameters
    infrastructureProviderId
    string <uuid>
    Deprecated

    Filter Allocations by Infrastructure Provider ID.

    -
    tenantId
    string <uuid>
    Deprecated

    Filter Allocations by Tenant ID.

    -
    includeRelation
    string
    Enum: "InfrastructureProvider" "Tenant" "Site"

    Related entity to expand

    -

    Responses

    Response Schema: application/json
    id
    string <uuid>

    ID of the Allocation

    -
    name
    string [ 2 .. 256 ] characters

    Concise and descriptive name of the Allocation

    -
    description
    string or null

    Detailed description of the Allocation

    -
    infrastructureProviderId
    string <uuid>

    ID of the Infrastructure Provider that created the Allocation

    -
    tenantId
    string <uuid>

    ID of the Tenant that received the Allocation

    -
    siteId
    string <uuid>

    ID of the Site where resources are allocated

    -
    status
    string (AllocationStatus)
    Enum: "Pending" "Registered" "Deleting" "Error"

    Status values for Allocation objects

    -
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    Array of objects (AllocationConstraint)
    Array
    id
    string <uuid>

    ID of the Allocation Constraint

    -
    allocationId
    string <uuid>

    ID of the Allocation that contains the Allocation Constraint

    -
    resourceType
    string
    Enum: "InstanceType" "IPBlock"

    Type of the Resource that the Allocation Constraint applies to

    -
    resourceTypeId
    string <uuid>

    ID of the Resource Type that acts as the source of the Allocation. For resource type: InstanceType, this is the ID of the Instance Type whose associated Machines are allocated to the Tenant. For resource type IPBlock, this is the ID of the Site level IP Block from where a prefix is allocated to the Tenant.

    -
    constraintType
    string
    Enum: "Reserved" "OnDemand" "Preemptible"

    Type of the Allocation Constraint. Reserved is the only constraint type supported by current implementation.

    -
    constraintValue
    integer

    Value of the Allocation Constraint. For resource type: InstanceType, this value represents number of Machines associated with the Instance Type that is allocated to the Tenant. For resource type IPBlock, this value represents the prefix length of the IP Block allocated to the Tenant.

    -
    derivedResourceId
    string or null

    ID of the allocated Tenant IP Block when resource type is IPBlock

    -
    object (InstanceTypeSummary)

    Describes a subset of core attributes of an Instance Type

    -
    object (IpBlockSummary)

    Describes a subset of core attributes of an IP block

    -
    created
    string <date-time>

    Date/time when the Allocation Constraint was created

    -
    updated
    string <date-time>

    Date/time when the Allocation Constraint was last updated

    -
    created
    string <date-time>

    Date/time when the Allocation was created

    -
    updated
    string <date-time>

    Date/time when the Allocation was last updated

    -

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "Echo Studios",
    • "description": "Echo Studios resource allocation in SJC4",
    • "infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
    • "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z",
    • "allocationConstraints": [
      ]
    }

    Delete Allocation

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    allocationId
    required
    string <uuid>

    ID of the Allocation

    +
    query Parameters
    infrastructureProviderId
    string <uuid>
    Deprecated

    Filter Allocations by Infrastructure Provider ID.

    +
    tenantId
    string <uuid>
    Deprecated

    Filter Allocations by Tenant ID.

    +
    includeRelation
    string
    Enum: "InfrastructureProvider" "Tenant" "Site"

    Related entity to expand

    +

    Responses

    Response Schema: application/json
    id
    string <uuid>

    ID of the Allocation

    +
    name
    string [ 2 .. 256 ] characters

    Concise and descriptive name of the Allocation

    +
    description
    string or null

    Detailed description of the Allocation

    +
    infrastructureProviderId
    string <uuid>

    ID of the Infrastructure Provider that created the Allocation

    +
    tenantId
    string <uuid>

    ID of the Tenant that received the Allocation

    +
    siteId
    string <uuid>

    ID of the Site where resources are allocated

    +
    status
    string (AllocationStatus)
    Enum: "Pending" "Registered" "Deleting" "Error"

    Status values for Allocation objects

    +
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    Array of objects (AllocationConstraint)
    Array
    id
    string <uuid>

    ID of the Allocation Constraint

    +
    allocationId
    string <uuid>

    ID of the Allocation that contains the Allocation Constraint

    +
    resourceType
    string
    Enum: "InstanceType" "IPBlock"

    Type of the Resource that the Allocation Constraint applies to

    +
    resourceTypeId
    string <uuid>

    ID of the Resource Type that acts as the source of the Allocation. For resource type: InstanceType, this is the ID of the Instance Type whose associated Machines are allocated to the Tenant. For resource type IPBlock, this is the ID of the Site level IP Block from where a prefix is allocated to the Tenant.

    +
    constraintType
    string
    Enum: "Reserved" "OnDemand" "Preemptible"

    Type of the Allocation Constraint. Reserved is the only constraint type supported by current implementation.

    +
    constraintValue
    integer

    Value of the Allocation Constraint. For resource type: InstanceType, this value represents number of Machines associated with the Instance Type that is allocated to the Tenant. For resource type IPBlock, this value represents the prefix length of the IP Block allocated to the Tenant.

    +
    derivedResourceId
    string or null

    ID of the allocated Tenant IP Block when resource type is IPBlock

    +
    object (InstanceTypeSummary)

    Describes a subset of core attributes of an Instance Type

    +
    object (IpBlockSummary)

    Describes a subset of core attributes of an IP block

    +
    created
    string <date-time>

    Date/time when the Allocation Constraint was created

    +
    updated
    string <date-time>

    Date/time when the Allocation Constraint was last updated

    +
    created
    string <date-time>

    Date/time when the Allocation was created

    +
    updated
    string <date-time>

    Date/time when the Allocation was last updated

    +

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "Echo Studios",
    • "description": "Echo Studios resource allocation in SJC4",
    • "infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
    • "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z",
    • "allocationConstraints": [
      ]
    }

    Delete Allocation

    Delete an Allocation by ID.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Delete an Allocation by ID.

    Org must have an Infrastructure Provider entity, specified Allocation must be created by said Provider. Requesting user must have PROVIDER_ADMIN role.

    Tenant management of Allocation is not supported in MVP.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    allocationId
    required
    string <uuid>

    ID of the Allocation

    -

    Responses

    Update Allocation

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    allocationId
    required
    string <uuid>

    ID of the Allocation

    +

    Responses

    Update Allocation

    Update an existing Allocation

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Update an existing Allocation

    Org must have an Infrastructure Provider entity. User must have authorization role with PROVIDER_ADMIN suffix. Provider must own the Allocation.

    Tenant management of Allocation is not supported in MVP.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    allocationId
    required
    string <uuid>

    ID of the Allocation

    -
    Request Body schema: application/json
    name
    string or null [ 2 .. 256 ] characters

    Update name of the Allocation

    -
    description
    string or null

    Update description of the Allocation

    -

    Responses

    Response Schema: application/json
    id
    string <uuid>

    ID of the Allocation

    -
    name
    string [ 2 .. 256 ] characters

    Concise and descriptive name of the Allocation

    -
    description
    string or null

    Detailed description of the Allocation

    -
    infrastructureProviderId
    string <uuid>

    ID of the Infrastructure Provider that created the Allocation

    -
    tenantId
    string <uuid>

    ID of the Tenant that received the Allocation

    -
    siteId
    string <uuid>

    ID of the Site where resources are allocated

    -
    status
    string (AllocationStatus)
    Enum: "Pending" "Registered" "Deleting" "Error"

    Status values for Allocation objects

    -
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    Array of objects (AllocationConstraint)
    Array
    id
    string <uuid>

    ID of the Allocation Constraint

    -
    allocationId
    string <uuid>

    ID of the Allocation that contains the Allocation Constraint

    -
    resourceType
    string
    Enum: "InstanceType" "IPBlock"

    Type of the Resource that the Allocation Constraint applies to

    -
    resourceTypeId
    string <uuid>

    ID of the Resource Type that acts as the source of the Allocation. For resource type: InstanceType, this is the ID of the Instance Type whose associated Machines are allocated to the Tenant. For resource type IPBlock, this is the ID of the Site level IP Block from where a prefix is allocated to the Tenant.

    -
    constraintType
    string
    Enum: "Reserved" "OnDemand" "Preemptible"

    Type of the Allocation Constraint. Reserved is the only constraint type supported by current implementation.

    -
    constraintValue
    integer

    Value of the Allocation Constraint. For resource type: InstanceType, this value represents number of Machines associated with the Instance Type that is allocated to the Tenant. For resource type IPBlock, this value represents the prefix length of the IP Block allocated to the Tenant.

    -
    derivedResourceId
    string or null

    ID of the allocated Tenant IP Block when resource type is IPBlock

    -
    object (InstanceTypeSummary)

    Describes a subset of core attributes of an Instance Type

    -
    object (IpBlockSummary)

    Describes a subset of core attributes of an IP block

    -
    created
    string <date-time>

    Date/time when the Allocation Constraint was created

    -
    updated
    string <date-time>

    Date/time when the Allocation Constraint was last updated

    -
    created
    string <date-time>

    Date/time when the Allocation was created

    -
    updated
    string <date-time>

    Date/time when the Allocation was last updated

    -

    Request samples

    Content type
    application/json
    {
    • "name": "Echo Studios Compute",
    • "description": "Echo Studios compute resource allocation in SJC4"
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "Echo Studios Compute",
    • "description": "Echo Studios compute resource allocation in SJC4",
    • "infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
    • "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z",
    • "allocationConstraints": [
      ]
    }

    Retrieve all Allocation Constraints

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    allocationId
    required
    string <uuid>

    ID of the Allocation

    +
    Request Body schema: application/json
    name
    string or null [ 2 .. 256 ] characters

    Update name of the Allocation

    +
    description
    string or null

    Update description of the Allocation

    +

    Responses

    Response Schema: application/json
    id
    string <uuid>

    ID of the Allocation

    +
    name
    string [ 2 .. 256 ] characters

    Concise and descriptive name of the Allocation

    +
    description
    string or null

    Detailed description of the Allocation

    +
    infrastructureProviderId
    string <uuid>

    ID of the Infrastructure Provider that created the Allocation

    +
    tenantId
    string <uuid>

    ID of the Tenant that received the Allocation

    +
    siteId
    string <uuid>

    ID of the Site where resources are allocated

    +
    status
    string (AllocationStatus)
    Enum: "Pending" "Registered" "Deleting" "Error"

    Status values for Allocation objects

    +
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    Array of objects (AllocationConstraint)
    Array
    id
    string <uuid>

    ID of the Allocation Constraint

    +
    allocationId
    string <uuid>

    ID of the Allocation that contains the Allocation Constraint

    +
    resourceType
    string
    Enum: "InstanceType" "IPBlock"

    Type of the Resource that the Allocation Constraint applies to

    +
    resourceTypeId
    string <uuid>

    ID of the Resource Type that acts as the source of the Allocation. For resource type: InstanceType, this is the ID of the Instance Type whose associated Machines are allocated to the Tenant. For resource type IPBlock, this is the ID of the Site level IP Block from where a prefix is allocated to the Tenant.

    +
    constraintType
    string
    Enum: "Reserved" "OnDemand" "Preemptible"

    Type of the Allocation Constraint. Reserved is the only constraint type supported by current implementation.

    +
    constraintValue
    integer

    Value of the Allocation Constraint. For resource type: InstanceType, this value represents number of Machines associated with the Instance Type that is allocated to the Tenant. For resource type IPBlock, this value represents the prefix length of the IP Block allocated to the Tenant.

    +
    derivedResourceId
    string or null

    ID of the allocated Tenant IP Block when resource type is IPBlock

    +
    object (InstanceTypeSummary)

    Describes a subset of core attributes of an Instance Type

    +
    object (IpBlockSummary)

    Describes a subset of core attributes of an IP block

    +
    created
    string <date-time>

    Date/time when the Allocation Constraint was created

    +
    updated
    string <date-time>

    Date/time when the Allocation Constraint was last updated

    +
    created
    string <date-time>

    Date/time when the Allocation was created

    +
    updated
    string <date-time>

    Date/time when the Allocation was last updated

    +

    Request samples

    Content type
    application/json
    {
    • "name": "Echo Studios Compute",
    • "description": "Echo Studios compute resource allocation in SJC4"
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "Echo Studios Compute",
    • "description": "Echo Studios compute resource allocation in SJC4",
    • "infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
    • "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z",
    • "allocationConstraints": [
      ]
    }

    Retrieve all Allocation Constraints

    Retrieve all Allocation Constraints for a given Allocation ID.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve all Allocation Constraints for a given Allocation ID.

    If org has an Infrastructure Provider entity, then specified Allocation must have been created by the Provider and requesting user must have PROVIDER_ADMIN role.

    If org does not have an Infrastructure Provider entity but has a Tenant entity, then specified Allocation must belong to the Tenant and requesting user must have TENANT_ADMIN role.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    allocationId
    required
    string <uuid>

    ID of the Allocation

    -
    query Parameters
    pageNumber
    integer >= 1
    Default: 1
    Example: pageNumber=1

    Page number for pagination query

    -
    pageSize
    integer [ 1 .. 100 ]
    Example: pageSize=20

    Page size for pagination query

    -
    orderBy
    string
    Enum: "RESOURCE_TYPE_ASC" "RESOURCE_TYPE_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC"

    Ordering for pagination query

    -

    Responses

    Response Headers
    X-Pagination
    string
    Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}"

    Pagination result in JSON format

    -
    Response Schema: application/json
    Array
    id
    string <uuid>

    ID of the Allocation Constraint

    -
    allocationId
    string <uuid>

    ID of the Allocation that contains the Allocation Constraint

    -
    resourceType
    string
    Enum: "InstanceType" "IPBlock"

    Type of the Resource that the Allocation Constraint applies to

    -
    resourceTypeId
    string <uuid>

    ID of the Resource Type that acts as the source of the Allocation. For resource type: InstanceType, this is the ID of the Instance Type whose associated Machines are allocated to the Tenant. For resource type IPBlock, this is the ID of the Site level IP Block from where a prefix is allocated to the Tenant.

    -
    constraintType
    string
    Enum: "Reserved" "OnDemand" "Preemptible"

    Type of the Allocation Constraint. Reserved is the only constraint type supported by current implementation.

    -
    constraintValue
    integer

    Value of the Allocation Constraint. For resource type: InstanceType, this value represents number of Machines associated with the Instance Type that is allocated to the Tenant. For resource type IPBlock, this value represents the prefix length of the IP Block allocated to the Tenant.

    -
    derivedResourceId
    string or null

    ID of the allocated Tenant IP Block when resource type is IPBlock

    -
    object (InstanceTypeSummary)

    Describes a subset of core attributes of an Instance Type

    -
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    infrastructureProviderId
    string <uuid>
    siteId
    string <uuid>
    status
    string (InstanceTypeStatus)
    Enum: "Pending" "Registering" "Ready" "Deleting" "Error"

    Status values for Instance Type objects

    -
    object (IpBlockSummary)

    Describes a subset of core attributes of an IP block

    -
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    routingType
    string
    Enum: "Public" "DatacenterOnly"
    prefix
    string

    Either IPv4 or IPv6 address

    -
    prefixLength
    integer

    Min: 1, Max: 32 for ipv4, 128 for ipv6

    -
    status
    string (IpBlockStatus)
    Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error"

    Status values for IP Block objects

    -
    created
    string <date-time>

    Date/time when the Allocation Constraint was created

    -
    updated
    string <date-time>

    Date/time when the Allocation Constraint was last updated

    -

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Create Allocation Constraint

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    allocationId
    required
    string <uuid>

    ID of the Allocation

    +
    query Parameters
    pageNumber
    integer >= 1
    Default: 1
    Example: pageNumber=1

    Page number for pagination query

    +
    pageSize
    integer [ 1 .. 100 ]
    Example: pageSize=20

    Page size for pagination query

    +
    orderBy
    string
    Enum: "RESOURCE_TYPE_ASC" "RESOURCE_TYPE_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC"

    Ordering for pagination query

    +

    Responses

    Response Headers
    X-Pagination
    string
    Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}"

    Pagination result in JSON format

    +
    Response Schema: application/json
    Array
    id
    string <uuid>

    ID of the Allocation Constraint

    +
    allocationId
    string <uuid>

    ID of the Allocation that contains the Allocation Constraint

    +
    resourceType
    string
    Enum: "InstanceType" "IPBlock"

    Type of the Resource that the Allocation Constraint applies to

    +
    resourceTypeId
    string <uuid>

    ID of the Resource Type that acts as the source of the Allocation. For resource type: InstanceType, this is the ID of the Instance Type whose associated Machines are allocated to the Tenant. For resource type IPBlock, this is the ID of the Site level IP Block from where a prefix is allocated to the Tenant.

    +
    constraintType
    string
    Enum: "Reserved" "OnDemand" "Preemptible"

    Type of the Allocation Constraint. Reserved is the only constraint type supported by current implementation.

    +
    constraintValue
    integer

    Value of the Allocation Constraint. For resource type: InstanceType, this value represents number of Machines associated with the Instance Type that is allocated to the Tenant. For resource type IPBlock, this value represents the prefix length of the IP Block allocated to the Tenant.

    +
    derivedResourceId
    string or null

    ID of the allocated Tenant IP Block when resource type is IPBlock

    +
    object (InstanceTypeSummary)

    Describes a subset of core attributes of an Instance Type

    +
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    infrastructureProviderId
    string <uuid>
    siteId
    string <uuid>
    status
    string (InstanceTypeStatus)
    Enum: "Pending" "Registering" "Ready" "Deleting" "Error"

    Status values for Instance Type objects

    +
    object (IpBlockSummary)

    Describes a subset of core attributes of an IP block

    +
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    routingType
    string
    Enum: "Public" "DatacenterOnly"
    prefix
    string

    Either IPv4 or IPv6 address

    +
    prefixLength
    integer

    Min: 1, Max: 32 for ipv4, 128 for ipv6

    +
    status
    string (IpBlockStatus)
    Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error"

    Status values for IP Block objects

    +
    created
    string <date-time>

    Date/time when the Allocation Constraint was created

    +
    updated
    string <date-time>

    Date/time when the Allocation Constraint was last updated

    +

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Create Allocation Constraint

    Create an Allocation Constraint for a given Allocation ID.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Create an Allocation Constraint for a given Allocation ID.

    Org must have an Infrastructure Provider entity and specified Allocation must have been created by the Provider. User must have authorization role with PROVIDER_ADMIN suffix.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    allocationId
    required
    string <uuid>

    ID of the Allocation

    -
    Request Body schema: application/json
    resourceType
    required
    string
    Enum: "InstanceType" "IPBlock"

    Type of the Resource that the Allocation Constraint applies to

    -
    resourceTypeId
    required
    string <uuid>

    ID of the Resource Type that the Allocation Constraint applies to. For InstanceType, this is the ID of the Instance Type. For IPBlock, this is the ID of the IP Block.

    -
    constraintType
    required
    string
    Enum: "Reserved" "OnDemand" "Preemptible"

    Type of the Allocation Constraint. Please note that OnDemand and Preemptible are not supported by current implementation.

    -
    constraintValue
    required
    integer

    Value of the Allocation Constraint. For InstanceType, this value represents number of Machines allocated for Tenant. For IPBlock, this value represents the prefix Length of the IP Block.

    -

    Responses

    Response Schema: application/json
    id
    string <uuid>

    ID of the Allocation Constraint

    -
    allocationId
    string <uuid>

    ID of the Allocation that contains the Allocation Constraint

    -
    resourceType
    string
    Enum: "InstanceType" "IPBlock"

    Type of the Resource that the Allocation Constraint applies to

    -
    resourceTypeId
    string <uuid>

    ID of the Resource Type that acts as the source of the Allocation. For resource type: InstanceType, this is the ID of the Instance Type whose associated Machines are allocated to the Tenant. For resource type IPBlock, this is the ID of the Site level IP Block from where a prefix is allocated to the Tenant.

    -
    constraintType
    string
    Enum: "Reserved" "OnDemand" "Preemptible"

    Type of the Allocation Constraint. Reserved is the only constraint type supported by current implementation.

    -
    constraintValue
    integer

    Value of the Allocation Constraint. For resource type: InstanceType, this value represents number of Machines associated with the Instance Type that is allocated to the Tenant. For resource type IPBlock, this value represents the prefix length of the IP Block allocated to the Tenant.

    -
    derivedResourceId
    string or null

    ID of the allocated Tenant IP Block when resource type is IPBlock

    -
    object (InstanceTypeSummary)

    Describes a subset of core attributes of an Instance Type

    -
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    infrastructureProviderId
    string <uuid>
    siteId
    string <uuid>
    status
    string (InstanceTypeStatus)
    Enum: "Pending" "Registering" "Ready" "Deleting" "Error"

    Status values for Instance Type objects

    -
    object (IpBlockSummary)

    Describes a subset of core attributes of an IP block

    -
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    routingType
    string
    Enum: "Public" "DatacenterOnly"
    prefix
    string

    Either IPv4 or IPv6 address

    -
    prefixLength
    integer

    Min: 1, Max: 32 for ipv4, 128 for ipv6

    -
    status
    string (IpBlockStatus)
    Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error"

    Status values for IP Block objects

    -
    created
    string <date-time>

    Date/time when the Allocation Constraint was created

    -
    updated
    string <date-time>

    Date/time when the Allocation Constraint was last updated

    -

    Request samples

    Content type
    application/json
    {
    • "resourceType": "InstanceType",
    • "resourceTypeId": "bd5a0240-eb62-4bff-91f7-335e6bb86459",
    • "constraintType": "Reserved",
    • "constraintValue": 10
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "allocationId": "9ec871ce-3363-4de2-8f79-062881067628",
    • "resourceType": "InstanceType",
    • "resourceTypeId": "a59ee688-b5e5-4606-9891-f4a605edacd3",
    • "constraintType": "Reserved",
    • "constraintValue": 10,
    • "derivedResourceId": null,
    • "instanceType": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Retrieve Allocation Constraint

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    allocationId
    required
    string <uuid>

    ID of the Allocation

    +
    Request Body schema: application/json
    resourceType
    required
    string
    Enum: "InstanceType" "IPBlock"

    Type of the Resource that the Allocation Constraint applies to

    +
    resourceTypeId
    required
    string <uuid>

    ID of the Resource Type that the Allocation Constraint applies to. For InstanceType, this is the ID of the Instance Type. For IPBlock, this is the ID of the IP Block.

    +
    constraintType
    required
    string
    Enum: "Reserved" "OnDemand" "Preemptible"

    Type of the Allocation Constraint. Please note that OnDemand and Preemptible are not supported by current implementation.

    +
    constraintValue
    required
    integer

    Value of the Allocation Constraint. For InstanceType, this value represents number of Machines allocated for Tenant. For IPBlock, this value represents the prefix Length of the IP Block.

    +

    Responses

    Response Schema: application/json
    id
    string <uuid>

    ID of the Allocation Constraint

    +
    allocationId
    string <uuid>

    ID of the Allocation that contains the Allocation Constraint

    +
    resourceType
    string
    Enum: "InstanceType" "IPBlock"

    Type of the Resource that the Allocation Constraint applies to

    +
    resourceTypeId
    string <uuid>

    ID of the Resource Type that acts as the source of the Allocation. For resource type: InstanceType, this is the ID of the Instance Type whose associated Machines are allocated to the Tenant. For resource type IPBlock, this is the ID of the Site level IP Block from where a prefix is allocated to the Tenant.

    +
    constraintType
    string
    Enum: "Reserved" "OnDemand" "Preemptible"

    Type of the Allocation Constraint. Reserved is the only constraint type supported by current implementation.

    +
    constraintValue
    integer

    Value of the Allocation Constraint. For resource type: InstanceType, this value represents number of Machines associated with the Instance Type that is allocated to the Tenant. For resource type IPBlock, this value represents the prefix length of the IP Block allocated to the Tenant.

    +
    derivedResourceId
    string or null

    ID of the allocated Tenant IP Block when resource type is IPBlock

    +
    object (InstanceTypeSummary)

    Describes a subset of core attributes of an Instance Type

    +
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    infrastructureProviderId
    string <uuid>
    siteId
    string <uuid>
    status
    string (InstanceTypeStatus)
    Enum: "Pending" "Registering" "Ready" "Deleting" "Error"

    Status values for Instance Type objects

    +
    object (IpBlockSummary)

    Describes a subset of core attributes of an IP block

    +
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    routingType
    string
    Enum: "Public" "DatacenterOnly"
    prefix
    string

    Either IPv4 or IPv6 address

    +
    prefixLength
    integer

    Min: 1, Max: 32 for ipv4, 128 for ipv6

    +
    status
    string (IpBlockStatus)
    Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error"

    Status values for IP Block objects

    +
    created
    string <date-time>

    Date/time when the Allocation Constraint was created

    +
    updated
    string <date-time>

    Date/time when the Allocation Constraint was last updated

    +

    Request samples

    Content type
    application/json
    {
    • "resourceType": "InstanceType",
    • "resourceTypeId": "bd5a0240-eb62-4bff-91f7-335e6bb86459",
    • "constraintType": "Reserved",
    • "constraintValue": 10
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "allocationId": "9ec871ce-3363-4de2-8f79-062881067628",
    • "resourceType": "InstanceType",
    • "resourceTypeId": "a59ee688-b5e5-4606-9891-f4a605edacd3",
    • "constraintType": "Reserved",
    • "constraintValue": 10,
    • "derivedResourceId": null,
    • "instanceType": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Retrieve Allocation Constraint

    Retrieve an Allocation Constraint for a given Allocation ID.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve an Allocation Constraint for a given Allocation ID.

    If org has an Infrastructure Provider entity, then specified Allocation must have been created by the Provider and requesting user must have PROVIDER_ADMIN role.

    If org does not have an Infrastructure Provider entity but has a Tenant entity, then specified Allocation must belong to the Tenant and requesting user must have TENANT_ADMIN role.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    allocationId
    required
    string

    ID of the Allocation

    -
    allocationConstraintId
    required
    string <uuid>

    ID of the Allocation Constraint

    -

    Responses

    Response Schema: application/json
    Array
    id
    string <uuid>

    ID of the Allocation Constraint

    -
    allocationId
    string <uuid>

    ID of the Allocation that contains the Allocation Constraint

    -
    resourceType
    string
    Enum: "InstanceType" "IPBlock"

    Type of the Resource that the Allocation Constraint applies to

    -
    resourceTypeId
    string <uuid>

    ID of the Resource Type that acts as the source of the Allocation. For resource type: InstanceType, this is the ID of the Instance Type whose associated Machines are allocated to the Tenant. For resource type IPBlock, this is the ID of the Site level IP Block from where a prefix is allocated to the Tenant.

    -
    constraintType
    string
    Enum: "Reserved" "OnDemand" "Preemptible"

    Type of the Allocation Constraint. Reserved is the only constraint type supported by current implementation.

    -
    constraintValue
    integer

    Value of the Allocation Constraint. For resource type: InstanceType, this value represents number of Machines associated with the Instance Type that is allocated to the Tenant. For resource type IPBlock, this value represents the prefix length of the IP Block allocated to the Tenant.

    -
    derivedResourceId
    string or null

    ID of the allocated Tenant IP Block when resource type is IPBlock

    -
    object (InstanceTypeSummary)

    Describes a subset of core attributes of an Instance Type

    -
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    infrastructureProviderId
    string <uuid>
    siteId
    string <uuid>
    status
    string (InstanceTypeStatus)
    Enum: "Pending" "Registering" "Ready" "Deleting" "Error"

    Status values for Instance Type objects

    -
    object (IpBlockSummary)

    Describes a subset of core attributes of an IP block

    -
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    routingType
    string
    Enum: "Public" "DatacenterOnly"
    prefix
    string

    Either IPv4 or IPv6 address

    -
    prefixLength
    integer

    Min: 1, Max: 32 for ipv4, 128 for ipv6

    -
    status
    string (IpBlockStatus)
    Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error"

    Status values for IP Block objects

    -
    created
    string <date-time>

    Date/time when the Allocation Constraint was created

    -
    updated
    string <date-time>

    Date/time when the Allocation Constraint was last updated

    -

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Update Allocation Constraint

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    allocationId
    required
    string

    ID of the Allocation

    +
    allocationConstraintId
    required
    string <uuid>

    ID of the Allocation Constraint

    +

    Responses

    Response Schema: application/json
    Array
    id
    string <uuid>

    ID of the Allocation Constraint

    +
    allocationId
    string <uuid>

    ID of the Allocation that contains the Allocation Constraint

    +
    resourceType
    string
    Enum: "InstanceType" "IPBlock"

    Type of the Resource that the Allocation Constraint applies to

    +
    resourceTypeId
    string <uuid>

    ID of the Resource Type that acts as the source of the Allocation. For resource type: InstanceType, this is the ID of the Instance Type whose associated Machines are allocated to the Tenant. For resource type IPBlock, this is the ID of the Site level IP Block from where a prefix is allocated to the Tenant.

    +
    constraintType
    string
    Enum: "Reserved" "OnDemand" "Preemptible"

    Type of the Allocation Constraint. Reserved is the only constraint type supported by current implementation.

    +
    constraintValue
    integer

    Value of the Allocation Constraint. For resource type: InstanceType, this value represents number of Machines associated with the Instance Type that is allocated to the Tenant. For resource type IPBlock, this value represents the prefix length of the IP Block allocated to the Tenant.

    +
    derivedResourceId
    string or null

    ID of the allocated Tenant IP Block when resource type is IPBlock

    +
    object (InstanceTypeSummary)

    Describes a subset of core attributes of an Instance Type

    +
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    infrastructureProviderId
    string <uuid>
    siteId
    string <uuid>
    status
    string (InstanceTypeStatus)
    Enum: "Pending" "Registering" "Ready" "Deleting" "Error"

    Status values for Instance Type objects

    +
    object (IpBlockSummary)

    Describes a subset of core attributes of an IP block

    +
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    routingType
    string
    Enum: "Public" "DatacenterOnly"
    prefix
    string

    Either IPv4 or IPv6 address

    +
    prefixLength
    integer

    Min: 1, Max: 32 for ipv4, 128 for ipv6

    +
    status
    string (IpBlockStatus)
    Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error"

    Status values for IP Block objects

    +
    created
    string <date-time>

    Date/time when the Allocation Constraint was created

    +
    updated
    string <date-time>

    Date/time when the Allocation Constraint was last updated

    +

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Update Allocation Constraint

    Update an existing Allocation Constraint by ID

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Update an existing Allocation Constraint by ID

    Org must have an Infrastructure Provider. Specified Allocation must have been created by the Provider and requesting user must have PROVIDER_ADMIN role.

    Modifying allocations may not be possible if Tenant has started utilizing resources from this allocation.

    In case of InstanceType resource, constraintValue can be incremented anytime, but not decremented if it requires decommissioning Tenant resources.

    In case of IPBlock resource, constraintValue can not be modified if Tenant resources are using IPs from the block.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    allocationId
    required
    string

    ID of the Allocation

    -
    allocationConstraintId
    required
    string <uuid>

    ID of the Allocation Constraint

    -
    Request Body schema: application/json
    constraintValue
    required
    integer

    Value of the Allocation Constraint. For InstanceType, this value represents number of Machines allocated for Tenant. For IPBlock, this value represents the prefix Length of the IP Block.

    -

    Responses

    Response Schema: application/json
    id
    string <uuid>

    ID of the Allocation Constraint

    -
    allocationId
    string <uuid>

    ID of the Allocation that contains the Allocation Constraint

    -
    resourceType
    string
    Enum: "InstanceType" "IPBlock"

    Type of the Resource that the Allocation Constraint applies to

    -
    resourceTypeId
    string <uuid>

    ID of the Resource Type that acts as the source of the Allocation. For resource type: InstanceType, this is the ID of the Instance Type whose associated Machines are allocated to the Tenant. For resource type IPBlock, this is the ID of the Site level IP Block from where a prefix is allocated to the Tenant.

    -
    constraintType
    string
    Enum: "Reserved" "OnDemand" "Preemptible"

    Type of the Allocation Constraint. Reserved is the only constraint type supported by current implementation.

    -
    constraintValue
    integer

    Value of the Allocation Constraint. For resource type: InstanceType, this value represents number of Machines associated with the Instance Type that is allocated to the Tenant. For resource type IPBlock, this value represents the prefix length of the IP Block allocated to the Tenant.

    -
    derivedResourceId
    string or null

    ID of the allocated Tenant IP Block when resource type is IPBlock

    -
    object (InstanceTypeSummary)

    Describes a subset of core attributes of an Instance Type

    -
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    infrastructureProviderId
    string <uuid>
    siteId
    string <uuid>
    status
    string (InstanceTypeStatus)
    Enum: "Pending" "Registering" "Ready" "Deleting" "Error"

    Status values for Instance Type objects

    -
    object (IpBlockSummary)

    Describes a subset of core attributes of an IP block

    -
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    routingType
    string
    Enum: "Public" "DatacenterOnly"
    prefix
    string

    Either IPv4 or IPv6 address

    -
    prefixLength
    integer

    Min: 1, Max: 32 for ipv4, 128 for ipv6

    -
    status
    string (IpBlockStatus)
    Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error"

    Status values for IP Block objects

    -
    created
    string <date-time>

    Date/time when the Allocation Constraint was created

    -
    updated
    string <date-time>

    Date/time when the Allocation Constraint was last updated

    -

    Request samples

    Content type
    application/json
    {
    • "constraintValue": 20
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "allocationId": "9ec871ce-3363-4de2-8f79-062881067628",
    • "resourceType": "InstanceType",
    • "resourceTypeId": "a59ee688-b5e5-4606-9891-f4a605edacd3",
    • "constraintType": "Reserved",
    • "constraintValue": 20,
    • "derivedResourceId": null,
    • "instanceType": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Delete Allocation Constraint

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    allocationId
    required
    string

    ID of the Allocation

    +
    allocationConstraintId
    required
    string <uuid>

    ID of the Allocation Constraint

    +
    Request Body schema: application/json
    constraintValue
    required
    integer

    Value of the Allocation Constraint. For InstanceType, this value represents number of Machines allocated for Tenant. For IPBlock, this value represents the prefix Length of the IP Block.

    +

    Responses

    Response Schema: application/json
    id
    string <uuid>

    ID of the Allocation Constraint

    +
    allocationId
    string <uuid>

    ID of the Allocation that contains the Allocation Constraint

    +
    resourceType
    string
    Enum: "InstanceType" "IPBlock"

    Type of the Resource that the Allocation Constraint applies to

    +
    resourceTypeId
    string <uuid>

    ID of the Resource Type that acts as the source of the Allocation. For resource type: InstanceType, this is the ID of the Instance Type whose associated Machines are allocated to the Tenant. For resource type IPBlock, this is the ID of the Site level IP Block from where a prefix is allocated to the Tenant.

    +
    constraintType
    string
    Enum: "Reserved" "OnDemand" "Preemptible"

    Type of the Allocation Constraint. Reserved is the only constraint type supported by current implementation.

    +
    constraintValue
    integer

    Value of the Allocation Constraint. For resource type: InstanceType, this value represents number of Machines associated with the Instance Type that is allocated to the Tenant. For resource type IPBlock, this value represents the prefix length of the IP Block allocated to the Tenant.

    +
    derivedResourceId
    string or null

    ID of the allocated Tenant IP Block when resource type is IPBlock

    +
    object (InstanceTypeSummary)

    Describes a subset of core attributes of an Instance Type

    +
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    infrastructureProviderId
    string <uuid>
    siteId
    string <uuid>
    status
    string (InstanceTypeStatus)
    Enum: "Pending" "Registering" "Ready" "Deleting" "Error"

    Status values for Instance Type objects

    +
    object (IpBlockSummary)

    Describes a subset of core attributes of an IP block

    +
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    routingType
    string
    Enum: "Public" "DatacenterOnly"
    prefix
    string

    Either IPv4 or IPv6 address

    +
    prefixLength
    integer

    Min: 1, Max: 32 for ipv4, 128 for ipv6

    +
    status
    string (IpBlockStatus)
    Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error"

    Status values for IP Block objects

    +
    created
    string <date-time>

    Date/time when the Allocation Constraint was created

    +
    updated
    string <date-time>

    Date/time when the Allocation Constraint was last updated

    +

    Request samples

    Content type
    application/json
    {
    • "constraintValue": 20
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "allocationId": "9ec871ce-3363-4de2-8f79-062881067628",
    • "resourceType": "InstanceType",
    • "resourceTypeId": "a59ee688-b5e5-4606-9891-f4a605edacd3",
    • "constraintType": "Reserved",
    • "constraintValue": 20,
    • "derivedResourceId": null,
    • "instanceType": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Delete Allocation Constraint

    Delete an existing Allocation Constraint by ID

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Delete an existing Allocation Constraint by ID

    Org must have an Infrastructure Provider. Specified Allocation must have been created by the Provider and requesting user must have PROVIDER_ADMIN role.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    allocationId
    required
    string

    ID of the Allocation

    -
    allocationConstraintId
    required
    string <uuid>

    ID of the Allocation Constraint

    -

    Responses

    VPC

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    allocationId
    required
    string

    ID of the Allocation

    +
    allocationConstraintId
    required
    string <uuid>

    ID of the Allocation Constraint

    +

    Responses

    VPC

    VPC defines the networking isolation boundary for Tenant's Instances.

    -

    Retrieve all VPCs

    Retrieve all VPCs

    Retrieve all VPCs for the org.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve all VPCs for the org.

    Org must have a Tenant entity. User must have authorization role with TENANT_ADMIN suffix

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    query Parameters
    siteId
    string <uuid>

    Filter VPCs by Site ID. Can be specified multiple times to filter on more than one Site.

    -
    status
    string

    Filter VPCs by Status. Can be specified multiple times to filter on more than one Status.

    -
    networkSecurityGroupId
    string

    Filter VPCs by Network Security Group ID. Can be specified multiple times to filter on more than one Network Security Group.

    -
    nvLinkLogicalPartitionId
    string <uuid>

    Filter VPCs by NVLink Logical Partition ID. Can be specified multiple times to filter on more than one NVLink Logical Partition.

    -
    query
    string

    Search for matches across all VPCs. Input will be matched against name, description, labels and status fields

    -
    includeRelation
    string
    Enum: "InfrastructureProvider" "Tenant" "Site" "NetworkSecurityGroup"

    Related entity to expand

    -
    pageNumber
    integer >= 1
    Default: 1
    Example: pageNumber=1

    Page number for pagination query

    -
    pageSize
    integer [ 1 .. 100 ]
    Example: pageSize=20

    Page size for pagination query

    -
    orderBy
    string
    Enum: "NAME_ASC" "NAME_DESC" "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC"

    Ordering for pagination query

    -

    Responses

    Response Headers
    X-Pagination
    string
    Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}"

    Pagination result in JSON format

    -
    Response Schema: application/json
    Array
    id
    string <uuid>

    ID of the VPC

    -
    name
    string [ 2 .. 256 ] characters

    Name of the VPC

    -
    description
    string or null

    Description of the VPC, can be empty

    -
    org
    string

    Organization the VPC belongs to

    -
    tenantId
    string <uuid>

    ID of the Tenant the VPC belongs to

    -
    siteId
    string <uuid>

    ID of the Site the VPC belongs to

    -
    controllerVpcId
    string or null <uuid>

    Legacy attribute, contains the same value as ID

    -
    networkVirtualizationType
    string or null
    Enum: "ETHERNET_VIRTUALIZER" "FNN"

    Network virtualization type of the VPC

    -
    routingProfile
    string or null [ 3 .. 64 ] characters

    Routing profile type for the VPC. Populated when Site has Native Networking enabled and network virtualization type is FNN.

    -
    requestedVni
    integer or null [ 1 .. 65535 ]

    Explicitly requested VNI for the VPC if one was requested at creation time

    -
    vni
    integer or null [ 1 .. 65535 ]

    Active VNI assigned to the VPC

    -
    networkSecurityGroupId
    string or null

    ID of the Network Security Group attached to the VPC

    -
    object (NetworkSecurityGroupPropagationDetails)

    Propagation details for the attached Network Security Group

    -
    id
    string <uuid>

    The VPC or Instance ID

    -
    detailedStatus
    string
    Enum: "None" "Partial" "Full" "Unknown" "Error"
    status
    string (NetworkSecurityGroupPropagationStatus)
    Enum: "Synchronizing" "Synchronized" "Error"

    Status values for Network Security Group propagation

    -
    details
    string or null
    unpropagatedInstanceIds
    Array of strings <uuid> [ items <uuid > ]
    relatedInstanceIds
    Array of strings <uuid> [ items <uuid > ]
    nvLinkLogicalPartitionId
    string or null <uuid>

    ID of the default NVLink Logical Partition that GPUs for all Instances in the VPC will attach to

    -
    object (Labels) <= 10 properties

    String key value pairs describing VPC labels

    -
    property name*
    additional property
    string
    status
    string (VpcStatus)
    Enum: "Pending" "Provisioning" "Ready" "Configuring" "Deleting" "Error"

    Status of the VPC

    -
    Array of objects (StatusDetail)

    History of status changes for the VPC

    -
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>

    Date/time when VPC was created

    -
    updated
    string <date-time>

    Date/time when VPC was last updated

    -

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Create VPC

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    query Parameters
    siteId
    string <uuid>

    Filter VPCs by Site ID. Can be specified multiple times to filter on more than one Site.

    +
    status
    string

    Filter VPCs by Status. Can be specified multiple times to filter on more than one Status.

    +
    networkSecurityGroupId
    string

    Filter VPCs by Network Security Group ID. Can be specified multiple times to filter on more than one Network Security Group.

    +
    nvLinkLogicalPartitionId
    string <uuid>

    Filter VPCs by NVLink Logical Partition ID. Can be specified multiple times to filter on more than one NVLink Logical Partition.

    +
    query
    string

    Search for matches across all VPCs. Input will be matched against name, description, labels and status fields

    +
    includeRelation
    string
    Enum: "InfrastructureProvider" "Tenant" "Site" "NetworkSecurityGroup"

    Related entity to expand

    +
    pageNumber
    integer >= 1
    Default: 1
    Example: pageNumber=1

    Page number for pagination query

    +
    pageSize
    integer [ 1 .. 100 ]
    Example: pageSize=20

    Page size for pagination query

    +
    orderBy
    string
    Enum: "NAME_ASC" "NAME_DESC" "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC"

    Ordering for pagination query

    +

    Responses

    Response Headers
    X-Pagination
    string
    Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}"

    Pagination result in JSON format

    +
    Response Schema: application/json
    Array
    id
    string <uuid>

    ID of the VPC

    +
    name
    string [ 2 .. 256 ] characters

    Name of the VPC

    +
    description
    string or null

    Description of the VPC, can be empty

    +
    org
    string

    Organization the VPC belongs to

    +
    tenantId
    string <uuid>

    ID of the Tenant the VPC belongs to

    +
    siteId
    string <uuid>

    ID of the Site the VPC belongs to

    +
    controllerVpcId
    string or null <uuid>

    Legacy attribute, contains the same value as ID

    +
    networkVirtualizationType
    string or null
    Enum: "ETHERNET_VIRTUALIZER" "FNN"

    Network virtualization type of the VPC

    +
    routingProfile
    string or null [ 3 .. 64 ] characters

    Routing profile type for the VPC. Populated when Site has Native Networking enabled and network virtualization type is FNN.

    +
    requestedVni
    integer or null [ 1 .. 65535 ]

    Explicitly requested VNI for the VPC if one was requested at creation time

    +
    vni
    integer or null [ 1 .. 65535 ]

    Active VNI assigned to the VPC

    +
    networkSecurityGroupId
    string or null

    ID of the Network Security Group attached to the VPC

    +
    object (NetworkSecurityGroupPropagationDetails)

    Propagation details for the attached Network Security Group

    +
    id
    string <uuid>

    The VPC or Instance ID

    +
    detailedStatus
    string
    Enum: "None" "Partial" "Full" "Unknown" "Error"
    status
    string (NetworkSecurityGroupPropagationStatus)
    Enum: "Synchronizing" "Synchronized" "Error"

    Status values for Network Security Group propagation

    +
    details
    string or null
    unpropagatedInstanceIds
    Array of strings <uuid> [ items <uuid > ]
    relatedInstanceIds
    Array of strings <uuid> [ items <uuid > ]
    nvLinkLogicalPartitionId
    string or null <uuid>

    ID of the default NVLink Logical Partition that GPUs for all Instances in the VPC will attach to

    +
    object (Labels) <= 10 properties

    String key value pairs describing VPC labels

    +
    property name*
    additional property
    string
    status
    string (VpcStatus)
    Enum: "Pending" "Provisioning" "Ready" "Configuring" "Deleting" "Error"

    Status of the VPC

    +
    Array of objects (StatusDetail)

    History of status changes for the VPC

    +
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>

    Date/time when VPC was created

    +
    updated
    string <date-time>

    Date/time when VPC was last updated

    +

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Create VPC

    Create a VPC for the org.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Create a VPC for the org.

    Org must have a Tenant entity. User must have authorization role with TENANT_ADMIN suffix

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    Request Body schema: application/json
    id
    string <uuid>

    Optional user-specified UUID for the VPC

    -
    name
    required
    string [ 2 .. 256 ] characters

    Name of the VPC

    -
    description
    string or null

    Optional description for the VPC

    -
    siteId
    required
    string <uuid>

    ID of the Site where the VPC should be created

    -
    networkVirtualizationType
    string or null
    Enum: "ETHERNET_VIRTUALIZER" "FNN"

    Network virtualization type of the VPC. If no value is specified, then defaults to FNN if Site has native networking enabled, or ETHERNET_VIRTUALIZER if native networking is disabled

    -
    routingProfile
    string or null [ 3 .. 64 ] characters

    Specify routing profile for the VPC. Only supported when networkVirtualizationType is set to FNN, or when networkVirtualizationType is omitted and Site has Native Networking enabled. Requires Tenant to have elevated privilege. Current accepted values are privileged-internal, internal, and external.

    -
    networkSecurityGroupId
    string or null

    ID of the Network Security Group to attach to the VPC

    -
    vni
    integer or null [ 1 .. 65535 ]

    Explicitly requested VNI for the VPC

    -
    nvLinkLogicalPartitionId
    string or null <uuid>

    ID of the default NVLink Logical Partition that GPUs for all Instances in the VPC will attach to

    -
    object (Labels) <= 10 properties

    String key value pairs describing VPC labels. Up to 10 key value pairs can be specified

    -
    property name*
    additional property
    string

    Responses

    Response Schema: application/json
    id
    string <uuid>

    ID of the VPC

    -
    name
    string [ 2 .. 256 ] characters

    Name of the VPC

    -
    description
    string or null

    Description of the VPC, can be empty

    -
    org
    string

    Organization the VPC belongs to

    -
    tenantId
    string <uuid>

    ID of the Tenant the VPC belongs to

    -
    siteId
    string <uuid>

    ID of the Site the VPC belongs to

    -
    controllerVpcId
    string or null <uuid>

    Legacy attribute, contains the same value as ID

    -
    networkVirtualizationType
    string or null
    Enum: "ETHERNET_VIRTUALIZER" "FNN"

    Network virtualization type of the VPC

    -
    routingProfile
    string or null [ 3 .. 64 ] characters

    Routing profile type for the VPC. Populated when Site has Native Networking enabled and network virtualization type is FNN.

    -
    requestedVni
    integer or null [ 1 .. 65535 ]

    Explicitly requested VNI for the VPC if one was requested at creation time

    -
    vni
    integer or null [ 1 .. 65535 ]

    Active VNI assigned to the VPC

    -
    networkSecurityGroupId
    string or null

    ID of the Network Security Group attached to the VPC

    -
    object (NetworkSecurityGroupPropagationDetails)

    Propagation details for the attached Network Security Group

    -
    id
    string <uuid>

    The VPC or Instance ID

    -
    detailedStatus
    string
    Enum: "None" "Partial" "Full" "Unknown" "Error"
    status
    string (NetworkSecurityGroupPropagationStatus)
    Enum: "Synchronizing" "Synchronized" "Error"

    Status values for Network Security Group propagation

    -
    details
    string or null
    unpropagatedInstanceIds
    Array of strings <uuid> [ items <uuid > ]
    relatedInstanceIds
    Array of strings <uuid> [ items <uuid > ]
    nvLinkLogicalPartitionId
    string or null <uuid>

    ID of the default NVLink Logical Partition that GPUs for all Instances in the VPC will attach to

    -
    object (Labels) <= 10 properties

    String key value pairs describing VPC labels

    -
    property name*
    additional property
    string
    status
    string (VpcStatus)
    Enum: "Pending" "Provisioning" "Ready" "Configuring" "Deleting" "Error"

    Status of the VPC

    -
    Array of objects (StatusDetail)

    History of status changes for the VPC

    -
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>

    Date/time when VPC was created

    -
    updated
    string <date-time>

    Date/time when VPC was last updated

    -

    Request samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "spark-vpc",
    • "description": "Virtual network for machines executing Spark jobs",
    • "siteId": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
    • "networkVirtualizationType": "ETHERNET_VIRTUALIZER",
    • "vni": 12001,
    • "nvLinkLogicalPartitionId": "dd887330-dbd3-45ce-b400-c42fc8e47315",
    • "labels": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "spark-vpc",
    • "description": "Virtual network for machines executing Spark jobs",
    • "org": "xskkpgqpeakn",
    • "tenantId": "34f5c98e-f430-457b-a812-92637d0c6fd0",
    • "siteId": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
    • "controllerVpcId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "networkVirtualizationType": "ETHERNET_VIRTUALIZER",
    • "requestedVni": 12001,
    • "vni": 12001,
    • "nvLinkLogicalPartitionId": "dd887330-dbd3-45ce-b400-c42fc8e47315",
    • "labels": {
      },
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Retrieve a VPC

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    Request Body schema: application/json
    id
    string <uuid>

    Optional user-specified UUID for the VPC

    +
    name
    required
    string [ 2 .. 256 ] characters

    Name of the VPC

    +
    description
    string or null

    Optional description for the VPC

    +
    siteId
    required
    string <uuid>

    ID of the Site where the VPC should be created

    +
    networkVirtualizationType
    string or null
    Enum: "ETHERNET_VIRTUALIZER" "FNN"

    Network virtualization type of the VPC. If no value is specified, then defaults to FNN if Site has native networking enabled, or ETHERNET_VIRTUALIZER if native networking is disabled

    +
    routingProfile
    string or null [ 3 .. 64 ] characters

    Specify routing profile for the VPC. Only supported when networkVirtualizationType is set to FNN, or when networkVirtualizationType is omitted and Site has Native Networking enabled. Requires Tenant to have elevated privilege. Current accepted values are privileged-internal, internal, and external.

    +
    networkSecurityGroupId
    string or null

    ID of the Network Security Group to attach to the VPC

    +
    vni
    integer or null [ 1 .. 65535 ]

    Explicitly requested VNI for the VPC

    +
    nvLinkLogicalPartitionId
    string or null <uuid>

    ID of the default NVLink Logical Partition that GPUs for all Instances in the VPC will attach to

    +
    object (Labels) <= 10 properties

    String key value pairs describing VPC labels. Up to 10 key value pairs can be specified

    +
    property name*
    additional property
    string

    Responses

    Response Schema: application/json
    id
    string <uuid>

    ID of the VPC

    +
    name
    string [ 2 .. 256 ] characters

    Name of the VPC

    +
    description
    string or null

    Description of the VPC, can be empty

    +
    org
    string

    Organization the VPC belongs to

    +
    tenantId
    string <uuid>

    ID of the Tenant the VPC belongs to

    +
    siteId
    string <uuid>

    ID of the Site the VPC belongs to

    +
    controllerVpcId
    string or null <uuid>

    Legacy attribute, contains the same value as ID

    +
    networkVirtualizationType
    string or null
    Enum: "ETHERNET_VIRTUALIZER" "FNN"

    Network virtualization type of the VPC

    +
    routingProfile
    string or null [ 3 .. 64 ] characters

    Routing profile type for the VPC. Populated when Site has Native Networking enabled and network virtualization type is FNN.

    +
    requestedVni
    integer or null [ 1 .. 65535 ]

    Explicitly requested VNI for the VPC if one was requested at creation time

    +
    vni
    integer or null [ 1 .. 65535 ]

    Active VNI assigned to the VPC

    +
    networkSecurityGroupId
    string or null

    ID of the Network Security Group attached to the VPC

    +
    object (NetworkSecurityGroupPropagationDetails)

    Propagation details for the attached Network Security Group

    +
    id
    string <uuid>

    The VPC or Instance ID

    +
    detailedStatus
    string
    Enum: "None" "Partial" "Full" "Unknown" "Error"
    status
    string (NetworkSecurityGroupPropagationStatus)
    Enum: "Synchronizing" "Synchronized" "Error"

    Status values for Network Security Group propagation

    +
    details
    string or null
    unpropagatedInstanceIds
    Array of strings <uuid> [ items <uuid > ]
    relatedInstanceIds
    Array of strings <uuid> [ items <uuid > ]
    nvLinkLogicalPartitionId
    string or null <uuid>

    ID of the default NVLink Logical Partition that GPUs for all Instances in the VPC will attach to

    +
    object (Labels) <= 10 properties

    String key value pairs describing VPC labels

    +
    property name*
    additional property
    string
    status
    string (VpcStatus)
    Enum: "Pending" "Provisioning" "Ready" "Configuring" "Deleting" "Error"

    Status of the VPC

    +
    Array of objects (StatusDetail)

    History of status changes for the VPC

    +
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>

    Date/time when VPC was created

    +
    updated
    string <date-time>

    Date/time when VPC was last updated

    +

    Request samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "spark-vpc",
    • "description": "Virtual network for machines executing Spark jobs",
    • "siteId": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
    • "networkVirtualizationType": "ETHERNET_VIRTUALIZER",
    • "vni": 12001,
    • "nvLinkLogicalPartitionId": "dd887330-dbd3-45ce-b400-c42fc8e47315",
    • "labels": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "spark-vpc",
    • "description": "Virtual network for machines executing Spark jobs",
    • "org": "xskkpgqpeakn",
    • "tenantId": "34f5c98e-f430-457b-a812-92637d0c6fd0",
    • "siteId": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
    • "controllerVpcId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "networkVirtualizationType": "ETHERNET_VIRTUALIZER",
    • "requestedVni": 12001,
    • "vni": 12001,
    • "nvLinkLogicalPartitionId": "dd887330-dbd3-45ce-b400-c42fc8e47315",
    • "labels": {
      },
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Retrieve a VPC

    Retrieve a specific VPC by ID.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve a specific VPC by ID.

    Org must have a Tenant entity. User must have authorization role with TENANT_ADMIN suffix.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    vpcId
    required
    string <uuid>

    ID of the VPC

    -
    query Parameters
    includeRelation
    string
    Enum: "InfrastructureProvider" "Tenant" "Site" "NetworkSecurityGroup"

    Related entity to expand

    -

    Responses

    Response Schema: application/json
    id
    string <uuid>

    ID of the VPC

    -
    name
    string [ 2 .. 256 ] characters

    Name of the VPC

    -
    description
    string or null

    Description of the VPC, can be empty

    -
    org
    string

    Organization the VPC belongs to

    -
    tenantId
    string <uuid>

    ID of the Tenant the VPC belongs to

    -
    siteId
    string <uuid>

    ID of the Site the VPC belongs to

    -
    controllerVpcId
    string or null <uuid>

    Legacy attribute, contains the same value as ID

    -
    networkVirtualizationType
    string or null
    Enum: "ETHERNET_VIRTUALIZER" "FNN"

    Network virtualization type of the VPC

    -
    routingProfile
    string or null [ 3 .. 64 ] characters

    Routing profile type for the VPC. Populated when Site has Native Networking enabled and network virtualization type is FNN.

    -
    requestedVni
    integer or null [ 1 .. 65535 ]

    Explicitly requested VNI for the VPC if one was requested at creation time

    -
    vni
    integer or null [ 1 .. 65535 ]

    Active VNI assigned to the VPC

    -
    networkSecurityGroupId
    string or null

    ID of the Network Security Group attached to the VPC

    -
    object (NetworkSecurityGroupPropagationDetails)

    Propagation details for the attached Network Security Group

    -
    id
    string <uuid>

    The VPC or Instance ID

    -
    detailedStatus
    string
    Enum: "None" "Partial" "Full" "Unknown" "Error"
    status
    string (NetworkSecurityGroupPropagationStatus)
    Enum: "Synchronizing" "Synchronized" "Error"

    Status values for Network Security Group propagation

    -
    details
    string or null
    unpropagatedInstanceIds
    Array of strings <uuid> [ items <uuid > ]
    relatedInstanceIds
    Array of strings <uuid> [ items <uuid > ]
    nvLinkLogicalPartitionId
    string or null <uuid>

    ID of the default NVLink Logical Partition that GPUs for all Instances in the VPC will attach to

    -
    object (Labels) <= 10 properties

    String key value pairs describing VPC labels

    -
    property name*
    additional property
    string
    status
    string (VpcStatus)
    Enum: "Pending" "Provisioning" "Ready" "Configuring" "Deleting" "Error"

    Status of the VPC

    -
    Array of objects (StatusDetail)

    History of status changes for the VPC

    -
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>

    Date/time when VPC was created

    -
    updated
    string <date-time>

    Date/time when VPC was last updated

    -

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "spark-vpc",
    • "description": "Virtual network for machines executing Spark jobs",
    • "org": "xskkpgqpeakn",
    • "tenantId": "34f5c98e-f430-457b-a812-92637d0c6fd0",
    • "siteId": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
    • "controllerVpcId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "networkVirtualizationType": "ETHERNET_VIRTUALIZER",
    • "requestedVni": 12001,
    • "vni": 12001,
    • "nvLinkLogicalPartitionId": "dd887330-dbd3-45ce-b400-c42fc8e47315",
    • "labels": {
      },
    • "status": "Ready",
    • "networkSecurityGroupId": "c602eb90-3039-11f0-997a-b38d4fc8389e,",
    • "networkSecurityGroupPropagationDetails": {
      },
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Delete a VPC

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    vpcId
    required
    string <uuid>

    ID of the VPC

    +
    query Parameters
    includeRelation
    string
    Enum: "InfrastructureProvider" "Tenant" "Site" "NetworkSecurityGroup"

    Related entity to expand

    +

    Responses

    Response Schema: application/json
    id
    string <uuid>

    ID of the VPC

    +
    name
    string [ 2 .. 256 ] characters

    Name of the VPC

    +
    description
    string or null

    Description of the VPC, can be empty

    +
    org
    string

    Organization the VPC belongs to

    +
    tenantId
    string <uuid>

    ID of the Tenant the VPC belongs to

    +
    siteId
    string <uuid>

    ID of the Site the VPC belongs to

    +
    controllerVpcId
    string or null <uuid>

    Legacy attribute, contains the same value as ID

    +
    networkVirtualizationType
    string or null
    Enum: "ETHERNET_VIRTUALIZER" "FNN"

    Network virtualization type of the VPC

    +
    routingProfile
    string or null [ 3 .. 64 ] characters

    Routing profile type for the VPC. Populated when Site has Native Networking enabled and network virtualization type is FNN.

    +
    requestedVni
    integer or null [ 1 .. 65535 ]

    Explicitly requested VNI for the VPC if one was requested at creation time

    +
    vni
    integer or null [ 1 .. 65535 ]

    Active VNI assigned to the VPC

    +
    networkSecurityGroupId
    string or null

    ID of the Network Security Group attached to the VPC

    +
    object (NetworkSecurityGroupPropagationDetails)

    Propagation details for the attached Network Security Group

    +
    id
    string <uuid>

    The VPC or Instance ID

    +
    detailedStatus
    string
    Enum: "None" "Partial" "Full" "Unknown" "Error"
    status
    string (NetworkSecurityGroupPropagationStatus)
    Enum: "Synchronizing" "Synchronized" "Error"

    Status values for Network Security Group propagation

    +
    details
    string or null
    unpropagatedInstanceIds
    Array of strings <uuid> [ items <uuid > ]
    relatedInstanceIds
    Array of strings <uuid> [ items <uuid > ]
    nvLinkLogicalPartitionId
    string or null <uuid>

    ID of the default NVLink Logical Partition that GPUs for all Instances in the VPC will attach to

    +
    object (Labels) <= 10 properties

    String key value pairs describing VPC labels

    +
    property name*
    additional property
    string
    status
    string (VpcStatus)
    Enum: "Pending" "Provisioning" "Ready" "Configuring" "Deleting" "Error"

    Status of the VPC

    +
    Array of objects (StatusDetail)

    History of status changes for the VPC

    +
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>

    Date/time when VPC was created

    +
    updated
    string <date-time>

    Date/time when VPC was last updated

    +

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "spark-vpc",
    • "description": "Virtual network for machines executing Spark jobs",
    • "org": "xskkpgqpeakn",
    • "tenantId": "34f5c98e-f430-457b-a812-92637d0c6fd0",
    • "siteId": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
    • "controllerVpcId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "networkVirtualizationType": "ETHERNET_VIRTUALIZER",
    • "requestedVni": 12001,
    • "vni": 12001,
    • "nvLinkLogicalPartitionId": "dd887330-dbd3-45ce-b400-c42fc8e47315",
    • "labels": {
      },
    • "status": "Ready",
    • "networkSecurityGroupId": "c602eb90-3039-11f0-997a-b38d4fc8389e,",
    • "networkSecurityGroupPropagationDetails": {
      },
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Delete a VPC

    Delete a specific VPC by ID.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Delete a specific VPC by ID.

    Org must have a Tenant entity. User must have authorization role with TENANT_ADMIN suffix.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    vpcId
    required
    string <uuid>

    ID of the VPC

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "source": "nico",
    • "message": "User is not allowed to perform this action",
    • "data": null
    }

    Update VPC

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    vpcId
    required
    string <uuid>

    ID of the VPC

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "source": "nico",
    • "message": "User is not allowed to perform this action",
    • "data": null
    }

    Update VPC

    Update an existing VPC

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Update an existing VPC

    Org must have a Tenant entity. User must have authorization role with TENANT_ADMIN suffix

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    vpcId
    required
    string <uuid>

    ID of the VPC

    -
    Request Body schema: application/json
    name
    string or null [ 2 .. 256 ] characters

    Updated name of the VPC

    -
    description
    string or null

    Updated description of the VPC

    -
    networkSecurityGroupId
    string or null

    ID of the Network Security Group to attach to the VPC

    -
    nvLinkLogicalPartitionId
    string or null <uuid>

    ID of the default NVLink Logical Partition that GPUs for all Instances in the VPC will attach to. Can only be updated if VPC currently has no active Instances

    -
    object (Labels) <= 10 properties

    Update labels of the VPC. Up to 10 key value pairs can be specified. The labels will be entirely replaced by those sent in the request. Any labels not included in the request will be removed. To retain existing labels, first fetch them and include them along with this request.

    -
    property name*
    additional property
    string

    Responses

    Response Schema: application/json
    id
    string <uuid>

    ID of the VPC

    -
    name
    string [ 2 .. 256 ] characters

    Name of the VPC

    -
    description
    string or null

    Description of the VPC, can be empty

    -
    org
    string

    Organization the VPC belongs to

    -
    tenantId
    string <uuid>

    ID of the Tenant the VPC belongs to

    -
    siteId
    string <uuid>

    ID of the Site the VPC belongs to

    -
    controllerVpcId
    string or null <uuid>

    Legacy attribute, contains the same value as ID

    -
    networkVirtualizationType
    string or null
    Enum: "ETHERNET_VIRTUALIZER" "FNN"

    Network virtualization type of the VPC

    -
    routingProfile
    string or null [ 3 .. 64 ] characters

    Routing profile type for the VPC. Populated when Site has Native Networking enabled and network virtualization type is FNN.

    -
    requestedVni
    integer or null [ 1 .. 65535 ]

    Explicitly requested VNI for the VPC if one was requested at creation time

    -
    vni
    integer or null [ 1 .. 65535 ]

    Active VNI assigned to the VPC

    -
    networkSecurityGroupId
    string or null

    ID of the Network Security Group attached to the VPC

    -
    object (NetworkSecurityGroupPropagationDetails)

    Propagation details for the attached Network Security Group

    -
    id
    string <uuid>

    The VPC or Instance ID

    -
    detailedStatus
    string
    Enum: "None" "Partial" "Full" "Unknown" "Error"
    status
    string (NetworkSecurityGroupPropagationStatus)
    Enum: "Synchronizing" "Synchronized" "Error"

    Status values for Network Security Group propagation

    -
    details
    string or null
    unpropagatedInstanceIds
    Array of strings <uuid> [ items <uuid > ]
    relatedInstanceIds
    Array of strings <uuid> [ items <uuid > ]
    nvLinkLogicalPartitionId
    string or null <uuid>

    ID of the default NVLink Logical Partition that GPUs for all Instances in the VPC will attach to

    -
    object (Labels) <= 10 properties

    String key value pairs describing VPC labels

    -
    property name*
    additional property
    string
    status
    string (VpcStatus)
    Enum: "Pending" "Provisioning" "Ready" "Configuring" "Deleting" "Error"

    Status of the VPC

    -
    Array of objects (StatusDetail)

    History of status changes for the VPC

    -
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>

    Date/time when VPC was created

    -
    updated
    string <date-time>

    Date/time when VPC was last updated

    -

    Request samples

    Content type
    application/json
    {
    • "name": "spark-vpc-v1",
    • "description": "Virtual network for machines executing Spark jobs v1",
    • "labels": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "spark-vpc-v1",
    • "description": "Virtual network for machines executing Spark jobs v1",
    • "org": "xskkpgqpeakn",
    • "tenantId": "34f5c98e-f430-457b-a812-92637d0c6fd0",
    • "siteId": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
    • "controllerVpcId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "networkVirtualizationType": "ETHERNET_VIRTUALIZER",
    • "requestedVni": 12001,
    • "vni": 12001,
    • "nvLinkLogicalPartitionId": "dd887330-dbd3-45ce-b400-c42fc8e47315",
    • "labels": {
      },
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Update VPC Virtualization

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    vpcId
    required
    string <uuid>

    ID of the VPC

    +
    Request Body schema: application/json
    name
    string or null [ 2 .. 256 ] characters

    Updated name of the VPC

    +
    description
    string or null

    Updated description of the VPC

    +
    networkSecurityGroupId
    string or null

    ID of the Network Security Group to attach to the VPC

    +
    nvLinkLogicalPartitionId
    string or null <uuid>

    ID of the default NVLink Logical Partition that GPUs for all Instances in the VPC will attach to. Can only be updated if VPC currently has no active Instances

    +
    object (Labels) <= 10 properties

    Update labels of the VPC. Up to 10 key value pairs can be specified. The labels will be entirely replaced by those sent in the request. Any labels not included in the request will be removed. To retain existing labels, first fetch them and include them along with this request.

    +
    property name*
    additional property
    string

    Responses

    Response Schema: application/json
    id
    string <uuid>

    ID of the VPC

    +
    name
    string [ 2 .. 256 ] characters

    Name of the VPC

    +
    description
    string or null

    Description of the VPC, can be empty

    +
    org
    string

    Organization the VPC belongs to

    +
    tenantId
    string <uuid>

    ID of the Tenant the VPC belongs to

    +
    siteId
    string <uuid>

    ID of the Site the VPC belongs to

    +
    controllerVpcId
    string or null <uuid>

    Legacy attribute, contains the same value as ID

    +
    networkVirtualizationType
    string or null
    Enum: "ETHERNET_VIRTUALIZER" "FNN"

    Network virtualization type of the VPC

    +
    routingProfile
    string or null [ 3 .. 64 ] characters

    Routing profile type for the VPC. Populated when Site has Native Networking enabled and network virtualization type is FNN.

    +
    requestedVni
    integer or null [ 1 .. 65535 ]

    Explicitly requested VNI for the VPC if one was requested at creation time

    +
    vni
    integer or null [ 1 .. 65535 ]

    Active VNI assigned to the VPC

    +
    networkSecurityGroupId
    string or null

    ID of the Network Security Group attached to the VPC

    +
    object (NetworkSecurityGroupPropagationDetails)

    Propagation details for the attached Network Security Group

    +
    id
    string <uuid>

    The VPC or Instance ID

    +
    detailedStatus
    string
    Enum: "None" "Partial" "Full" "Unknown" "Error"
    status
    string (NetworkSecurityGroupPropagationStatus)
    Enum: "Synchronizing" "Synchronized" "Error"

    Status values for Network Security Group propagation

    +
    details
    string or null
    unpropagatedInstanceIds
    Array of strings <uuid> [ items <uuid > ]
    relatedInstanceIds
    Array of strings <uuid> [ items <uuid > ]
    nvLinkLogicalPartitionId
    string or null <uuid>

    ID of the default NVLink Logical Partition that GPUs for all Instances in the VPC will attach to

    +
    object (Labels) <= 10 properties

    String key value pairs describing VPC labels

    +
    property name*
    additional property
    string
    status
    string (VpcStatus)
    Enum: "Pending" "Provisioning" "Ready" "Configuring" "Deleting" "Error"

    Status of the VPC

    +
    Array of objects (StatusDetail)

    History of status changes for the VPC

    +
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>

    Date/time when VPC was created

    +
    updated
    string <date-time>

    Date/time when VPC was last updated

    +

    Request samples

    Content type
    application/json
    {
    • "name": "spark-vpc-v1",
    • "description": "Virtual network for machines executing Spark jobs v1",
    • "labels": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "spark-vpc-v1",
    • "description": "Virtual network for machines executing Spark jobs v1",
    • "org": "xskkpgqpeakn",
    • "tenantId": "34f5c98e-f430-457b-a812-92637d0c6fd0",
    • "siteId": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
    • "controllerVpcId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "networkVirtualizationType": "ETHERNET_VIRTUALIZER",
    • "requestedVni": 12001,
    • "vni": 12001,
    • "nvLinkLogicalPartitionId": "dd887330-dbd3-45ce-b400-c42fc8e47315",
    • "labels": {
      },
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Update VPC Virtualization

    Update network virtualization type for a VPC

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Update network virtualization type for a VPC

    Org must have a Tenant entity. User must have authorization role with TENANT_ADMIN suffix

    Tenant must own the VPC Request is rejected if the VPC already has Subnets or Instances

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    vpcId
    required
    string <uuid>

    ID of the VPC

    -
    Request Body schema: application/json
    networkVirtualizationType
    string
    Value: "FNN"

    Network virtualization type of the VPC. Can only be updated to FNN

    -

    Responses

    Response Schema: application/json
    id
    string <uuid>

    ID of the VPC

    -
    name
    string [ 2 .. 256 ] characters

    Name of the VPC

    -
    description
    string or null

    Description of the VPC, can be empty

    -
    org
    string

    Organization the VPC belongs to

    -
    tenantId
    string <uuid>

    ID of the Tenant the VPC belongs to

    -
    siteId
    string <uuid>

    ID of the Site the VPC belongs to

    -
    controllerVpcId
    string or null <uuid>

    Legacy attribute, contains the same value as ID

    -
    networkVirtualizationType
    string or null
    Enum: "ETHERNET_VIRTUALIZER" "FNN"

    Network virtualization type of the VPC

    -
    routingProfile
    string or null [ 3 .. 64 ] characters

    Routing profile type for the VPC. Populated when Site has Native Networking enabled and network virtualization type is FNN.

    -
    requestedVni
    integer or null [ 1 .. 65535 ]

    Explicitly requested VNI for the VPC if one was requested at creation time

    -
    vni
    integer or null [ 1 .. 65535 ]

    Active VNI assigned to the VPC

    -
    networkSecurityGroupId
    string or null

    ID of the Network Security Group attached to the VPC

    -
    object (NetworkSecurityGroupPropagationDetails)

    Propagation details for the attached Network Security Group

    -
    id
    string <uuid>

    The VPC or Instance ID

    -
    detailedStatus
    string
    Enum: "None" "Partial" "Full" "Unknown" "Error"
    status
    string (NetworkSecurityGroupPropagationStatus)
    Enum: "Synchronizing" "Synchronized" "Error"

    Status values for Network Security Group propagation

    -
    details
    string or null
    unpropagatedInstanceIds
    Array of strings <uuid> [ items <uuid > ]
    relatedInstanceIds
    Array of strings <uuid> [ items <uuid > ]
    nvLinkLogicalPartitionId
    string or null <uuid>

    ID of the default NVLink Logical Partition that GPUs for all Instances in the VPC will attach to

    -
    object (Labels) <= 10 properties

    String key value pairs describing VPC labels

    -
    property name*
    additional property
    string
    status
    string (VpcStatus)
    Enum: "Pending" "Provisioning" "Ready" "Configuring" "Deleting" "Error"

    Status of the VPC

    -
    Array of objects (StatusDetail)

    History of status changes for the VPC

    -
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>

    Date/time when VPC was created

    -
    updated
    string <date-time>

    Date/time when VPC was last updated

    -

    Request samples

    Content type
    application/json
    {
    • "networkVirtualizationType": "FNN"
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "spark-vpc-v1",
    • "description": "Virtual network for machines executing Spark jobs v1",
    • "org": "xskkpgqpeakn",
    • "tenantId": "34f5c98e-f430-457b-a812-92637d0c6fd0",
    • "siteId": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
    • "controllerVpcId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "networkVirtualizationType": "FNN",
    • "requestedVni": 12001,
    • "vni": 12001,
    • "nvLinkLogicalPartitionId": "dd887330-dbd3-45ce-b400-c42fc8e47315",
    • "labels": {
      },
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    VPC Peering

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    vpcId
    required
    string <uuid>

    ID of the VPC

    +
    Request Body schema: application/json
    networkVirtualizationType
    string
    Value: "FNN"

    Network virtualization type of the VPC. Can only be updated to FNN

    +

    Responses

    Response Schema: application/json
    id
    string <uuid>

    ID of the VPC

    +
    name
    string [ 2 .. 256 ] characters

    Name of the VPC

    +
    description
    string or null

    Description of the VPC, can be empty

    +
    org
    string

    Organization the VPC belongs to

    +
    tenantId
    string <uuid>

    ID of the Tenant the VPC belongs to

    +
    siteId
    string <uuid>

    ID of the Site the VPC belongs to

    +
    controllerVpcId
    string or null <uuid>

    Legacy attribute, contains the same value as ID

    +
    networkVirtualizationType
    string or null
    Enum: "ETHERNET_VIRTUALIZER" "FNN"

    Network virtualization type of the VPC

    +
    routingProfile
    string or null [ 3 .. 64 ] characters

    Routing profile type for the VPC. Populated when Site has Native Networking enabled and network virtualization type is FNN.

    +
    requestedVni
    integer or null [ 1 .. 65535 ]

    Explicitly requested VNI for the VPC if one was requested at creation time

    +
    vni
    integer or null [ 1 .. 65535 ]

    Active VNI assigned to the VPC

    +
    networkSecurityGroupId
    string or null

    ID of the Network Security Group attached to the VPC

    +
    object (NetworkSecurityGroupPropagationDetails)

    Propagation details for the attached Network Security Group

    +
    id
    string <uuid>

    The VPC or Instance ID

    +
    detailedStatus
    string
    Enum: "None" "Partial" "Full" "Unknown" "Error"
    status
    string (NetworkSecurityGroupPropagationStatus)
    Enum: "Synchronizing" "Synchronized" "Error"

    Status values for Network Security Group propagation

    +
    details
    string or null
    unpropagatedInstanceIds
    Array of strings <uuid> [ items <uuid > ]
    relatedInstanceIds
    Array of strings <uuid> [ items <uuid > ]
    nvLinkLogicalPartitionId
    string or null <uuid>

    ID of the default NVLink Logical Partition that GPUs for all Instances in the VPC will attach to

    +
    object (Labels) <= 10 properties

    String key value pairs describing VPC labels

    +
    property name*
    additional property
    string
    status
    string (VpcStatus)
    Enum: "Pending" "Provisioning" "Ready" "Configuring" "Deleting" "Error"

    Status of the VPC

    +
    Array of objects (StatusDetail)

    History of status changes for the VPC

    +
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>

    Date/time when VPC was created

    +
    updated
    string <date-time>

    Date/time when VPC was last updated

    +

    Request samples

    Content type
    application/json
    {
    • "networkVirtualizationType": "FNN"
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "spark-vpc-v1",
    • "description": "Virtual network for machines executing Spark jobs v1",
    • "org": "xskkpgqpeakn",
    • "tenantId": "34f5c98e-f430-457b-a812-92637d0c6fd0",
    • "siteId": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
    • "controllerVpcId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "networkVirtualizationType": "FNN",
    • "requestedVni": 12001,
    • "vni": 12001,
    • "nvLinkLogicalPartitionId": "dd887330-dbd3-45ce-b400-c42fc8e47315",
    • "labels": {
      },
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    VPC Peering

    VPC Peering allows Instances in one VPC to communicate with Instances in another VPC on the same Site.

    -

    Retrieve all VPC peerings

    Retrieve all VPC peerings

    Get all VPC peerings. +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Get all VPC peerings. Tenant Admin can get all peerings where the tenant owns at least one VPC. Provider Admin can get all peerings in a site. User must have authorization role with TENANT_ADMIN or PROVIDER_ADMIN suffix.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    query Parameters
    siteId
    string <uuid>

    Optional Site ID filter. If provided, caller must have access to the specified Site.

    -
    pageNumber
    integer >= 1
    Default: 1
    Example: pageNumber=1

    Page number for pagination query

    -
    pageSize
    integer [ 1 .. 100 ]
    Example: pageSize=20

    Page size for pagination query

    -
    orderBy
    string

    Ordering for pagination query

    -
    isMultiTenant
    boolean

    Optional filter by peering tenancy type (single-tenant or multi-tenant).

    -
    includeRelation
    string
    Enum: "Vpc1" "Vpc2" "Site"

    Related entity to expand

    -

    Responses

    Response Headers
    X-Pagination
    string
    Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}"

    Pagination result in JSON format

    -
    Response Schema: application/json
    Array
    id
    string <uuid>

    Unique identifier of the VPC peering

    -
    vpc1Id
    string <uuid>

    ID of the first VPC in the peering

    -
    vpc2Id
    string <uuid>

    ID of the second VPC in the peering

    -
    siteId
    string <uuid>

    ID of the Site where the peering exists

    -
    isMultiTenant
    boolean

    Indicates if this is a multi-tenant peering (VPCs from different tenants)

    -
    status
    string (VpcPeeringStatus)
    Enum: "Pending" "Configuring" "Requested" "Ready" "Deleting" "Error"

    Status of the VPC peering

    -
    created
    string <date-time>

    Date and time when the VPC peering was created

    -
    updated
    string <date-time>

    Date and time when the VPC peering was last updated

    -

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Create VPC peering

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    query Parameters
    siteId
    string <uuid>

    Optional Site ID filter. If provided, caller must have access to the specified Site.

    +
    pageNumber
    integer >= 1
    Default: 1
    Example: pageNumber=1

    Page number for pagination query

    +
    pageSize
    integer [ 1 .. 100 ]
    Example: pageSize=20

    Page size for pagination query

    +
    orderBy
    string

    Ordering for pagination query

    +
    isMultiTenant
    boolean

    Optional filter by peering tenancy type (single-tenant or multi-tenant).

    +
    includeRelation
    string
    Enum: "Vpc1" "Vpc2" "Site"

    Related entity to expand

    +

    Responses

    Response Headers
    X-Pagination
    string
    Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}"

    Pagination result in JSON format

    +
    Response Schema: application/json
    Array
    id
    string <uuid>

    Unique identifier of the VPC peering

    +
    vpc1Id
    string <uuid>

    ID of the first VPC in the peering

    +
    vpc2Id
    string <uuid>

    ID of the second VPC in the peering

    +
    siteId
    string <uuid>

    ID of the Site where the peering exists

    +
    isMultiTenant
    boolean

    Indicates if this is a multi-tenant peering (VPCs from different tenants)

    +
    status
    string (VpcPeeringStatus)
    Enum: "Pending" "Configuring" "Requested" "Ready" "Deleting" "Error"

    Status of the VPC peering

    +
    created
    string <date-time>

    Date and time when the VPC peering was created

    +
    updated
    string <date-time>

    Date and time when the VPC peering was last updated

    +

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Create VPC peering

    Create a VPC peering between two VPCs on the same site.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Create a VPC peering between two VPCs on the same site.

    Tenant Admin can create single-tenant peerings (both VPCs belong to their tenant). Provider Admin can create multi-tenant peerings (VPCs from different tenants).

    User must have authorization role with TENANT_ADMIN or PROVIDER_ADMIN suffix.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    Request Body schema: application/json
    required
    vpc1Id
    required
    string <uuid>

    ID of the first VPC in the peering

    -
    vpc2Id
    required
    string <uuid>

    ID of the second VPC to peer with

    -
    siteId
    required
    string <uuid>

    ID of the Site where the peering exists

    -

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier of the VPC peering

    -
    vpc1Id
    string <uuid>

    ID of the first VPC in the peering

    -
    vpc2Id
    string <uuid>

    ID of the second VPC in the peering

    -
    siteId
    string <uuid>

    ID of the Site where the peering exists

    -
    isMultiTenant
    boolean

    Indicates if this is a multi-tenant peering (VPCs from different tenants)

    -
    status
    string (VpcPeeringStatus)
    Enum: "Pending" "Configuring" "Requested" "Ready" "Deleting" "Error"

    Status of the VPC peering

    -
    created
    string <date-time>

    Date and time when the VPC peering was created

    -
    updated
    string <date-time>

    Date and time when the VPC peering was last updated

    -

    Request samples

    Content type
    application/json
    {
    • "vpc1Id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "vpc2Id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
    • "siteId": "72771e6a-6f5e-4de4-a5b9-1266c4197811"
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "vpc1Id": "bafbaf4c-c730-48ae-8f5d-d7d251f3315a",
    • "vpc2Id": "a7cd678e-fe62-4184-9f75-66ac903ae1c3",
    • "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
    • "isMultiTenant": true,
    • "status": "Pending",
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Retrieve a VPC peering

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    Request Body schema: application/json
    required
    vpc1Id
    required
    string <uuid>

    ID of the first VPC in the peering

    +
    vpc2Id
    required
    string <uuid>

    ID of the second VPC to peer with

    +
    siteId
    required
    string <uuid>

    ID of the Site where the peering exists

    +

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier of the VPC peering

    +
    vpc1Id
    string <uuid>

    ID of the first VPC in the peering

    +
    vpc2Id
    string <uuid>

    ID of the second VPC in the peering

    +
    siteId
    string <uuid>

    ID of the Site where the peering exists

    +
    isMultiTenant
    boolean

    Indicates if this is a multi-tenant peering (VPCs from different tenants)

    +
    status
    string (VpcPeeringStatus)
    Enum: "Pending" "Configuring" "Requested" "Ready" "Deleting" "Error"

    Status of the VPC peering

    +
    created
    string <date-time>

    Date and time when the VPC peering was created

    +
    updated
    string <date-time>

    Date and time when the VPC peering was last updated

    +

    Request samples

    Content type
    application/json
    {
    • "vpc1Id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "vpc2Id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
    • "siteId": "72771e6a-6f5e-4de4-a5b9-1266c4197811"
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "vpc1Id": "bafbaf4c-c730-48ae-8f5d-d7d251f3315a",
    • "vpc2Id": "a7cd678e-fe62-4184-9f75-66ac903ae1c3",
    • "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
    • "isMultiTenant": true,
    • "status": "Pending",
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Retrieve a VPC peering

    Get details of a VPC peering by ID.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Get details of a VPC peering by ID.

    Tenant Admin can get a peering if at least one VPC belongs to their tenant. Provider Admin can get a peering if it is in a site provided by their org.

    User must have authorization role with TENANT_ADMIN or PROVIDER_ADMIN suffix.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    id
    required
    string <uuid>

    VPC Peering ID

    -
    query Parameters
    includeRelation
    string
    Enum: "Vpc1" "Vpc2" "Site"

    Related entity to expand

    -

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier of the VPC peering

    -
    vpc1Id
    string <uuid>

    ID of the first VPC in the peering

    -
    vpc2Id
    string <uuid>

    ID of the second VPC in the peering

    -
    siteId
    string <uuid>

    ID of the Site where the peering exists

    -
    isMultiTenant
    boolean

    Indicates if this is a multi-tenant peering (VPCs from different tenants)

    -
    status
    string (VpcPeeringStatus)
    Enum: "Pending" "Configuring" "Requested" "Ready" "Deleting" "Error"

    Status of the VPC peering

    -
    created
    string <date-time>

    Date and time when the VPC peering was created

    -
    updated
    string <date-time>

    Date and time when the VPC peering was last updated

    -

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "vpc1Id": "bafbaf4c-c730-48ae-8f5d-d7d251f3315a",
    • "vpc2Id": "a7cd678e-fe62-4184-9f75-66ac903ae1c3",
    • "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
    • "isMultiTenant": true,
    • "status": "Pending",
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Delete a VPC peering

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    id
    required
    string <uuid>

    VPC Peering ID

    +
    query Parameters
    includeRelation
    string
    Enum: "Vpc1" "Vpc2" "Site"

    Related entity to expand

    +

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier of the VPC peering

    +
    vpc1Id
    string <uuid>

    ID of the first VPC in the peering

    +
    vpc2Id
    string <uuid>

    ID of the second VPC in the peering

    +
    siteId
    string <uuid>

    ID of the Site where the peering exists

    +
    isMultiTenant
    boolean

    Indicates if this is a multi-tenant peering (VPCs from different tenants)

    +
    status
    string (VpcPeeringStatus)
    Enum: "Pending" "Configuring" "Requested" "Ready" "Deleting" "Error"

    Status of the VPC peering

    +
    created
    string <date-time>

    Date and time when the VPC peering was created

    +
    updated
    string <date-time>

    Date and time when the VPC peering was last updated

    +

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "vpc1Id": "bafbaf4c-c730-48ae-8f5d-d7d251f3315a",
    • "vpc2Id": "a7cd678e-fe62-4184-9f75-66ac903ae1c3",
    • "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
    • "isMultiTenant": true,
    • "status": "Pending",
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Delete a VPC peering

    Delete a VPC peering by ID.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Delete a VPC peering by ID.

    Tenant Admin can delete only peerings where both VPCs belong to their tenant. Provider Admin can delete only multi-tenant peerings in sites they provide.

    User must have authorization role with TENANT_ADMIN or PROVIDER_ADMIN suffix.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    id
    required
    string <uuid>

    VPC Peering ID

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "source": "nico",
    • "message": "Error validating request data",
    • "data": {
      }
    }

    VPC Prefix

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    id
    required
    string <uuid>

    VPC Peering ID

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "source": "nico",
    • "message": "Error validating request data",
    • "data": {
      }
    }

    VPC Prefix

    VPC Prefix is a network prefix belonging to an IP Block allocated to a Tenant. Tenant can use VPC Prefixes to enable network connectivity between their Instances.

    Only Sites that support Native Networking (FNN) offer VPC Prefix management.

    -

    Retrieve all VPC Prefixes

    Retrieve all VPC Prefixes

    Retrieve all VPC Prefixes for the org

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve all VPC Prefixes for the org

    Org must have a Tenant entity. User must have authorization role with TENANT_ADMIN suffix.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    query Parameters
    siteId
    string <uuid>

    Filter VPC Prefixes by Site, required if vpcId query param is not specified

    -
    vpcId
    string <uuid>

    Filter VPC Prefixes by VPC

    -
    status
    string

    Filter VPC Prefixes by Status

    -
    query
    string

    Search for matches across all Sites. Input will be matched against name and status fields

    -
    includeRelation
    string
    Enum: "VPC" "Tenant" "IPBlock"

    Related entity to expand

    -
    includeUsageStats
    boolean

    When true, each VPC Prefix includes IPv4 usageStats using the same JSON shape as IP Block usage counters. Values are projected from ethernet interface addresses on Instances in this prefix (/31-paired consumption; counts include two host addresses per interface slot). The parent IP Block relation may be loaded internally when resolving allocation context.

    -
    pageNumber
    integer >= 1
    Default: 1
    Example: pageNumber=1

    Page number for pagination query

    -
    pageSize
    integer [ 1 .. 100 ]
    Example: pageSize=20

    Page size for pagination query

    -
    orderBy
    string
    Enum: "NAME_ASC" "NAME_DESC" "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC"

    Ordering for pagination query

    -

    Responses

    Response Headers
    X-Pagination
    string
    Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}"

    Pagination result in JSON format

    -
    Response Schema: application/json
    Array
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters

    Name of the VPC Prefix

    -
    siteId
    string <uuid>

    ID of the Site the VPC Prefix belongs to

    -
    vpcId
    string <uuid>

    ID of the VPC the VPC Prefix belongs to

    -
    tenantId
    string <uuid>

    ID of the Tenant the VPC Prefix belongs to

    -
    ipBlockId
    string or null <uuid>

    ID of the IP Block that contains the prefix of the VPC Prefix

    -
    prefix
    string or null

    The network prefix including prefix length in CIDR notation

    -
    prefixLength
    integer [ 8 .. 31 ]

    Length of the prefix. Valid range is 8 to 31, and max usable value depends on prefix length of parent IP Block.

    -
    status
    string (VpcPrefixStatus)
    Enum: "Ready" "Deleting" "Error"

    Status of the VPC Prefix

    -
    object (IpBlockUsageStats)

    Present when query param includeUsageStats=true. IPv4 usage applies interface-based rules (including 2 IPs per Ethernet interface slot); -availablePrefixes reflects /31-sized subdivisions inferred from assigned interface IP addresses.

    -
    availableIPs
    integer <int64>

    Number of IP addresses available in the block

    -
    acquiredIPs
    integer <int64>

    Number of individual IP addresses acquired from the block

    -
    availablePrefixes
    Array of strings

    Example prefixes available to acquire. For IPBlocks this comes from IPAM. -For Subnets and VPC Prefixes with interface-derived usage, at most 10 sample prefixes are returned -(/32 host prefixes for Subnets; /31 prefixes for VPC Prefixes).

    -
    availableSmallestPrefixes
    integer <int64>

    Number of smallest prefixes available to acquire. For VPC Prefix interface-derived usage this is the count of remaining /31 interface slots (half of remaining IPs). -Subnet interface-derived usage leaves this as zero; IPBlocks use IPAM semantics.

    -
    acquiredPrefixes
    integer <int64>

    Number of prefixes acquired from this block

    -
    Array of objects (StatusDetail)

    Details of 20 most recent status changes

    -
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>

    Date and time when the VPC Prefix was created

    -
    updated
    string <date-time>

    Date and time when the VPC Prefix was updated

    -

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Create VPC Prefix

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    query Parameters
    siteId
    string <uuid>

    Filter VPC Prefixes by Site, required if vpcId query param is not specified

    +
    vpcId
    string <uuid>

    Filter VPC Prefixes by VPC

    +
    status
    string

    Filter VPC Prefixes by Status

    +
    query
    string

    Search for matches across all Sites. Input will be matched against name and status fields

    +
    includeRelation
    string
    Enum: "VPC" "Tenant" "IPBlock"

    Related entity to expand

    +
    includeUsageStats
    boolean

    When true, each VPC Prefix object includes usage statistic 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

    Page number for pagination query

    +
    pageSize
    integer [ 1 .. 100 ]
    Example: pageSize=20

    Page size for pagination query

    +
    orderBy
    string
    Enum: "NAME_ASC" "NAME_DESC" "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC"

    Ordering for pagination query

    +

    Responses

    Response Headers
    X-Pagination
    string
    Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}"

    Pagination result in JSON format

    +
    Response Schema: application/json
    Array
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters

    Name of the VPC Prefix

    +
    siteId
    string <uuid>

    ID of the Site the VPC Prefix belongs to

    +
    vpcId
    string <uuid>

    ID of the VPC the VPC Prefix belongs to

    +
    tenantId
    string <uuid>

    ID of the Tenant the VPC Prefix belongs to

    +
    ipBlockId
    string or null <uuid>

    ID of the IP Block that contains the prefix of the VPC Prefix

    +
    prefix
    string or null

    The network prefix including prefix length in CIDR notation

    +
    prefixLength
    integer [ 8 .. 31 ]

    Length of the prefix. Valid range is 8 to 31, and max usable value depends on prefix length of parent IP Block.

    +
    status
    string (VpcPrefixStatus)
    Enum: "Ready" "Deleting" "Error"

    Status of the VPC Prefix

    +
    object (IpBlockUsageStats)

    Present when query param includeUsageStats=true. Prefix and IP usage data is derived by evaluating associated Ethernet interfaces. Each Interface associated with a VPC Prefix consumes a /31 prefix.

    +
    availableIPs
    integer <int64>

    Number of IP addresses available in the block

    +
    acquiredIPs
    integer <int64>

    Number of individual IP addresses acquired from the block

    +
    availablePrefixes
    Array of strings

    Example prefixes available to acquire

    +
    availableSmallestPrefixes
    integer <int64>

    Number of smallest prefixes available to acquire

    +
    acquiredPrefixes
    integer <int64>

    Number of prefixes acquired from this block

    +
    Array of objects (StatusDetail)

    Details of 20 most recent status changes

    +
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>

    Date and time when the VPC Prefix was created

    +
    updated
    string <date-time>

    Date and time when the VPC Prefix was updated

    +

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Create VPC Prefix

    Create a VPC Prefix for the org.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Create a VPC Prefix for the org.

    Org must have a Tenant entity. User must have authorization role with TENANT_ADMIN suffix.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    Request Body schema: application/json
    name
    required
    string [ 2 .. 256 ] characters

    Human readable name for the VPC Prefix

    -
    vpcId
    required
    string <uuid>

    ID of the VPC

    -
    ipBlockId
    required
    string <uuid>

    ID of the IP Block to allocate the VPC Prefix from

    -
    prefixLength
    required
    integer [ 8 .. 31 ]

    Prefix length for the VPC Prefix. Valid range is 8 to 31, and max usable value depends on prefix length of parent IP Block.

    -

    Responses

    Response Schema: application/json
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters

    Name of the VPC Prefix

    -
    siteId
    string <uuid>

    ID of the Site the VPC Prefix belongs to

    -
    vpcId
    string <uuid>

    ID of the VPC the VPC Prefix belongs to

    -
    tenantId
    string <uuid>

    ID of the Tenant the VPC Prefix belongs to

    -
    ipBlockId
    string or null <uuid>

    ID of the IP Block that contains the prefix of the VPC Prefix

    -
    prefix
    string or null

    The network prefix including prefix length in CIDR notation

    -
    prefixLength
    integer [ 8 .. 31 ]

    Length of the prefix. Valid range is 8 to 31, and max usable value depends on prefix length of parent IP Block.

    -
    status
    string (VpcPrefixStatus)
    Enum: "Ready" "Deleting" "Error"

    Status of the VPC Prefix

    -
    object (IpBlockUsageStats)

    Present when query param includeUsageStats=true. IPv4 usage applies interface-based rules (including 2 IPs per Ethernet interface slot); -availablePrefixes reflects /31-sized subdivisions inferred from assigned interface IP addresses.

    -
    availableIPs
    integer <int64>

    Number of IP addresses available in the block

    -
    acquiredIPs
    integer <int64>

    Number of individual IP addresses acquired from the block

    -
    availablePrefixes
    Array of strings

    Example prefixes available to acquire. For IPBlocks this comes from IPAM. -For Subnets and VPC Prefixes with interface-derived usage, at most 10 sample prefixes are returned -(/32 host prefixes for Subnets; /31 prefixes for VPC Prefixes).

    -
    availableSmallestPrefixes
    integer <int64>

    Number of smallest prefixes available to acquire. For VPC Prefix interface-derived usage this is the count of remaining /31 interface slots (half of remaining IPs). -Subnet interface-derived usage leaves this as zero; IPBlocks use IPAM semantics.

    -
    acquiredPrefixes
    integer <int64>

    Number of prefixes acquired from this block

    -
    Array of objects (StatusDetail)

    Details of 20 most recent status changes

    -
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>

    Date and time when the VPC Prefix was created

    -
    updated
    string <date-time>

    Date and time when the VPC Prefix was updated

    -

    Request samples

    Content type
    application/json
    {
    • "name": "east-vpc-traffic-net",
    • "vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
    • "ipBlockId": "8c1d1a06-90a2-4863-8ee1-6029265b9f0a",
    • "prefixLength": 20
    }

    Response samples

    Content type
    application/json
    {
    • "id": "0c03ba01-d86b-4a57-a41e-cc359b380a6f",
    • "name": "east-vpc-traffic-net",
    • "siteId": "ea144def-d68f-44c3-9485-4b103fa2686f",
    • "vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "prefix": "192.168.1.0/26",
    • "ipBlockId": "8c1d1a06-90a2-4863-8ee1-6029265b9f0a",
    • "prefixLength": 26,
    • "status": "Ready",
    • "usageStats": {
      },
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Retrieve VPC Prefix

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    Request Body schema: application/json
    name
    required
    string [ 2 .. 256 ] characters

    Human readable name for the VPC Prefix

    +
    vpcId
    required
    string <uuid>

    ID of the VPC

    +
    ipBlockId
    required
    string <uuid>

    ID of the IP Block to allocate the VPC Prefix from

    +
    prefixLength
    required
    integer [ 8 .. 31 ]

    Prefix length for the VPC Prefix. Valid range is 8 to 31, and max usable value depends on prefix length of parent IP Block.

    +

    Responses

    Response Schema: application/json
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters

    Name of the VPC Prefix

    +
    siteId
    string <uuid>

    ID of the Site the VPC Prefix belongs to

    +
    vpcId
    string <uuid>

    ID of the VPC the VPC Prefix belongs to

    +
    tenantId
    string <uuid>

    ID of the Tenant the VPC Prefix belongs to

    +
    ipBlockId
    string or null <uuid>

    ID of the IP Block that contains the prefix of the VPC Prefix

    +
    prefix
    string or null

    The network prefix including prefix length in CIDR notation

    +
    prefixLength
    integer [ 8 .. 31 ]

    Length of the prefix. Valid range is 8 to 31, and max usable value depends on prefix length of parent IP Block.

    +
    status
    string (VpcPrefixStatus)
    Enum: "Ready" "Deleting" "Error"

    Status of the VPC Prefix

    +
    object (IpBlockUsageStats)

    Present when query param includeUsageStats=true. Prefix and IP usage data is derived by evaluating associated Ethernet interfaces. Each Interface associated with a VPC Prefix consumes a /31 prefix.

    +
    availableIPs
    integer <int64>

    Number of IP addresses available in the block

    +
    acquiredIPs
    integer <int64>

    Number of individual IP addresses acquired from the block

    +
    availablePrefixes
    Array of strings

    Example prefixes available to acquire

    +
    availableSmallestPrefixes
    integer <int64>

    Number of smallest prefixes available to acquire

    +
    acquiredPrefixes
    integer <int64>

    Number of prefixes acquired from this block

    +
    Array of objects (StatusDetail)

    Details of 20 most recent status changes

    +
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>

    Date and time when the VPC Prefix was created

    +
    updated
    string <date-time>

    Date and time when the VPC Prefix was updated

    +

    Request samples

    Content type
    application/json
    {
    • "name": "east-vpc-traffic-net",
    • "vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
    • "ipBlockId": "8c1d1a06-90a2-4863-8ee1-6029265b9f0a",
    • "prefixLength": 20
    }

    Response samples

    Content type
    application/json
    {
    • "id": "0c03ba01-d86b-4a57-a41e-cc359b380a6f",
    • "name": "east-vpc-traffic-net",
    • "siteId": "ea144def-d68f-44c3-9485-4b103fa2686f",
    • "vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "prefix": "192.168.1.0/26",
    • "ipBlockId": "8c1d1a06-90a2-4863-8ee1-6029265b9f0a",
    • "prefixLength": 26,
    • "status": "Ready",
    • "usageStats": {
      },
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Retrieve VPC Prefix

    Retrieve a specific VPC Prefix

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve a specific VPC Prefix

    Org must have a Tenant entity. User must have authorization role with TENANT_ADMIN suffix.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    vpcPrefixId
    required
    string <uuid>

    ID of the VPC Prefix

    -
    query Parameters
    includeRelation
    string
    Enum: "VPC" "Tenant" "IPBlock"

    Related entity to expand

    -
    includeUsageStats
    boolean

    When true, each VPC Prefix includes IPv4 usageStats using the same JSON shape as IP Block usage counters. Values are projected from ethernet interface addresses on Instances in this prefix (/31-paired consumption; counts include two host addresses per interface slot). The parent IP Block relation may be loaded internally when resolving allocation context.

    -

    Responses

    Response Schema: application/json
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters

    Name of the VPC Prefix

    -
    siteId
    string <uuid>

    ID of the Site the VPC Prefix belongs to

    -
    vpcId
    string <uuid>

    ID of the VPC the VPC Prefix belongs to

    -
    tenantId
    string <uuid>

    ID of the Tenant the VPC Prefix belongs to

    -
    ipBlockId
    string or null <uuid>

    ID of the IP Block that contains the prefix of the VPC Prefix

    -
    prefix
    string or null

    The network prefix including prefix length in CIDR notation

    -
    prefixLength
    integer [ 8 .. 31 ]

    Length of the prefix. Valid range is 8 to 31, and max usable value depends on prefix length of parent IP Block.

    -
    status
    string (VpcPrefixStatus)
    Enum: "Ready" "Deleting" "Error"

    Status of the VPC Prefix

    -
    object (IpBlockUsageStats)

    Present when query param includeUsageStats=true. IPv4 usage applies interface-based rules (including 2 IPs per Ethernet interface slot); -availablePrefixes reflects /31-sized subdivisions inferred from assigned interface IP addresses.

    -
    availableIPs
    integer <int64>

    Number of IP addresses available in the block

    -
    acquiredIPs
    integer <int64>

    Number of individual IP addresses acquired from the block

    -
    availablePrefixes
    Array of strings

    Example prefixes available to acquire. For IPBlocks this comes from IPAM. -For Subnets and VPC Prefixes with interface-derived usage, at most 10 sample prefixes are returned -(/32 host prefixes for Subnets; /31 prefixes for VPC Prefixes).

    -
    availableSmallestPrefixes
    integer <int64>

    Number of smallest prefixes available to acquire. For VPC Prefix interface-derived usage this is the count of remaining /31 interface slots (half of remaining IPs). -Subnet interface-derived usage leaves this as zero; IPBlocks use IPAM semantics.

    -
    acquiredPrefixes
    integer <int64>

    Number of prefixes acquired from this block

    -
    Array of objects (StatusDetail)

    Details of 20 most recent status changes

    -
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>

    Date and time when the VPC Prefix was created

    -
    updated
    string <date-time>

    Date and time when the VPC Prefix was updated

    -

    Response samples

    Content type
    application/json
    {
    • "id": "0c03ba01-d86b-4a57-a41e-cc359b380a6f",
    • "name": "east-vpc-traffic-net",
    • "siteId": "ea144def-d68f-44c3-9485-4b103fa2686f",
    • "vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "prefix": "192.168.1.0/26",
    • "ipBlockId": "8c1d1a06-90a2-4863-8ee1-6029265b9f0a",
    • "prefixLength": 26,
    • "status": "Ready",
    • "usageStats": {
      },
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Delete VPC Prefix

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    vpcPrefixId
    required
    string <uuid>

    ID of the VPC Prefix

    +
    query Parameters
    includeRelation
    string
    Enum: "VPC" "Tenant" "IPBlock"

    Related entity to expand

    +
    includeUsageStats
    boolean

    When true, each VPC Prefix object includes usage statistic 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.

    +

    Responses

    Response Schema: application/json
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters

    Name of the VPC Prefix

    +
    siteId
    string <uuid>

    ID of the Site the VPC Prefix belongs to

    +
    vpcId
    string <uuid>

    ID of the VPC the VPC Prefix belongs to

    +
    tenantId
    string <uuid>

    ID of the Tenant the VPC Prefix belongs to

    +
    ipBlockId
    string or null <uuid>

    ID of the IP Block that contains the prefix of the VPC Prefix

    +
    prefix
    string or null

    The network prefix including prefix length in CIDR notation

    +
    prefixLength
    integer [ 8 .. 31 ]

    Length of the prefix. Valid range is 8 to 31, and max usable value depends on prefix length of parent IP Block.

    +
    status
    string (VpcPrefixStatus)
    Enum: "Ready" "Deleting" "Error"

    Status of the VPC Prefix

    +
    object (IpBlockUsageStats)

    Present when query param includeUsageStats=true. Prefix and IP usage data is derived by evaluating associated Ethernet interfaces. Each Interface associated with a VPC Prefix consumes a /31 prefix.

    +
    availableIPs
    integer <int64>

    Number of IP addresses available in the block

    +
    acquiredIPs
    integer <int64>

    Number of individual IP addresses acquired from the block

    +
    availablePrefixes
    Array of strings

    Example prefixes available to acquire

    +
    availableSmallestPrefixes
    integer <int64>

    Number of smallest prefixes available to acquire

    +
    acquiredPrefixes
    integer <int64>

    Number of prefixes acquired from this block

    +
    Array of objects (StatusDetail)

    Details of 20 most recent status changes

    +
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>

    Date and time when the VPC Prefix was created

    +
    updated
    string <date-time>

    Date and time when the VPC Prefix was updated

    +

    Response samples

    Content type
    application/json
    {
    • "id": "0c03ba01-d86b-4a57-a41e-cc359b380a6f",
    • "name": "east-vpc-traffic-net",
    • "siteId": "ea144def-d68f-44c3-9485-4b103fa2686f",
    • "vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "prefix": "192.168.1.0/26",
    • "ipBlockId": "8c1d1a06-90a2-4863-8ee1-6029265b9f0a",
    • "prefixLength": 26,
    • "status": "Ready",
    • "usageStats": {
      },
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Delete VPC Prefix

    Delete a specific VPC Prefix by ID.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Delete a specific VPC Prefix by ID.

    Org must have a Tenant entity. User must have authorization role with TENANT_ADMIN suffix.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    vpcPrefixId
    required
    string <uuid>

    ID of the VPC Prefix

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "source": "nico",
    • "message": "User is not allowed to perform this action",
    • "data": null
    }

    Update VPC Prefix

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    vpcPrefixId
    required
    string <uuid>

    ID of the VPC Prefix

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "source": "nico",
    • "message": "User is not allowed to perform this action",
    • "data": null
    }

    Update VPC Prefix

    Update an existing VPC Prefix

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Update an existing VPC Prefix

    Org must have a Tenant entity. User must have authorization role with TENANT_ADMIN suffix.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    vpcPrefixId
    required
    string <uuid>

    ID of the VPC Prefix

    -
    Request Body schema: application/json
    name
    required
    string [ 2 .. 256 ] characters

    Responses

    Response Schema: application/json
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters

    Name of the VPC Prefix

    -
    siteId
    string <uuid>

    ID of the Site the VPC Prefix belongs to

    -
    vpcId
    string <uuid>

    ID of the VPC the VPC Prefix belongs to

    -
    tenantId
    string <uuid>

    ID of the Tenant the VPC Prefix belongs to

    -
    ipBlockId
    string or null <uuid>

    ID of the IP Block that contains the prefix of the VPC Prefix

    -
    prefix
    string or null

    The network prefix including prefix length in CIDR notation

    -
    prefixLength
    integer [ 8 .. 31 ]

    Length of the prefix. Valid range is 8 to 31, and max usable value depends on prefix length of parent IP Block.

    -
    status
    string (VpcPrefixStatus)
    Enum: "Ready" "Deleting" "Error"

    Status of the VPC Prefix

    -
    object (IpBlockUsageStats)

    Present when query param includeUsageStats=true. IPv4 usage applies interface-based rules (including 2 IPs per Ethernet interface slot); -availablePrefixes reflects /31-sized subdivisions inferred from assigned interface IP addresses.

    -
    availableIPs
    integer <int64>

    Number of IP addresses available in the block

    -
    acquiredIPs
    integer <int64>

    Number of individual IP addresses acquired from the block

    -
    availablePrefixes
    Array of strings

    Example prefixes available to acquire. For IPBlocks this comes from IPAM. -For Subnets and VPC Prefixes with interface-derived usage, at most 10 sample prefixes are returned -(/32 host prefixes for Subnets; /31 prefixes for VPC Prefixes).

    -
    availableSmallestPrefixes
    integer <int64>

    Number of smallest prefixes available to acquire. For VPC Prefix interface-derived usage this is the count of remaining /31 interface slots (half of remaining IPs). -Subnet interface-derived usage leaves this as zero; IPBlocks use IPAM semantics.

    -
    acquiredPrefixes
    integer <int64>

    Number of prefixes acquired from this block

    -
    Array of objects (StatusDetail)

    Details of 20 most recent status changes

    -
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>

    Date and time when the VPC Prefix was created

    -
    updated
    string <date-time>

    Date and time when the VPC Prefix was updated

    -

    Request samples

    Content type
    application/json
    {
    • "name": "east-vpc-traffic-net"
    }

    Response samples

    Content type
    application/json
    {
    • "id": "0c03ba01-d86b-4a57-a41e-cc359b380a6f",
    • "name": "east-vpc-traffic-net",
    • "siteId": "ea144def-d68f-44c3-9485-4b103fa2686f",
    • "vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "prefix": "192.168.1.0/26",
    • "ipBlockId": "8c1d1a06-90a2-4863-8ee1-6029265b9f0a",
    • "prefixLength": 26,
    • "status": "Ready",
    • "usageStats": {
      },
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Subnet

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    vpcPrefixId
    required
    string <uuid>

    ID of the VPC Prefix

    +
    Request Body schema: application/json
    name
    required
    string [ 2 .. 256 ] characters

    Responses

    Response Schema: application/json
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters

    Name of the VPC Prefix

    +
    siteId
    string <uuid>

    ID of the Site the VPC Prefix belongs to

    +
    vpcId
    string <uuid>

    ID of the VPC the VPC Prefix belongs to

    +
    tenantId
    string <uuid>

    ID of the Tenant the VPC Prefix belongs to

    +
    ipBlockId
    string or null <uuid>

    ID of the IP Block that contains the prefix of the VPC Prefix

    +
    prefix
    string or null

    The network prefix including prefix length in CIDR notation

    +
    prefixLength
    integer [ 8 .. 31 ]

    Length of the prefix. Valid range is 8 to 31, and max usable value depends on prefix length of parent IP Block.

    +
    status
    string (VpcPrefixStatus)
    Enum: "Ready" "Deleting" "Error"

    Status of the VPC Prefix

    +
    object (IpBlockUsageStats)

    Present when query param includeUsageStats=true. Prefix and IP usage data is derived by evaluating associated Ethernet interfaces. Each Interface associated with a VPC Prefix consumes a /31 prefix.

    +
    availableIPs
    integer <int64>

    Number of IP addresses available in the block

    +
    acquiredIPs
    integer <int64>

    Number of individual IP addresses acquired from the block

    +
    availablePrefixes
    Array of strings

    Example prefixes available to acquire

    +
    availableSmallestPrefixes
    integer <int64>

    Number of smallest prefixes available to acquire

    +
    acquiredPrefixes
    integer <int64>

    Number of prefixes acquired from this block

    +
    Array of objects (StatusDetail)

    Details of 20 most recent status changes

    +
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>

    Date and time when the VPC Prefix was created

    +
    updated
    string <date-time>

    Date and time when the VPC Prefix was updated

    +

    Request samples

    Content type
    application/json
    {
    • "name": "east-vpc-traffic-net"
    }

    Response samples

    Content type
    application/json
    {
    • "id": "0c03ba01-d86b-4a57-a41e-cc359b380a6f",
    • "name": "east-vpc-traffic-net",
    • "siteId": "ea144def-d68f-44c3-9485-4b103fa2686f",
    • "vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "prefix": "192.168.1.0/26",
    • "ipBlockId": "8c1d1a06-90a2-4863-8ee1-6029265b9f0a",
    • "prefixLength": 26,
    • "status": "Ready",
    • "usageStats": {
      },
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Subnet

    Typical API Call Flow for Tenant
    • ipBlockSize was deprecated in favor of prefixLength and was removed on April 15th, 2023 0:00 UTC. Please use prefixLength instead.
    -

    Retrieve all Subnets

    Retrieve all Subnets

    Retrieve all Subnets for the org

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve all Subnets for the org

    Org must have a Tenant entity. User must have authorization role with TENANT_ADMIN suffix.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    query Parameters
    siteId
    string <uuid>

    Filter subnets by Site, required if vpcId query param is not specified

    -
    vpcId
    string <uuid>

    Filter subnets by VPC

    -
    status
    string

    Filter Subnets by Status

    -
    query
    string

    Search for matches across all Sites. Input will be matched against name, description and status fields

    -
    includeRelation
    string
    Enum: "VPC" "Tenant" "IPv4Block" "IPv6Block"

    Related entity to expand

    -
    includeUsageStats
    boolean

    When true, each Subnet includes IPv4 usageStats using the same JSON shape as IP Block usage counters. Figures account for ethernet interfaces on Instances in this Subnet—one host address per interface plus allowances for gateway and subnet bookkeeping on the / IPv4 allocation. The parent IPv4 IP Block relation may be loaded internally when resolving allocation context.

    -
    pageNumber
    integer >= 1
    Default: 1
    Example: pageNumber=1

    Page number for pagination query

    -
    pageSize
    integer [ 1 .. 100 ]
    Example: pageSize=20

    Page size for pagination query

    -
    orderBy
    string
    Enum: "NAME_ASC" "NAME_DESC" "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC"

    Ordering for pagination query

    -

    Responses

    Response Headers
    X-Pagination
    string
    Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}"

    Pagination result in JSON format

    -
    Response Schema: application/json
    Array
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    description
    string or null
    siteId
    string <uuid>
    vpcId
    string <uuid>
    tenantId
    string <uuid>
    controllerNetworkSegmentId
    string or null <uuid>
    ipv4Prefix
    string or null <ipv4>

    The prefix that gets assigned to the subnet if ipv4 block is chosen

    -
    ipv4BlockId
    string or null <uuid>
    ipv4Gateway
    string or null <ipv4>
    ipv6Prefix
    string or null <ipv6>
    ipv6BlockId
    string or null <uuid>
    ipv6Gateway
    string or null <ipv6>
    mtu
    integer

    Maximum Transmission Unit size in bytes. This property is system-determined and read-only.

    -
    prefixLength
    integer

    Max value depends on prefix length of parent IP Block

    -
    routingType
    string or null
    Enum: "Public" "DatacenterOnly"
    status
    string (SubnetStatus)
    Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error"

    Status values for Subnet objects

    -
    object (IpBlockUsageStats)

    Present when query param includeUsageStats=true. IPv4 counters treat each Ethernet interface as one assigned host plus reserves for gateway and subnet bookkeeping.

    -
    availableIPs
    integer <int64>

    Number of IP addresses available in the block

    -
    acquiredIPs
    integer <int64>

    Number of individual IP addresses acquired from the block

    -
    availablePrefixes
    Array of strings

    Example prefixes available to acquire. For IPBlocks this comes from IPAM. -For Subnets and VPC Prefixes with interface-derived usage, at most 10 sample prefixes are returned -(/32 host prefixes for Subnets; /31 prefixes for VPC Prefixes).

    -
    availableSmallestPrefixes
    integer <int64>

    Number of smallest prefixes available to acquire. For VPC Prefix interface-derived usage this is the count of remaining /31 interface slots (half of remaining IPs). -Subnet interface-derived usage leaves this as zero; IPBlocks use IPAM semantics.

    -
    acquiredPrefixes
    integer <int64>

    Number of prefixes acquired from this block

    -
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>
    Array of objects (Deprecation)
    Array
    attribute
    string or null
    queryParam
    string or null
    endpoint
    string or null
    replacedBy
    string or null
    takeActionBy
    string <date-time>
    notice
    string

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Create Subnet

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    query Parameters
    siteId
    string <uuid>

    Filter subnets by Site, required if vpcId query param is not specified

    +
    vpcId
    string <uuid>

    Filter subnets by VPC

    +
    status
    string

    Filter Subnets by Status

    +
    query
    string

    Search for matches across all Sites. Input will be matched against name, description and status fields

    +
    includeRelation
    string
    Enum: "VPC" "Tenant" "IPv4Block" "IPv6Block"

    Related entity to expand

    +
    includeUsageStats
    boolean

    When true, each Subnet object includes usage statistic 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 Subnets consumes a single IP. In addition, 1 gateway and 1 broadcast IP address is reserved per Subnet.

    +
    pageNumber
    integer >= 1
    Default: 1
    Example: pageNumber=1

    Page number for pagination query

    +
    pageSize
    integer [ 1 .. 100 ]
    Example: pageSize=20

    Page size for pagination query

    +
    orderBy
    string
    Enum: "NAME_ASC" "NAME_DESC" "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC"

    Ordering for pagination query

    +

    Responses

    Response Headers
    X-Pagination
    string
    Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}"

    Pagination result in JSON format

    +
    Response Schema: application/json
    Array
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    description
    string or null
    siteId
    string <uuid>
    vpcId
    string <uuid>
    tenantId
    string <uuid>
    controllerNetworkSegmentId
    string or null <uuid>
    ipv4Prefix
    string or null <ipv4>

    The prefix that gets assigned to the subnet if ipv4 block is chosen

    +
    ipv4BlockId
    string or null <uuid>
    ipv4Gateway
    string or null <ipv4>
    ipv6Prefix
    string or null <ipv6>
    ipv6BlockId
    string or null <uuid>
    ipv6Gateway
    string or null <ipv6>
    mtu
    integer

    Maximum Transmission Unit size in bytes. This property is system-determined and read-only.

    +
    prefixLength
    integer

    Max value depends on prefix length of parent IP Block

    +
    routingType
    string or null
    Enum: "Public" "DatacenterOnly"
    status
    string (SubnetStatus)
    Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error"

    Status values for Subnet objects

    +
    object (IpBlockUsageStats)

    Present when query param includeUsageStats=true. Prefix and IP usage data is derived by evaluating associated Ethernet interfaces. Each Interface associated with a Subnet consumes a single IP. In addition, 1 gateway and 1 broadcast IP address is reserved per Subnet.

    +
    availableIPs
    integer <int64>

    Number of IP addresses available in the block

    +
    acquiredIPs
    integer <int64>

    Number of individual IP addresses acquired from the block

    +
    availablePrefixes
    Array of strings

    Example prefixes available to acquire

    +
    availableSmallestPrefixes
    integer <int64>

    Number of smallest prefixes available to acquire

    +
    acquiredPrefixes
    integer <int64>

    Number of prefixes acquired from this block

    +
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>
    Array of objects (Deprecation)
    Array
    attribute
    string or null
    queryParam
    string or null
    endpoint
    string or null
    replacedBy
    string or null
    takeActionBy
    string <date-time>
    notice
    string

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Create Subnet

    Create a Subnet for the org.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Create a Subnet for the org.

    Org must have a Tenant entity. User must have authorization role with TENANT_ADMIN suffix.

    At least 1 IPv4 IP block or 1 IPv6 IP block must be specified.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    Request Body schema: application/json
    name
    required
    string [ 2 .. 256 ] characters
    description
    string or null
    vpcId
    required
    string <uuid>
    ipv4BlockId
    string or null <uuid>
    ipv6BlockId
    string or null <uuid>
    prefixLength
    required
    integer

    Responses

    Response Schema: application/json
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    description
    string or null
    siteId
    string <uuid>
    vpcId
    string <uuid>
    tenantId
    string <uuid>
    controllerNetworkSegmentId
    string or null <uuid>
    ipv4Prefix
    string or null <ipv4>

    The prefix that gets assigned to the subnet if ipv4 block is chosen

    -
    ipv4BlockId
    string or null <uuid>
    ipv4Gateway
    string or null <ipv4>
    ipv6Prefix
    string or null <ipv6>
    ipv6BlockId
    string or null <uuid>
    ipv6Gateway
    string or null <ipv6>
    mtu
    integer

    Maximum Transmission Unit size in bytes. This property is system-determined and read-only.

    -
    prefixLength
    integer

    Max value depends on prefix length of parent IP Block

    -
    routingType
    string or null
    Enum: "Public" "DatacenterOnly"
    status
    string (SubnetStatus)
    Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error"

    Status values for Subnet objects

    -
    object (IpBlockUsageStats)

    Present when query param includeUsageStats=true. IPv4 counters treat each Ethernet interface as one assigned host plus reserves for gateway and subnet bookkeeping.

    -
    availableIPs
    integer <int64>

    Number of IP addresses available in the block

    -
    acquiredIPs
    integer <int64>

    Number of individual IP addresses acquired from the block

    -
    availablePrefixes
    Array of strings

    Example prefixes available to acquire. For IPBlocks this comes from IPAM. -For Subnets and VPC Prefixes with interface-derived usage, at most 10 sample prefixes are returned -(/32 host prefixes for Subnets; /31 prefixes for VPC Prefixes).

    -
    availableSmallestPrefixes
    integer <int64>

    Number of smallest prefixes available to acquire. For VPC Prefix interface-derived usage this is the count of remaining /31 interface slots (half of remaining IPs). -Subnet interface-derived usage leaves this as zero; IPBlocks use IPAM semantics.

    -
    acquiredPrefixes
    integer <int64>

    Number of prefixes acquired from this block

    -
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>
    Array of objects (Deprecation)
    Array
    attribute
    string or null
    queryParam
    string or null
    endpoint
    string or null
    replacedBy
    string or null
    takeActionBy
    string <date-time>
    notice
    string

    Request samples

    Content type
    application/json
    {
    • "name": "spark-gpu-net",
    • "vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
    • "ipv4BlockId": "8c1d1a06-90a2-4863-8ee1-6029265b9f0a",
    • "prefixLength": 20
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "spark-gpu-net",
    • "siteId": "ea144def-d68f-44c3-9485-4b103fa2686f",
    • "vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "controllerNetworkSegmentId": null,
    • "ipv4Prefix": "202.168.16.0",
    • "ipv4BlockId": "8c1d1a06-90a2-4863-8ee1-6029265b9f0a",
    • "ipv4Gateway": "202.168.0.1",
    • "ipv6Prefix": null,
    • "ipv6BlockId": null,
    • "ipv6Gateway": null,
    • "prefixLength": 20,
    • "routingType": "Public",
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Retrieve Subnet

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    Request Body schema: application/json
    name
    required
    string [ 2 .. 256 ] characters
    description
    string or null
    vpcId
    required
    string <uuid>
    ipv4BlockId
    string or null <uuid>
    ipv6BlockId
    string or null <uuid>
    prefixLength
    required
    integer

    Responses

    Response Schema: application/json
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    description
    string or null
    siteId
    string <uuid>
    vpcId
    string <uuid>
    tenantId
    string <uuid>
    controllerNetworkSegmentId
    string or null <uuid>
    ipv4Prefix
    string or null <ipv4>

    The prefix that gets assigned to the subnet if ipv4 block is chosen

    +
    ipv4BlockId
    string or null <uuid>
    ipv4Gateway
    string or null <ipv4>
    ipv6Prefix
    string or null <ipv6>
    ipv6BlockId
    string or null <uuid>
    ipv6Gateway
    string or null <ipv6>
    mtu
    integer

    Maximum Transmission Unit size in bytes. This property is system-determined and read-only.

    +
    prefixLength
    integer

    Max value depends on prefix length of parent IP Block

    +
    routingType
    string or null
    Enum: "Public" "DatacenterOnly"
    status
    string (SubnetStatus)
    Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error"

    Status values for Subnet objects

    +
    object (IpBlockUsageStats)

    Present when query param includeUsageStats=true. Prefix and IP usage data is derived by evaluating associated Ethernet interfaces. Each Interface associated with a Subnet consumes a single IP. In addition, 1 gateway and 1 broadcast IP address is reserved per Subnet.

    +
    availableIPs
    integer <int64>

    Number of IP addresses available in the block

    +
    acquiredIPs
    integer <int64>

    Number of individual IP addresses acquired from the block

    +
    availablePrefixes
    Array of strings

    Example prefixes available to acquire

    +
    availableSmallestPrefixes
    integer <int64>

    Number of smallest prefixes available to acquire

    +
    acquiredPrefixes
    integer <int64>

    Number of prefixes acquired from this block

    +
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>
    Array of objects (Deprecation)
    Array
    attribute
    string or null
    queryParam
    string or null
    endpoint
    string or null
    replacedBy
    string or null
    takeActionBy
    string <date-time>
    notice
    string

    Request samples

    Content type
    application/json
    {
    • "name": "spark-gpu-net",
    • "vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
    • "ipv4BlockId": "8c1d1a06-90a2-4863-8ee1-6029265b9f0a",
    • "prefixLength": 20
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "spark-gpu-net",
    • "siteId": "ea144def-d68f-44c3-9485-4b103fa2686f",
    • "vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "controllerNetworkSegmentId": null,
    • "ipv4Prefix": "202.168.16.0",
    • "ipv4BlockId": "8c1d1a06-90a2-4863-8ee1-6029265b9f0a",
    • "ipv4Gateway": "202.168.0.1",
    • "ipv6Prefix": null,
    • "ipv6BlockId": null,
    • "ipv6Gateway": null,
    • "prefixLength": 20,
    • "routingType": "Public",
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Retrieve Subnet

    Retrieve a specific Subnet

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve a specific Subnet

    Org must have a Tenant entity. User must have authorization role with TENANT_ADMIN suffix.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    subnetId
    required
    string <uuid>

    ID of the Subnet

    -
    query Parameters
    includeRelation
    string
    Enum: "VPC" "Tenant" "IPv4Block" "IPv6Block"

    Related entity to expand

    -
    includeUsageStats
    boolean

    When true, each Subnet includes IPv4 usageStats using the same JSON shape as IP Block usage counters. Figures account for ethernet interfaces on Instances in this Subnet—one host address per interface plus allowances for gateway and subnet bookkeeping on the / IPv4 allocation. The parent IPv4 IP Block relation may be loaded internally when resolving allocation context.

    -

    Responses

    Response Schema: application/json
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    description
    string or null
    siteId
    string <uuid>
    vpcId
    string <uuid>
    tenantId
    string <uuid>
    controllerNetworkSegmentId
    string or null <uuid>
    ipv4Prefix
    string or null <ipv4>

    The prefix that gets assigned to the subnet if ipv4 block is chosen

    -
    ipv4BlockId
    string or null <uuid>
    ipv4Gateway
    string or null <ipv4>
    ipv6Prefix
    string or null <ipv6>
    ipv6BlockId
    string or null <uuid>
    ipv6Gateway
    string or null <ipv6>
    mtu
    integer

    Maximum Transmission Unit size in bytes. This property is system-determined and read-only.

    -
    prefixLength
    integer

    Max value depends on prefix length of parent IP Block

    -
    routingType
    string or null
    Enum: "Public" "DatacenterOnly"
    status
    string (SubnetStatus)
    Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error"

    Status values for Subnet objects

    -
    object (IpBlockUsageStats)

    Present when query param includeUsageStats=true. IPv4 counters treat each Ethernet interface as one assigned host plus reserves for gateway and subnet bookkeeping.

    -
    availableIPs
    integer <int64>

    Number of IP addresses available in the block

    -
    acquiredIPs
    integer <int64>

    Number of individual IP addresses acquired from the block

    -
    availablePrefixes
    Array of strings

    Example prefixes available to acquire. For IPBlocks this comes from IPAM. -For Subnets and VPC Prefixes with interface-derived usage, at most 10 sample prefixes are returned -(/32 host prefixes for Subnets; /31 prefixes for VPC Prefixes).

    -
    availableSmallestPrefixes
    integer <int64>

    Number of smallest prefixes available to acquire. For VPC Prefix interface-derived usage this is the count of remaining /31 interface slots (half of remaining IPs). -Subnet interface-derived usage leaves this as zero; IPBlocks use IPAM semantics.

    -
    acquiredPrefixes
    integer <int64>

    Number of prefixes acquired from this block

    -
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>
    Array of objects (Deprecation)
    Array
    attribute
    string or null
    queryParam
    string or null
    endpoint
    string or null
    replacedBy
    string or null
    takeActionBy
    string <date-time>
    notice
    string

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "spark-gpu-net",
    • "siteId": "ea144def-d68f-44c3-9485-4b103fa2686f",
    • "vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "controllerNetworkSegmentId": "abe7b0e8-67db-4e89-903e-fc4f2bd7f034",
    • "ipv4Prefix": "202.168.16.0",
    • "ipv4BlockId": "8c1d1a06-90a2-4863-8ee1-6029265b9f0a",
    • "ipv4Gateway": "202.168.0.1",
    • "ipv6Prefix": null,
    • "ipv6BlockId": null,
    • "ipv6Gateway": null,
    • "prefixLength": 20,
    • "routingType": "Public",
    • "status": "Ready",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Delete Subnet

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    subnetId
    required
    string <uuid>

    ID of the Subnet

    +
    query Parameters
    includeRelation
    string
    Enum: "VPC" "Tenant" "IPv4Block" "IPv6Block"

    Related entity to expand

    +
    includeUsageStats
    boolean

    When true, each Subnet object includes usage statistic 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 Subnets consumes a single IP. In addition, 1 gateway and 1 broadcast IP address is reserved per Subnet.

    +

    Responses

    Response Schema: application/json
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    description
    string or null
    siteId
    string <uuid>
    vpcId
    string <uuid>
    tenantId
    string <uuid>
    controllerNetworkSegmentId
    string or null <uuid>
    ipv4Prefix
    string or null <ipv4>

    The prefix that gets assigned to the subnet if ipv4 block is chosen

    +
    ipv4BlockId
    string or null <uuid>
    ipv4Gateway
    string or null <ipv4>
    ipv6Prefix
    string or null <ipv6>
    ipv6BlockId
    string or null <uuid>
    ipv6Gateway
    string or null <ipv6>
    mtu
    integer

    Maximum Transmission Unit size in bytes. This property is system-determined and read-only.

    +
    prefixLength
    integer

    Max value depends on prefix length of parent IP Block

    +
    routingType
    string or null
    Enum: "Public" "DatacenterOnly"
    status
    string (SubnetStatus)
    Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error"

    Status values for Subnet objects

    +
    object (IpBlockUsageStats)

    Present when query param includeUsageStats=true. Prefix and IP usage data is derived by evaluating associated Ethernet interfaces. Each Interface associated with a Subnet consumes a single IP. In addition, 1 gateway and 1 broadcast IP address is reserved per Subnet.

    +
    availableIPs
    integer <int64>

    Number of IP addresses available in the block

    +
    acquiredIPs
    integer <int64>

    Number of individual IP addresses acquired from the block

    +
    availablePrefixes
    Array of strings

    Example prefixes available to acquire

    +
    availableSmallestPrefixes
    integer <int64>

    Number of smallest prefixes available to acquire

    +
    acquiredPrefixes
    integer <int64>

    Number of prefixes acquired from this block

    +
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>
    Array of objects (Deprecation)
    Array
    attribute
    string or null
    queryParam
    string or null
    endpoint
    string or null
    replacedBy
    string or null
    takeActionBy
    string <date-time>
    notice
    string

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "spark-gpu-net",
    • "siteId": "ea144def-d68f-44c3-9485-4b103fa2686f",
    • "vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "controllerNetworkSegmentId": "abe7b0e8-67db-4e89-903e-fc4f2bd7f034",
    • "ipv4Prefix": "202.168.16.0",
    • "ipv4BlockId": "8c1d1a06-90a2-4863-8ee1-6029265b9f0a",
    • "ipv4Gateway": "202.168.0.1",
    • "ipv6Prefix": null,
    • "ipv6BlockId": null,
    • "ipv6Gateway": null,
    • "prefixLength": 20,
    • "routingType": "Public",
    • "status": "Ready",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Delete Subnet

    Delete a specific Subnet by ID.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Delete a specific Subnet by ID.

    Org must have a Tenant entity. User must have authorization role with TENANT_ADMIN suffix.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    subnetId
    required
    string <uuid>

    ID of the Subnet

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "source": "nico",
    • "message": "User is not allowed to perform this action",
    • "data": null
    }

    Update Subnet

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    subnetId
    required
    string <uuid>

    ID of the Subnet

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "source": "nico",
    • "message": "User is not allowed to perform this action",
    • "data": null
    }

    Update Subnet

    Update an existing Subnet

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Update an existing Subnet

    Org must have a Tenant entity. User must have authorization role with TENANT_ADMIN suffix.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    subnetId
    required
    string <uuid>

    ID of the Subnet

    -
    Request Body schema: application/json
    name
    required
    string [ 2 .. 256 ] characters
    description
    string or null

    Responses

    Response Schema: application/json
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    description
    string or null
    siteId
    string <uuid>
    vpcId
    string <uuid>
    tenantId
    string <uuid>
    controllerNetworkSegmentId
    string or null <uuid>
    ipv4Prefix
    string or null <ipv4>

    The prefix that gets assigned to the subnet if ipv4 block is chosen

    -
    ipv4BlockId
    string or null <uuid>
    ipv4Gateway
    string or null <ipv4>
    ipv6Prefix
    string or null <ipv6>
    ipv6BlockId
    string or null <uuid>
    ipv6Gateway
    string or null <ipv6>
    mtu
    integer

    Maximum Transmission Unit size in bytes. This property is system-determined and read-only.

    -
    prefixLength
    integer

    Max value depends on prefix length of parent IP Block

    -
    routingType
    string or null
    Enum: "Public" "DatacenterOnly"
    status
    string (SubnetStatus)
    Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error"

    Status values for Subnet objects

    -
    object (IpBlockUsageStats)

    Present when query param includeUsageStats=true. IPv4 counters treat each Ethernet interface as one assigned host plus reserves for gateway and subnet bookkeeping.

    -
    availableIPs
    integer <int64>

    Number of IP addresses available in the block

    -
    acquiredIPs
    integer <int64>

    Number of individual IP addresses acquired from the block

    -
    availablePrefixes
    Array of strings

    Example prefixes available to acquire. For IPBlocks this comes from IPAM. -For Subnets and VPC Prefixes with interface-derived usage, at most 10 sample prefixes are returned -(/32 host prefixes for Subnets; /31 prefixes for VPC Prefixes).

    -
    availableSmallestPrefixes
    integer <int64>

    Number of smallest prefixes available to acquire. For VPC Prefix interface-derived usage this is the count of remaining /31 interface slots (half of remaining IPs). -Subnet interface-derived usage leaves this as zero; IPBlocks use IPAM semantics.

    -
    acquiredPrefixes
    integer <int64>

    Number of prefixes acquired from this block

    -
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>
    Array of objects (Deprecation)
    Array
    attribute
    string or null
    queryParam
    string or null
    endpoint
    string or null
    replacedBy
    string or null
    takeActionBy
    string <date-time>
    notice
    string

    Request samples

    Content type
    application/json
    {
    • "name": "spark-gpu-subnet",
    • "description": "Subnet for dedicated GPU nodes"
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "spark-gpu-subnet",
    • "description": "Subnet for dedicated GPU nodes",
    • "siteId": "ea144def-d68f-44c3-9485-4b103fa2686f",
    • "vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "controllerNetworkSegmentId": null,
    • "ipv4Prefix": "212.168.0.250",
    • "ipv4BlockId": "8c1d1a06-90a2-4863-8ee1-6029265b9f0a",
    • "ipv4Gateway": "202.168.0.1",
    • "ipv6Prefix": null,
    • "ipv6BlockId": null,
    • "ipv6Gateway": null,
    • "prefixLength": 20,
    • "routingType": "Public",
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Expected Machine

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    subnetId
    required
    string <uuid>

    ID of the Subnet

    +
    Request Body schema: application/json
    name
    required
    string [ 2 .. 256 ] characters
    description
    string or null

    Responses

    Response Schema: application/json
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    description
    string or null
    siteId
    string <uuid>
    vpcId
    string <uuid>
    tenantId
    string <uuid>
    controllerNetworkSegmentId
    string or null <uuid>
    ipv4Prefix
    string or null <ipv4>

    The prefix that gets assigned to the subnet if ipv4 block is chosen

    +
    ipv4BlockId
    string or null <uuid>
    ipv4Gateway
    string or null <ipv4>
    ipv6Prefix
    string or null <ipv6>
    ipv6BlockId
    string or null <uuid>
    ipv6Gateway
    string or null <ipv6>
    mtu
    integer

    Maximum Transmission Unit size in bytes. This property is system-determined and read-only.

    +
    prefixLength
    integer

    Max value depends on prefix length of parent IP Block

    +
    routingType
    string or null
    Enum: "Public" "DatacenterOnly"
    status
    string (SubnetStatus)
    Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error"

    Status values for Subnet objects

    +
    object (IpBlockUsageStats)

    Present when query param includeUsageStats=true. Prefix and IP usage data is derived by evaluating associated Ethernet interfaces. Each Interface associated with a Subnet consumes a single IP. In addition, 1 gateway and 1 broadcast IP address is reserved per Subnet.

    +
    availableIPs
    integer <int64>

    Number of IP addresses available in the block

    +
    acquiredIPs
    integer <int64>

    Number of individual IP addresses acquired from the block

    +
    availablePrefixes
    Array of strings

    Example prefixes available to acquire

    +
    availableSmallestPrefixes
    integer <int64>

    Number of smallest prefixes available to acquire

    +
    acquiredPrefixes
    integer <int64>

    Number of prefixes acquired from this block

    +
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>
    Array of objects (Deprecation)
    Array
    attribute
    string or null
    queryParam
    string or null
    endpoint
    string or null
    replacedBy
    string or null
    takeActionBy
    string <date-time>
    notice
    string

    Request samples

    Content type
    application/json
    {
    • "name": "spark-gpu-subnet",
    • "description": "Subnet for dedicated GPU nodes"
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "spark-gpu-subnet",
    • "description": "Subnet for dedicated GPU nodes",
    • "siteId": "ea144def-d68f-44c3-9485-4b103fa2686f",
    • "vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "controllerNetworkSegmentId": null,
    • "ipv4Prefix": "212.168.0.250",
    • "ipv4BlockId": "8c1d1a06-90a2-4863-8ee1-6029265b9f0a",
    • "ipv4Gateway": "202.168.0.1",
    • "ipv6Prefix": null,
    • "ipv6BlockId": null,
    • "ipv6Gateway": null,
    • "prefixLength": 20,
    • "routingType": "Public",
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Expected Machine

    Expected Machine identifies a Machine that is expected to be discovered at a Site. Infrastructure Providers can pre-register Expected Machines using BMC credentials and serial numbers to help with Machine discovery and ingestion.

    -

    Create Expected Machine

    Create Expected Machine

    Create an Expected Machine to pre-register Machines expected to be discovered at a Site.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Create an Expected Machine to pre-register Machines expected to be discovered at a Site.

    Org must have an Infrastructure Provider entity. User must have authorization role with PROVIDER_ADMIN suffix.

    Alternatively, Tenant Admins with TargetedInstanceCreation capability can also create Expected Machines if they have an account with the Site's Infrastructure Provider.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    Request Body schema: application/json
    required

    Expected Machine creation request

    -
    siteId
    required
    string <uuid>

    ID of the site the Expected Machine belongs to

    -
    bmcMacAddress
    required
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Machine's BMC (Baseboard Management Controller)

    -
    defaultBmcUsername
    string or null <= 20 characters

    Username for accessing the Expected Machine's BMC

    -
    defaultBmcPassword
    string or null <= 50 characters

    Password for accessing the Expected Machine's BMC

    -
    chassisSerialNumber
    required
    string [ 1 .. 100 ] characters

    Serial number of the Expected Machine's chassis

    -
    fallbackDPUSerialNumbers
    Array of strings or null

    Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)

    -
    skuId
    string or null

    Optional ID of the SKU to associate with this Expected Machine

    -
    rackId
    string or null

    Optional rack identifier for this component

    -
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    -
    name
    string or null

    Display name for this component

    -
    manufacturer
    string or null

    Manufacturer of this component

    -
    model
    string or null

    Model of this component

    -
    description
    string or null

    Description of this component

    -
    firmwareVersion
    string or null

    Firmware version of this component

    -
    slotId
    integer or null <int32>

    Slot ID within the rack

    -
    trayIdx
    integer or null <int32>

    Tray index within the rack

    -
    hostId
    integer or null <int32>

    Host ID within the tray

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Machines

    -
    property name*
    additional property
    string

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier for the Expected Machine

    -
    siteId
    string <uuid>

    ID of the site the Expected Machine belongs to

    -
    bmcMacAddress
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Machine's BMC (Baseboard Management Controller)

    -
    chassisSerialNumber
    string

    Serial number of the Expected Machine's chassis

    -
    fallbackDPUSerialNumbers
    Array of strings

    Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)

    -
    skuId
    string or null

    Optional ID of the SKU associated with this Expected Machine

    -
    object (Sku)

    SKU information for this Expected Machine (populated when includeRelation=Sku is specified)

    -
    id
    string

    Unique identifier for the SKU

    -
    siteId
    string <uuid>

    ID of the Site this SKU belongs to

    -
    deviceType
    string or null

    Optional device type identifier (e.g. "gpu", "cpu", "storage")

    -
    associatedMachineIds
    Array of strings

    List of machine IDs associated with this SKU

    -
    object (SkuComponents)

    Hardware components of this SKU

    -
    Array of objects (SkuCpu)

    CPU components

    -
    Array of objects (SkuGpu)

    GPU components

    -
    Array of objects (SkuMemory)

    Memory components

    -
    Array of objects (SkuStorage)

    Storage components

    -
    object (SkuChassis)

    Chassis component

    -
    Array of objects (SkuEthernetDevice)

    Ethernet device components

    -
    Array of objects (SkuInfinibandDevice)

    Infiniband device components

    -
    Array of objects (SkuTpm)

    TPM components

    -
    created
    string <date-time>

    ISO 8601 datetime when the SKU was created

    -
    updated
    string <date-time>

    ISO 8601 datetime when the SKU was last updated

    -
    machineId
    string or null

    Optional ID of the Machine associated with this Expected Machine

    -
    object (MachineSummary)

    Machine information for this Expected Machine (populated when includeRelation=Machine is specified)

    -
    id
    string

    Unique ID of Machine

    -
    controllerMachineId
    string

    ID of the Machine at Site, now same as the primary ID

    -
    controllerMachineType
    string or null

    Denotes architecture (x86 vs ARM) of the Machine

    -
    hwSkuDeviceType
    string or null

    SKU derived device type of the machine, e.g. cpu, gpu, cache, storage, etc.

    -
    vendor
    string or null

    Name of the vendor of the Machine

    -
    productName
    string or null

    Product name of the Machine

    -
    maintenanceMessage
    string or null

    If the Machine is in maintenance mode, this message will typically describe the reason and how long it is expected to be in maintenance

    -
    status
    string (MachineStatus)
    Enum: "Initializing" "Ready" "Reset" "Maintenance" "InUse" "Error" "Decommissioned" "Unknown"

    Status values for Machine objects

    -
    rackId
    string or null

    Optional rack identifier for this component

    -
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    -
    name
    string or null

    Display name for this component

    -
    manufacturer
    string or null

    Manufacturer of this component

    -
    model
    string or null

    Model of this component

    -
    description
    string or null

    Description of this component

    -
    firmwareVersion
    string or null

    Firmware version of this component

    -
    slotId
    integer or null <int32>

    Slot ID within the rack

    -
    trayIdx
    integer or null <int32>

    Tray index within the rack

    -
    hostId
    integer or null <int32>

    Host ID within the tray

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Machines

    -
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Machine was created

    -
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Machine was last updated

    -

    Request samples

    Content type
    application/json
    {
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "bmcMacAddress": "00:1A:2B:3C:4D:5E",
    • "defaultBmcUsername": "admin",
    • "defaultBmcPassword": "password123",
    • "chassisSerialNumber": "CHASSIS-12345",
    • "fallbackDPUSerialNumbers": [
      ],
    • "labels": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "bmcMacAddress": "00:1A:2B:3C:4D:5E",
    • "bmcIpAddress": "192.168.1.100",
    • "chassisSerialNumber": "CHASSIS-12345",
    • "fallbackDPUSerialNumbers": [
      ],
    • "skuId": "lenovo.sr650v2.cpu.1",
    • "machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
    • "rackId": "rack-01",
    • "manufacturer": "Lenovo",
    • "labels": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Retrieve all Expected Machines

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    Request Body schema: application/json
    required

    Expected Machine creation request

    +
    siteId
    required
    string <uuid>

    ID of the site the Expected Machine belongs to

    +
    bmcMacAddress
    required
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Machine's BMC (Baseboard Management Controller)

    +
    defaultBmcUsername
    string or null <= 20 characters

    Username for accessing the Expected Machine's BMC

    +
    defaultBmcPassword
    string or null <= 50 characters

    Password for accessing the Expected Machine's BMC

    +
    chassisSerialNumber
    required
    string [ 1 .. 100 ] characters

    Serial number of the Expected Machine's chassis

    +
    fallbackDPUSerialNumbers
    Array of strings or null

    Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)

    +
    skuId
    string or null

    Optional ID of the SKU to associate with this Expected Machine

    +
    rackId
    string or null

    Optional rack identifier for this component

    +
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    +
    name
    string or null

    Display name for this component

    +
    manufacturer
    string or null

    Manufacturer of this component

    +
    model
    string or null

    Model of this component

    +
    description
    string or null

    Description of this component

    +
    firmwareVersion
    string or null

    Firmware version of this component

    +
    slotId
    integer or null <int32>

    Slot ID within the rack

    +
    trayIdx
    integer or null <int32>

    Tray index within the rack

    +
    hostId
    integer or null <int32>

    Host ID within the tray

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Machines

    +
    property name*
    additional property
    string

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier for the Expected Machine

    +
    siteId
    string <uuid>

    ID of the site the Expected Machine belongs to

    +
    bmcMacAddress
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Machine's BMC (Baseboard Management Controller)

    +
    chassisSerialNumber
    string

    Serial number of the Expected Machine's chassis

    +
    fallbackDPUSerialNumbers
    Array of strings

    Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)

    +
    skuId
    string or null

    Optional ID of the SKU associated with this Expected Machine

    +
    object (Sku)

    SKU information for this Expected Machine (populated when includeRelation=Sku is specified)

    +
    id
    string

    Unique identifier for the SKU

    +
    siteId
    string <uuid>

    ID of the Site this SKU belongs to

    +
    deviceType
    string or null

    Optional device type identifier (e.g. "gpu", "cpu", "storage")

    +
    associatedMachineIds
    Array of strings

    List of machine IDs associated with this SKU

    +
    object (SkuComponents)

    Hardware components of this SKU

    +
    Array of objects (SkuCpu)

    CPU components

    +
    Array of objects (SkuGpu)

    GPU components

    +
    Array of objects (SkuMemory)

    Memory components

    +
    Array of objects (SkuStorage)

    Storage components

    +
    object (SkuChassis)

    Chassis component

    +
    Array of objects (SkuEthernetDevice)

    Ethernet device components

    +
    Array of objects (SkuInfinibandDevice)

    Infiniband device components

    +
    Array of objects (SkuTpm)

    TPM components

    +
    created
    string <date-time>

    ISO 8601 datetime when the SKU was created

    +
    updated
    string <date-time>

    ISO 8601 datetime when the SKU was last updated

    +
    machineId
    string or null

    Optional ID of the Machine associated with this Expected Machine

    +
    object (MachineSummary)

    Machine information for this Expected Machine (populated when includeRelation=Machine is specified)

    +
    id
    string

    Unique ID of Machine

    +
    controllerMachineId
    string

    ID of the Machine at Site, now same as the primary ID

    +
    controllerMachineType
    string or null

    Denotes architecture (x86 vs ARM) of the Machine

    +
    hwSkuDeviceType
    string or null

    SKU derived device type of the machine, e.g. cpu, gpu, cache, storage, etc.

    +
    vendor
    string or null

    Name of the vendor of the Machine

    +
    productName
    string or null

    Product name of the Machine

    +
    maintenanceMessage
    string or null

    If the Machine is in maintenance mode, this message will typically describe the reason and how long it is expected to be in maintenance

    +
    status
    string (MachineStatus)
    Enum: "Initializing" "Ready" "Reset" "Maintenance" "InUse" "Error" "Decommissioned" "Unknown"

    Status values for Machine objects

    +
    rackId
    string or null

    Optional rack identifier for this component

    +
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    +
    name
    string or null

    Display name for this component

    +
    manufacturer
    string or null

    Manufacturer of this component

    +
    model
    string or null

    Model of this component

    +
    description
    string or null

    Description of this component

    +
    firmwareVersion
    string or null

    Firmware version of this component

    +
    slotId
    integer or null <int32>

    Slot ID within the rack

    +
    trayIdx
    integer or null <int32>

    Tray index within the rack

    +
    hostId
    integer or null <int32>

    Host ID within the tray

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Machines

    +
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Machine was created

    +
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Machine was last updated

    +

    Request samples

    Content type
    application/json
    {
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "bmcMacAddress": "00:1A:2B:3C:4D:5E",
    • "defaultBmcUsername": "admin",
    • "defaultBmcPassword": "password123",
    • "chassisSerialNumber": "CHASSIS-12345",
    • "fallbackDPUSerialNumbers": [
      ],
    • "labels": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "bmcMacAddress": "00:1A:2B:3C:4D:5E",
    • "bmcIpAddress": "192.168.1.100",
    • "chassisSerialNumber": "CHASSIS-12345",
    • "fallbackDPUSerialNumbers": [
      ],
    • "skuId": "lenovo.sr650v2.cpu.1",
    • "machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
    • "rackId": "rack-01",
    • "manufacturer": "Lenovo",
    • "labels": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Retrieve all Expected Machines

    Retrieve all Expected Machines.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve all Expected Machines.

    Org must have an Infrastructure Provider entity. User must have authorization role with PROVIDER_ADMIN or PROVIDER_VIEWER suffix.

    Alternatively, Tenant Admins with TargetedInstanceCreation capability can also retrieve Expected Machines if they have an account with the Site's Infrastructure Provider (siteId query parameter is required for Tenants).

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    query Parameters
    siteId
    string <uuid>

    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

    Page number for pagination query

    -
    pageSize
    integer [ 1 .. 100 ]
    Example: pageSize=20

    Page size for pagination query

    -
    orderBy
    string
    Enum: "BMC_MAC_ADDRESS_ASC" "BMC_MAC_ADDRESS_DESC" "CHASSIS_SERIAL_NUMBER_ASC" "CHASSIS_SERIAL_NUMBER_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC"

    Ordering for pagination query

    -

    Responses

    Response Headers
    X-Pagination
    string
    Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}"

    Pagination result in JSON format

    -
    Response Schema: application/json
    Array
    id
    string <uuid>

    Unique identifier for the Expected Machine

    -
    siteId
    string <uuid>

    ID of the site the Expected Machine belongs to

    -
    bmcMacAddress
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Machine's BMC (Baseboard Management Controller)

    -
    chassisSerialNumber
    string

    Serial number of the Expected Machine's chassis

    -
    fallbackDPUSerialNumbers
    Array of strings

    Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)

    -
    skuId
    string or null

    Optional ID of the SKU associated with this Expected Machine

    -
    object (Sku)

    SKU information for this Expected Machine (populated when includeRelation=Sku is specified)

    -
    id
    string

    Unique identifier for the SKU

    -
    siteId
    string <uuid>

    ID of the Site this SKU belongs to

    -
    deviceType
    string or null

    Optional device type identifier (e.g. "gpu", "cpu", "storage")

    -
    associatedMachineIds
    Array of strings

    List of machine IDs associated with this SKU

    -
    object (SkuComponents)

    Hardware components of this SKU

    -
    created
    string <date-time>

    ISO 8601 datetime when the SKU was created

    -
    updated
    string <date-time>

    ISO 8601 datetime when the SKU was last updated

    -
    machineId
    string or null

    Optional ID of the Machine associated with this Expected Machine

    -
    object (MachineSummary)

    Machine information for this Expected Machine (populated when includeRelation=Machine is specified)

    -
    id
    string

    Unique ID of Machine

    -
    controllerMachineId
    string

    ID of the Machine at Site, now same as the primary ID

    -
    controllerMachineType
    string or null

    Denotes architecture (x86 vs ARM) of the Machine

    -
    hwSkuDeviceType
    string or null

    SKU derived device type of the machine, e.g. cpu, gpu, cache, storage, etc.

    -
    vendor
    string or null

    Name of the vendor of the Machine

    -
    productName
    string or null

    Product name of the Machine

    -
    maintenanceMessage
    string or null

    If the Machine is in maintenance mode, this message will typically describe the reason and how long it is expected to be in maintenance

    -
    status
    string (MachineStatus)
    Enum: "Initializing" "Ready" "Reset" "Maintenance" "InUse" "Error" "Decommissioned" "Unknown"

    Status values for Machine objects

    -
    rackId
    string or null

    Optional rack identifier for this component

    -
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    -
    name
    string or null

    Display name for this component

    -
    manufacturer
    string or null

    Manufacturer of this component

    -
    model
    string or null

    Model of this component

    -
    description
    string or null

    Description of this component

    -
    firmwareVersion
    string or null

    Firmware version of this component

    -
    slotId
    integer or null <int32>

    Slot ID within the rack

    -
    trayIdx
    integer or null <int32>

    Tray index within the rack

    -
    hostId
    integer or null <int32>

    Host ID within the tray

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Machines

    -
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Machine was created

    -
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Machine was last updated

    -

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Retrieve Expected Machine

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    query Parameters
    siteId
    string <uuid>

    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

    Page number for pagination query

    +
    pageSize
    integer [ 1 .. 100 ]
    Example: pageSize=20

    Page size for pagination query

    +
    orderBy
    string
    Enum: "BMC_MAC_ADDRESS_ASC" "BMC_MAC_ADDRESS_DESC" "CHASSIS_SERIAL_NUMBER_ASC" "CHASSIS_SERIAL_NUMBER_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC"

    Ordering for pagination query

    +

    Responses

    Response Headers
    X-Pagination
    string
    Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}"

    Pagination result in JSON format

    +
    Response Schema: application/json
    Array
    id
    string <uuid>

    Unique identifier for the Expected Machine

    +
    siteId
    string <uuid>

    ID of the site the Expected Machine belongs to

    +
    bmcMacAddress
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Machine's BMC (Baseboard Management Controller)

    +
    chassisSerialNumber
    string

    Serial number of the Expected Machine's chassis

    +
    fallbackDPUSerialNumbers
    Array of strings

    Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)

    +
    skuId
    string or null

    Optional ID of the SKU associated with this Expected Machine

    +
    object (Sku)

    SKU information for this Expected Machine (populated when includeRelation=Sku is specified)

    +
    id
    string

    Unique identifier for the SKU

    +
    siteId
    string <uuid>

    ID of the Site this SKU belongs to

    +
    deviceType
    string or null

    Optional device type identifier (e.g. "gpu", "cpu", "storage")

    +
    associatedMachineIds
    Array of strings

    List of machine IDs associated with this SKU

    +
    object (SkuComponents)

    Hardware components of this SKU

    +
    created
    string <date-time>

    ISO 8601 datetime when the SKU was created

    +
    updated
    string <date-time>

    ISO 8601 datetime when the SKU was last updated

    +
    machineId
    string or null

    Optional ID of the Machine associated with this Expected Machine

    +
    object (MachineSummary)

    Machine information for this Expected Machine (populated when includeRelation=Machine is specified)

    +
    id
    string

    Unique ID of Machine

    +
    controllerMachineId
    string

    ID of the Machine at Site, now same as the primary ID

    +
    controllerMachineType
    string or null

    Denotes architecture (x86 vs ARM) of the Machine

    +
    hwSkuDeviceType
    string or null

    SKU derived device type of the machine, e.g. cpu, gpu, cache, storage, etc.

    +
    vendor
    string or null

    Name of the vendor of the Machine

    +
    productName
    string or null

    Product name of the Machine

    +
    maintenanceMessage
    string or null

    If the Machine is in maintenance mode, this message will typically describe the reason and how long it is expected to be in maintenance

    +
    status
    string (MachineStatus)
    Enum: "Initializing" "Ready" "Reset" "Maintenance" "InUse" "Error" "Decommissioned" "Unknown"

    Status values for Machine objects

    +
    rackId
    string or null

    Optional rack identifier for this component

    +
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    +
    name
    string or null

    Display name for this component

    +
    manufacturer
    string or null

    Manufacturer of this component

    +
    model
    string or null

    Model of this component

    +
    description
    string or null

    Description of this component

    +
    firmwareVersion
    string or null

    Firmware version of this component

    +
    slotId
    integer or null <int32>

    Slot ID within the rack

    +
    trayIdx
    integer or null <int32>

    Tray index within the rack

    +
    hostId
    integer or null <int32>

    Host ID within the tray

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Machines

    +
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Machine was created

    +
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Machine was last updated

    +

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Retrieve Expected Machine

    Retrieve a specific Expected Machine by ID.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve a specific Expected Machine by ID.

    Org must have an Infrastructure Provider entity. User must have authorization role with PROVIDER_ADMIN or PROVIDER_VIEWER suffix.

    Alternatively, Tenant Admins with TargetedInstanceCreation capability can also retrieve Expected Machines if they have an account with the Site's Infrastructure Provider.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    expectedMachineId
    required
    string

    ID of the Expected Machine

    -
    query Parameters
    includeRelation
    string
    Enum: "Site" "Sku"

    Related entity to expand

    -

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier for the Expected Machine

    -
    siteId
    string <uuid>

    ID of the site the Expected Machine belongs to

    -
    bmcMacAddress
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Machine's BMC (Baseboard Management Controller)

    -
    chassisSerialNumber
    string

    Serial number of the Expected Machine's chassis

    -
    fallbackDPUSerialNumbers
    Array of strings

    Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)

    -
    skuId
    string or null

    Optional ID of the SKU associated with this Expected Machine

    -
    object (Sku)

    SKU information for this Expected Machine (populated when includeRelation=Sku is specified)

    -
    id
    string

    Unique identifier for the SKU

    -
    siteId
    string <uuid>

    ID of the Site this SKU belongs to

    -
    deviceType
    string or null

    Optional device type identifier (e.g. "gpu", "cpu", "storage")

    -
    associatedMachineIds
    Array of strings

    List of machine IDs associated with this SKU

    -
    object (SkuComponents)

    Hardware components of this SKU

    -
    Array of objects (SkuCpu)

    CPU components

    -
    Array of objects (SkuGpu)

    GPU components

    -
    Array of objects (SkuMemory)

    Memory components

    -
    Array of objects (SkuStorage)

    Storage components

    -
    object (SkuChassis)

    Chassis component

    -
    Array of objects (SkuEthernetDevice)

    Ethernet device components

    -
    Array of objects (SkuInfinibandDevice)

    Infiniband device components

    -
    Array of objects (SkuTpm)

    TPM components

    -
    created
    string <date-time>

    ISO 8601 datetime when the SKU was created

    -
    updated
    string <date-time>

    ISO 8601 datetime when the SKU was last updated

    -
    machineId
    string or null

    Optional ID of the Machine associated with this Expected Machine

    -
    object (MachineSummary)

    Machine information for this Expected Machine (populated when includeRelation=Machine is specified)

    -
    id
    string

    Unique ID of Machine

    -
    controllerMachineId
    string

    ID of the Machine at Site, now same as the primary ID

    -
    controllerMachineType
    string or null

    Denotes architecture (x86 vs ARM) of the Machine

    -
    hwSkuDeviceType
    string or null

    SKU derived device type of the machine, e.g. cpu, gpu, cache, storage, etc.

    -
    vendor
    string or null

    Name of the vendor of the Machine

    -
    productName
    string or null

    Product name of the Machine

    -
    maintenanceMessage
    string or null

    If the Machine is in maintenance mode, this message will typically describe the reason and how long it is expected to be in maintenance

    -
    status
    string (MachineStatus)
    Enum: "Initializing" "Ready" "Reset" "Maintenance" "InUse" "Error" "Decommissioned" "Unknown"

    Status values for Machine objects

    -
    rackId
    string or null

    Optional rack identifier for this component

    -
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    -
    name
    string or null

    Display name for this component

    -
    manufacturer
    string or null

    Manufacturer of this component

    -
    model
    string or null

    Model of this component

    -
    description
    string or null

    Description of this component

    -
    firmwareVersion
    string or null

    Firmware version of this component

    -
    slotId
    integer or null <int32>

    Slot ID within the rack

    -
    trayIdx
    integer or null <int32>

    Tray index within the rack

    -
    hostId
    integer or null <int32>

    Host ID within the tray

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Machines

    -
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Machine was created

    -
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Machine was last updated

    -

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "bmcMacAddress": "00:1A:2B:3C:4D:5E",
    • "bmcIpAddress": "192.168.1.100",
    • "chassisSerialNumber": "CHASSIS-12345",
    • "fallbackDPUSerialNumbers": [
      ],
    • "skuId": "lenovo.sr650v2.cpu.1",
    • "machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
    • "rackId": "rack-01",
    • "manufacturer": "Lenovo",
    • "labels": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Update Expected Machine

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    expectedMachineId
    required
    string

    ID of the Expected Machine

    +
    query Parameters
    includeRelation
    string
    Enum: "Site" "Sku"

    Related entity to expand

    +

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier for the Expected Machine

    +
    siteId
    string <uuid>

    ID of the site the Expected Machine belongs to

    +
    bmcMacAddress
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Machine's BMC (Baseboard Management Controller)

    +
    chassisSerialNumber
    string

    Serial number of the Expected Machine's chassis

    +
    fallbackDPUSerialNumbers
    Array of strings

    Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)

    +
    skuId
    string or null

    Optional ID of the SKU associated with this Expected Machine

    +
    object (Sku)

    SKU information for this Expected Machine (populated when includeRelation=Sku is specified)

    +
    id
    string

    Unique identifier for the SKU

    +
    siteId
    string <uuid>

    ID of the Site this SKU belongs to

    +
    deviceType
    string or null

    Optional device type identifier (e.g. "gpu", "cpu", "storage")

    +
    associatedMachineIds
    Array of strings

    List of machine IDs associated with this SKU

    +
    object (SkuComponents)

    Hardware components of this SKU

    +
    Array of objects (SkuCpu)

    CPU components

    +
    Array of objects (SkuGpu)

    GPU components

    +
    Array of objects (SkuMemory)

    Memory components

    +
    Array of objects (SkuStorage)

    Storage components

    +
    object (SkuChassis)

    Chassis component

    +
    Array of objects (SkuEthernetDevice)

    Ethernet device components

    +
    Array of objects (SkuInfinibandDevice)

    Infiniband device components

    +
    Array of objects (SkuTpm)

    TPM components

    +
    created
    string <date-time>

    ISO 8601 datetime when the SKU was created

    +
    updated
    string <date-time>

    ISO 8601 datetime when the SKU was last updated

    +
    machineId
    string or null

    Optional ID of the Machine associated with this Expected Machine

    +
    object (MachineSummary)

    Machine information for this Expected Machine (populated when includeRelation=Machine is specified)

    +
    id
    string

    Unique ID of Machine

    +
    controllerMachineId
    string

    ID of the Machine at Site, now same as the primary ID

    +
    controllerMachineType
    string or null

    Denotes architecture (x86 vs ARM) of the Machine

    +
    hwSkuDeviceType
    string or null

    SKU derived device type of the machine, e.g. cpu, gpu, cache, storage, etc.

    +
    vendor
    string or null

    Name of the vendor of the Machine

    +
    productName
    string or null

    Product name of the Machine

    +
    maintenanceMessage
    string or null

    If the Machine is in maintenance mode, this message will typically describe the reason and how long it is expected to be in maintenance

    +
    status
    string (MachineStatus)
    Enum: "Initializing" "Ready" "Reset" "Maintenance" "InUse" "Error" "Decommissioned" "Unknown"

    Status values for Machine objects

    +
    rackId
    string or null

    Optional rack identifier for this component

    +
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    +
    name
    string or null

    Display name for this component

    +
    manufacturer
    string or null

    Manufacturer of this component

    +
    model
    string or null

    Model of this component

    +
    description
    string or null

    Description of this component

    +
    firmwareVersion
    string or null

    Firmware version of this component

    +
    slotId
    integer or null <int32>

    Slot ID within the rack

    +
    trayIdx
    integer or null <int32>

    Tray index within the rack

    +
    hostId
    integer or null <int32>

    Host ID within the tray

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Machines

    +
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Machine was created

    +
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Machine was last updated

    +

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "bmcMacAddress": "00:1A:2B:3C:4D:5E",
    • "bmcIpAddress": "192.168.1.100",
    • "chassisSerialNumber": "CHASSIS-12345",
    • "fallbackDPUSerialNumbers": [
      ],
    • "skuId": "lenovo.sr650v2.cpu.1",
    • "machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
    • "rackId": "rack-01",
    • "manufacturer": "Lenovo",
    • "labels": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Update Expected Machine

    Update an existing Expected Machine by ID.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Update an existing Expected Machine by ID.

    Org must have an Infrastructure Provider entity. User must have authorization role with PROVIDER_ADMIN suffix.

    Infrastructure Provider must own the Expected Machine.

    Alternatively, Tenant Admins with TargetedInstanceCreation capability can also update Expected Machines if they have an account with the Site's Infrastructure Provider.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    expectedMachineId
    required
    string

    ID of the Expected Machine

    -
    Request Body schema: application/json
    required

    Expected Machine update request

    -
    id
    string or null <uuid>
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    expectedMachineId
    required
    string

    ID of the Expected Machine

    +
    Request Body schema: application/json
    required

    Expected Machine update request

    +
    id
    string or null <uuid>

    ID of the Expected Machine to update.

    +" class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

    ID of the Expected Machine to update.

    Optional for individual Expected Machine update (ignored if provided, ID from URL path is used).

    Required for batch update operations.

    -
    bmcMacAddress
    string or null^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Machine's BMC (Baseboard Management Controller)

    -
    defaultBmcUsername
    string or null <= 20 characters

    Username for accessing the Expected Machine's BMC

    -
    defaultBmcPassword
    string or null <= 50 characters

    Password for accessing the Expected Machine's BMC

    -
    chassisSerialNumber
    string or null [ 1 .. 100 ] characters

    Serial number of the Expected Machine's chassis

    -
    fallbackDPUSerialNumbers
    Array of strings or null

    Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)

    -
    skuId
    string or null

    Optional ID of the SKU to associate with this Expected Machine

    -
    rackId
    string or null

    Optional rack identifier for this component

    -
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    -
    name
    string or null

    Display name for this component

    -
    manufacturer
    string or null

    Manufacturer of this component

    -
    model
    string or null

    Model of this component

    -
    description
    string or null

    Description of this component

    -
    firmwareVersion
    string or null

    Firmware version of this component

    -
    slotId
    integer or null <int32>

    Slot ID within the rack

    -
    trayIdx
    integer or null <int32>

    Tray index within the rack

    -
    hostId
    integer or null <int32>

    Host ID within the tray

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Machines

    -
    property name*
    additional property
    string

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier for the Expected Machine

    -
    siteId
    string <uuid>

    ID of the site the Expected Machine belongs to

    -
    bmcMacAddress
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Machine's BMC (Baseboard Management Controller)

    -
    chassisSerialNumber
    string

    Serial number of the Expected Machine's chassis

    -
    fallbackDPUSerialNumbers
    Array of strings

    Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)

    -
    skuId
    string or null

    Optional ID of the SKU associated with this Expected Machine

    -
    object (Sku)

    SKU information for this Expected Machine (populated when includeRelation=Sku is specified)

    -
    id
    string

    Unique identifier for the SKU

    -
    siteId
    string <uuid>

    ID of the Site this SKU belongs to

    -
    deviceType
    string or null

    Optional device type identifier (e.g. "gpu", "cpu", "storage")

    -
    associatedMachineIds
    Array of strings

    List of machine IDs associated with this SKU

    -
    object (SkuComponents)

    Hardware components of this SKU

    -
    Array of objects (SkuCpu)

    CPU components

    -
    Array of objects (SkuGpu)

    GPU components

    -
    Array of objects (SkuMemory)

    Memory components

    -
    Array of objects (SkuStorage)

    Storage components

    -
    object (SkuChassis)

    Chassis component

    -
    Array of objects (SkuEthernetDevice)

    Ethernet device components

    -
    Array of objects (SkuInfinibandDevice)

    Infiniband device components

    -
    Array of objects (SkuTpm)

    TPM components

    -
    created
    string <date-time>

    ISO 8601 datetime when the SKU was created

    -
    updated
    string <date-time>

    ISO 8601 datetime when the SKU was last updated

    -
    machineId
    string or null

    Optional ID of the Machine associated with this Expected Machine

    -
    object (MachineSummary)

    Machine information for this Expected Machine (populated when includeRelation=Machine is specified)

    -
    id
    string

    Unique ID of Machine

    -
    controllerMachineId
    string

    ID of the Machine at Site, now same as the primary ID

    -
    controllerMachineType
    string or null

    Denotes architecture (x86 vs ARM) of the Machine

    -
    hwSkuDeviceType
    string or null

    SKU derived device type of the machine, e.g. cpu, gpu, cache, storage, etc.

    -
    vendor
    string or null

    Name of the vendor of the Machine

    -
    productName
    string or null

    Product name of the Machine

    -
    maintenanceMessage
    string or null

    If the Machine is in maintenance mode, this message will typically describe the reason and how long it is expected to be in maintenance

    -
    status
    string (MachineStatus)
    Enum: "Initializing" "Ready" "Reset" "Maintenance" "InUse" "Error" "Decommissioned" "Unknown"

    Status values for Machine objects

    -
    rackId
    string or null

    Optional rack identifier for this component

    -
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    -
    name
    string or null

    Display name for this component

    -
    manufacturer
    string or null

    Manufacturer of this component

    -
    model
    string or null

    Model of this component

    -
    description
    string or null

    Description of this component

    -
    firmwareVersion
    string or null

    Firmware version of this component

    -
    slotId
    integer or null <int32>

    Slot ID within the rack

    -
    trayIdx
    integer or null <int32>

    Tray index within the rack

    -
    hostId
    integer or null <int32>

    Host ID within the tray

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Machines

    -
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Machine was created

    -
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Machine was last updated

    -

    Request samples

    Content type
    application/json
    {
    • "defaultBmcUsername": "newadmin",
    • "defaultBmcPassword": "newpassword123",
    • "chassisSerialNumber": "CHASSIS-54321",
    • "labels": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "bmcMacAddress": "00:1A:2B:3C:4D:5E",
    • "bmcIpAddress": "192.168.1.100",
    • "chassisSerialNumber": "CHASSIS-12345",
    • "fallbackDPUSerialNumbers": [
      ],
    • "skuId": "lenovo.sr650v2.cpu.1",
    • "machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
    • "rackId": "rack-01",
    • "manufacturer": "Lenovo",
    • "labels": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Delete Expected Machine

    		bmcMacAddress
    string or null^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Machine's BMC (Baseboard Management Controller)

    +
    defaultBmcUsername
    string or null <= 20 characters

    Username for accessing the Expected Machine's BMC

    +
    defaultBmcPassword
    string or null <= 50 characters

    Password for accessing the Expected Machine's BMC

    +
    chassisSerialNumber
    string or null [ 1 .. 100 ] characters

    Serial number of the Expected Machine's chassis

    +
    fallbackDPUSerialNumbers
    Array of strings or null

    Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)

    +
    skuId
    string or null

    Optional ID of the SKU to associate with this Expected Machine

    +
    rackId
    string or null

    Optional rack identifier for this component

    +
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    +
    name
    string or null

    Display name for this component

    +
    manufacturer
    string or null

    Manufacturer of this component

    +
    model
    string or null

    Model of this component

    +
    description
    string or null

    Description of this component

    +
    firmwareVersion
    string or null

    Firmware version of this component

    +
    slotId
    integer or null <int32>

    Slot ID within the rack

    +
    trayIdx
    integer or null <int32>

    Tray index within the rack

    +
    hostId
    integer or null <int32>

    Host ID within the tray

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Machines

    +
    property name*
    additional property
    string

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier for the Expected Machine

    +
    siteId
    string <uuid>

    ID of the site the Expected Machine belongs to

    +
    bmcMacAddress
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Machine's BMC (Baseboard Management Controller)

    +
    chassisSerialNumber
    string

    Serial number of the Expected Machine's chassis

    +
    fallbackDPUSerialNumbers
    Array of strings

    Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)

    +
    skuId
    string or null

    Optional ID of the SKU associated with this Expected Machine

    +
    object (Sku)

    SKU information for this Expected Machine (populated when includeRelation=Sku is specified)

    +
    id
    string

    Unique identifier for the SKU

    +
    siteId
    string <uuid>

    ID of the Site this SKU belongs to

    +
    deviceType
    string or null

    Optional device type identifier (e.g. "gpu", "cpu", "storage")

    +
    associatedMachineIds
    Array of strings

    List of machine IDs associated with this SKU

    +
    object (SkuComponents)

    Hardware components of this SKU

    +
    Array of objects (SkuCpu)

    CPU components

    +
    Array of objects (SkuGpu)

    GPU components

    +
    Array of objects (SkuMemory)

    Memory components

    +
    Array of objects (SkuStorage)

    Storage components

    +
    object (SkuChassis)

    Chassis component

    +
    Array of objects (SkuEthernetDevice)

    Ethernet device components

    +
    Array of objects (SkuInfinibandDevice)

    Infiniband device components

    +
    Array of objects (SkuTpm)

    TPM components

    +
    created
    string <date-time>

    ISO 8601 datetime when the SKU was created

    +
    updated
    string <date-time>

    ISO 8601 datetime when the SKU was last updated

    +
    machineId
    string or null

    Optional ID of the Machine associated with this Expected Machine

    +
    object (MachineSummary)

    Machine information for this Expected Machine (populated when includeRelation=Machine is specified)

    +
    id
    string

    Unique ID of Machine

    +
    controllerMachineId
    string

    ID of the Machine at Site, now same as the primary ID

    +
    controllerMachineType
    string or null

    Denotes architecture (x86 vs ARM) of the Machine

    +
    hwSkuDeviceType
    string or null

    SKU derived device type of the machine, e.g. cpu, gpu, cache, storage, etc.

    +
    vendor
    string or null

    Name of the vendor of the Machine

    +
    productName
    string or null

    Product name of the Machine

    +
    maintenanceMessage
    string or null

    If the Machine is in maintenance mode, this message will typically describe the reason and how long it is expected to be in maintenance

    +
    status
    string (MachineStatus)
    Enum: "Initializing" "Ready" "Reset" "Maintenance" "InUse" "Error" "Decommissioned" "Unknown"

    Status values for Machine objects

    +
    rackId
    string or null

    Optional rack identifier for this component

    +
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    +
    name
    string or null

    Display name for this component

    +
    manufacturer
    string or null

    Manufacturer of this component

    +
    model
    string or null

    Model of this component

    +
    description
    string or null

    Description of this component

    +
    firmwareVersion
    string or null

    Firmware version of this component

    +
    slotId
    integer or null <int32>

    Slot ID within the rack

    +
    trayIdx
    integer or null <int32>

    Tray index within the rack

    +
    hostId
    integer or null <int32>

    Host ID within the tray

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Machines

    +
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Machine was created

    +
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Machine was last updated

    +

    Request samples

    Content type
    application/json
    {
    • "defaultBmcUsername": "newadmin",
    • "defaultBmcPassword": "newpassword123",
    • "chassisSerialNumber": "CHASSIS-54321",
    • "labels": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "bmcMacAddress": "00:1A:2B:3C:4D:5E",
    • "bmcIpAddress": "192.168.1.100",
    • "chassisSerialNumber": "CHASSIS-12345",
    • "fallbackDPUSerialNumbers": [
      ],
    • "skuId": "lenovo.sr650v2.cpu.1",
    • "machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
    • "rackId": "rack-01",
    • "manufacturer": "Lenovo",
    • "labels": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Delete Expected Machine

    Delete an existing Expected Machine by ID.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Delete an existing Expected Machine by ID.

    Org must have an Infrastructure Provider entity. User must have authorization role with PROVIDER_ADMIN suffix.

    Infrastructure Provider must own the Expected Machine.

    Alternatively, Tenant Admins with TargetedInstanceCreation capability can also delete Expected Machines if they have an account with the Site's Infrastructure Provider.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    expectedMachineId
    required
    string

    ID of the Expected Machine

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "source": "nico",
    • "message": "Error validating request data",
    • "data": {
      }
    }

    Batch Create Expected Machines

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    expectedMachineId
    required
    string

    ID of the Expected Machine

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "source": "nico",
    • "message": "Error validating request data",
    • "data": {
      }
    }

    Batch Create Expected Machines

    Create multiple Expected Machines in a single request. All machines must belong to the same site.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Create multiple Expected Machines in a single request. All machines must belong to the same site.

    Org must have an Infrastructure Provider entity. User must have authorization role with PROVIDER_ADMIN suffix.

    Alternatively, Tenant Admins with TargetedInstanceCreation capability can also create Expected Machines if they have an account with the Site's Infrastructure Provider.

    Maximum batch size: 100 Expected Machines per request.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    Request Body schema: application/json
    required

    Array of Expected Machine creation requests

    -
    Array ([ 1 .. 100 ] items)
    siteId
    required
    string <uuid>

    ID of the site the Expected Machine belongs to

    -
    bmcMacAddress
    required
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Machine's BMC (Baseboard Management Controller)

    -
    defaultBmcUsername
    string or null <= 20 characters

    Username for accessing the Expected Machine's BMC

    -
    defaultBmcPassword
    string or null <= 50 characters

    Password for accessing the Expected Machine's BMC

    -
    chassisSerialNumber
    required
    string [ 1 .. 100 ] characters

    Serial number of the Expected Machine's chassis

    -
    fallbackDPUSerialNumbers
    Array of strings or null

    Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)

    -
    skuId
    string or null

    Optional ID of the SKU to associate with this Expected Machine

    -
    rackId
    string or null

    Optional rack identifier for this component

    -
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    -
    name
    string or null

    Display name for this component

    -
    manufacturer
    string or null

    Manufacturer of this component

    -
    model
    string or null

    Model of this component

    -
    description
    string or null

    Description of this component

    -
    firmwareVersion
    string or null

    Firmware version of this component

    -
    slotId
    integer or null <int32>

    Slot ID within the rack

    -
    trayIdx
    integer or null <int32>

    Tray index within the rack

    -
    hostId
    integer or null <int32>

    Host ID within the tray

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Machines

    -
    property name*
    additional property
    string

    Responses

    Response Schema: application/json
    Array
    id
    string <uuid>

    Unique identifier for the Expected Machine

    -
    siteId
    string <uuid>

    ID of the site the Expected Machine belongs to

    -
    bmcMacAddress
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Machine's BMC (Baseboard Management Controller)

    -
    chassisSerialNumber
    string

    Serial number of the Expected Machine's chassis

    -
    fallbackDPUSerialNumbers
    Array of strings

    Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)

    -
    skuId
    string or null

    Optional ID of the SKU associated with this Expected Machine

    -
    object (Sku)

    SKU information for this Expected Machine (populated when includeRelation=Sku is specified)

    -
    id
    string

    Unique identifier for the SKU

    -
    siteId
    string <uuid>

    ID of the Site this SKU belongs to

    -
    deviceType
    string or null

    Optional device type identifier (e.g. "gpu", "cpu", "storage")

    -
    associatedMachineIds
    Array of strings

    List of machine IDs associated with this SKU

    -
    object (SkuComponents)

    Hardware components of this SKU

    -
    created
    string <date-time>

    ISO 8601 datetime when the SKU was created

    -
    updated
    string <date-time>

    ISO 8601 datetime when the SKU was last updated

    -
    machineId
    string or null

    Optional ID of the Machine associated with this Expected Machine

    -
    object (MachineSummary)

    Machine information for this Expected Machine (populated when includeRelation=Machine is specified)

    -
    id
    string

    Unique ID of Machine

    -
    controllerMachineId
    string

    ID of the Machine at Site, now same as the primary ID

    -
    controllerMachineType
    string or null

    Denotes architecture (x86 vs ARM) of the Machine

    -
    hwSkuDeviceType
    string or null

    SKU derived device type of the machine, e.g. cpu, gpu, cache, storage, etc.

    -
    vendor
    string or null

    Name of the vendor of the Machine

    -
    productName
    string or null

    Product name of the Machine

    -
    maintenanceMessage
    string or null

    If the Machine is in maintenance mode, this message will typically describe the reason and how long it is expected to be in maintenance

    -
    status
    string (MachineStatus)
    Enum: "Initializing" "Ready" "Reset" "Maintenance" "InUse" "Error" "Decommissioned" "Unknown"

    Status values for Machine objects

    -
    rackId
    string or null

    Optional rack identifier for this component

    -
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    -
    name
    string or null

    Display name for this component

    -
    manufacturer
    string or null

    Manufacturer of this component

    -
    model
    string or null

    Model of this component

    -
    description
    string or null

    Description of this component

    -
    firmwareVersion
    string or null

    Firmware version of this component

    -
    slotId
    integer or null <int32>

    Slot ID within the rack

    -
    trayIdx
    integer or null <int32>

    Tray index within the rack

    -
    hostId
    integer or null <int32>

    Host ID within the tray

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Machines

    -
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Machine was created

    -
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Machine was last updated

    -

    Request samples

    Content type
    application/json
    [
    • {
      },
    • {
      }
    ]

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Batch Update Expected Machines

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    Request Body schema: application/json
    required

    Array of Expected Machine creation requests

    +
    Array ([ 1 .. 100 ] items)
    siteId
    required
    string <uuid>

    ID of the site the Expected Machine belongs to

    +
    bmcMacAddress
    required
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Machine's BMC (Baseboard Management Controller)

    +
    defaultBmcUsername
    string or null <= 20 characters

    Username for accessing the Expected Machine's BMC

    +
    defaultBmcPassword
    string or null <= 50 characters

    Password for accessing the Expected Machine's BMC

    +
    chassisSerialNumber
    required
    string [ 1 .. 100 ] characters

    Serial number of the Expected Machine's chassis

    +
    fallbackDPUSerialNumbers
    Array of strings or null

    Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)

    +
    skuId
    string or null

    Optional ID of the SKU to associate with this Expected Machine

    +
    rackId
    string or null

    Optional rack identifier for this component

    +
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    +
    name
    string or null

    Display name for this component

    +
    manufacturer
    string or null

    Manufacturer of this component

    +
    model
    string or null

    Model of this component

    +
    description
    string or null

    Description of this component

    +
    firmwareVersion
    string or null

    Firmware version of this component

    +
    slotId
    integer or null <int32>

    Slot ID within the rack

    +
    trayIdx
    integer or null <int32>

    Tray index within the rack

    +
    hostId
    integer or null <int32>

    Host ID within the tray

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Machines

    +
    property name*
    additional property
    string

    Responses

    Response Schema: application/json
    Array
    id
    string <uuid>

    Unique identifier for the Expected Machine

    +
    siteId
    string <uuid>

    ID of the site the Expected Machine belongs to

    +
    bmcMacAddress
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Machine's BMC (Baseboard Management Controller)

    +
    chassisSerialNumber
    string

    Serial number of the Expected Machine's chassis

    +
    fallbackDPUSerialNumbers
    Array of strings

    Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)

    +
    skuId
    string or null

    Optional ID of the SKU associated with this Expected Machine

    +
    object (Sku)

    SKU information for this Expected Machine (populated when includeRelation=Sku is specified)

    +
    id
    string

    Unique identifier for the SKU

    +
    siteId
    string <uuid>

    ID of the Site this SKU belongs to

    +
    deviceType
    string or null

    Optional device type identifier (e.g. "gpu", "cpu", "storage")

    +
    associatedMachineIds
    Array of strings

    List of machine IDs associated with this SKU

    +
    object (SkuComponents)

    Hardware components of this SKU

    +
    created
    string <date-time>

    ISO 8601 datetime when the SKU was created

    +
    updated
    string <date-time>

    ISO 8601 datetime when the SKU was last updated

    +
    machineId
    string or null

    Optional ID of the Machine associated with this Expected Machine

    +
    object (MachineSummary)

    Machine information for this Expected Machine (populated when includeRelation=Machine is specified)

    +
    id
    string

    Unique ID of Machine

    +
    controllerMachineId
    string

    ID of the Machine at Site, now same as the primary ID

    +
    controllerMachineType
    string or null

    Denotes architecture (x86 vs ARM) of the Machine

    +
    hwSkuDeviceType
    string or null

    SKU derived device type of the machine, e.g. cpu, gpu, cache, storage, etc.

    +
    vendor
    string or null

    Name of the vendor of the Machine

    +
    productName
    string or null

    Product name of the Machine

    +
    maintenanceMessage
    string or null

    If the Machine is in maintenance mode, this message will typically describe the reason and how long it is expected to be in maintenance

    +
    status
    string (MachineStatus)
    Enum: "Initializing" "Ready" "Reset" "Maintenance" "InUse" "Error" "Decommissioned" "Unknown"

    Status values for Machine objects

    +
    rackId
    string or null

    Optional rack identifier for this component

    +
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    +
    name
    string or null

    Display name for this component

    +
    manufacturer
    string or null

    Manufacturer of this component

    +
    model
    string or null

    Model of this component

    +
    description
    string or null

    Description of this component

    +
    firmwareVersion
    string or null

    Firmware version of this component

    +
    slotId
    integer or null <int32>

    Slot ID within the rack

    +
    trayIdx
    integer or null <int32>

    Tray index within the rack

    +
    hostId
    integer or null <int32>

    Host ID within the tray

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Machines

    +
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Machine was created

    +
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Machine was last updated

    +

    Request samples

    Content type
    application/json
    [
    • {
      },
    • {
      }
    ]

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Batch Update Expected Machines

    Update multiple Expected Machines in a single request. All machines must belong to the same site.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Update multiple Expected Machines in a single request. All machines must belong to the same site.

    Org must have an Infrastructure Provider entity. User must have authorization role with PROVIDER_ADMIN suffix.

    Infrastructure Provider must own the Expected Machines.

    Alternatively, Tenant Admins with TargetedInstanceCreation capability can also update Expected Machines if they have an account with the Site's Infrastructure Provider.

    Maximum batch size: 100 Expected Machines per request.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    Request Body schema: application/json
    required

    Array of Expected Machine update requests

    -
    Array ([ 1 .. 100 ] items)
    id
    string or null <uuid>
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    Request Body schema: application/json
    required

    Array of Expected Machine update requests

    +
    Array ([ 1 .. 100 ] items)
    id
    string or null <uuid>

    ID of the Expected Machine to update.

    +" class="sc-iKGpAq sc-cCYyou dXXcln cFvDiF">

    ID of the Expected Machine to update.

    Optional for individual Expected Machine update (ignored if provided, ID from URL path is used).

    Required for batch update operations.

    -
    bmcMacAddress
    string or null^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Machine's BMC (Baseboard Management Controller)

    -
    defaultBmcUsername
    string or null <= 20 characters

    Username for accessing the Expected Machine's BMC

    -
    defaultBmcPassword
    string or null <= 50 characters

    Password for accessing the Expected Machine's BMC

    -
    chassisSerialNumber
    string or null [ 1 .. 100 ] characters

    Serial number of the Expected Machine's chassis

    -
    fallbackDPUSerialNumbers
    Array of strings or null

    Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)

    -
    skuId
    string or null

    Optional ID of the SKU to associate with this Expected Machine

    -
    rackId
    string or null

    Optional rack identifier for this component

    -
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    -
    name
    string or null

    Display name for this component

    -
    manufacturer
    string or null

    Manufacturer of this component

    -
    model
    string or null

    Model of this component

    -
    description
    string or null

    Description of this component

    -
    firmwareVersion
    string or null

    Firmware version of this component

    -
    slotId
    integer or null <int32>

    Slot ID within the rack

    -
    trayIdx
    integer or null <int32>

    Tray index within the rack

    -
    hostId
    integer or null <int32>

    Host ID within the tray

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Machines

    -
    property name*
    additional property
    string

    Responses

    Response Schema: application/json
    Array
    id
    string <uuid>

    Unique identifier for the Expected Machine

    -
    siteId
    string <uuid>

    ID of the site the Expected Machine belongs to

    -
    bmcMacAddress
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Machine's BMC (Baseboard Management Controller)

    -
    chassisSerialNumber
    string

    Serial number of the Expected Machine's chassis

    -
    fallbackDPUSerialNumbers
    Array of strings

    Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)

    -
    skuId
    string or null

    Optional ID of the SKU associated with this Expected Machine

    -
    object (Sku)

    SKU information for this Expected Machine (populated when includeRelation=Sku is specified)

    -
    id
    string

    Unique identifier for the SKU

    -
    siteId
    string <uuid>

    ID of the Site this SKU belongs to

    -
    deviceType
    string or null

    Optional device type identifier (e.g. "gpu", "cpu", "storage")

    -
    associatedMachineIds
    Array of strings

    List of machine IDs associated with this SKU

    -
    object (SkuComponents)

    Hardware components of this SKU

    -
    created
    string <date-time>

    ISO 8601 datetime when the SKU was created

    -
    updated
    string <date-time>

    ISO 8601 datetime when the SKU was last updated

    -
    machineId
    string or null

    Optional ID of the Machine associated with this Expected Machine

    -
    object (MachineSummary)

    Machine information for this Expected Machine (populated when includeRelation=Machine is specified)

    -
    id
    string

    Unique ID of Machine

    -
    controllerMachineId
    string

    ID of the Machine at Site, now same as the primary ID

    -
    controllerMachineType
    string or null

    Denotes architecture (x86 vs ARM) of the Machine

    -
    hwSkuDeviceType
    string or null

    SKU derived device type of the machine, e.g. cpu, gpu, cache, storage, etc.

    -
    vendor
    string or null

    Name of the vendor of the Machine

    -
    productName
    string or null

    Product name of the Machine

    -
    maintenanceMessage
    string or null

    If the Machine is in maintenance mode, this message will typically describe the reason and how long it is expected to be in maintenance

    -
    status
    string (MachineStatus)
    Enum: "Initializing" "Ready" "Reset" "Maintenance" "InUse" "Error" "Decommissioned" "Unknown"

    Status values for Machine objects

    -
    rackId
    string or null

    Optional rack identifier for this component

    -
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    -
    name
    string or null

    Display name for this component

    -
    manufacturer
    string or null

    Manufacturer of this component

    -
    model
    string or null

    Model of this component

    -
    description
    string or null

    Description of this component

    -
    firmwareVersion
    string or null

    Firmware version of this component

    -
    slotId
    integer or null <int32>

    Slot ID within the rack

    -
    trayIdx
    integer or null <int32>

    Tray index within the rack

    -
    hostId
    integer or null <int32>

    Host ID within the tray

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Machines

    -
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Machine was created

    -
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Machine was last updated

    -

    Request samples

    Content type
    application/json
    [
    • {
      },
    • {
      }
    ]

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Expected Power Shelf

    		bmcMacAddress
    string or null^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Machine's BMC (Baseboard Management Controller)

    +
    defaultBmcUsername
    string or null <= 20 characters

    Username for accessing the Expected Machine's BMC

    +
    defaultBmcPassword
    string or null <= 50 characters

    Password for accessing the Expected Machine's BMC

    +
    chassisSerialNumber
    string or null [ 1 .. 100 ] characters

    Serial number of the Expected Machine's chassis

    +
    fallbackDPUSerialNumbers
    Array of strings or null

    Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)

    +
    skuId
    string or null

    Optional ID of the SKU to associate with this Expected Machine

    +
    rackId
    string or null

    Optional rack identifier for this component

    +
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    +
    name
    string or null

    Display name for this component

    +
    manufacturer
    string or null

    Manufacturer of this component

    +
    model
    string or null

    Model of this component

    +
    description
    string or null

    Description of this component

    +
    firmwareVersion
    string or null

    Firmware version of this component

    +
    slotId
    integer or null <int32>

    Slot ID within the rack

    +
    trayIdx
    integer or null <int32>

    Tray index within the rack

    +
    hostId
    integer or null <int32>

    Host ID within the tray

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Machines

    +
    property name*
    additional property
    string

    Responses

    Response Schema: application/json
    Array
    id
    string <uuid>

    Unique identifier for the Expected Machine

    +
    siteId
    string <uuid>

    ID of the site the Expected Machine belongs to

    +
    bmcMacAddress
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Machine's BMC (Baseboard Management Controller)

    +
    chassisSerialNumber
    string

    Serial number of the Expected Machine's chassis

    +
    fallbackDPUSerialNumbers
    Array of strings

    Serial numbers of the Expected Machine's fallback DPUs (Data Processing Units)

    +
    skuId
    string or null

    Optional ID of the SKU associated with this Expected Machine

    +
    object (Sku)

    SKU information for this Expected Machine (populated when includeRelation=Sku is specified)

    +
    id
    string

    Unique identifier for the SKU

    +
    siteId
    string <uuid>

    ID of the Site this SKU belongs to

    +
    deviceType
    string or null

    Optional device type identifier (e.g. "gpu", "cpu", "storage")

    +
    associatedMachineIds
    Array of strings

    List of machine IDs associated with this SKU

    +
    object (SkuComponents)

    Hardware components of this SKU

    +
    created
    string <date-time>

    ISO 8601 datetime when the SKU was created

    +
    updated
    string <date-time>

    ISO 8601 datetime when the SKU was last updated

    +
    machineId
    string or null

    Optional ID of the Machine associated with this Expected Machine

    +
    object (MachineSummary)

    Machine information for this Expected Machine (populated when includeRelation=Machine is specified)

    +
    id
    string

    Unique ID of Machine

    +
    controllerMachineId
    string

    ID of the Machine at Site, now same as the primary ID

    +
    controllerMachineType
    string or null

    Denotes architecture (x86 vs ARM) of the Machine

    +
    hwSkuDeviceType
    string or null

    SKU derived device type of the machine, e.g. cpu, gpu, cache, storage, etc.

    +
    vendor
    string or null

    Name of the vendor of the Machine

    +
    productName
    string or null

    Product name of the Machine

    +
    maintenanceMessage
    string or null

    If the Machine is in maintenance mode, this message will typically describe the reason and how long it is expected to be in maintenance

    +
    status
    string (MachineStatus)
    Enum: "Initializing" "Ready" "Reset" "Maintenance" "InUse" "Error" "Decommissioned" "Unknown"

    Status values for Machine objects

    +
    rackId
    string or null

    Optional rack identifier for this component

    +
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    +
    name
    string or null

    Display name for this component

    +
    manufacturer
    string or null

    Manufacturer of this component

    +
    model
    string or null

    Model of this component

    +
    description
    string or null

    Description of this component

    +
    firmwareVersion
    string or null

    Firmware version of this component

    +
    slotId
    integer or null <int32>

    Slot ID within the rack

    +
    trayIdx
    integer or null <int32>

    Tray index within the rack

    +
    hostId
    integer or null <int32>

    Host ID within the tray

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Machines

    +
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Machine was created

    +
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Machine was last updated

    +

    Request samples

    Content type
    application/json
    [
    • {
      },
    • {
      }
    ]

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Expected Power Shelf

    Expected Power Shelf identifies a Power Shelf that is expected to be discovered at a Site. Infrastructure Providers can pre-register Expected Power Shelves using BMC credentials and serial numbers to help with Power Shelf discovery and ingestion.

    -

    Create Expected Power Shelf

    Create Expected Power Shelf

    Create an Expected Power Shelf to pre-register power shelves expected to be discovered at a Site.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Create an Expected Power Shelf to pre-register power shelves expected to be discovered at a Site.

    Org must have an Infrastructure Provider entity. User must have authorization role with PROVIDER_ADMIN suffix.

    Alternatively, Tenant Admins with TargetedInstanceCreation capability can also create Expected Power Shelves if they have an account with the Site's Infrastructure Provider.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    Request Body schema: application/json
    required

    Expected Power Shelf creation request

    -
    siteId
    required
    string <uuid>

    ID of the site the Expected Power Shelf belongs to

    -
    bmcMacAddress
    required
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Power Shelf's BMC (Baseboard Management Controller)

    -
    defaultBmcUsername
    string or null <= 16 characters

    Username for accessing the Expected Power Shelf's BMC

    -
    defaultBmcPassword
    string or null <= 20 characters

    Password for accessing the Expected Power Shelf's BMC

    -
    shelfSerialNumber
    required
    string [ 1 .. 32 ] characters

    Serial number of the Expected Power Shelf

    -
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    -
    rackId
    string or null

    Optional rack identifier for this component

    -
    name
    string or null

    Display name for this component

    -
    manufacturer
    string or null

    Manufacturer of this component

    -
    model
    string or null

    Model of this component

    -
    description
    string or null

    Description of this component

    -
    firmwareVersion
    string or null

    Firmware version of this component

    -
    slotId
    integer or null <int32>

    Slot ID within the rack

    -
    trayIdx
    integer or null <int32>

    Tray index within the rack

    -
    hostId
    integer or null <int32>

    Host ID within the tray

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Power Shelves

    -
    property name*
    additional property
    string

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier for the Expected Power Shelf

    -
    siteId
    string <uuid>

    ID of the site the Expected Power Shelf belongs to

    -
    bmcMacAddress
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Power Shelf's BMC (Baseboard Management Controller)

    -
    shelfSerialNumber
    string

    Serial number of the Expected Power Shelf

    -
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    -
    rackId
    string or null

    Optional rack identifier for this component

    -
    name
    string or null

    Display name for this component

    -
    manufacturer
    string or null

    Manufacturer of this component

    -
    model
    string or null

    Model of this component

    -
    description
    string or null

    Description of this component

    -
    firmwareVersion
    string or null

    Firmware version of this component

    -
    slotId
    integer or null <int32>

    Slot ID within the rack

    -
    trayIdx
    integer or null <int32>

    Tray index within the rack

    -
    hostId
    integer or null <int32>

    Host ID within the tray

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Power Shelves

    -
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Power Shelf was created

    -
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Power Shelf was last updated

    -

    Request samples

    Content type
    application/json
    {
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "bmcMacAddress": "00:1A:2B:3C:4D:5E",
    • "defaultBmcUsername": "admin",
    • "defaultBmcPassword": "password123",
    • "shelfSerialNumber": "SHELF-12345",
    • "bmcIpAddress": "192.168.1.100",
    • "labels": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "bmcMacAddress": "00:1A:2B:3C:4D:5E",
    • "shelfSerialNumber": "SHELF-12345",
    • "bmcIpAddress": "192.168.1.100",
    • "rackId": "rack-01",
    • "manufacturer": "Delta",
    • "labels": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Retrieve all Expected Power Shelves

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    Request Body schema: application/json
    required

    Expected Power Shelf creation request

    +
    siteId
    required
    string <uuid>

    ID of the site the Expected Power Shelf belongs to

    +
    bmcMacAddress
    required
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Power Shelf's BMC (Baseboard Management Controller)

    +
    defaultBmcUsername
    string or null <= 16 characters

    Username for accessing the Expected Power Shelf's BMC

    +
    defaultBmcPassword
    string or null <= 20 characters

    Password for accessing the Expected Power Shelf's BMC

    +
    shelfSerialNumber
    required
    string [ 1 .. 32 ] characters

    Serial number of the Expected Power Shelf

    +
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    +
    rackId
    string or null

    Optional rack identifier for this component

    +
    name
    string or null

    Display name for this component

    +
    manufacturer
    string or null

    Manufacturer of this component

    +
    model
    string or null

    Model of this component

    +
    description
    string or null

    Description of this component

    +
    firmwareVersion
    string or null

    Firmware version of this component

    +
    slotId
    integer or null <int32>

    Slot ID within the rack

    +
    trayIdx
    integer or null <int32>

    Tray index within the rack

    +
    hostId
    integer or null <int32>

    Host ID within the tray

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Power Shelves

    +
    property name*
    additional property
    string

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier for the Expected Power Shelf

    +
    siteId
    string <uuid>

    ID of the site the Expected Power Shelf belongs to

    +
    bmcMacAddress
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Power Shelf's BMC (Baseboard Management Controller)

    +
    shelfSerialNumber
    string

    Serial number of the Expected Power Shelf

    +
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    +
    rackId
    string or null

    Optional rack identifier for this component

    +
    name
    string or null

    Display name for this component

    +
    manufacturer
    string or null

    Manufacturer of this component

    +
    model
    string or null

    Model of this component

    +
    description
    string or null

    Description of this component

    +
    firmwareVersion
    string or null

    Firmware version of this component

    +
    slotId
    integer or null <int32>

    Slot ID within the rack

    +
    trayIdx
    integer or null <int32>

    Tray index within the rack

    +
    hostId
    integer or null <int32>

    Host ID within the tray

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Power Shelves

    +
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Power Shelf was created

    +
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Power Shelf was last updated

    +

    Request samples

    Content type
    application/json
    {
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "bmcMacAddress": "00:1A:2B:3C:4D:5E",
    • "defaultBmcUsername": "admin",
    • "defaultBmcPassword": "password123",
    • "shelfSerialNumber": "SHELF-12345",
    • "bmcIpAddress": "192.168.1.100",
    • "labels": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "bmcMacAddress": "00:1A:2B:3C:4D:5E",
    • "shelfSerialNumber": "SHELF-12345",
    • "bmcIpAddress": "192.168.1.100",
    • "rackId": "rack-01",
    • "manufacturer": "Delta",
    • "labels": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Retrieve all Expected Power Shelves

    Retrieve all Expected Power Shelves.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve all Expected Power Shelves.

    Org must have an Infrastructure Provider entity. User must have authorization role with PROVIDER_ADMIN or PROVIDER_VIEWER suffix.

    Alternatively, Tenant Admins with TargetedInstanceCreation capability can also retrieve Expected Power Shelves if they have an account with the Site's Infrastructure Provider (siteId query parameter is required for Tenants).

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    query Parameters
    siteId
    string <uuid>

    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

    Page number for pagination query

    -
    pageSize
    integer [ 1 .. 100 ]
    Example: pageSize=20

    Page size for pagination query

    -
    orderBy
    string
    Enum: "BMC_MAC_ADDRESS_ASC" "BMC_MAC_ADDRESS_DESC" "SHELF_SERIAL_NUMBER_ASC" "SHELF_SERIAL_NUMBER_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC"

    Ordering for pagination query

    -

    Responses

    Response Headers
    X-Pagination
    string
    Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}"

    Pagination result in JSON format

    -
    Response Schema: application/json
    Array
    id
    string <uuid>

    Unique identifier for the Expected Power Shelf

    -
    siteId
    string <uuid>

    ID of the site the Expected Power Shelf belongs to

    -
    bmcMacAddress
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Power Shelf's BMC (Baseboard Management Controller)

    -
    shelfSerialNumber
    string

    Serial number of the Expected Power Shelf

    -
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    -
    rackId
    string or null

    Optional rack identifier for this component

    -
    name
    string or null

    Display name for this component

    -
    manufacturer
    string or null

    Manufacturer of this component

    -
    model
    string or null

    Model of this component

    -
    description
    string or null

    Description of this component

    -
    firmwareVersion
    string or null

    Firmware version of this component

    -
    slotId
    integer or null <int32>

    Slot ID within the rack

    -
    trayIdx
    integer or null <int32>

    Tray index within the rack

    -
    hostId
    integer or null <int32>

    Host ID within the tray

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Power Shelves

    -
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Power Shelf was created

    -
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Power Shelf was last updated

    -

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Retrieve Expected Power Shelf

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    query Parameters
    siteId
    string <uuid>

    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

    Page number for pagination query

    +
    pageSize
    integer [ 1 .. 100 ]
    Example: pageSize=20

    Page size for pagination query

    +
    orderBy
    string
    Enum: "BMC_MAC_ADDRESS_ASC" "BMC_MAC_ADDRESS_DESC" "SHELF_SERIAL_NUMBER_ASC" "SHELF_SERIAL_NUMBER_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC"

    Ordering for pagination query

    +

    Responses

    Response Headers
    X-Pagination
    string
    Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}"

    Pagination result in JSON format

    +
    Response Schema: application/json
    Array
    id
    string <uuid>

    Unique identifier for the Expected Power Shelf

    +
    siteId
    string <uuid>

    ID of the site the Expected Power Shelf belongs to

    +
    bmcMacAddress
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Power Shelf's BMC (Baseboard Management Controller)

    +
    shelfSerialNumber
    string

    Serial number of the Expected Power Shelf

    +
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    +
    rackId
    string or null

    Optional rack identifier for this component

    +
    name
    string or null

    Display name for this component

    +
    manufacturer
    string or null

    Manufacturer of this component

    +
    model
    string or null

    Model of this component

    +
    description
    string or null

    Description of this component

    +
    firmwareVersion
    string or null

    Firmware version of this component

    +
    slotId
    integer or null <int32>

    Slot ID within the rack

    +
    trayIdx
    integer or null <int32>

    Tray index within the rack

    +
    hostId
    integer or null <int32>

    Host ID within the tray

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Power Shelves

    +
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Power Shelf was created

    +
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Power Shelf was last updated

    +

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Retrieve Expected Power Shelf

    Retrieve a specific Expected Power Shelf by ID.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve a specific Expected Power Shelf by ID.

    Org must have an Infrastructure Provider entity. User must have authorization role with PROVIDER_ADMIN or PROVIDER_VIEWER suffix.

    Alternatively, Tenant Admins with TargetedInstanceCreation capability can also retrieve Expected Power Shelves if they have an account with the Site's Infrastructure Provider.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    expectedPowerShelfId
    required
    string

    ID of the Expected Power Shelf

    -
    query Parameters
    includeRelation
    string
    Value: "Site"

    Related entity to expand

    -

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier for the Expected Power Shelf

    -
    siteId
    string <uuid>

    ID of the site the Expected Power Shelf belongs to

    -
    bmcMacAddress
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Power Shelf's BMC (Baseboard Management Controller)

    -
    shelfSerialNumber
    string

    Serial number of the Expected Power Shelf

    -
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    -
    rackId
    string or null

    Optional rack identifier for this component

    -
    name
    string or null

    Display name for this component

    -
    manufacturer
    string or null

    Manufacturer of this component

    -
    model
    string or null

    Model of this component

    -
    description
    string or null

    Description of this component

    -
    firmwareVersion
    string or null

    Firmware version of this component

    -
    slotId
    integer or null <int32>

    Slot ID within the rack

    -
    trayIdx
    integer or null <int32>

    Tray index within the rack

    -
    hostId
    integer or null <int32>

    Host ID within the tray

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Power Shelves

    -
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Power Shelf was created

    -
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Power Shelf was last updated

    -

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "bmcMacAddress": "00:1A:2B:3C:4D:5E",
    • "shelfSerialNumber": "SHELF-12345",
    • "bmcIpAddress": "192.168.1.100",
    • "rackId": "rack-01",
    • "manufacturer": "Delta",
    • "labels": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Update Expected Power Shelf

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    expectedPowerShelfId
    required
    string

    ID of the Expected Power Shelf

    +
    query Parameters
    includeRelation
    string
    Value: "Site"

    Related entity to expand

    +

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier for the Expected Power Shelf

    +
    siteId
    string <uuid>

    ID of the site the Expected Power Shelf belongs to

    +
    bmcMacAddress
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Power Shelf's BMC (Baseboard Management Controller)

    +
    shelfSerialNumber
    string

    Serial number of the Expected Power Shelf

    +
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    +
    rackId
    string or null

    Optional rack identifier for this component

    +
    name
    string or null

    Display name for this component

    +
    manufacturer
    string or null

    Manufacturer of this component

    +
    model
    string or null

    Model of this component

    +
    description
    string or null

    Description of this component

    +
    firmwareVersion
    string or null

    Firmware version of this component

    +
    slotId
    integer or null <int32>

    Slot ID within the rack

    +
    trayIdx
    integer or null <int32>

    Tray index within the rack

    +
    hostId
    integer or null <int32>

    Host ID within the tray

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Power Shelves

    +
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Power Shelf was created

    +
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Power Shelf was last updated

    +

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "bmcMacAddress": "00:1A:2B:3C:4D:5E",
    • "shelfSerialNumber": "SHELF-12345",
    • "bmcIpAddress": "192.168.1.100",
    • "rackId": "rack-01",
    • "manufacturer": "Delta",
    • "labels": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Update Expected Power Shelf

    Update an existing Expected Power Shelf by ID.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Update an existing Expected Power Shelf by ID.

    Org must have an Infrastructure Provider entity. User must have authorization role with PROVIDER_ADMIN suffix.

    Infrastructure Provider must own the Expected Power Shelf.

    Alternatively, Tenant Admins with TargetedInstanceCreation capability can also update Expected Power Shelves if they have an account with the Site's Infrastructure Provider.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    expectedPowerShelfId
    required
    string

    ID of the Expected Power Shelf

    -
    Request Body schema: application/json
    required

    Expected Power Shelf update request

    -
    id
    string or null <uuid>

    ID of the Expected Power Shelf to update (ignored for single update, used for identification in batch operations).

    -
    bmcMacAddress
    string or null^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Power Shelf's BMC (Baseboard Management Controller)

    -
    defaultBmcUsername
    string or null <= 16 characters

    Username for accessing the Expected Power Shelf's BMC

    -
    defaultBmcPassword
    string or null <= 20 characters

    Password for accessing the Expected Power Shelf's BMC

    -
    shelfSerialNumber
    string or null [ 1 .. 32 ] characters

    Serial number of the Expected Power Shelf

    -
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    -
    rackId
    string or null

    Optional rack identifier for this component

    -
    name
    string or null

    Display name for this component

    -
    manufacturer
    string or null

    Manufacturer of this component

    -
    model
    string or null

    Model of this component

    -
    description
    string or null

    Description of this component

    -
    firmwareVersion
    string or null

    Firmware version of this component

    -
    slotId
    integer or null <int32>

    Slot ID within the rack

    -
    trayIdx
    integer or null <int32>

    Tray index within the rack

    -
    hostId
    integer or null <int32>

    Host ID within the tray

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Power Shelves

    -
    property name*
    additional property
    string

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier for the Expected Power Shelf

    -
    siteId
    string <uuid>

    ID of the site the Expected Power Shelf belongs to

    -
    bmcMacAddress
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Power Shelf's BMC (Baseboard Management Controller)

    -
    shelfSerialNumber
    string

    Serial number of the Expected Power Shelf

    -
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    -
    rackId
    string or null

    Optional rack identifier for this component

    -
    name
    string or null

    Display name for this component

    -
    manufacturer
    string or null

    Manufacturer of this component

    -
    model
    string or null

    Model of this component

    -
    description
    string or null

    Description of this component

    -
    firmwareVersion
    string or null

    Firmware version of this component

    -
    slotId
    integer or null <int32>

    Slot ID within the rack

    -
    trayIdx
    integer or null <int32>

    Tray index within the rack

    -
    hostId
    integer or null <int32>

    Host ID within the tray

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Power Shelves

    -
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Power Shelf was created

    -
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Power Shelf was last updated

    -

    Request samples

    Content type
    application/json
    {
    • "defaultBmcUsername": "newadmin",
    • "defaultBmcPassword": "newpassword123",
    • "shelfSerialNumber": "SHELF-54321",
    • "bmcIpAddress": "192.168.1.200",
    • "labels": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "bmcMacAddress": "00:1A:2B:3C:4D:5E",
    • "shelfSerialNumber": "SHELF-12345",
    • "bmcIpAddress": "192.168.1.100",
    • "rackId": "rack-01",
    • "manufacturer": "Delta",
    • "labels": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Delete Expected Power Shelf

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    expectedPowerShelfId
    required
    string

    ID of the Expected Power Shelf

    +
    Request Body schema: application/json
    required

    Expected Power Shelf update request

    +
    id
    string or null <uuid>

    ID of the Expected Power Shelf to update (ignored for single update, used for identification in batch operations).

    +
    bmcMacAddress
    string or null^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Power Shelf's BMC (Baseboard Management Controller)

    +
    defaultBmcUsername
    string or null <= 16 characters

    Username for accessing the Expected Power Shelf's BMC

    +
    defaultBmcPassword
    string or null <= 20 characters

    Password for accessing the Expected Power Shelf's BMC

    +
    shelfSerialNumber
    string or null [ 1 .. 32 ] characters

    Serial number of the Expected Power Shelf

    +
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    +
    rackId
    string or null

    Optional rack identifier for this component

    +
    name
    string or null

    Display name for this component

    +
    manufacturer
    string or null

    Manufacturer of this component

    +
    model
    string or null

    Model of this component

    +
    description
    string or null

    Description of this component

    +
    firmwareVersion
    string or null

    Firmware version of this component

    +
    slotId
    integer or null <int32>

    Slot ID within the rack

    +
    trayIdx
    integer or null <int32>

    Tray index within the rack

    +
    hostId
    integer or null <int32>

    Host ID within the tray

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Power Shelves

    +
    property name*
    additional property
    string

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier for the Expected Power Shelf

    +
    siteId
    string <uuid>

    ID of the site the Expected Power Shelf belongs to

    +
    bmcMacAddress
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Power Shelf's BMC (Baseboard Management Controller)

    +
    shelfSerialNumber
    string

    Serial number of the Expected Power Shelf

    +
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    +
    rackId
    string or null

    Optional rack identifier for this component

    +
    name
    string or null

    Display name for this component

    +
    manufacturer
    string or null

    Manufacturer of this component

    +
    model
    string or null

    Model of this component

    +
    description
    string or null

    Description of this component

    +
    firmwareVersion
    string or null

    Firmware version of this component

    +
    slotId
    integer or null <int32>

    Slot ID within the rack

    +
    trayIdx
    integer or null <int32>

    Tray index within the rack

    +
    hostId
    integer or null <int32>

    Host ID within the tray

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Power Shelves

    +
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Power Shelf was created

    +
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Power Shelf was last updated

    +

    Request samples

    Content type
    application/json
    {
    • "defaultBmcUsername": "newadmin",
    • "defaultBmcPassword": "newpassword123",
    • "shelfSerialNumber": "SHELF-54321",
    • "bmcIpAddress": "192.168.1.200",
    • "labels": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "bmcMacAddress": "00:1A:2B:3C:4D:5E",
    • "shelfSerialNumber": "SHELF-12345",
    • "bmcIpAddress": "192.168.1.100",
    • "rackId": "rack-01",
    • "manufacturer": "Delta",
    • "labels": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Delete Expected Power Shelf

    Delete an existing Expected Power Shelf by ID.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Delete an existing Expected Power Shelf by ID.

    Org must have an Infrastructure Provider entity. User must have authorization role with PROVIDER_ADMIN suffix.

    Infrastructure Provider must own the Expected Power Shelf.

    Alternatively, Tenant Admins with TargetedInstanceCreation capability can also delete Expected Power Shelves if they have an account with the Site's Infrastructure Provider.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    expectedPowerShelfId
    required
    string

    ID of the Expected Power Shelf

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "source": "nico",
    • "message": "Error validating request data",
    • "data": {
      }
    }

    Expected Rack

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    expectedPowerShelfId
    required
    string

    ID of the Expected Power Shelf

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "source": "nico",
    • "message": "Error validating request data",
    • "data": {
      }
    }

    Expected Rack

    Expected Rack identifies a Rack that is expected to be discovered at a Site. Infrastructure Providers can pre-register Expected Racks with an operator-supplied rack identifier and a Rack Profile reference to help with Rack discovery and ingestion. Chassis identity and physical location information are conveyed via well-known label keys (chassis.manufacturer, chassis.serial-number, chassis.model, location.region, location.datacenter, location.room, location.position).

    -

    Create Expected Rack

    Create Expected Rack

    Typical API Call Flow for Tenant <li><code>chassis.manufacturer</code>, <code>chassis.serial-number</code>, <code>chassis.model</code></li> <li><code>location.region</code>, <code>location.datacenter</code>, <code>location.room</code>, <code>location.position</code></li> </ul> -" class="sc-iJuXkV sc-cBNeAB iNuSsz jtfGmi">

    Create an Expected Rack to pre-register a rack expected to be discovered at a Site. The rackId is an operator-supplied string identifier (not a UUID) that uniquely identifies the rack within the Site.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Create an Expected Rack to pre-register a rack expected to be discovered at a Site. The rackId is an operator-supplied string identifier (not a UUID) that uniquely identifies the rack within the Site.

    Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN role.

    Alternatively, Tenant Admins with TargetedInstanceCreation capability can also create Expected Racks if they have an account with the Site's Infrastructure Provider.

    Chassis identity and physical location information are conveyed via well-known label keys in labels:

    @@ -4050,1563 +4000,1563 @@

    Typical API Call Flow for Tenant

  • chassis.manufacturer, chassis.serial-number, chassis.model
  • location.region, location.datacenter, location.room, location.position
    • -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    Request Body schema: application/json
    required

    Expected Rack creation request

    -
    siteId
    required
    string <uuid>

    ID of the Site the Expected Rack belongs to

    -
    rackId
    required
    string non-empty

    Operator-supplied identifier for the rack (string, not UUID). Must be non-empty and unique within the Site.

    -
    rackProfileId
    required
    string non-empty

    Identifier of the Rack Profile this rack conforms to. Must be non-empty.

    -
    name
    string or null non-empty

    Human-readable name of the Expected Rack

    -
    description
    string or null non-empty

    Human-readable description of the Expected Rack

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Racks. Well-known keys (chassis.*, location.*) are used to convey chassis identity and physical location.

    -
    property name*
    additional property
    string

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier (UUID) for the Expected Rack

    -
    rackId
    string

    Operator-supplied identifier for the rack (string, not UUID). Unique within a Site.

    -
    siteId
    string <uuid>

    ID of the Site the Expected Rack belongs to

    -
    rackProfileId
    string

    Identifier of the Rack Profile this rack conforms to

    -
    name
    string

    Human-readable name of the Expected Rack

    -
    description
    string

    Human-readable description of the Expected Rack

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Racks. Well-known keys (chassis.*, location.*) are used to convey chassis identity and physical location.

    -
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Rack was created

    -
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Rack was last updated

    -

    Request samples

    Content type
    application/json
    {
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "rackId": "rack-01",
    • "rackProfileId": "rp-standard-42u",
    • "name": "Rack 01",
    • "description": "Production rack in row A",
    • "labels": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "rackId": "rack-01",
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "rackProfileId": "rp-standard-42u",
    • "name": "Rack 01",
    • "description": "Production rack in row A",
    • "labels": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Retrieve all Expected Racks

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    Request Body schema: application/json
    required

    Expected Rack creation request

    +
    siteId
    required
    string <uuid>

    ID of the Site the Expected Rack belongs to

    +
    rackId
    required
    string non-empty

    Operator-supplied identifier for the rack (string, not UUID). Must be non-empty and unique within the Site.

    +
    rackProfileId
    required
    string non-empty

    Identifier of the Rack Profile this rack conforms to. Must be non-empty.

    +
    name
    string or null non-empty

    Human-readable name of the Expected Rack

    +
    description
    string or null non-empty

    Human-readable description of the Expected Rack

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Racks. Well-known keys (chassis.*, location.*) are used to convey chassis identity and physical location.

    +
    property name*
    additional property
    string

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier (UUID) for the Expected Rack

    +
    rackId
    string

    Operator-supplied identifier for the rack (string, not UUID). Unique within a Site.

    +
    siteId
    string <uuid>

    ID of the Site the Expected Rack belongs to

    +
    rackProfileId
    string

    Identifier of the Rack Profile this rack conforms to

    +
    name
    string

    Human-readable name of the Expected Rack

    +
    description
    string

    Human-readable description of the Expected Rack

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Racks. Well-known keys (chassis.*, location.*) are used to convey chassis identity and physical location.

    +
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Rack was created

    +
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Rack was last updated

    +

    Request samples

    Content type
    application/json
    {
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "rackId": "rack-01",
    • "rackProfileId": "rp-standard-42u",
    • "name": "Rack 01",
    • "description": "Production rack in row A",
    • "labels": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "rackId": "rack-01",
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "rackProfileId": "rp-standard-42u",
    • "name": "Rack 01",
    • "description": "Production rack in row A",
    • "labels": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Retrieve all Expected Racks

    Retrieve all Expected Racks.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve all Expected Racks.

    Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN or FORGE_PROVIDER_VIEWER role.

    Alternatively, Tenant Admins with TargetedInstanceCreation capability can also retrieve Expected Racks if they have an account with the Site's Infrastructure Provider (siteId query parameter is required for Tenants).

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    query Parameters
    siteId
    string <uuid>

    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

    Page number for pagination query

    -
    pageSize
    integer [ 1 .. 100 ]
    Example: pageSize=20

    Page size for pagination query

    -
    orderBy
    string
    Enum: "RACK_ID_ASC" "RACK_ID_DESC" "RACK_PROFILE_ID_ASC" "RACK_PROFILE_ID_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC"

    Ordering for pagination query

    -

    Responses

    Response Headers
    X-Pagination
    string
    Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}"

    Pagination result in JSON format

    -
    Response Schema: application/json
    Array
    id
    string <uuid>

    Unique identifier (UUID) for the Expected Rack

    -
    rackId
    string

    Operator-supplied identifier for the rack (string, not UUID). Unique within a Site.

    -
    siteId
    string <uuid>

    ID of the Site the Expected Rack belongs to

    -
    rackProfileId
    string

    Identifier of the Rack Profile this rack conforms to

    -
    name
    string

    Human-readable name of the Expected Rack

    -
    description
    string

    Human-readable description of the Expected Rack

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Racks. Well-known keys (chassis.*, location.*) are used to convey chassis identity and physical location.

    -
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Rack was created

    -
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Rack was last updated

    -

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Replace all Expected Racks

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    query Parameters
    siteId
    string <uuid>

    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

    Page number for pagination query

    +
    pageSize
    integer [ 1 .. 100 ]
    Example: pageSize=20

    Page size for pagination query

    +
    orderBy
    string
    Enum: "RACK_ID_ASC" "RACK_ID_DESC" "RACK_PROFILE_ID_ASC" "RACK_PROFILE_ID_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC"

    Ordering for pagination query

    +

    Responses

    Response Headers
    X-Pagination
    string
    Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}"

    Pagination result in JSON format

    +
    Response Schema: application/json
    Array
    id
    string <uuid>

    Unique identifier (UUID) for the Expected Rack

    +
    rackId
    string

    Operator-supplied identifier for the rack (string, not UUID). Unique within a Site.

    +
    siteId
    string <uuid>

    ID of the Site the Expected Rack belongs to

    +
    rackProfileId
    string

    Identifier of the Rack Profile this rack conforms to

    +
    name
    string

    Human-readable name of the Expected Rack

    +
    description
    string

    Human-readable description of the Expected Rack

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Racks. Well-known keys (chassis.*, location.*) are used to convey chassis identity and physical location.

    +
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Rack was created

    +
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Rack was last updated

    +

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Replace all Expected Racks

    Replace the full set of Expected Racks for a Site with the provided list. All existing Expected Racks for the Site that are not in the request body will be deleted, and any new Expected Racks in the request will be created. Existing Expected Racks with matching rackId values will be updated.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Replace the full set of Expected Racks for a Site with the provided list. All existing Expected Racks for the Site that are not in the request body will be deleted, and any new Expected Racks in the request will be created. Existing Expected Racks with matching rackId values will be updated.

    Every entry in expectedRacks must reference the same siteId as the top-level siteId. rackId values must be unique within the request. The expectedRacks array may be empty to clear all Expected Racks for the Site.

    Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN role.

    Alternatively, Tenant Admins with TargetedInstanceCreation capability can also replace Expected Racks if they have an account with the Site's Infrastructure Provider.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    Request Body schema: application/json
    required

    Replace-all Expected Racks request

    -
    siteId
    required
    string <uuid>

    ID of the Site whose Expected Racks should be replaced

    -
    required
    Array of objects (ExpectedRackCreateRequest)

    The full desired set of Expected Racks for the Site. Every entry must reference the same siteId as the top-level field, and rackId values must be unique within the request. May be empty to clear all Expected Racks for the Site.

    -
    Array
    siteId
    required
    string <uuid>

    ID of the Site the Expected Rack belongs to

    -
    rackId
    required
    string non-empty

    Operator-supplied identifier for the rack (string, not UUID). Must be non-empty and unique within the Site.

    -
    rackProfileId
    required
    string non-empty

    Identifier of the Rack Profile this rack conforms to. Must be non-empty.

    -
    name
    string or null non-empty

    Human-readable name of the Expected Rack

    -
    description
    string or null non-empty

    Human-readable description of the Expected Rack

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Racks. Well-known keys (chassis.*, location.*) are used to convey chassis identity and physical location.

    -

    Responses

    Response Schema: application/json
    Array
    id
    string <uuid>

    Unique identifier (UUID) for the Expected Rack

    -
    rackId
    string

    Operator-supplied identifier for the rack (string, not UUID). Unique within a Site.

    -
    siteId
    string <uuid>

    ID of the Site the Expected Rack belongs to

    -
    rackProfileId
    string

    Identifier of the Rack Profile this rack conforms to

    -
    name
    string

    Human-readable name of the Expected Rack

    -
    description
    string

    Human-readable description of the Expected Rack

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Racks. Well-known keys (chassis.*, location.*) are used to convey chassis identity and physical location.

    -
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Rack was created

    -
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Rack was last updated

    -

    Request samples

    Content type
    application/json
    {
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "expectedRacks": [
      ]
    }

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Delete all Expected Racks

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    Request Body schema: application/json
    required

    Replace-all Expected Racks request

    +
    siteId
    required
    string <uuid>

    ID of the Site whose Expected Racks should be replaced

    +
    required
    Array of objects (ExpectedRackCreateRequest)

    The full desired set of Expected Racks for the Site. Every entry must reference the same siteId as the top-level field, and rackId values must be unique within the request. May be empty to clear all Expected Racks for the Site.

    +
    Array
    siteId
    required
    string <uuid>

    ID of the Site the Expected Rack belongs to

    +
    rackId
    required
    string non-empty

    Operator-supplied identifier for the rack (string, not UUID). Must be non-empty and unique within the Site.

    +
    rackProfileId
    required
    string non-empty

    Identifier of the Rack Profile this rack conforms to. Must be non-empty.

    +
    name
    string or null non-empty

    Human-readable name of the Expected Rack

    +
    description
    string or null non-empty

    Human-readable description of the Expected Rack

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Racks. Well-known keys (chassis.*, location.*) are used to convey chassis identity and physical location.

    +

    Responses

    Response Schema: application/json
    Array
    id
    string <uuid>

    Unique identifier (UUID) for the Expected Rack

    +
    rackId
    string

    Operator-supplied identifier for the rack (string, not UUID). Unique within a Site.

    +
    siteId
    string <uuid>

    ID of the Site the Expected Rack belongs to

    +
    rackProfileId
    string

    Identifier of the Rack Profile this rack conforms to

    +
    name
    string

    Human-readable name of the Expected Rack

    +
    description
    string

    Human-readable description of the Expected Rack

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Racks. Well-known keys (chassis.*, location.*) are used to convey chassis identity and physical location.

    +
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Rack was created

    +
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Rack was last updated

    +

    Request samples

    Content type
    application/json
    {
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "expectedRacks": [
      ]
    }

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Delete all Expected Racks

    Delete all Expected Racks for a Site.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Delete all Expected Racks for a Site.

    Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN role.

    Infrastructure Provider must own the Expected Racks.

    Alternatively, Tenant Admins with TargetedInstanceCreation capability can also delete Expected Racks if they have an account with the Site's Infrastructure Provider.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    query Parameters
    siteId
    required
    string <uuid>

    ID of the Site whose Expected Racks should be deleted

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "source": "nico",
    • "message": "Error validating request data",
    • "data": {
      }
    }

    Retrieve Expected Rack

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    query Parameters
    siteId
    required
    string <uuid>

    ID of the Site whose Expected Racks should be deleted

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "source": "nico",
    • "message": "Error validating request data",
    • "data": {
      }
    }

    Retrieve Expected Rack

    Retrieve a specific Expected Rack by its id.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve a specific Expected Rack by its id.

    Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN or FORGE_PROVIDER_VIEWER role.

    Alternatively, Tenant Admins with TargetedInstanceCreation capability can also retrieve Expected Racks if they have an account with the Site's Infrastructure Provider.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    id
    required
    string <uuid>

    ID of the Expected Rack

    -
    query Parameters
    includeRelation
    string
    Value: "Site"

    Related entity to expand

    -

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier (UUID) for the Expected Rack

    -
    rackId
    string

    Operator-supplied identifier for the rack (string, not UUID). Unique within a Site.

    -
    siteId
    string <uuid>

    ID of the Site the Expected Rack belongs to

    -
    rackProfileId
    string

    Identifier of the Rack Profile this rack conforms to

    -
    name
    string

    Human-readable name of the Expected Rack

    -
    description
    string

    Human-readable description of the Expected Rack

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Racks. Well-known keys (chassis.*, location.*) are used to convey chassis identity and physical location.

    -
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Rack was created

    -
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Rack was last updated

    -

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "rackId": "rack-01",
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "rackProfileId": "rp-standard-42u",
    • "name": "Rack 01",
    • "description": "Production rack in row A",
    • "labels": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Update Expected Rack

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    id
    required
    string <uuid>

    ID of the Expected Rack

    +
    query Parameters
    includeRelation
    string
    Value: "Site"

    Related entity to expand

    +

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier (UUID) for the Expected Rack

    +
    rackId
    string

    Operator-supplied identifier for the rack (string, not UUID). Unique within a Site.

    +
    siteId
    string <uuid>

    ID of the Site the Expected Rack belongs to

    +
    rackProfileId
    string

    Identifier of the Rack Profile this rack conforms to

    +
    name
    string

    Human-readable name of the Expected Rack

    +
    description
    string

    Human-readable description of the Expected Rack

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Racks. Well-known keys (chassis.*, location.*) are used to convey chassis identity and physical location.

    +
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Rack was created

    +
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Rack was last updated

    +

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "rackId": "rack-01",
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "rackProfileId": "rp-standard-42u",
    • "name": "Rack 01",
    • "description": "Production rack in row A",
    • "labels": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Update Expected Rack

    Update an existing Expected Rack identified by its id.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Update an existing Expected Rack identified by its id.

    Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN role.

    Infrastructure Provider must own the Expected Rack.

    Alternatively, Tenant Admins with TargetedInstanceCreation capability can also update Expected Racks if they have an account with the Site's Infrastructure Provider.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    id
    required
    string <uuid>

    ID of the Expected Rack

    -
    Request Body schema: application/json
    required

    Expected Rack update request

    -
    id
    string or null <uuid>

    Unique identifier (UUID) of the Expected Rack to update. Optional for single Expected Rack update (must be empty or match the id from the URL path).

    -
    rackId
    string or null non-empty

    Optional new operator-supplied rack identifier. If provided, must be non-empty and unique within the Site.

    -
    rackProfileId
    string or null non-empty

    Optional new Rack Profile identifier. If provided, must be non-empty.

    -
    name
    string or null non-empty

    Human-readable name of the Expected Rack

    -
    description
    string or null non-empty

    Human-readable description of the Expected Rack

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Racks. Well-known keys (chassis.*, location.*) are used to convey chassis identity and physical location.

    -
    property name*
    additional property
    string

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier (UUID) for the Expected Rack

    -
    rackId
    string

    Operator-supplied identifier for the rack (string, not UUID). Unique within a Site.

    -
    siteId
    string <uuid>

    ID of the Site the Expected Rack belongs to

    -
    rackProfileId
    string

    Identifier of the Rack Profile this rack conforms to

    -
    name
    string

    Human-readable name of the Expected Rack

    -
    description
    string

    Human-readable description of the Expected Rack

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Racks. Well-known keys (chassis.*, location.*) are used to convey chassis identity and physical location.

    -
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Rack was created

    -
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Rack was last updated

    -

    Request samples

    Content type
    application/json
    {
    • "rackProfileId": "rp-standard-48u",
    • "name": "Rack 01 (updated)",
    • "description": "Production rack in row A, upgraded chassis",
    • "labels": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "rackId": "rack-01",
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "rackProfileId": "rp-standard-42u",
    • "name": "Rack 01",
    • "description": "Production rack in row A",
    • "labels": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Delete Expected Rack

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    id
    required
    string <uuid>

    ID of the Expected Rack

    +
    Request Body schema: application/json
    required

    Expected Rack update request

    +
    id
    string or null <uuid>

    Unique identifier (UUID) of the Expected Rack to update. Optional for single Expected Rack update (must be empty or match the id from the URL path).

    +
    rackId
    string or null non-empty

    Optional new operator-supplied rack identifier. If provided, must be non-empty and unique within the Site.

    +
    rackProfileId
    string or null non-empty

    Optional new Rack Profile identifier. If provided, must be non-empty.

    +
    name
    string or null non-empty

    Human-readable name of the Expected Rack

    +
    description
    string or null non-empty

    Human-readable description of the Expected Rack

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Racks. Well-known keys (chassis.*, location.*) are used to convey chassis identity and physical location.

    +
    property name*
    additional property
    string

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier (UUID) for the Expected Rack

    +
    rackId
    string

    Operator-supplied identifier for the rack (string, not UUID). Unique within a Site.

    +
    siteId
    string <uuid>

    ID of the Site the Expected Rack belongs to

    +
    rackProfileId
    string

    Identifier of the Rack Profile this rack conforms to

    +
    name
    string

    Human-readable name of the Expected Rack

    +
    description
    string

    Human-readable description of the Expected Rack

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Racks. Well-known keys (chassis.*, location.*) are used to convey chassis identity and physical location.

    +
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Rack was created

    +
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Rack was last updated

    +

    Request samples

    Content type
    application/json
    {
    • "rackProfileId": "rp-standard-48u",
    • "name": "Rack 01 (updated)",
    • "description": "Production rack in row A, upgraded chassis",
    • "labels": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "rackId": "rack-01",
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "rackProfileId": "rp-standard-42u",
    • "name": "Rack 01",
    • "description": "Production rack in row A",
    • "labels": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Delete Expected Rack

    Delete an existing Expected Rack identified by its id.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Delete an existing Expected Rack identified by its id.

    Org must have an Infrastructure Provider entity. User must have FORGE_PROVIDER_ADMIN role.

    Infrastructure Provider must own the Expected Rack.

    Alternatively, Tenant Admins with TargetedInstanceCreation capability can also delete Expected Racks if they have an account with the Site's Infrastructure Provider.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    id
    required
    string <uuid>

    ID of the Expected Rack

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "source": "nico",
    • "message": "Error validating request data",
    • "data": {
      }
    }

    Expected Switch

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    id
    required
    string <uuid>

    ID of the Expected Rack

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "source": "nico",
    • "message": "Error validating request data",
    • "data": {
      }
    }

    Expected Switch

    Expected Switch identifies a Switch that is expected to be discovered at a Site. Infrastructure Providers can pre-register Expected Switches using BMC, NvOS credentials and serial numbers to help with Switch discovery and ingestion.

    -

    Create Expected Switch

    Create Expected Switch

    Create an Expected Switch to pre-register network switches expected to be discovered at a Site.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Create an Expected Switch to pre-register network switches expected to be discovered at a Site.

    Org must have an Infrastructure Provider entity. User must have authorization role with PROVIDER_ADMIN suffix.

    Alternatively, Tenant Admins with TargetedInstanceCreation capability can also create Expected Switches if they have an account with the Site's Infrastructure Provider.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    Request Body schema: application/json
    required

    Expected Switch creation request

    -
    siteId
    required
    string <uuid>

    ID of the site the Expected Switch belongs to

    -
    bmcMacAddress
    required
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Switch's BMC (Baseboard Management Controller)

    -
    defaultBmcUsername
    string or null <= 16 characters

    Username for accessing the Expected Switch's BMC

    -
    defaultBmcPassword
    string or null <= 20 characters

    Password for accessing the Expected Switch's BMC

    -
    switchSerialNumber
    required
    string [ 1 .. 32 ] characters

    Serial number of the Expected Switch

    -
    nvOsUsername
    string or null

    NvOS username for the Expected Switch

    -
    nvOsPassword
    string or null

    NvOS password for the Expected Switch

    -
    rackId
    string or null

    Optional rack identifier for this component

    -
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    -
    name
    string or null

    Display name for this component

    -
    manufacturer
    string or null

    Manufacturer of this component

    -
    model
    string or null

    Model of this component

    -
    description
    string or null

    Description of this component

    -
    firmwareVersion
    string or null

    Firmware version of this component

    -
    slotId
    integer or null <int32>

    Slot ID within the rack

    -
    trayIdx
    integer or null <int32>

    Tray index within the rack

    -
    hostId
    integer or null <int32>

    Host ID within the tray

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Switches

    -
    property name*
    additional property
    string

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier for the Expected Switch

    -
    siteId
    string <uuid>

    ID of the site the Expected Switch belongs to

    -
    bmcMacAddress
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Switch's BMC (Baseboard Management Controller)

    -
    switchSerialNumber
    string

    Serial number of the Expected Switch

    -
    rackId
    string or null

    Optional rack identifier for this component

    -
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    -
    name
    string or null

    Display name for this component

    -
    manufacturer
    string or null

    Manufacturer of this component

    -
    model
    string or null

    Model of this component

    -
    description
    string or null

    Description of this component

    -
    firmwareVersion
    string or null

    Firmware version of this component

    -
    slotId
    integer or null <int32>

    Slot ID within the rack

    -
    trayIdx
    integer or null <int32>

    Tray index within the rack

    -
    hostId
    integer or null <int32>

    Host ID within the tray

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Switches

    -
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Switch was created

    -
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Switch was last updated

    -

    Request samples

    Content type
    application/json
    {
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "bmcMacAddress": "00:1A:2B:3C:4D:5E",
    • "defaultBmcUsername": "admin",
    • "defaultBmcPassword": "password123",
    • "switchSerialNumber": "SWITCH-12345",
    • "nvOsUsername": "nvadmin",
    • "nvOsPassword": "nvpassword123",
    • "labels": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "bmcMacAddress": "00:1A:2B:3C:4D:5E",
    • "bmcIpAddress": "192.168.1.100",
    • "switchSerialNumber": "SWITCH-12345",
    • "rackId": "rack-01",
    • "manufacturer": "NVIDIA",
    • "labels": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Retrieve all Expected Switches

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    Request Body schema: application/json
    required

    Expected Switch creation request

    +
    siteId
    required
    string <uuid>

    ID of the site the Expected Switch belongs to

    +
    bmcMacAddress
    required
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Switch's BMC (Baseboard Management Controller)

    +
    defaultBmcUsername
    string or null <= 16 characters

    Username for accessing the Expected Switch's BMC

    +
    defaultBmcPassword
    string or null <= 20 characters

    Password for accessing the Expected Switch's BMC

    +
    switchSerialNumber
    required
    string [ 1 .. 32 ] characters

    Serial number of the Expected Switch

    +
    nvOsUsername
    string or null

    NvOS username for the Expected Switch

    +
    nvOsPassword
    string or null

    NvOS password for the Expected Switch

    +
    rackId
    string or null

    Optional rack identifier for this component

    +
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    +
    name
    string or null

    Display name for this component

    +
    manufacturer
    string or null

    Manufacturer of this component

    +
    model
    string or null

    Model of this component

    +
    description
    string or null

    Description of this component

    +
    firmwareVersion
    string or null

    Firmware version of this component

    +
    slotId
    integer or null <int32>

    Slot ID within the rack

    +
    trayIdx
    integer or null <int32>

    Tray index within the rack

    +
    hostId
    integer or null <int32>

    Host ID within the tray

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Switches

    +
    property name*
    additional property
    string

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier for the Expected Switch

    +
    siteId
    string <uuid>

    ID of the site the Expected Switch belongs to

    +
    bmcMacAddress
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Switch's BMC (Baseboard Management Controller)

    +
    switchSerialNumber
    string

    Serial number of the Expected Switch

    +
    rackId
    string or null

    Optional rack identifier for this component

    +
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    +
    name
    string or null

    Display name for this component

    +
    manufacturer
    string or null

    Manufacturer of this component

    +
    model
    string or null

    Model of this component

    +
    description
    string or null

    Description of this component

    +
    firmwareVersion
    string or null

    Firmware version of this component

    +
    slotId
    integer or null <int32>

    Slot ID within the rack

    +
    trayIdx
    integer or null <int32>

    Tray index within the rack

    +
    hostId
    integer or null <int32>

    Host ID within the tray

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Switches

    +
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Switch was created

    +
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Switch was last updated

    +

    Request samples

    Content type
    application/json
    {
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "bmcMacAddress": "00:1A:2B:3C:4D:5E",
    • "defaultBmcUsername": "admin",
    • "defaultBmcPassword": "password123",
    • "switchSerialNumber": "SWITCH-12345",
    • "nvOsUsername": "nvadmin",
    • "nvOsPassword": "nvpassword123",
    • "labels": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "bmcMacAddress": "00:1A:2B:3C:4D:5E",
    • "bmcIpAddress": "192.168.1.100",
    • "switchSerialNumber": "SWITCH-12345",
    • "rackId": "rack-01",
    • "manufacturer": "NVIDIA",
    • "labels": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Retrieve all Expected Switches

    Retrieve all Expected Switches.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve all Expected Switches.

    Org must have an Infrastructure Provider entity. User must have authorization role with PROVIDER_ADMIN or PROVIDER_VIEWER suffix.

    Alternatively, Tenant Admins with TargetedInstanceCreation capability can also retrieve Expected Switches if they have an account with the Site's Infrastructure Provider (siteId query parameter is required for Tenants).

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    query Parameters
    siteId
    string <uuid>

    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

    Page number for pagination query

    -
    pageSize
    integer [ 1 .. 100 ]
    Example: pageSize=20

    Page size for pagination query

    -
    orderBy
    string
    Enum: "BMC_MAC_ADDRESS_ASC" "BMC_MAC_ADDRESS_DESC" "SWITCH_SERIAL_NUMBER_ASC" "SWITCH_SERIAL_NUMBER_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC"

    Ordering for pagination query

    -

    Responses

    Response Headers
    X-Pagination
    string
    Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}"

    Pagination result in JSON format

    -
    Response Schema: application/json
    Array
    id
    string <uuid>

    Unique identifier for the Expected Switch

    -
    siteId
    string <uuid>

    ID of the site the Expected Switch belongs to

    -
    bmcMacAddress
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Switch's BMC (Baseboard Management Controller)

    -
    switchSerialNumber
    string

    Serial number of the Expected Switch

    -
    rackId
    string or null

    Optional rack identifier for this component

    -
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    -
    name
    string or null

    Display name for this component

    -
    manufacturer
    string or null

    Manufacturer of this component

    -
    model
    string or null

    Model of this component

    -
    description
    string or null

    Description of this component

    -
    firmwareVersion
    string or null

    Firmware version of this component

    -
    slotId
    integer or null <int32>

    Slot ID within the rack

    -
    trayIdx
    integer or null <int32>

    Tray index within the rack

    -
    hostId
    integer or null <int32>

    Host ID within the tray

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Switches

    -
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Switch was created

    -
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Switch was last updated

    -

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Retrieve Expected Switch

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    query Parameters
    siteId
    string <uuid>

    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

    Page number for pagination query

    +
    pageSize
    integer [ 1 .. 100 ]
    Example: pageSize=20

    Page size for pagination query

    +
    orderBy
    string
    Enum: "BMC_MAC_ADDRESS_ASC" "BMC_MAC_ADDRESS_DESC" "SWITCH_SERIAL_NUMBER_ASC" "SWITCH_SERIAL_NUMBER_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC"

    Ordering for pagination query

    +

    Responses

    Response Headers
    X-Pagination
    string
    Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}"

    Pagination result in JSON format

    +
    Response Schema: application/json
    Array
    id
    string <uuid>

    Unique identifier for the Expected Switch

    +
    siteId
    string <uuid>

    ID of the site the Expected Switch belongs to

    +
    bmcMacAddress
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Switch's BMC (Baseboard Management Controller)

    +
    switchSerialNumber
    string

    Serial number of the Expected Switch

    +
    rackId
    string or null

    Optional rack identifier for this component

    +
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    +
    name
    string or null

    Display name for this component

    +
    manufacturer
    string or null

    Manufacturer of this component

    +
    model
    string or null

    Model of this component

    +
    description
    string or null

    Description of this component

    +
    firmwareVersion
    string or null

    Firmware version of this component

    +
    slotId
    integer or null <int32>

    Slot ID within the rack

    +
    trayIdx
    integer or null <int32>

    Tray index within the rack

    +
    hostId
    integer or null <int32>

    Host ID within the tray

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Switches

    +
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Switch was created

    +
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Switch was last updated

    +

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Retrieve Expected Switch

    Retrieve a specific Expected Switch by ID.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve a specific Expected Switch by ID.

    Org must have an Infrastructure Provider entity. User must have authorization role with PROVIDER_ADMIN or PROVIDER_VIEWER suffix.

    Alternatively, Tenant Admins with TargetedInstanceCreation capability can also retrieve Expected Switches if they have an account with the Site's Infrastructure Provider.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    expectedSwitchId
    required
    string

    ID of the Expected Switch

    -
    query Parameters
    includeRelation
    string
    Value: "Site"

    Related entity to expand

    -

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier for the Expected Switch

    -
    siteId
    string <uuid>

    ID of the site the Expected Switch belongs to

    -
    bmcMacAddress
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Switch's BMC (Baseboard Management Controller)

    -
    switchSerialNumber
    string

    Serial number of the Expected Switch

    -
    rackId
    string or null

    Optional rack identifier for this component

    -
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    -
    name
    string or null

    Display name for this component

    -
    manufacturer
    string or null

    Manufacturer of this component

    -
    model
    string or null

    Model of this component

    -
    description
    string or null

    Description of this component

    -
    firmwareVersion
    string or null

    Firmware version of this component

    -
    slotId
    integer or null <int32>

    Slot ID within the rack

    -
    trayIdx
    integer or null <int32>

    Tray index within the rack

    -
    hostId
    integer or null <int32>

    Host ID within the tray

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Switches

    -
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Switch was created

    -
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Switch was last updated

    -

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "bmcMacAddress": "00:1A:2B:3C:4D:5E",
    • "bmcIpAddress": "192.168.1.100",
    • "switchSerialNumber": "SWITCH-12345",
    • "rackId": "rack-01",
    • "manufacturer": "NVIDIA",
    • "labels": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Update Expected Switch

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    expectedSwitchId
    required
    string

    ID of the Expected Switch

    +
    query Parameters
    includeRelation
    string
    Value: "Site"

    Related entity to expand

    +

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier for the Expected Switch

    +
    siteId
    string <uuid>

    ID of the site the Expected Switch belongs to

    +
    bmcMacAddress
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Switch's BMC (Baseboard Management Controller)

    +
    switchSerialNumber
    string

    Serial number of the Expected Switch

    +
    rackId
    string or null

    Optional rack identifier for this component

    +
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    +
    name
    string or null

    Display name for this component

    +
    manufacturer
    string or null

    Manufacturer of this component

    +
    model
    string or null

    Model of this component

    +
    description
    string or null

    Description of this component

    +
    firmwareVersion
    string or null

    Firmware version of this component

    +
    slotId
    integer or null <int32>

    Slot ID within the rack

    +
    trayIdx
    integer or null <int32>

    Tray index within the rack

    +
    hostId
    integer or null <int32>

    Host ID within the tray

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Switches

    +
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Switch was created

    +
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Switch was last updated

    +

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "bmcMacAddress": "00:1A:2B:3C:4D:5E",
    • "bmcIpAddress": "192.168.1.100",
    • "switchSerialNumber": "SWITCH-12345",
    • "rackId": "rack-01",
    • "manufacturer": "NVIDIA",
    • "labels": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Update Expected Switch

    Update an existing Expected Switch by ID.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Update an existing Expected Switch by ID.

    Org must have an Infrastructure Provider entity. User must have authorization role with PROVIDER_ADMIN suffix.

    Infrastructure Provider must own the Expected Switch.

    Alternatively, Tenant Admins with TargetedInstanceCreation capability can also update Expected Switches if they have an account with the Site's Infrastructure Provider.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    expectedSwitchId
    required
    string

    ID of the Expected Switch

    -
    Request Body schema: application/json
    required

    Expected Switch update request

    -
    id
    string or null <uuid>

    ID of the Expected Switch to update (ignored for single update, used for identification in batch operations).

    -
    bmcMacAddress
    string or null^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Switch's BMC (Baseboard Management Controller)

    -
    defaultBmcUsername
    string or null <= 16 characters

    Username for accessing the Expected Switch's BMC

    -
    defaultBmcPassword
    string or null <= 20 characters

    Password for accessing the Expected Switch's BMC

    -
    switchSerialNumber
    string or null [ 1 .. 32 ] characters

    Serial number of the Expected Switch

    -
    nvOsUsername
    string or null

    NvOS username for the Expected Switch

    -
    nvOsPassword
    string or null

    NvOS password for the Expected Switch

    -
    rackId
    string or null

    Optional rack identifier for this component

    -
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    -
    name
    string or null

    Display name for this component

    -
    manufacturer
    string or null

    Manufacturer of this component

    -
    model
    string or null

    Model of this component

    -
    description
    string or null

    Description of this component

    -
    firmwareVersion
    string or null

    Firmware version of this component

    -
    slotId
    integer or null <int32>

    Slot ID within the rack

    -
    trayIdx
    integer or null <int32>

    Tray index within the rack

    -
    hostId
    integer or null <int32>

    Host ID within the tray

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Switches

    -
    property name*
    additional property
    string

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier for the Expected Switch

    -
    siteId
    string <uuid>

    ID of the site the Expected Switch belongs to

    -
    bmcMacAddress
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Switch's BMC (Baseboard Management Controller)

    -
    switchSerialNumber
    string

    Serial number of the Expected Switch

    -
    rackId
    string or null

    Optional rack identifier for this component

    -
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    -
    name
    string or null

    Display name for this component

    -
    manufacturer
    string or null

    Manufacturer of this component

    -
    model
    string or null

    Model of this component

    -
    description
    string or null

    Description of this component

    -
    firmwareVersion
    string or null

    Firmware version of this component

    -
    slotId
    integer or null <int32>

    Slot ID within the rack

    -
    trayIdx
    integer or null <int32>

    Tray index within the rack

    -
    hostId
    integer or null <int32>

    Host ID within the tray

    -
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Switches

    -
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Switch was created

    -
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Switch was last updated

    -

    Request samples

    Content type
    application/json
    {
    • "defaultBmcUsername": "newadmin",
    • "defaultBmcPassword": "newpassword123",
    • "switchSerialNumber": "SWITCH-54321",
    • "nvOsUsername": "newnvadmin",
    • "nvOsPassword": "newnvpassword123",
    • "labels": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "bmcMacAddress": "00:1A:2B:3C:4D:5E",
    • "bmcIpAddress": "192.168.1.100",
    • "switchSerialNumber": "SWITCH-12345",
    • "rackId": "rack-01",
    • "manufacturer": "NVIDIA",
    • "labels": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Delete Expected Switch

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    expectedSwitchId
    required
    string

    ID of the Expected Switch

    +
    Request Body schema: application/json
    required

    Expected Switch update request

    +
    id
    string or null <uuid>

    ID of the Expected Switch to update (ignored for single update, used for identification in batch operations).

    +
    bmcMacAddress
    string or null^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Switch's BMC (Baseboard Management Controller)

    +
    defaultBmcUsername
    string or null <= 16 characters

    Username for accessing the Expected Switch's BMC

    +
    defaultBmcPassword
    string or null <= 20 characters

    Password for accessing the Expected Switch's BMC

    +
    switchSerialNumber
    string or null [ 1 .. 32 ] characters

    Serial number of the Expected Switch

    +
    nvOsUsername
    string or null

    NvOS username for the Expected Switch

    +
    nvOsPassword
    string or null

    NvOS password for the Expected Switch

    +
    rackId
    string or null

    Optional rack identifier for this component

    +
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    +
    name
    string or null

    Display name for this component

    +
    manufacturer
    string or null

    Manufacturer of this component

    +
    model
    string or null

    Model of this component

    +
    description
    string or null

    Description of this component

    +
    firmwareVersion
    string or null

    Firmware version of this component

    +
    slotId
    integer or null <int32>

    Slot ID within the rack

    +
    trayIdx
    integer or null <int32>

    Tray index within the rack

    +
    hostId
    integer or null <int32>

    Host ID within the tray

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Switches

    +
    property name*
    additional property
    string

    Responses

    Response Schema: application/json
    id
    string <uuid>

    Unique identifier for the Expected Switch

    +
    siteId
    string <uuid>

    ID of the site the Expected Switch belongs to

    +
    bmcMacAddress
    string^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$

    MAC address of the Expected Switch's BMC (Baseboard Management Controller)

    +
    switchSerialNumber
    string

    Serial number of the Expected Switch

    +
    rackId
    string or null

    Optional rack identifier for this component

    +
    bmcIpAddress
    string or null

    Optional BMC IP address (IPv4 or IPv6). When set, pre-allocates a reserved IP for the BMC.

    +
    name
    string or null

    Display name for this component

    +
    manufacturer
    string or null

    Manufacturer of this component

    +
    model
    string or null

    Model of this component

    +
    description
    string or null

    Description of this component

    +
    firmwareVersion
    string or null

    Firmware version of this component

    +
    slotId
    integer or null <int32>

    Slot ID within the rack

    +
    trayIdx
    integer or null <int32>

    Tray index within the rack

    +
    hostId
    integer or null <int32>

    Host ID within the tray

    +
    object (Labels) <= 10 properties

    User-defined key-value pairs for organizing and categorizing Expected Switches

    +
    property name*
    additional property
    string
    created
    string <date-time>

    ISO 8601 datetime when the Expected Switch was created

    +
    updated
    string <date-time>

    ISO 8601 datetime when the Expected Switch was last updated

    +

    Request samples

    Content type
    application/json
    {
    • "defaultBmcUsername": "newadmin",
    • "defaultBmcPassword": "newpassword123",
    • "switchSerialNumber": "SWITCH-54321",
    • "nvOsUsername": "newnvadmin",
    • "nvOsPassword": "newnvpassword123",
    • "labels": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "siteId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "bmcMacAddress": "00:1A:2B:3C:4D:5E",
    • "bmcIpAddress": "192.168.1.100",
    • "switchSerialNumber": "SWITCH-12345",
    • "rackId": "rack-01",
    • "manufacturer": "NVIDIA",
    • "labels": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Delete Expected Switch

    Delete an existing Expected Switch by ID.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Delete an existing Expected Switch by ID.

    Org must have an Infrastructure Provider entity. User must have authorization role with PROVIDER_ADMIN suffix.

    Infrastructure Provider must own the Expected Switch.

    Alternatively, Tenant Admins with TargetedInstanceCreation capability can also delete Expected Switches if they have an account with the Site's Infrastructure Provider.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    expectedSwitchId
    required
    string

    ID of the Expected Switch

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "source": "nico",
    • "message": "Error validating request data",
    • "data": {
      }
    }

    SKU

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    expectedSwitchId
    required
    string

    ID of the Expected Switch

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "source": "nico",
    • "message": "Error validating request data",
    • "data": {
      }
    }

    SKU

    SKU (Stock Keeping Unit) defines one or more hardware configurations or Machine Bill of Materials (BOM).

    SKUs are automatically derived from machine hardware characteristics and used to group similar machines. SKUs are read-only and managed by the system.

    -

    Retrieve all SKUs

    Retrieve all SKUs

    Retrieve all SKUs (Stock Keeping Units) for the Infrastructure Provider or privileged Tenant.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve all SKUs (Stock Keeping Units) for the Infrastructure Provider or privileged Tenant.

    SKUs represent unique hardware configurations discovered at sites. They are automatically derived from machine characteristics.

    A siteId query parameter is required for all requests.

    For Infrastructure Providers: Org must have an Infrastructure Provider entity. User must have authorization role with PROVIDER_ADMIN or PROVIDER_VIEWER suffix.

    For Tenants: Org must have a Tenant with TargetedInstanceCreation capability enabled. User must have authorization role with TENANT_ADMIN suffix. The Tenant must have an account with the Site's Infrastructure Provider.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    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

    Page number for pagination query

    -
    pageSize
    integer [ 1 .. 100 ]
    Example: pageSize=20

    Page size for pagination query

    -
    orderBy
    string
    Enum: "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" "ID_ASC" "ID_DESC"

    Ordering for pagination query

    -

    Responses

    Response Headers
    X-Pagination
    string
    Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}"

    Pagination result in JSON format

    -
    Response Schema: application/json
    Array
    id
    string

    Unique identifier for the SKU

    -
    siteId
    string <uuid>

    ID of the Site this SKU belongs to

    -
    deviceType
    string or null

    Optional device type identifier (e.g. "gpu", "cpu", "storage")

    -
    associatedMachineIds
    Array of strings

    List of machine IDs associated with this SKU

    -
    object (SkuComponents)

    Hardware components of this SKU

    -
    Array of objects (SkuCpu)

    CPU components

    -
    Array of objects (SkuGpu)

    GPU components

    -
    Array of objects (SkuMemory)

    Memory components

    -
    Array of objects (SkuStorage)

    Storage components

    -
    object (SkuChassis)

    Chassis component

    -
    Array of objects (SkuEthernetDevice)

    Ethernet device components

    -
    Array of objects (SkuInfinibandDevice)

    Infiniband device components

    -
    Array of objects (SkuTpm)

    TPM components

    -
    created
    string <date-time>

    ISO 8601 datetime when the SKU was created

    -
    updated
    string <date-time>

    ISO 8601 datetime when the SKU was last updated

    -

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Retrieve SKU

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    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

    Page number for pagination query

    +
    pageSize
    integer [ 1 .. 100 ]
    Example: pageSize=20

    Page size for pagination query

    +
    orderBy
    string
    Enum: "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC" "ID_ASC" "ID_DESC"

    Ordering for pagination query

    +

    Responses

    Response Headers
    X-Pagination
    string
    Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}"

    Pagination result in JSON format

    +
    Response Schema: application/json
    Array
    id
    string

    Unique identifier for the SKU

    +
    siteId
    string <uuid>

    ID of the Site this SKU belongs to

    +
    deviceType
    string or null

    Optional device type identifier (e.g. "gpu", "cpu", "storage")

    +
    associatedMachineIds
    Array of strings

    List of machine IDs associated with this SKU

    +
    object (SkuComponents)

    Hardware components of this SKU

    +
    Array of objects (SkuCpu)

    CPU components

    +
    Array of objects (SkuGpu)

    GPU components

    +
    Array of objects (SkuMemory)

    Memory components

    +
    Array of objects (SkuStorage)

    Storage components

    +
    object (SkuChassis)

    Chassis component

    +
    Array of objects (SkuEthernetDevice)

    Ethernet device components

    +
    Array of objects (SkuInfinibandDevice)

    Infiniband device components

    +
    Array of objects (SkuTpm)

    TPM components

    +
    created
    string <date-time>

    ISO 8601 datetime when the SKU was created

    +
    updated
    string <date-time>

    ISO 8601 datetime when the SKU was last updated

    +

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Retrieve SKU

    Retrieve a specific SKU (Stock Keeping Unit) by ID.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve a specific SKU (Stock Keeping Unit) by ID.

    SKUs represent unique hardware configurations discovered at sites. They are automatically derived from machine characteristics.

    For Infrastructure Providers: Org must have an Infrastructure Provider entity. User must have authorization role with PROVIDER_ADMIN or PROVIDER_VIEWER suffix.

    For Tenants: Org must have a Tenant with TargetedInstanceCreation capability enabled. User must have authorization role with TENANT_ADMIN suffix. The Tenant must have an account with the SKU's Site's Infrastructure Provider.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    skuId
    required
    string

    ID of the SKU

    -

    Responses

    Response Schema: application/json
    id
    string

    Unique identifier for the SKU

    -
    siteId
    string <uuid>

    ID of the Site this SKU belongs to

    -
    deviceType
    string or null

    Optional device type identifier (e.g. "gpu", "cpu", "storage")

    -
    associatedMachineIds
    Array of strings

    List of machine IDs associated with this SKU

    -
    object (SkuComponents)

    Hardware components of this SKU

    -
    Array of objects (SkuCpu)

    CPU components

    -
    Array
    vendor
    string

    Vendor of the CPU

    -
    model
    string

    Model of the CPU

    -
    threadCount
    integer <uint32>

    Number of threads for the CPU

    -
    count
    integer <uint32>

    Number of CPUs present

    -
    Array of objects (SkuGpu)

    GPU components

    -
    Array
    vendor
    string

    Vendor of the GPU

    -
    model
    string

    Model of the GPU

    -
    totalMemory
    string

    Total memory of the GPU (e.g. "80GB HBM3")

    -
    count
    integer <uint32>

    Number of GPUs present

    -
    Array of objects (SkuMemory)

    Memory components

    -
    Array
    capacityMb
    integer <uint32>

    Capacity in megabytes

    -
    memoryType
    string

    Type of memory (e.g. "DDR4", "DDR5")

    -
    count
    integer <uint32>

    Number of memory modules present

    -
    Array of objects (SkuStorage)

    Storage components

    -
    Array
    vendor
    string

    Vendor of the storage device

    -
    model
    string

    Model of the storage device

    -
    capacityMb
    integer <uint32>

    Capacity in megabytes

    -
    count
    integer <uint32>

    Number of storage devices present

    -
    object (SkuChassis)

    Chassis component

    -
    vendor
    string

    Vendor of the chassis

    -
    model
    string

    Model of the chassis

    -
    Array of objects (SkuEthernetDevice)

    Ethernet device components

    -
    Array
    vendor
    string

    Vendor of the ethernet device

    -
    model
    string

    Model of the ethernet device

    -
    count
    integer <uint32>

    Number of ethernet devices present

    -
    Array of objects (SkuInfinibandDevice)

    Infiniband device components

    -
    Array
    vendor
    string

    Vendor of the infiniband device

    -
    model
    string

    Model of the infiniband device

    -
    count
    integer <uint32>

    Number of infiniband devices present

    -
    Array of objects (SkuTpm)

    TPM components

    -
    Array
    vendor
    string

    Vendor of the TPM

    -
    model
    string

    Model of the TPM

    -
    count
    integer <uint32>

    Number of TPMs present

    -
    created
    string <date-time>

    ISO 8601 datetime when the SKU was created

    -
    updated
    string <date-time>

    ISO 8601 datetime when the SKU was last updated

    -

    Response samples

    Content type
    application/json
    {
    • "id": "lenovo.sr650v2.cpu.1",
    • "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
    • "deviceType": "gpu",
    • "associatedMachineIds": [
      ],
    • "components": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    InfiniBand Partition

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    skuId
    required
    string

    ID of the SKU

    +

    Responses

    Response Schema: application/json
    id
    string

    Unique identifier for the SKU

    +
    siteId
    string <uuid>

    ID of the Site this SKU belongs to

    +
    deviceType
    string or null

    Optional device type identifier (e.g. "gpu", "cpu", "storage")

    +
    associatedMachineIds
    Array of strings

    List of machine IDs associated with this SKU

    +
    object (SkuComponents)

    Hardware components of this SKU

    +
    Array of objects (SkuCpu)

    CPU components

    +
    Array
    vendor
    string

    Vendor of the CPU

    +
    model
    string

    Model of the CPU

    +
    threadCount
    integer <uint32>

    Number of threads for the CPU

    +
    count
    integer <uint32>

    Number of CPUs present

    +
    Array of objects (SkuGpu)

    GPU components

    +
    Array
    vendor
    string

    Vendor of the GPU

    +
    model
    string

    Model of the GPU

    +
    totalMemory
    string

    Total memory of the GPU (e.g. "80GB HBM3")

    +
    count
    integer <uint32>

    Number of GPUs present

    +
    Array of objects (SkuMemory)

    Memory components

    +
    Array
    capacityMb
    integer <uint32>

    Capacity in megabytes

    +
    memoryType
    string

    Type of memory (e.g. "DDR4", "DDR5")

    +
    count
    integer <uint32>

    Number of memory modules present

    +
    Array of objects (SkuStorage)

    Storage components

    +
    Array
    vendor
    string

    Vendor of the storage device

    +
    model
    string

    Model of the storage device

    +
    capacityMb
    integer <uint32>

    Capacity in megabytes

    +
    count
    integer <uint32>

    Number of storage devices present

    +
    object (SkuChassis)

    Chassis component

    +
    vendor
    string

    Vendor of the chassis

    +
    model
    string

    Model of the chassis

    +
    Array of objects (SkuEthernetDevice)

    Ethernet device components

    +
    Array
    vendor
    string

    Vendor of the ethernet device

    +
    model
    string

    Model of the ethernet device

    +
    count
    integer <uint32>

    Number of ethernet devices present

    +
    Array of objects (SkuInfinibandDevice)

    Infiniband device components

    +
    Array
    vendor
    string

    Vendor of the infiniband device

    +
    model
    string

    Model of the infiniband device

    +
    count
    integer <uint32>

    Number of infiniband devices present

    +
    Array of objects (SkuTpm)

    TPM components

    +
    Array
    vendor
    string

    Vendor of the TPM

    +
    model
    string

    Model of the TPM

    +
    count
    integer <uint32>

    Number of TPMs present

    +
    created
    string <date-time>

    ISO 8601 datetime when the SKU was created

    +
    updated
    string <date-time>

    ISO 8601 datetime when the SKU was last updated

    +

    Response samples

    Content type
    application/json
    {
    • "id": "lenovo.sr650v2.cpu.1",
    • "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
    • "deviceType": "gpu",
    • "associatedMachineIds": [
      ],
    • "components": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    InfiniBand Partition

    InfiniBand (IB) is a high-performance, low-latency networking standard designed for interconnecting servers and storage in HPC (High-Performance Computing) and AI systems, utilizing RDMA (Remote Direct Memory Access) to reduce CPU overhead. InfiniBand Partitions are used to group Machines into logical partitions for network isolation and load distribution.

    -

    Retrieve all InfiniBand Partitions

    Retrieve all InfiniBand Partitions

    Retrieve all InfiniBand Partitions for the org

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve all InfiniBand Partitions for the org

    Org must have a Tenant entity. User must have authorization role with TENANT_ADMIN suffix.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    query Parameters
    siteId
    string <uuid>

    Filter Partitions by Site

    -
    status
    string

    Filter Partitions by Status

    -
    query
    string

    Search for matches across all Sites. 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

    Page number for pagination query

    -
    pageSize
    integer [ 1 .. 100 ]
    Example: pageSize=20

    Page size for pagination query

    -
    orderBy
    string
    Enum: "NAME_ASC" "NAME_DESC" "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC"

    Ordering for pagination query

    -

    Responses

    Response Headers
    X-Pagination
    string
    Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}"

    Pagination result in JSON format

    -
    Response Schema: application/json
    Array
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    description
    string or null
    siteId
    string <uuid>
    tenantId
    string <uuid>
    controllerIBPartitionId
    string or null <uuid>
    partitionKey
    string or null
    partitionName
    string or null
    serviceLevel
    integer or null [ 0 .. 15 ]
    rateLimit
    number or null
    Enum: 2 5 10 14 20 25 30 40 56 60 80 100 112 120 168 200 300
    mtu
    integer or null
    Enum: 4000 8000
    enableSharp
    boolean
    object (Labels) <= 10 properties

    String key value pairs describing InfiniBand Partition labels. Up to 10 key value pairs can be specified

    -
    property name*
    additional property
    string
    status
    string (InfiniBandPartitionStatus)
    Enum: "Pending" "Provisioning" "Ready" "Configuring" "Deleting" "Error"

    Status values for InfiniBand Partition objects

    -
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Create InfiniBand Partition

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    query Parameters
    siteId
    string <uuid>

    Filter Partitions by Site

    +
    status
    string

    Filter Partitions by Status

    +
    query
    string

    Search for matches across all Sites. 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

    Page number for pagination query

    +
    pageSize
    integer [ 1 .. 100 ]
    Example: pageSize=20

    Page size for pagination query

    +
    orderBy
    string
    Enum: "NAME_ASC" "NAME_DESC" "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC"

    Ordering for pagination query

    +

    Responses

    Response Headers
    X-Pagination
    string
    Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}"

    Pagination result in JSON format

    +
    Response Schema: application/json
    Array
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    description
    string or null
    siteId
    string <uuid>
    tenantId
    string <uuid>
    controllerIBPartitionId
    string or null <uuid>
    partitionKey
    string or null
    partitionName
    string or null
    serviceLevel
    integer or null [ 0 .. 15 ]
    rateLimit
    number or null
    Enum: 2 5 10 14 20 25 30 40 56 60 80 100 112 120 168 200 300
    mtu
    integer or null
    Enum: 4000 8000
    enableSharp
    boolean
    object (Labels) <= 10 properties

    String key value pairs describing InfiniBand Partition labels. Up to 10 key value pairs can be specified

    +
    property name*
    additional property
    string
    status
    string (InfiniBandPartitionStatus)
    Enum: "Pending" "Provisioning" "Ready" "Configuring" "Deleting" "Error"

    Status values for InfiniBand Partition objects

    +
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Create InfiniBand Partition

    Create an InfiniBand Partition for the org.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Create an InfiniBand Partition for the org.

    Org must have a Tenant entity. User must have authorization role with TENANT_ADMIN suffix.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    Request Body schema: application/json
    name
    required
    string [ 2 .. 256 ] characters

    Name of the Partition to create

    -
    description
    string or null

    Optional description of the Partition

    -
    siteId
    required
    string <uuid>

    ID of the Site the Partition should belong to

    -
    object (Labels) <= 10 properties

    String key value pairs describing Partition labels. Up to 10 key value pairs can be specified

    -
    property name*
    additional property
    string

    Responses

    Response Schema: application/json
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    description
    string or null
    siteId
    string <uuid>
    tenantId
    string <uuid>
    controllerIBPartitionId
    string or null <uuid>
    partitionKey
    string or null
    partitionName
    string or null
    serviceLevel
    integer or null [ 0 .. 15 ]
    rateLimit
    number or null
    Enum: 2 5 10 14 20 25 30 40 56 60 80 100 112 120 168 200 300
    mtu
    integer or null
    Enum: 4000 8000
    enableSharp
    boolean
    object (Labels) <= 10 properties

    String key value pairs describing InfiniBand Partition labels. Up to 10 key value pairs can be specified

    -
    property name*
    additional property
    string
    status
    string (InfiniBandPartitionStatus)
    Enum: "Pending" "Provisioning" "Ready" "Configuring" "Deleting" "Error"

    Status values for InfiniBand Partition objects

    -
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>

    Request samples

    Content type
    application/json
    {
    • "name": "turbo-net",
    • "siteId": "69dae3c8-3554-4a1f-b391-858c6dc47fff",
    • "labels": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "turbo-net",
    • "description": "InfiniBand Partition for model training Instances",
    • "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "controllerIBPartitionId": "0e60d064-3d38-4812-84d9-c3353bd96eaf",
    • "partitionKey": "0x1",
    • "partitionName": "turbo-net",
    • "serviceLevel": 5,
    • "rateLimit": 40,
    • "mtu": 4000,
    • "enableSharp": true,
    • "labels": {
      },
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Retrieve InfiniBand Partition

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    Request Body schema: application/json
    name
    required
    string [ 2 .. 256 ] characters

    Name of the Partition to create

    +
    description
    string or null

    Optional description of the Partition

    +
    siteId
    required
    string <uuid>

    ID of the Site the Partition should belong to

    +
    object (Labels) <= 10 properties

    String key value pairs describing Partition labels. Up to 10 key value pairs can be specified

    +
    property name*
    additional property
    string

    Responses

    Response Schema: application/json
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    description
    string or null
    siteId
    string <uuid>
    tenantId
    string <uuid>
    controllerIBPartitionId
    string or null <uuid>
    partitionKey
    string or null
    partitionName
    string or null
    serviceLevel
    integer or null [ 0 .. 15 ]
    rateLimit
    number or null
    Enum: 2 5 10 14 20 25 30 40 56 60 80 100 112 120 168 200 300
    mtu
    integer or null
    Enum: 4000 8000
    enableSharp
    boolean
    object (Labels) <= 10 properties

    String key value pairs describing InfiniBand Partition labels. Up to 10 key value pairs can be specified

    +
    property name*
    additional property
    string
    status
    string (InfiniBandPartitionStatus)
    Enum: "Pending" "Provisioning" "Ready" "Configuring" "Deleting" "Error"

    Status values for InfiniBand Partition objects

    +
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>

    Request samples

    Content type
    application/json
    {
    • "name": "turbo-net",
    • "siteId": "69dae3c8-3554-4a1f-b391-858c6dc47fff",
    • "labels": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "turbo-net",
    • "description": "InfiniBand Partition for model training Instances",
    • "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "controllerIBPartitionId": "0e60d064-3d38-4812-84d9-c3353bd96eaf",
    • "partitionKey": "0x1",
    • "partitionName": "turbo-net",
    • "serviceLevel": 5,
    • "rateLimit": 40,
    • "mtu": 4000,
    • "enableSharp": true,
    • "labels": {
      },
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Retrieve InfiniBand Partition

    Retrieve a specific InfiniBand Partition

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Retrieve a specific InfiniBand Partition

    Org must have a Tenant entity. User must have authorization role with TENANT_ADMIN suffix.

    Tenant must own the Partition.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    infiniBandPartitionId
    required
    string

    ID of the InfiniBand Partition

    -
    query Parameters
    includeRelation
    string
    Enum: "Site" "VPC" "Tenant"

    Related entity to expand

    -

    Responses

    Response Schema: application/json
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    description
    string or null
    siteId
    string <uuid>
    tenantId
    string <uuid>
    controllerIBPartitionId
    string or null <uuid>
    partitionKey
    string or null
    partitionName
    string or null
    serviceLevel
    integer or null [ 0 .. 15 ]
    rateLimit
    number or null
    Enum: 2 5 10 14 20 25 30 40 56 60 80 100 112 120 168 200 300
    mtu
    integer or null
    Enum: 4000 8000
    enableSharp
    boolean
    object (Labels) <= 10 properties

    String key value pairs describing InfiniBand Partition labels. Up to 10 key value pairs can be specified

    -
    property name*
    additional property
    string
    status
    string (InfiniBandPartitionStatus)
    Enum: "Pending" "Provisioning" "Ready" "Configuring" "Deleting" "Error"

    Status values for InfiniBand Partition objects

    -
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "turbo-net",
    • "description": "InfiniBand Partition for model training Instances",
    • "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "controllerIBPartitionId": "0e60d064-3d38-4812-84d9-c3353bd96eaf",
    • "partitionKey": "0x1",
    • "partitionName": "turbo-net",
    • "serviceLevel": 5,
    • "rateLimit": 40,
    • "mtu": 4000,
    • "enableSharp": true,
    • "labels": {
      },
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Delete InfiniBand Partition

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    infiniBandPartitionId
    required
    string

    ID of the InfiniBand Partition

    +
    query Parameters
    includeRelation
    string
    Enum: "Site" "VPC" "Tenant"

    Related entity to expand

    +

    Responses

    Response Schema: application/json
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    description
    string or null
    siteId
    string <uuid>
    tenantId
    string <uuid>
    controllerIBPartitionId
    string or null <uuid>
    partitionKey
    string or null
    partitionName
    string or null
    serviceLevel
    integer or null [ 0 .. 15 ]
    rateLimit
    number or null
    Enum: 2 5 10 14 20 25 30 40 56 60 80 100 112 120 168 200 300
    mtu
    integer or null
    Enum: 4000 8000
    enableSharp
    boolean
    object (Labels) <= 10 properties

    String key value pairs describing InfiniBand Partition labels. Up to 10 key value pairs can be specified

    +
    property name*
    additional property
    string
    status
    string (InfiniBandPartitionStatus)
    Enum: "Pending" "Provisioning" "Ready" "Configuring" "Deleting" "Error"

    Status values for InfiniBand Partition objects

    +
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "turbo-net",
    • "description": "InfiniBand Partition for model training Instances",
    • "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "controllerIBPartitionId": "0e60d064-3d38-4812-84d9-c3353bd96eaf",
    • "partitionKey": "0x1",
    • "partitionName": "turbo-net",
    • "serviceLevel": 5,
    • "rateLimit": 40,
    • "mtu": 4000,
    • "enableSharp": true,
    • "labels": {
      },
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Delete InfiniBand Partition

    Delete a specific InfiniBand Partition by ID.

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Delete a specific InfiniBand Partition by ID.

    Org must have a Tenant entity. User must have authorization role with TENANT_ADMIN suffix.

    Tenant must own the Partition.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    infiniBandPartitionId
    required
    string

    ID of the InfiniBand Partition

    -

    Responses

    Response samples

    Content type
    application/json
    {
    • "source": "nico",
    • "message": "User is not allowed to perform this action",
    • "data": null
    }

    Update InfiniBand Partition

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    infiniBandPartitionId
    required
    string

    ID of the InfiniBand Partition

    +

    Responses

    Response samples

    Content type
    application/json
    {
    • "source": "nico",
    • "message": "User is not allowed to perform this action",
    • "data": null
    }

    Update InfiniBand Partition

    Update an existing InfiniBand Partition

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Update an existing InfiniBand Partition

    Org must have a Tenant entity. User must have authorization role with TENANT_ADMIN suffix.

    Tenant must own the Partition.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    infiniBandPartitionId
    required
    string

    ID of the InfiniBand Partition

    -
    Request Body schema: application/json
    name
    required
    string [ 2 .. 256 ] characters
    description
    string or null
    object (Labels) <= 10 properties

    String key value pairs describing Partition labels. Up to 10 key value pairs can be specified

    -
    property name*
    additional property
    string

    Responses

    Response Schema: application/json
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    description
    string or null
    siteId
    string <uuid>
    tenantId
    string <uuid>
    controllerIBPartitionId
    string or null <uuid>
    partitionKey
    string or null
    partitionName
    string or null
    serviceLevel
    integer or null [ 0 .. 15 ]
    rateLimit
    number or null
    Enum: 2 5 10 14 20 25 30 40 56 60 80 100 112 120 168 200 300
    mtu
    integer or null
    Enum: 4000 8000
    enableSharp
    boolean
    object (Labels) <= 10 properties

    String key value pairs describing InfiniBand Partition labels. Up to 10 key value pairs can be specified

    -
    property name*
    additional property
    string
    status
    string (InfiniBandPartitionStatus)
    Enum: "Pending" "Provisioning" "Ready" "Configuring" "Deleting" "Error"

    Status values for InfiniBand Partition objects

    -
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>

    Request samples

    Content type
    application/json
    {
    • "name": "turbo-net-v2",
    • "description": "Second version of the model training network",
    • "labels": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "turbo-net-v2",
    • "description": "Second version of the model training network",
    • "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "controllerIBPartitionId": "0e60d064-3d38-4812-84d9-c3353bd96eaf",
    • "partitionKey": "0x1",
    • "partitionName": "turbo-net",
    • "serviceLevel": 5,
    • "rateLimit": 40,
    • "mtu": 4000,
    • "enableSharp": true,
    • "labels": {
      },
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Retrieve all InfiniBand Interfaces

    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    +
    infiniBandPartitionId
    required
    string

    ID of the InfiniBand Partition

    +
    Request Body schema: application/json
    name
    required
    string [ 2 .. 256 ] characters
    description
    string or null
    object (Labels) <= 10 properties

    String key value pairs describing Partition labels. Up to 10 key value pairs can be specified

    +
    property name*
    additional property
    string

    Responses

    Response Schema: application/json
    id
    string <uuid>
    name
    string [ 2 .. 256 ] characters
    description
    string or null
    siteId
    string <uuid>
    tenantId
    string <uuid>
    controllerIBPartitionId
    string or null <uuid>
    partitionKey
    string or null
    partitionName
    string or null
    serviceLevel
    integer or null [ 0 .. 15 ]
    rateLimit
    number or null
    Enum: 2 5 10 14 20 25 30 40 56 60 80 100 112 120 168 200 300
    mtu
    integer or null
    Enum: 4000 8000
    enableSharp
    boolean
    object (Labels) <= 10 properties

    String key value pairs describing InfiniBand Partition labels. Up to 10 key value pairs can be specified

    +
    property name*
    additional property
    string
    status
    string (InfiniBandPartitionStatus)
    Enum: "Pending" "Provisioning" "Ready" "Configuring" "Deleting" "Error"

    Status values for InfiniBand Partition objects

    +
    Array of objects (StatusDetail)
    Array
    status
    string
    message
    string or null
    created
    string <date-time>
    updated
    string <date-time>
    created
    string <date-time>
    updated
    string <date-time>

    Request samples

    Content type
    application/json
    {
    • "name": "turbo-net-v2",
    • "description": "Second version of the model training network",
    • "labels": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "name": "turbo-net-v2",
    • "description": "Second version of the model training network",
    • "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
    • "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    • "controllerIBPartitionId": "0e60d064-3d38-4812-84d9-c3353bd96eaf",
    • "partitionKey": "0x1",
    • "partitionName": "turbo-net",
    • "serviceLevel": 5,
    • "rateLimit": 40,
    • "mtu": 4000,
    • "enableSharp": true,
    • "labels": {
      },
    • "status": "Pending",
    • "statusHistory": [
      ],
    • "created": "2019-08-24T14:15:22Z",
    • "updated": "2019-08-24T14:15:22Z"
    }

    Retrieve all InfiniBand Interfaces

    Get all InfiniBand Interfaces

    +" class="sc-iKGpAq sc-cCYyou dXXcln dHaogz">

    Get all InfiniBand Interfaces

    Org must have a Tenant entity. User must have authorization role with TENANT_ADMIN suffix.

    -
    Authorizations:
    JWTBearerToken
    path Parameters
    org
    required
    string

    Name of the Org

    -
    query Parameters
    siteId
    string

    Filter InfiniBand Interfaces by Site ID. Can be specified multiple times to filter on more than one ID.

    -
    instanceId
    string

    Filter InfiniBand Interfaces by Instance ID. Can be specified multiple times to filter on more than one ID.

    -
    infinibandPartitionId
    string

    Filter InfiniBand Interfaces by InfiniBand Partition ID. Can be specified multiple times to filter on more than one ID.

    -
    status
    string

    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

    Page number for pagination query

    -
    pageSize
    integer [ 1 .. 100 ]
    Example: pageSize=20

    Page size for pagination query

    -
    orderBy
    string
    Enum: "STATUS_ASC" "STATUS_DESC" "CREATED_ASC" "CREATED_DESC" "UPDATED_ASC" "UPDATED_DESC"

    Ordering for pagination query

    -

    Responses

    Response Headers
    X-Pagination
    string
    Example: "{\"pageNumber\":1,\"pageSize\":20,\"total\":30,\"orderBy\": \"CREATED_DESC\"}"

    Pagination result in JSON format

    -
    Response Schema: application/json
    Array
    id
    string <uuid> non-empty
    instanceId
    string <uuid>
    partitionId
    string <uuid>

    ID of the InfiniBand Partition associated with this interface

    -
    device
    string

    Name of the InfiniBand device associated with this interface

    -
    deviceInstance
    integer
    isPhysical
    boolean

    Indicates whether this is a physical interface

    -
    virtualFunctionId
    integer or null
    guid
    string or null
    status
    string (InfiniBandInterfaceStatus)
    Enum: "Pending" "Provisioning" "Ready" "Deleting" "Error"

    Status values for InfiniBand Interface objects

    -
    created
    string <date-time>
    updated
    string <date-time>

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]