Skip to content

Commit cac7003

Browse files
adyeungadyeung
authored
Merge pull request #1727 from nagarwal03/ss-pc-hld-internal-review
HLD document for portchannel interface (#2)
2 parents 6056424 + 39e4161 commit cac7003

File tree

1 file changed

+322
-0
lines changed

1 file changed

+322
-0
lines changed

‎doc/mgmt/OpenConfig_PortChannel_Interface.md

+322
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,322 @@
1+
# OpenConfig support for PortChannel (aggregate) interface.
2+
3+
# High Level Design Document
4+
#### Rev 0.1
5+
6+
# Table of Contents
7+
* [List of Tables](#list-of-tables)
8+
* [Revision](#revision)
9+
* [About This Manual](#about-this-manual)
10+
* [Scope](#scope)
11+
* [Definition/Abbreviation](#definitionabbreviation)
12+
* [1 Feature Overview](#1-feature-overview)
13+
* [1.1 Requirements](#11-requirements)
14+
* [1.1.1 Functional Requirements](#111-functional-requirements)
15+
* [1.1.2 Configuration and Management Requirements](#112-configuration-and-management-requirements)
16+
* [1.2 Design Overview](#12-design-overview)
17+
* [1.2.1 Basic Approach](#121-basic-approach)
18+
* [1.2.2 Container](#122-container)
19+
* [2 Functionality](#2-functionality)
20+
* [2.1 Target Deployment Use Cases](#21-target-deployment-use-cases)
21+
* [3 Design](#3-design)
22+
* [3.1 Overview](#31-overview)
23+
* [3.2 DB Changes](#32-db-changes)
24+
* [3.2.1 CONFIG DB](#321-config-db)
25+
* [3.2.2 APP DB](#322-app-db)
26+
* [3.2.3 STATE DB](#323-state-db)
27+
* [3.2.4 ASIC DB](#324-asic-db)
28+
* [3.2.5 COUNTER DB](#325-counter-db)
29+
* [3.3 User Interface](#33-user-interface)
30+
* [3.3.1 REST API Support](#332-rest-api-support)
31+
* [3.3.2 gNMI Support](#333-gnmi-support)
32+
* [4 Flow Diagrams](#4-flow-diagrams)
33+
* [5 Error Handling](#5-error-handling)
34+
* [6 Unit Test Cases](#6-unit-test-cases)
35+
* [6.1 Functional Test Cases](#61-functional-test-cases)
36+
* [6.2 Negative Test Cases](#62-negative-test-cases)
37+
38+
# List of Tables
39+
[Table 1: Abbreviations](#table-1-abbreviations)
40+
[Table 2: OC YANG SONiC YANG Mapping](#4-flow-diagrams)
41+
42+
# Revision
43+
| Rev | Date | Author | Change Description |
44+
|:---:|:-----------:|:---------------------:|-----------------------------------|
45+
| 0.1 | 02/24/2024 | Satoru Shinohara | Initial version |
46+
47+
# About this Manual
48+
This document provides general information about the OpenConfig configuration of portchannel (aggregate) interface in SONiC.
49+
50+
# Scope
51+
- This document describes the high level design of configuration of portchannel interfaces using openconfig models via REST & gNMI.
52+
- This does not cover the SONiC KLISH CLI.
53+
- This covers only the portchannel interfaces configuration.
54+
- This does not support subinterfaces configuration.
55+
- Supported attributes in OpenConfig YANG tree:
56+
57+
```
58+
module: openconfig-interfaces
59+
+--rw interfaces
60+
+--rw interface* [name]
61+
+--rw name -> ../config/name
62+
+--rw config
63+
| +--rw name? string
64+
| +--rw mtu? uint16
65+
| +--rw description? string
66+
| +--rw enabled? boolean
67+
+--ro state
68+
| +--ro name? string
69+
| +--ro mtu? uint16
70+
| +--ro description? string
71+
| +--ro enabled? boolean
72+
| +--ro admin-status enumeration
73+
| +--ro counters
74+
| +--ro in-octets? oc-yang:counter64
75+
| +--ro in-pkts? oc-yang:counter64
76+
| +--ro in-unicast-pkts? oc-yang:counter64
77+
| +--ro in-broadcast-pkts? oc-yang:counter64
78+
| +--ro in-multicast-pkts? oc-yang:counter64
79+
| +--ro in-discards? oc-yang:counter64
80+
| +--ro in-errors? oc-yang:counter64
81+
| +--ro out-octets? oc-yang:counter64
82+
| +--ro out-pkts? oc-yang:counter64
83+
| +--ro out-unicast-pkts? oc-yang:counter64
84+
| +--ro out-broadcast-pkts? oc-yang:counter64
85+
| +--ro out-multicast-pkts? oc-yang:counter64
86+
| +--ro out-discards? oc-yang:counter64
87+
| +--ro out-errors? oc-yang:counter64
88+
+--rw subinterfaces
89+
| +--rw subinterface* [index]
90+
| +--rw index -> ../config/index
91+
| +--rw config
92+
| | +--rw index? uint32
93+
| | +--rw description? string
94+
| | +--rw enabled? boolean
95+
| +--ro state
96+
| | +--ro index? uint32
97+
| | +--ro description? string
98+
| | +--ro enabled? boolean
99+
| +--rw oc-ip:ipv4
100+
| | +--rw oc-ip:addresses
101+
| | +--rw oc-ip:address* [ip]
102+
| | +--rw oc-ip:ip -> ../config/ip
103+
| | +--rw oc-ip:config
104+
| | | +--rw oc-ip:ip? oc-inet:ipv4-address
105+
| | | +--rw oc-ip:prefix-length? uint8
106+
| | +--ro oc-ip:state
107+
| | +--ro oc-ip:ip? oc-inet:ipv4-address
108+
| | +--ro oc-ip:prefix-length? uint8
109+
| +--rw oc-ip:ipv6
110+
| +--rw oc-ip:addresses
111+
| | +--rw oc-ip:address* [ip]
112+
| | +--rw oc-ip:ip -> ../config/ip
113+
| | +--rw oc-ip:config
114+
| | | +--rw oc-ip:ip? oc-inet:ipv6-address
115+
| | | +--rw oc-ip:prefix-length uint8
116+
| | +--ro oc-ip:state
117+
| | +--ro oc-ip:ip? oc-inet:ipv6-address
118+
| | +--ro oc-ip:prefix-length uint8
119+
| +--rw oc-ip:config
120+
| | +--rw oc-ip:enabled? boolean
121+
| +--ro oc-ip:state
122+
| +--ro oc-ip:enabled? boolean
123+
+--rw oc-eth:ethernet
124+
| +--rw oc-eth:config
125+
| | +--rw oc-eth:auto-negotiate? boolean
126+
| | +--rw oc-eth:port-speed? identityref
127+
| | +--rw oc-lag:aggregate-id? -> /oc-if:interfaces/interface/name
128+
| +--ro oc-eth:state
129+
| +--ro oc-eth:auto-negotiate? boolean
130+
| +--ro oc-eth:port-speed? identityref
131+
| +--ro oc-eth:counters
132+
| | +--ro oc-eth:in-oversize-frames? oc-yang:counter64
133+
| | +--ro oc-eth:in-undersize-frames? oc-yang:counter64
134+
| | +--ro oc-eth:in-jabber-frames? oc-yang:counter64
135+
| | +--ro oc-eth:in-fragment-frames? oc-yang:counter64
136+
| +--ro oc-lag:aggregate-id? -> /oc-if:interfaces/interface/name
137+
+--rw oc-lag:aggregation
138+
+--rw oc-lag:config
139+
| +--rw oc-lag:min-links? uint16
140+
+--ro oc-lag:state
141+
+--ro oc-lag:min-links? uint16
142+
```
143+
# Definition/Abbreviation
144+
### Table 1: Abbreviations
145+
| **Term** | **Definition** |
146+
|--------------------------|-------------------------------------|
147+
| YANG | Yet Another Next Generation: modular language representing data structures in an XML tree format |
148+
| REST | REpresentative State Transfer |
149+
| gNMI | gRPC Network Management Interface: used to retrieve or manipulate the state of a device via telemetry or configuration data |
150+
| XML | eXtensible Markup Language |
151+
| Aggregate | Interchangable with portchannel |
152+
153+
154+
# 1 Feature Overview
155+
## 1.1 Requirements
156+
### 1.1.1 Functional Requirements
157+
1. Provide support for OpenConfig YANG models.
158+
2. Configure/Set, GET, and Delete PortChannel interface attributes.
159+
3. Support min-links attribute on PortChannel interfaces via REST and gNMI.
160+
4. Support interface attributes on PortChannel type.
161+
### 1.1.2 Configuration and Management Requirements
162+
The PortChannel interface configurations can be done via REST and gNMI. The implementation will return an error if configuration is not allowed due to misconfiguration. There are no new configuration commands required to handle these configurations.
163+
164+
## 1.2 Design Overview
165+
### 1.2.1 Basic Approach
166+
SONiC already supports PortChannel interfaces configurations such as Get, Patch and Delete via REST and gNMI. This feature adds support for OpenConfig based YANG models using transformer based implementation instead of translib infra.
167+
### 1.2.2 Container
168+
The code changes for this feature are part of *Management Framework* container which includes the REST server and *gnmi* container for gNMI support in *sonic-mgmt-common* repository.
169+
170+
# 2 Functionality
171+
## 2.1 Target Deployment Use Cases
172+
1. REST client through which the user can perform POST, PUT, PATCH, DELETE, GET operations on the supported YANG paths.
173+
2. gNMI client with support for capabilities get and set based on the supported YANG models.
174+
175+
# 3 Design
176+
## 3.1 Overview
177+
This HLD design is in line with the [Management Framework HLD](https://github.com/project-arlo/SONiC/blob/354e75b44d4a37b37973a3a36b6f55141b4b9fdf/doc/mgmt/Management%20Framework.md)
178+
179+
## 3.2 DB Changes
180+
### 3.2.1 CONFIG DB
181+
There are no changes to CONFIG DB schema definition.
182+
### 3.2.2 APP DB
183+
There are no changes to APP DB schema definition.
184+
### 3.2.3 STATE DB
185+
There are no changes to STATE DB schema definition.
186+
### 3.2.4 ASIC DB
187+
There are no changes to ASIC DB schema definition.
188+
### 3.2.5 COUNTER DB
189+
There are no changes to COUNTER DB schema definition.
190+
191+
## 3.3 User Interface
192+
### 3.3.1 REST API Support
193+
#### 3.3.1.1 GET
194+
Supported at leaf level as well.
195+
Sample GET output on configured PortChannel:
196+
```
197+
curl -X GET -k "https://100.94.113.103/restconf/data/openconfig-interfaces:interfaces/interface=PortChannel103" -H "accept: application/yang-data+json"
198+
{"openconfig-interfaces:interface":[{"openconfig-if-aggregate:aggregation":{"config":{"min-links":1},"state":{"min-links":1}},"config":{"enabled":true,"mtu":9100,"name":"PortChannel103"},"name":"PortChannel103","state":{"admin-status":"UP","enabled":true,"mtu":9100,"name":"PortChannel103"},"subinterfaces":{"subinterface":[{"config":{"index":0},"index":0,"openconfig-if-ip:ipv6":{"config":{"enabled":false},"state":{"enabled":false}},"state":{"index":0}}]}}]}
199+
```
200+
Sample GET output of Ethernet interface configured as part of PortChannel:
201+
```
202+
curl -X GET -k "https://100.94.113.103/restconf/data/openconfig-interfaces:interfaces/interface=Ethernet257" -H "accept: application/yang-data+json"
203+
{"openconfig-interfaces:interface":[{"config":{"enabled":true,"mtu":9100,"name":"Ethernet257"},"openconfig-if-ethernet:ethernet":{"config":{"openconfig-if-aggregate:aggregate-id":"PortChannel103","port-speed":"openconfig-if-ethernet:SPEED_10GB"},"state":{"openconfig-if-aggregate:aggregate-id":"PortChannel103","counters":{"openconfig-if-ethernet-ext:in-distribution":{"in-frames-1024-1518-octets":"0","in-frames-128-255-octets":"0","in-frames-256-511-octets":"0","in-frames-512-1023-octets":"0","in-frames-64-octets":"0","in-frames-65-127-octets":"0"},"in-fragment-frames":"0","in-jabber-frames":"0","in-oversize-frames":"0","in-undersize-frames":"0"},"port-speed":"openconfig-if-ethernet:SPEED_10GB"}},"name":"Ethernet257","state":{"admin-status":"UP","counters":{"in-broadcast-pkts":"0","in-discards":"0","in-errors":"0","in-multicast-pkts":"0","in-octets":"0","in-pkts":"0","in-unicast-pkts":"0","out-broadcast-pkts":"0","out-discards":"0","out-errors":"0","out-multicast-pkts":"0","out-octets":"0","out-pkts":"0","out-unicast-pkts":"0"},"description":"","enabled":true,"mtu":9100,"name":"Ethernet257"},"subinterfaces":{"subinterface":[{"config":{"index":0},"index":0,"openconfig-if-ip:ipv6":{"config":{"enabled":false},"state":{"enabled":false}},"state":{"index":0}}]}}]}
204+
```
205+
#### 3.3.1.2 SET
206+
Supported at leaf level as well.
207+
Sample PUT to configure a new PortChannel Interface
208+
```
209+
curl -X PUT -k "https://100.94.113.103/restconf/data/openconfig-interfaces:interfaces/interface=PortChannel105" -H "accept: */*" -H "Content-Type: application/yang-data+json" -d "{\"openconfig-int
210+
erfaces:interface\":[{\"name\":\"PortChannel105\",\"config\":{\"name\":\"PortChannel105\",\"mtu\":9000,\"description\":\"tst_pc\",\"enabled\":true},\"openconfig-if-aggregate:aggregation\":{\"config\":{\"min-links\":3}}}]}"
211+
```
212+
Sample Verify PortChannel PUT with GET:
213+
```
214+
curl -X GET -k "https://100.94.113.103/restconf/data/openconfig-interfaces:interfaces/interface=PortChannel105" -H "accept: application/yang-data+json"
215+
{"openconfig-interfaces:interface":[{"openconfig-if-aggregate:aggregation":{"config":{"min-links":3},"state":{"min-links":3}},"config":{"description":"tst_pc","enabled":true,"mtu":9000,"name":"PortChannel105"},"name":"PortChannel105","state":{"admin-status":"UP","enabled":true,"mtu":9000,"name":"PortChannel105"},"subinterfaces":{"subinterface":[{"config":{"index":0},"index":0,"openconfig-if-ip:ipv6":{"config":{"enabled":false},"state":{"enabled":false}},"state":{"index":0}}]}}]}
216+
```
217+
218+
#### 3.3.1.3 PATCH
219+
Supported at leaf level as well.
220+
Illustration for PATCH at leaf level min-links:
221+
```
222+
curl -X PATCH -k "https://100.94.113.103/restconf/data/openconfig-interfaces:interfaces/interface=PortChannel105/openconfig-if-aggregate:aggregation/config/min-links" -H "accept: */*" -H "Content-
223+
Type: application/yang-data+json" -d "{\"openconfig-if-aggregate:min-links\":1}"
224+
```
225+
226+
Sample Verify PortChannel PATCH with GET:
227+
```
228+
curl -X GET -k "https://100.94.113.103/restconf/data/openconfig-interfaces:interfaces/interface=PortChannel105/openconfig-if-aggregate:aggregation" -H "accept: application/yang-data+json"
229+
{"openconfig-if-aggregate:aggregation":{"config":{"min-links":1},"state":{"min-links":1}}}
230+
```
231+
232+
#### 3.3.1.3 DELETE
233+
Supported at leaf level as well.
234+
Example for DELETE of PortChannel interface:
235+
```
236+
curl -X DELETE -k "https://100.94.113.103/restconf/data/openconfig-interfaces:interfaces/interface=PortChannel105" -H "accept: */*"
237+
```
238+
239+
### 3.3.2 gNMI Support
240+
#### 3.3.2.1 GET
241+
Supported
242+
#### 3.3.2.2 SET
243+
Supported
244+
#### 3.3.2.3 DELETE
245+
Supported
246+
247+
### 3.3.3 gNMI Subscription Support
248+
#### 3.3.3.1 On Change
249+
```
250+
root@sonic:/# gnmi_cli -insecure -logtostderr -address 100.94.113.103:8080 -query_type s -streaming_type ON_CHANGE -v 0 -target OC-YANG -q /openconfig-interfaces:interfaces/interface[name=PortChannel103]/config
251+
```
252+
#### 3.3.3.2 SAMPLE
253+
```
254+
root@sonic:/# gnmi_cli -insecure -logtostderr -address 100.94.113.103:8080 -query_type s -streaming_type SAMPLE -target OC-YANG -q /openconfig-interfaces:interfaces/interface[name=PortChannel103]/config -heartbeat_interval 20
255+
```
256+
#### 3.3.3.4 Target Defined
257+
```
258+
root@sonic:/# gnmi_cli -insecure -logtostderr -address 100.94.113.103:8080 -with_user_pass -query_type s -target OC-YANG -q /openconfig-interfaces:interfaces/interface[name=PortChannel103]/config
259+
```
260+
Example Output:
261+
```
262+
{
263+
"OC-YANG": {
264+
"openconfig-interfaces:interfaces": {
265+
"interface": {
266+
"PortChannel103": {
267+
"config": {
268+
"enabled": true,
269+
"mtu": 9100,
270+
"name": "PortChannel103"
271+
}
272+
}
273+
}
274+
}
275+
}
276+
},
277+
{
278+
"OC-YANG": {
279+
"openconfig-interfaces:interfaces": {
280+
"interface": {
281+
"PortChannel103": {
282+
"config": {
283+
"description": "tst_target"
284+
}
285+
}
286+
}
287+
}
288+
}
289+
},
290+
291+
```
292+
293+
# 4 Flow Diagrams
294+
Mapping attributes between OpenConfig YANG and SONiC YANG:
295+
| OpenConfig YANG | Sonic-port YANG |
296+
|-------------------------|-----------------------|
297+
| name | name |
298+
| auto-negotiate | autoneg |
299+
| port-speed | speed |
300+
| description | description |
301+
| mtu | mtu |
302+
| enabled | admin-status |
303+
| index | index |
304+
305+
| OpenConfig YANG | Sonic-interface YANG |
306+
|-------------------------|-------------------------|
307+
| name | name |
308+
| min-links | min_links |
309+
310+
# 5 Error Handling
311+
Invalid configurations will report an error.
312+
# 6 Unit Test cases
313+
## 6.1 Functional Test Cases
314+
1. Create and verify new PortChannel interface using PUT and GET via REST and gNMI.
315+
2. Add Ethernet member to PortChannel using PATCH of aggregate-id on Ethernet Interface via REST and gNMI
316+
3. Verify the addition of member interface using GET on Ethernet Config.
317+
4. Verify PATCH, GET, and DELETE of PortChannel attribute min-links via REST and gNMI.
318+
5. Verify PATCH, GET, and DELETE of interface attributes for PortChannel (name, mtu, enabled, and description)
319+
320+
## 6.2 Negative Test Cases
321+
1. Verify GET after DELETE returns a "Resource Not Found" Error.
322+
2. Verify setting min-links to 0 returns an Error.

0 commit comments

Comments
 (0)