Skip to content

Commit 0564b6d

Browse files
pjohnst5pjohnst5
committed
CNS API contracts for NUMA-Aware Pods
1 parent 7d56d36 commit 0564b6d

File tree

6 files changed

+480
-0
lines changed

6 files changed

+480
-0
lines changed

‎cns/api.go‎

Lines changed: 34 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/" // PUT /ibdevices/pod/{podname-podnamespace}
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,33 @@ 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+
// PUT /ibdevices/pod/{podname-podnamespace}
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 types.ResponseCode `json:"errorCode"` // Error code if applicable
402+
Msg string `json:"msg"` // Additional message or error description
403+
}
404+
405+
// GetIBDeviceInfoRequest represents the request to get InfiniBand device information
406+
// GET /ibdevices/{mac-address-of-device} - no request body needed for GET
407+
type GetIBDeviceInfoRequest struct {
408+
MACAddress string `json:"macAddress"` // MAC address of the device (from URL path)
409+
}
410+
411+
// GetIBDeviceInfoResponse represents the response containing InfiniBand device information
412+
type GetIBDeviceInfoResponse struct {
413+
MACAddress string `json:"macAddress"` // MAC address of the device
414+
PodID string `json:"podID"` // Pod that the device is assigned to
415+
Status infiniband.Status `json:"status"` // Device status (e.g., "pendingProgramming", "error", "programmed", "pendingDeletion", "available")
416+
ErrorCode types.ResponseCode `json:"errorCode"` // Error code if applicable
417+
Msg string `json:"msg"` // Additional message or error description
418+
}

‎cns/grpc/cns.go‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,3 +26,33 @@ func (s *CNS) GetNodeInfo(_ context.Context, req *pb.NodeInfoRequest) (*pb.NodeI
2626
// todo: Implement the logic
2727
return &pb.NodeInfoResponse{}, nil
2828
}
29+
30+
// AssignIBDevicesToPod assigns InfiniBand devices to a pod via gRPC.
31+
func (s *CNS) AssignIBDevicesToPod(_ context.Context, req *pb.AssignIBDevicesToPodRequest) (*pb.AssignIBDevicesToPodResponse, error) {
32+
s.Logger.Info("AssignIBDevicesToPod called",
33+
zap.String("podID", req.GetPodID()),
34+
zap.Strings("deviceIDs", req.GetDeviceIds()))
35+
36+
// TODO: Implement the actual logic by calling the IBDeviceManager
37+
// For now, return a success response
38+
return &pb.AssignIBDevicesToPodResponse{
39+
ErrorCode: 0,
40+
Message: "InfiniBand devices assigned successfully",
41+
}, nil
42+
}
43+
44+
// GetIBDeviceInfo retrieves information about a specific InfiniBand device via gRPC.
45+
func (s *CNS) GetIBDeviceInfo(_ context.Context, req *pb.GetIBDeviceInfoRequest) (*pb.GetIBDeviceInfoResponse, error) {
46+
s.Logger.Info("GetIBDeviceInfo called",
47+
zap.String("deviceID", req.GetDeviceID()))
48+
49+
// TODO: Implement the actual logic by calling the IBDeviceManager
50+
// For now, return a placeholder response
51+
return &pb.GetIBDeviceInfoResponse{
52+
DeviceID: req.GetDeviceID(),
53+
PodID: "",
54+
Status: "Available",
55+
ErrorCode: 0,
56+
Msg: "Device information retrieved successfully",
57+
}, nil
58+
}

‎cns/grpc/proto/server.proto‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,12 @@ service CNS {
1515
// Retrieves detailed information about a specific node.
1616
// Primarily used for health checks.
1717
rpc GetNodeInfo(NodeInfoRequest) returns (NodeInfoResponse);
18+
19+
// Assigns InfiniBand devices to a pod.
20+
rpc AssignIBDevicesToPod(AssignIBDevicesToPodRequest) returns (AssignIBDevicesToPodResponse);
21+
22+
// Retrieves information about a specific InfiniBand device.
23+
rpc GetIBDeviceInfo(GetIBDeviceInfoRequest) returns (GetIBDeviceInfoResponse);
1824
}
1925

2026
// SetOrchestratorInfoRequest is the request message for setting the orchestrator information.
@@ -41,3 +47,29 @@ message NodeInfoResponse {
4147
string status = 5; // The current status of the node (e.g., running, stopped).
4248
string message = 6; // Additional information about the node's health or status.
4349
}
50+
51+
// AssignIBDevicesToPodRequest is the request message for assigning InfiniBand devices to a pod.
52+
message AssignIBDevicesToPodRequest {
53+
string podID = 1; // The pod ID in format podname-podnamespace.
54+
repeated string deviceIds = 2; // List of device MAC addresses.
55+
}
56+
57+
// AssignIBDevicesToPodResponse is the response message for assigning InfiniBand devices to a pod.
58+
message AssignIBDevicesToPodResponse {
59+
int32 errorCode = 1; // Error code (0 for success).
60+
string message = 2; // Response message.
61+
}
62+
63+
// GetIBDeviceInfoRequest is the request message for retrieving InfiniBand device information.
64+
message GetIBDeviceInfoRequest {
65+
string deviceID = 1; // The device ID (MAC address).
66+
}
67+
68+
// GetIBDeviceInfoResponse is the response message containing InfiniBand device information.
69+
message GetIBDeviceInfoResponse {
70+
string deviceID = 1; // The device ID (MAC address).
71+
string podID = 2; // The pod ID that the device is assigned to.
72+
string status = 3; // The status of the device.
73+
int32 errorCode = 4; // Error code if applicable.
74+
string msg = 5; // Additional message or error description.
75+
}

‎cns/types/infiniband/status.go‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
package infiniband
2+
3+
type Status int
4+
5+
// IBStatus definitions
6+
const (
7+
PendingProgramming Status = 0
8+
Error Status = 1
9+
Programmed Status = 2
10+
PendingDeletion Status = 3
11+
Available Status = 4
12+
)

‎docs/cns-ibdevice-api-contracts.md‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
# CNS IBDevice API Contracts
2+
3+
## Overview
4+
Two new APIs for managing InfiniBand devices in Azure Container Network Service (CNS):
5+
6+
1. **Assign IB Devices to Pod** - Assigns multiple InfiniBand devices to a pod
7+
2. **Get IB Device Info** - Retrieves information about a specific InfiniBand device
8+
9+
These APIs support **gRPC**, **REST**, and **Unix Domain Socket** transports based on `cnsconfig.GRPCSettings.Enable` configuration.
10+
11+
---
12+
13+
## API 1: Assign InfiniBand Devices to Pod
14+
15+
### Endpoint
16+
```
17+
PUT /ibdevices/pod/{podname-podnamespace}
18+
```
19+
20+
### Request Body
21+
```json
22+
{
23+
"podID": "my-pod-my-namespace",
24+
"deviceIds": ["60:45:bd:a4:b5:7a", "7c:1e:52:07:11:36"]
25+
}
26+
```
27+
28+
### Success Response
29+
```json
30+
{
31+
"response": {
32+
"errorCode": 0,
33+
"message": "Successfully assigned 2 devices to pod my-pod-my-namespace"
34+
}
35+
}
36+
```
37+
38+
### Error Response
39+
```json
40+
{
41+
"response": {
42+
"errorCode": 23,
43+
"message": "Device 60:45:bd:a4:b5:7a is already assigned to another pod"
44+
}
45+
}
46+
```
47+
48+
---
49+
50+
## API 2: Get InfiniBand Device Information
51+
52+
### Endpoint
53+
```
54+
GET /ibdevices/{mac-address-of-device}
55+
```
56+
57+
### Request
58+
No request body (MAC address provided in URL path)
59+
60+
### Success Response
61+
```json
62+
{
63+
"deviceID": "60:45:bd:a4:b5:7a",
64+
"podID": "my-pod-my-namespace",
65+
"status": "assigned",
66+
"errorCode": 0,
67+
"msg": ""
68+
}
69+
```
70+
71+
### Device Not Found Response
72+
```json
73+
{
74+
"deviceID": "60:45:bd:a4:b5:7a",
75+
"podID": "",
76+
"status": "",
77+
"errorCode": 14,
78+
"msg": "Device not found"
79+
}
80+
```
81+
82+
---
83+
84+
## Go Data Structures
85+
See [api.go](../cns/api.go)
86+
87+
- `AssignIBDevicesToPodRequest`
88+
- `AssignIBDevicesToPodResponse`
89+
- `GetIBDeviceInfoRequest`
90+
- `GetIBDeviceInfoResponse`
91+
92+
---
93+
94+
## gRPC Protocol Buffers
95+
96+
### Service Definition
97+
```protobuf
98+
service CNS {
99+
rpc AssignIBDevicesToPod(AssignIBDevicesToPodRequest) returns (AssignIBDevicesToPodResponse);
100+
rpc GetIBDeviceInfo(GetIBDeviceInfoRequest) returns (GetIBDeviceInfoResponse);
101+
}
102+
```
103+
104+
### Message Definitions
105+
```protobuf
106+
message AssignIBDevicesToPodRequest {
107+
string podID = 1; // podname-podnamespace
108+
repeated string deviceIds = 2; // MAC addresses
109+
}
110+
111+
message AssignIBDevicesToPodResponse {
112+
int32 returnCode = 1; // 0 for success
113+
string message = 2; // Response message
114+
}
115+
116+
message GetIBDeviceInfoRequest {
117+
string deviceID = 1; // MAC address
118+
}
119+
120+
message GetIBDeviceInfoResponse {
121+
string deviceID = 1; // MAC address
122+
string podID = 2; // Assigned pod
123+
string status = 3; // Device status
124+
int32 errorCode = 4; // Error code
125+
string msg = 5; // Additional message
126+
}
127+
```
128+
129+
---
130+
131+
## Unix Domain Socket Support
132+
133+
### Configuration
134+
```yaml
135+
cnsconfig:
136+
grpcSettings:
137+
enable: true
138+
socketPath: "/var/run/cns/grpc.sock"
139+
```
140+
141+
### gRPC Client Example
142+
```go
143+
conn, err := grpc.Dial("unix:///var/run/cns/grpc.sock", grpc.WithInsecure())
144+
client := pb.NewCNSClient(conn)
145+
146+
// Assign devices
147+
resp, err := client.AssignIBDevicesToPod(ctx, &pb.AssignIBDevicesToPodRequest{
148+
PodID: "my-pod-my-namespace",
149+
DeviceIds: []string{"60:45:bd:a4:b5:7a"},
150+
})
151+
```
152+
153+
---
154+
155+
## Response Codes
156+
157+
| Code | Name | Description |
158+
|------|-------------------|---------------------------------------|
159+
| 0 | Success | Operation completed successfully |
160+
| 23 | InvalidRequest | Invalid request parameters |
161+
| 14 | NotFound | Device not found |
162+
See [codes.go](../cns/types/codes.go)
163+
- Not all of these codes are relevant, but we will take from this list
164+
165+
---
166+
167+
## Path Constants
168+
169+
```go
170+
const (
171+
IBDevicesPodPath = "/ibdevices/pod/" // PUT /ibdevices/pod/{podname-podnamespace}
172+
IBDevicesPath = "/ibdevices/" // GET /ibdevices/{mac-address-of-device}
173+
)
174+
```

0 commit comments

Comments
 (0)