CNS API contracts for NUMA-Aware Pods (#3825)

* CNS API contracts for NUMA-Aware Pods

* Addressing feedback

* only checking in the bare minimum to give structure to the APIs

* hardware addr

* remove unnecessary request body

* Reference MTPNC Infiniband status

* Update swagger and comment in api.go

* changing ibmacs to request body

* ibmacaddresses

Author: pjohnst5

cns/api.go

@@ -7,10 +7,12 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"net"
 	"time"
 
 	"github.com/Azure/azure-container-networking/cns/common"
 	"github.com/Azure/azure-container-networking/cns/types"
+	"github.com/Azure/azure-container-networking/crd/multitenancy/api/v1alpha1"
 	"github.com/Azure/azure-container-networking/crd/nodenetworkconfig/api/v1alpha"
 	"github.com/pkg/errors"
 )
@@ -32,6 +34,7 @@ const (
 	V1Prefix                      = "/v0.1"
 	V2Prefix                      = "/v0.2"
 	EndpointPath                  = "/network/endpoints/"
+	IBDevicesPath                 = "/ibdevices"
 	// Service Fabric SWIFTV2 mode
 	StandaloneSWIFTV2 SWIFTV2Mode = "StandaloneSWIFTV2"
 	// K8s SWIFTV2 mode
@@ -382,3 +385,26 @@ type GetVMUniqueIDResponse struct {
 	Response   Response `json:"response"`
 	VMUniqueID string   `json:"vmuniqueid"`
 }
+
+// AssignIBDevicesToPodRequest represents the request for assigning InfiniBand devices to a pod
+type AssignIBDevicesToPodRequest struct {
+	IBMACAddresses []net.HardwareAddr `json:"ibmacaddresses"` // List of IB device MAC addresses to assign
+	PodNamespace   string             `json:"podNamespace"`   // Namespace of the target pod
+	PodName        string             `json:"podName"`        // Name of the target pod
+}
+
+// AssignIBDevicesToPodRequest
+
+// AssignIBDevicesToPodResponse represents the response for assigning InfiniBand devices to a pod
+type AssignIBDevicesToPodResponse struct {
+	Message string `json:"message"` // Additional message or error description
+}
+
+// GetIBDeviceStatusResponse represents the response containing InfiniBand device programming status
+type GetIBDeviceStatusResponse struct {
+	IBMACAddress net.HardwareAddr          `json:"ibmacaddress"` // IB device MAC address
+	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       v1alpha1.InfinibandStatus `json:"status"`       // Device status (e.g., "Unprogrammed", "Programming", "Programmed" etc.)"
+	Message      string                    `json:"message"`      // Additional message or error description
+}

cns/swagger.yaml

@@ -120,6 +120,67 @@ paths:
               schema:
                 $ref: "#/components/schemas/UnpublishNetworkContainerResponse"
 
+  /ibdevices:
+    post:
+      summary: Assign IB devices to a pod
+      description: >
+        Assigns one or more Infiniband devices by MAC address to a given pod.
+      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"
+    get:
+      summary: Get status of an IB device
+      description: >-
+        Retrieves the current programming status of the specified IB device.
+      parameters:
+        - name: ibmac
+          in: query
+          required: true
+          description: The MAC address of the IB device.
+          schema:
+            type: string
+            example: "60:45:bd:a4:b5:7a"
+      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 +412,65 @@ components:
         Message:
           type: string
           description: The error message
+
+    AssignIBDevicesToPodRequest:
+      type: object
+      required:
+        - ibmacaddresses
+        - podNamespace
+        - podName
+      properties:
+        ibmacaddresses:
+          type: array
+          items:
+            type: string
+          description: List of IB device MAC addresses to assign such as "60:45:bd:a4:b5:7a"
+        podNamespace:
+          type: string
+          description: Namespace of the target pod
+        podName:
+          type: string
+          description: Name of the target pod
+
+    AssignIBDevicesToPodResponse:
+      type: object
+      required:
+        - Message
+      properties:
+        Message:
+          type: string
+          description: Human-readable message or error description
+
+    GetIBDeviceStatusResponse:
+      type: object
+      required:
+        - IBMACAddress
+        - PodNamespace
+        - PodName
+        - Status
+        - Message
+      properties:
+        IBMACAddress:
+          type: string
+          description: MAC address of the IB device
+        PodNamespace:
+          type: string
+          description: namespace of the pod to which the device is assigned, if any
+        PodName:
+          type: string
+          description: name of the pod to which the device is assigned, if any
+        Status:
+          $ref: "#/components/schemas/Status"
+        Message:
+          type: string
+          description: Human-readable message or error description
+      
+    Status:
+      type: string
+      description: Status of IB device
+      enum:
+        - Unprogrammed
+        - Programming
+        - Programmed
+        - Unprogramming
+        - Failed