From ac970744090181f631ed6bf10768fc598c2684d9 Mon Sep 17 00:00:00 2001 From: Paul Johnston Date: Mon, 14 Jul 2025 20:09:26 +0000 Subject: [PATCH 1/5] CNS API contracts for NUMA-Aware Pods --- cns/api.go | 29 ++++++ cns/swagger.yaml | 159 +++++++++++++++++++++++++++++ cns/types/infiniband/errorcodes.go | 13 +++ cns/types/infiniband/status.go | 11 ++ 4 files changed, 212 insertions(+) create mode 100644 cns/types/infiniband/errorcodes.go create mode 100644 cns/types/infiniband/status.go diff --git a/cns/api.go b/cns/api.go index 6974a4207f..7f925d2515 100644 --- a/cns/api.go +++ b/cns/api.go @@ -11,6 +11,7 @@ import ( "github.com/Azure/azure-container-networking/cns/common" "github.com/Azure/azure-container-networking/cns/types" + "github.com/Azure/azure-container-networking/cns/types/infiniband" "github.com/Azure/azure-container-networking/crd/nodenetworkconfig/api/v1alpha" "github.com/pkg/errors" ) @@ -32,6 +33,9 @@ const ( V1Prefix = "/v0.1" V2Prefix = "/v0.2" EndpointPath = "/network/endpoints/" + // IBDevice API paths + IBDevicesPodPath = "/ibdevices/pod" // POST /ibdevices/pod + IBDevicesPath = "/ibdevices/" // GET /ibdevices/{mac-address-of-device} // Service Fabric SWIFTV2 mode StandaloneSWIFTV2 SWIFTV2Mode = "StandaloneSWIFTV2" // K8s SWIFTV2 mode @@ -382,3 +386,28 @@ type GetVMUniqueIDResponse struct { Response Response `json:"response"` VMUniqueID string `json:"vmuniqueid"` } + +// IBDevice API Contracts + +// AssignIBDevicesToPodRequest represents the request to assign InfiniBand devices to a pod +// POST /ibdevices/pod +type AssignIBDevicesToPodRequest struct { + PodID string `json:"podID"` // podname-podnamespace format + MACAddresses []string `json:"macAddresses"` // Array of MAC addresses like ["60:45:bd:a4:b5:7a", "7c:1e:52:07:11:36"] +} + +// AssignIBDevicesToPodResponse represents the response for assigning InfiniBand devices to a pod +type AssignIBDevicesToPodResponse struct { + ErrorCode infiniband.ErrorCode `json:"errorCode"` // Error code if applicable + Message string `json:"message"` // Additional message or error description +} + +// GET /ibdevices/{mac-address-of-device} +// GetIBDeviceStatusResponse represents the response containing InfiniBand device programming status +type GetIBDeviceStatusResponse struct { + MACAddress string `json:"macAddress"` // MAC address of the device + PodID string `json:"podID"` // Pod that the device is assigned to + Status infiniband.Status `json:"status"` // Device status (e.g., "pendingProgramming", "error", "programmed", "pendingDeletion", "available") + ErrorCode infiniband.ErrorCode `json:"errorCode"` // Error code if applicable + Message string `json:"message"` // Additional message or error description +} diff --git a/cns/swagger.yaml b/cns/swagger.yaml index 6ed3e0aefd..5cbfc3ab6a 100644 --- a/cns/swagger.yaml +++ b/cns/swagger.yaml @@ -120,6 +120,69 @@ paths: schema: $ref: "#/components/schemas/UnpublishNetworkContainerResponse" + /ibdevices/pod: + post: + summary: Assigns IB devices to a pod + description: >- + Assigns the specified IB devices to the pod identified by PodID. The + MAC addresses of the devices are provided in the request body. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/AssignIBDevicesToPodRequest" + responses: + '200': + description: >- + The request passed initial validation and CNS was able to propagate its state. + content: + application/json: + schema: + $ref: "#/components/schemas/AssignIBDevicesToPodResponse" + '404': + description: >- + The pod specified by PodID was not found + content: + application/json: + schema: + $ref: "#/components/schemas/AssignIBDevicesToPodResponse" + '400': + description: >- + One of the IB devices specified is not available + content: + application/json: + schema: + $ref: "#/components/schemas/AssignIBDevicesToPodResponse" + + /ibdevices/{macaddress}: + get: + summary: Get status about an IB device + description: >- + Retrieves the current status of the specified IB device. + parameters: + - name: macaddress + in: path + required: true + description: The MAC address of the IB device (with colons ":") + schema: + type: string + responses: + '200': + description: >- + The request was successful and the status of the IB device is returned. + content: + application/json: + schema: + $ref: "#/components/schemas/GetIBDeviceStatusResponse" + '404': + description: >- + The IB device specified by MAC address was not found. + content: + application/json: + schema: + $ref: "#/components/schemas/GetIBDeviceStatusResponse" + components: schemas: UnpublishNetworkContainerResponse: @@ -351,3 +414,99 @@ components: Message: type: string description: The error message + + AssignIBDevicesToPodRequest: + type: object + required: + - PodID + - MACAddresses + properties: + PodID: + type: string + description: podname-podnamespace of which pod to attach these devices through + MACAddresses: + type: array + description: MAC addresses of IB devices such as "60:45:bd:a4:b5:7a" + items: + type: string + + AssignIBDevicesToPodResponse: + type: object + required: + - ErrorCode + - Message + properties: + ErrorCode: + $ref: "#/components/schemas/ErrorCode" + Message: + type: string + description: Human-readable message or error description + + GetIBDeviceStatusResponse: + type: object + required: + - MACAddress + - PodID + - Status + - ErrorCode + - Message + properties: + MACAddress: + type: string + description: MAC address of the IB device + PodID: + type: string + description: podname-podnamespace of the pod to which the device is assigned, if any + Status: + $ref: "#/components/schemas/Status" + ErrorCode: + $ref: "#/components/schemas/ErrorCode" + Message: + type: string + description: Human-readable message or error description + + ErrorCode: + type: integer + description: Pre-defined error code of what went wrong, if anything (see cns/types/infiniband/errorcodes.go) + oneOf: + - title: Success + const: 0 + description: Successful operation + - title: PodNotFound + const: 1 + description: Pod not found + - title: DeviceUnavailable + const: 2 + description: Device is unavailable + - title: DeviceNotFound + const: 3 + description: Device not found + - title: AnnotationNotFound + const: 4 + description: Annotation not found on pod + - title: PodAlreadyAllocated + const: 5 + description: Pod was already assigned IB devices (and new ones don't match) + - title: InternalProgrammingError + const: 6 + description: Something went wrong programming the devices + + Status: + type: integer + description: Status of IB device (see cns/types/infiniband/status.go) + oneOf: + - title: ProgrammingPending + const: 0 + description: Programming of device is pending + - title: ProgrammingFailed + const: 1 + description: Programming of device failed + - title: ProgrammingComplete + const: 2 + description: Programming of device is complete + - title: ReleasePending + const: 3 + description: Release of device is pending + - title: Available + const: 4 + description: Device is available for use diff --git a/cns/types/infiniband/errorcodes.go b/cns/types/infiniband/errorcodes.go new file mode 100644 index 0000000000..7750d0e66d --- /dev/null +++ b/cns/types/infiniband/errorcodes.go @@ -0,0 +1,13 @@ +package infiniband + +type ErrorCode int + +const ( + Success ErrorCode = 0 + PodNotFound ErrorCode = 1 + DeviceUnavailable ErrorCode = 2 + DeviceNotFound ErrorCode = 3 + AnnotationNotFound ErrorCode = 4 + PodAlreadyAllocated ErrorCode = 5 + InternalProgrammingError ErrorCode = 6 +) diff --git a/cns/types/infiniband/status.go b/cns/types/infiniband/status.go new file mode 100644 index 0000000000..5c836ba7cf --- /dev/null +++ b/cns/types/infiniband/status.go @@ -0,0 +1,11 @@ +package infiniband + +type Status int + +const ( + ProgrammingPending Status = 0 + ProgrammingFailed Status = 1 + ProgrammingComplete Status = 2 + ReleasePending Status = 3 + Available Status = 4 +) From dd9404e835985bf22e54ebe45c3e3c7dd8fdc145 Mon Sep 17 00:00:00 2001 From: Paul Johnston Date: Wed, 30 Jul 2025 20:50:21 +0000 Subject: [PATCH 2/5] Addressing feedback --- cns/swagger.yaml | 18 +++++++++--------- cns/types/infiniband/status.go | 10 +++++----- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/cns/swagger.yaml b/cns/swagger.yaml index 5cbfc3ab6a..83e65a6348 100644 --- a/cns/swagger.yaml +++ b/cns/swagger.yaml @@ -157,7 +157,7 @@ paths: /ibdevices/{macaddress}: get: - summary: Get status about an IB device + summary: Get status of an IB device description: >- Retrieves the current status of the specified IB device. parameters: @@ -423,7 +423,7 @@ components: properties: PodID: type: string - description: podname-podnamespace of which pod to attach these devices through + description: podname-podnamespace of which pod to attach these devices to MACAddresses: type: array description: MAC addresses of IB devices such as "60:45:bd:a4:b5:7a" @@ -495,18 +495,18 @@ components: type: integer description: Status of IB device (see cns/types/infiniband/status.go) oneOf: - - title: ProgrammingPending + - title: Available const: 0 + description: Device is available for use + - title: ProgrammingPending + const: 1 description: Programming of device is pending - title: ProgrammingFailed - const: 1 + const: 2 description: Programming of device failed - title: ProgrammingComplete - const: 2 + const: 3 description: Programming of device is complete - title: ReleasePending - const: 3 - description: Release of device is pending - - title: Available const: 4 - description: Device is available for use + description: Release of device is pending diff --git a/cns/types/infiniband/status.go b/cns/types/infiniband/status.go index 5c836ba7cf..31f8149b42 100644 --- a/cns/types/infiniband/status.go +++ b/cns/types/infiniband/status.go @@ -3,9 +3,9 @@ package infiniband type Status int const ( - ProgrammingPending Status = 0 - ProgrammingFailed Status = 1 - ProgrammingComplete Status = 2 - ReleasePending Status = 3 - Available Status = 4 + Available Status = 0 + ProgrammingPending Status = 1 + ProgrammingFailed Status = 2 + ProgrammingComplete Status = 3 + ReleasePending Status = 4 ) From f8b02afc9537c475b757ef401c458cc4c5dd3836 Mon Sep 17 00:00:00 2001 From: Paul Johnston Date: Fri, 1 Aug 2025 19:48:16 +0000 Subject: [PATCH 3/5] only checking in the bare minimum to give structure to the APIs --- cns/api.go | 27 +++------ cns/swagger.yaml | 96 +++++++++++++----------------- cns/types/infiniband/errorcodes.go | 13 ---- 3 files changed, 50 insertions(+), 86 deletions(-) delete mode 100644 cns/types/infiniband/errorcodes.go diff --git a/cns/api.go b/cns/api.go index 7f925d2515..f60a01b113 100644 --- a/cns/api.go +++ b/cns/api.go @@ -33,9 +33,7 @@ const ( V1Prefix = "/v0.1" V2Prefix = "/v0.2" EndpointPath = "/network/endpoints/" - // IBDevice API paths - IBDevicesPodPath = "/ibdevices/pod" // POST /ibdevices/pod - IBDevicesPath = "/ibdevices/" // GET /ibdevices/{mac-address-of-device} + IBDevicesPath = "/ibdevices" // Service Fabric SWIFTV2 mode StandaloneSWIFTV2 SWIFTV2Mode = "StandaloneSWIFTV2" // K8s SWIFTV2 mode @@ -387,27 +385,16 @@ type GetVMUniqueIDResponse struct { VMUniqueID string `json:"vmuniqueid"` } -// IBDevice API Contracts - -// AssignIBDevicesToPodRequest represents the request to assign InfiniBand devices to a pod -// POST /ibdevices/pod -type AssignIBDevicesToPodRequest struct { - PodID string `json:"podID"` // podname-podnamespace format - MACAddresses []string `json:"macAddresses"` // Array of MAC addresses like ["60:45:bd:a4:b5:7a", "7c:1e:52:07:11:36"] -} - // AssignIBDevicesToPodResponse represents the response for assigning InfiniBand devices to a pod type AssignIBDevicesToPodResponse struct { - ErrorCode infiniband.ErrorCode `json:"errorCode"` // Error code if applicable - Message string `json:"message"` // Additional message or error description + Message string `json:"message"` // Additional message or error description } -// GET /ibdevices/{mac-address-of-device} // GetIBDeviceStatusResponse represents the response containing InfiniBand device programming status type GetIBDeviceStatusResponse struct { - MACAddress string `json:"macAddress"` // MAC address of the device - PodID string `json:"podID"` // Pod that the device is assigned to - Status infiniband.Status `json:"status"` // Device status (e.g., "pendingProgramming", "error", "programmed", "pendingDeletion", "available") - ErrorCode infiniband.ErrorCode `json:"errorCode"` // Error code if applicable - Message string `json:"message"` // Additional message or error description + MACAddress string `json:"macAddress"` // MAC address of the device + PodNamespace string `json:"podNamespace"` // Namespace of pod to which the device is assigned, if any + PodName string `json:"podName"` // Name of pod to which the device is assigned, if any + Status infiniband.Status `json:"status"` // Device status (e.g., "Available", "ProgrammingPending", etc.)" + Message string `json:"message"` // Additional message or error description } diff --git a/cns/swagger.yaml b/cns/swagger.yaml index 83e65a6348..983a01975f 100644 --- a/cns/swagger.yaml +++ b/cns/swagger.yaml @@ -120,18 +120,35 @@ paths: schema: $ref: "#/components/schemas/UnpublishNetworkContainerResponse" - /ibdevices/pod: + /ibdevices:assign: post: - summary: Assigns IB devices to a pod - description: >- - Assigns the specified IB devices to the pod identified by PodID. The - MAC addresses of the devices are provided in the request body. - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/AssignIBDevicesToPodRequest" + summary: Assign IB devices to a pod + description: > + Assigns one or more Infiniband devices by MAC address to a given pod. + parameters: + - name: ibmacs + in: query + required: true + description: Comma-separated list of IB device MAC addresses. + schema: + type: array + items: + type: string + example: ["60:45:bd:a4:b5:7a", "7c:1e:52:07:11:36"] + - name: podnamespace + in: query + required: true + description: The namespace of the target pod. + schema: + type: string + example: "podnamespace" + - name: podname + in: query + required: true + description: The name of the target pod. + schema: + type: string + example: "podname" responses: '200': description: >- @@ -142,31 +159,32 @@ paths: $ref: "#/components/schemas/AssignIBDevicesToPodResponse" '404': description: >- - The pod specified by PodID was not found + The pod specified by PodID was not found. content: application/json: schema: $ref: "#/components/schemas/AssignIBDevicesToPodResponse" '400': description: >- - One of the IB devices specified is not available + One of the IB devices specified is not available. content: application/json: schema: $ref: "#/components/schemas/AssignIBDevicesToPodResponse" - /ibdevices/{macaddress}: + /ibdevices: get: summary: Get status of an IB device description: >- - Retrieves the current status of the specified IB device. + Retrieves the current programming status of the specified IB device. parameters: - - name: macaddress - in: path + - name: ibmac + in: query required: true - description: The MAC address of the IB device (with colons ":") + description: The MAC address of the IB device. schema: type: string + example: "60:45:bd:a4:b5:7a" responses: '200': description: >- @@ -433,11 +451,8 @@ components: AssignIBDevicesToPodResponse: type: object required: - - ErrorCode - Message properties: - ErrorCode: - $ref: "#/components/schemas/ErrorCode" Message: type: string description: Human-readable message or error description @@ -446,50 +461,25 @@ components: type: object required: - MACAddress - - PodID + - PodNamespace + - PodName - Status - - ErrorCode - Message properties: MACAddress: type: string description: MAC address of the IB device - PodID: + PodNamespace: + type: string + description: namespace of the pod to which the device is assigned, if any + PodName: type: string - description: podname-podnamespace of the pod to which the device is assigned, if any + description: name of the pod to which the device is assigned, if any Status: $ref: "#/components/schemas/Status" - ErrorCode: - $ref: "#/components/schemas/ErrorCode" Message: type: string description: Human-readable message or error description - - ErrorCode: - type: integer - description: Pre-defined error code of what went wrong, if anything (see cns/types/infiniband/errorcodes.go) - oneOf: - - title: Success - const: 0 - description: Successful operation - - title: PodNotFound - const: 1 - description: Pod not found - - title: DeviceUnavailable - const: 2 - description: Device is unavailable - - title: DeviceNotFound - const: 3 - description: Device not found - - title: AnnotationNotFound - const: 4 - description: Annotation not found on pod - - title: PodAlreadyAllocated - const: 5 - description: Pod was already assigned IB devices (and new ones don't match) - - title: InternalProgrammingError - const: 6 - description: Something went wrong programming the devices Status: type: integer diff --git a/cns/types/infiniband/errorcodes.go b/cns/types/infiniband/errorcodes.go deleted file mode 100644 index 7750d0e66d..0000000000 --- a/cns/types/infiniband/errorcodes.go +++ /dev/null @@ -1,13 +0,0 @@ -package infiniband - -type ErrorCode int - -const ( - Success ErrorCode = 0 - PodNotFound ErrorCode = 1 - DeviceUnavailable ErrorCode = 2 - DeviceNotFound ErrorCode = 3 - AnnotationNotFound ErrorCode = 4 - PodAlreadyAllocated ErrorCode = 5 - InternalProgrammingError ErrorCode = 6 -) From 9533b513a1421470807ed17b753e01237eac5b6c Mon Sep 17 00:00:00 2001 From: Paul Johnston Date: Fri, 1 Aug 2025 19:49:01 +0000 Subject: [PATCH 4/5] hardware addr --- cns/api.go | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/cns/api.go b/cns/api.go index f60a01b113..b05cc24ef6 100644 --- a/cns/api.go +++ b/cns/api.go @@ -7,6 +7,7 @@ import ( "context" "encoding/json" "fmt" + "net" "time" "github.com/Azure/azure-container-networking/cns/common" @@ -392,7 +393,7 @@ type AssignIBDevicesToPodResponse struct { // GetIBDeviceStatusResponse represents the response containing InfiniBand device programming status type GetIBDeviceStatusResponse struct { - MACAddress string `json:"macAddress"` // MAC address of the device + MACAddress net.HardwareAddr `json:"macAddress"` // MAC address of the device PodNamespace string `json:"podNamespace"` // Namespace of pod to which the device is assigned, if any PodName string `json:"podName"` // Name of pod to which the device is assigned, if any Status infiniband.Status `json:"status"` // Device status (e.g., "Available", "ProgrammingPending", etc.)" From 1539d9a6f83459cb4aa8c733e7ce71f66045f314 Mon Sep 17 00:00:00 2001 From: Paul Johnston Date: Fri, 1 Aug 2025 19:51:09 +0000 Subject: [PATCH 5/5] remove unnecessary request body --- cns/swagger.yaml | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/cns/swagger.yaml b/cns/swagger.yaml index 983a01975f..743ed6cd02 100644 --- a/cns/swagger.yaml +++ b/cns/swagger.yaml @@ -433,21 +433,6 @@ components: type: string description: The error message - AssignIBDevicesToPodRequest: - type: object - required: - - PodID - - MACAddresses - properties: - PodID: - type: string - description: podname-podnamespace of which pod to attach these devices to - MACAddresses: - type: array - description: MAC addresses of IB devices such as "60:45:bd:a4:b5:7a" - items: - type: string - AssignIBDevicesToPodResponse: type: object required: