Skip to content

Commit ac97074

Browse files
pjohnst5pjohnst5
committed
CNS API contracts for NUMA-Aware Pods
1 parent 2997eb4 commit ac97074

File tree

4 files changed

+212
-0
lines changed

4 files changed

+212
-0
lines changed

‎cns/api.go‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ import (
1111

1212
"github.com/Azure/azure-container-networking/cns/common"
1313
"github.com/Azure/azure-container-networking/cns/types"
14+
"github.com/Azure/azure-container-networking/cns/types/infiniband"
1415
"github.com/Azure/azure-container-networking/crd/nodenetworkconfig/api/v1alpha"
1516
"github.com/pkg/errors"
1617
)
@@ -32,6 +33,9 @@ const (
3233
V1Prefix = "/v0.1"
3334
V2Prefix = "/v0.2"
3435
EndpointPath = "/network/endpoints/"
36+
// IBDevice API paths
37+
IBDevicesPodPath = "/ibdevices/pod" // POST /ibdevices/pod
38+
IBDevicesPath = "/ibdevices/" // GET /ibdevices/{mac-address-of-device}
3539
// Service Fabric SWIFTV2 mode
3640
StandaloneSWIFTV2 SWIFTV2Mode = "StandaloneSWIFTV2"
3741
// K8s SWIFTV2 mode
@@ -382,3 +386,28 @@ type GetVMUniqueIDResponse struct {
382386
Response Response `json:"response"`
383387
VMUniqueID string `json:"vmuniqueid"`
384388
}
389+
390+
// IBDevice API Contracts
391+
392+
// AssignIBDevicesToPodRequest represents the request to assign InfiniBand devices to a pod
393+
// POST /ibdevices/pod
394+
type AssignIBDevicesToPodRequest struct {
395+
PodID string `json:"podID"` // podname-podnamespace format
396+
MACAddresses []string `json:"macAddresses"` // Array of MAC addresses like ["60:45:bd:a4:b5:7a", "7c:1e:52:07:11:36"]
397+
}
398+
399+
// AssignIBDevicesToPodResponse represents the response for assigning InfiniBand devices to a pod
400+
type AssignIBDevicesToPodResponse struct {
401+
ErrorCode infiniband.ErrorCode `json:"errorCode"` // Error code if applicable
402+
Message string `json:"message"` // Additional message or error description
403+
}
404+
405+
// GET /ibdevices/{mac-address-of-device}
406+
// GetIBDeviceStatusResponse represents the response containing InfiniBand device programming status
407+
type GetIBDeviceStatusResponse struct {
408+
MACAddress string `json:"macAddress"` // MAC address of the device
409+
PodID string `json:"podID"` // Pod that the device is assigned to
410+
Status infiniband.Status `json:"status"` // Device status (e.g., "pendingProgramming", "error", "programmed", "pendingDeletion", "available")
411+
ErrorCode infiniband.ErrorCode `json:"errorCode"` // Error code if applicable
412+
Message string `json:"message"` // Additional message or error description
413+
}

‎cns/swagger.yaml‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,69 @@ paths:
120120
schema:
121121
$ref: "#/components/schemas/UnpublishNetworkContainerResponse"
122122

123+
/ibdevices/pod:
124+
post:
125+
summary: Assigns IB devices to a pod
126+
description: >-
127+
Assigns the specified IB devices to the pod identified by PodID. The
128+
MAC addresses of the devices are provided in the request body.
129+
requestBody:
130+
required: true
131+
content:
132+
application/json:
133+
schema:
134+
$ref: "#/components/schemas/AssignIBDevicesToPodRequest"
135+
responses:
136+
'200':
137+
description: >-
138+
The request passed initial validation and CNS was able to propagate its state.
139+
content:
140+
application/json:
141+
schema:
142+
$ref: "#/components/schemas/AssignIBDevicesToPodResponse"
143+
'404':
144+
description: >-
145+
The pod specified by PodID was not found
146+
content:
147+
application/json:
148+
schema:
149+
$ref: "#/components/schemas/AssignIBDevicesToPodResponse"
150+
'400':
151+
description: >-
152+
One of the IB devices specified is not available
153+
content:
154+
application/json:
155+
schema:
156+
$ref: "#/components/schemas/AssignIBDevicesToPodResponse"
157+
158+
/ibdevices/{macaddress}:
159+
get:
160+
summary: Get status about an IB device
161+
description: >-
162+
Retrieves the current status of the specified IB device.
163+
parameters:
164+
- name: macaddress
165+
in: path
166+
required: true
167+
description: The MAC address of the IB device (with colons ":")
168+
schema:
169+
type: string
170+
responses:
171+
'200':
172+
description: >-
173+
The request was successful and the status of the IB device is returned.
174+
content:
175+
application/json:
176+
schema:
177+
$ref: "#/components/schemas/GetIBDeviceStatusResponse"
178+
'404':
179+
description: >-
180+
The IB device specified by MAC address was not found.
181+
content:
182+
application/json:
183+
schema:
184+
$ref: "#/components/schemas/GetIBDeviceStatusResponse"
185+
123186
components:
124187
schemas:
125188
UnpublishNetworkContainerResponse:
@@ -351,3 +414,99 @@ components:
351414
Message:
352415
type: string
353416
description: The error message
417+
418+
AssignIBDevicesToPodRequest:
419+
type: object
420+
required:
421+
- PodID
422+
- MACAddresses
423+
properties:
424+
PodID:
425+
type: string
426+
description: podname-podnamespace of which pod to attach these devices through
427+
MACAddresses:
428+
type: array
429+
description: MAC addresses of IB devices such as "60:45:bd:a4:b5:7a"
430+
items:
431+
type: string
432+
433+
AssignIBDevicesToPodResponse:
434+
type: object
435+
required:
436+
- ErrorCode
437+
- Message
438+
properties:
439+
ErrorCode:
440+
$ref: "#/components/schemas/ErrorCode"
441+
Message:
442+
type: string
443+
description: Human-readable message or error description
444+
445+
GetIBDeviceStatusResponse:
446+
type: object
447+
required:
448+
- MACAddress
449+
- PodID
450+
- Status
451+
- ErrorCode
452+
- Message
453+
properties:
454+
MACAddress:
455+
type: string
456+
description: MAC address of the IB device
457+
PodID:
458+
type: string
459+
description: podname-podnamespace of the pod to which the device is assigned, if any
460+
Status:
461+
$ref: "#/components/schemas/Status"
462+
ErrorCode:
463+
$ref: "#/components/schemas/ErrorCode"
464+
Message:
465+
type: string
466+
description: Human-readable message or error description
467+
468+
ErrorCode:
469+
type: integer
470+
description: Pre-defined error code of what went wrong, if anything (see cns/types/infiniband/errorcodes.go)
471+
oneOf:
472+
- title: Success
473+
const: 0
474+
description: Successful operation
475+
- title: PodNotFound
476+
const: 1
477+
description: Pod not found
478+
- title: DeviceUnavailable
479+
const: 2
480+
description: Device is unavailable
481+
- title: DeviceNotFound
482+
const: 3
483+
description: Device not found
484+
- title: AnnotationNotFound
485+
const: 4
486+
description: Annotation not found on pod
487+
- title: PodAlreadyAllocated
488+
const: 5
489+
description: Pod was already assigned IB devices (and new ones don't match)
490+
- title: InternalProgrammingError
491+
const: 6
492+
description: Something went wrong programming the devices
493+
494+
Status:
495+
type: integer
496+
description: Status of IB device (see cns/types/infiniband/status.go)
497+
oneOf:
498+
- title: ProgrammingPending
499+
const: 0
500+
description: Programming of device is pending
501+
- title: ProgrammingFailed
502+
const: 1
503+
description: Programming of device failed
504+
- title: ProgrammingComplete
505+
const: 2
506+
description: Programming of device is complete
507+
- title: ReleasePending
508+
const: 3
509+
description: Release of device is pending
510+
- title: Available
511+
const: 4
512+
description: Device is available for use

‎cns/types/infiniband/errorcodes.go‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
package infiniband
2+
3+
type ErrorCode int
4+
5+
const (
6+
Success ErrorCode = 0
7+
PodNotFound ErrorCode = 1
8+
DeviceUnavailable ErrorCode = 2
9+
DeviceNotFound ErrorCode = 3
10+
AnnotationNotFound ErrorCode = 4
11+
PodAlreadyAllocated ErrorCode = 5
12+
InternalProgrammingError ErrorCode = 6
13+
)

‎cns/types/infiniband/status.go‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
package infiniband
2+
3+
type Status int
4+
5+
const (
6+
ProgrammingPending Status = 0
7+
ProgrammingFailed Status = 1
8+
ProgrammingComplete Status = 2
9+
ReleasePending Status = 3
10+
Available Status = 4
11+
)

0 commit comments

Comments
 (0)