Skip to content

Commit 0fa18e4

Browse files
soumya-gargarisoumya-gargari
committed
Added support for Openconfig_L3SubInterface initial HLD
## Overview This document describes the implementation of L3 SubInterface functionality in SONiC using OpenConfig YANG models. The feature enables configuration of VLAN-tagged subinterfaces with IPv4/IPv6 addresses through gNMI/REST APIs. ### Key Features - **VLAN SubInterface Creation**: Support for VLAN-tagged subinterfaces with index > 0 - **L3 Address Configuration**: IPv4 and IPv6 address assignment on subinterfaces - **Database Integration**: Mapping to SONiC `VLAN_SUB_INTERFACE` and `INTERFACE` tables - **CRUD Operations**: Complete support for CREATE, READ, UPDATE, DELETE operations - **Index-based Logic**: Different behavior for index 0 vs index > 0 Signed-off-by: Soumya Gargari <[email protected]>
1 parent e74a6a8 commit 0fa18e4

File tree

1 file changed

+382
-0
lines changed

1 file changed

+382
-0
lines changed

‎doc/mgmt/Openconfig_L3SubInterface.md‎

Lines changed: 382 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,382 @@
1+
# L3 SubInterface Implementation High-Level Design
2+
3+
## Revision History
4+
5+
| Rev | Date | Author | Change Description |
6+
|:---:|:-----------:|:---------------------:|-----------------------------------|
7+
| 0.1 | 12/03/2025 | Soumya Gargari | Initial version |
8+
9+
## Table of Contents
10+
11+
1. [Overview](#overview)
12+
2. [Feature Requirements](#feature-requirements)
13+
3. [Database Schema](#database-schema)
14+
4. [YANG Model Mapping](#yang-model-mapping)
15+
5. [API Examples](#api-examples)
16+
6. [Error Handling](#error-handling)
17+
7. [Performance and Scaling](#performance-and-scaling)
18+
8. [References](#references)
19+
20+
## Overview
21+
22+
This document describes the implementation of L3 SubInterface functionality in SONiC using OpenConfig YANG models. The feature enables configuration of VLAN-tagged subinterfaces with IPv4/IPv6 addresses through gNMI/REST APIs.
23+
24+
### Key Features
25+
26+
- **VLAN SubInterface Creation**: Support for VLAN-tagged subinterfaces with index > 0
27+
- **L3 Address Configuration**: IPv4 and IPv6 address assignment on subinterfaces
28+
- **Database Integration**: Mapping to SONiC `VLAN_SUB_INTERFACE` and `INTERFACE` tables
29+
- **CRUD Operations**: Complete support for CREATE, READ, UPDATE, DELETE operations
30+
- **Index-based Logic**: Different behavior for index 0 vs index > 0
31+
32+
## Feature Requirements
33+
34+
### Functional Requirements
35+
36+
1. **SubInterface Creation**
37+
- Create VLAN subinterfaces with configurable index values
38+
- Support VLAN ID assignment to subinterfaces
39+
- Handle parent interface dependency validation
40+
41+
2. **L3 Address Management**
42+
- Configure IPv4 addresses with prefix length
43+
- Configure IPv6 addresses with prefix length
44+
- Support multiple addresses per subinterface
45+
46+
3. **Database Mapping**
47+
- Map to `VLAN_SUB_INTERFACE` table for index > 0
48+
- Map to `INTERFACE` table for L3 addresses
49+
- Maintain proper key formatting and relationships
50+
51+
4. **API Support**
52+
- gNMI SET/GET/DELETE operations
53+
- REST API PATCH/PUT/POST/DELETE operations
54+
- Proper error handling and validation
55+
56+
### Non-Functional Requirements
57+
58+
- **Performance**: Efficient handling of multiple subinterfaces
59+
- **Scalability**: Support for large numbers of subinterfaces per port
60+
- **Reliability**: Consistent database state management
61+
- **Maintainability**: Clean transformer code with proper error handling
62+
63+
## Architecture and Design
64+
65+
The L3 SubInterface feature follows SONiC's standard management architecture, utilizing OpenConfig YANG models for northbound API compatibility and mapping to SONiC native database schema. The implementation supports VLAN-tagged subinterfaces with configurable index values and proper L3 address assignment.
66+
67+
### Core Logic
68+
69+
- **Index-based Behavior**: Different table mapping based on subinterface index
70+
- Index 0: Uses main `INTERFACE` table
71+
- Index > 0: Uses `VLAN_SUB_INTERFACE` table for VLAN tagging
72+
- **Database Integration**: Seamless mapping to SONiC CONFIG_DB tables
73+
- **Address Family Support**: Both IPv4 and IPv6 address configuration
74+
- **Dependency Management**: Proper validation of parent interface existence
75+
76+
## Database Schema
77+
78+
### VLAN_SUB_INTERFACE Table
79+
80+
**Purpose**: Stores VLAN subinterface configuration for index > 0
81+
82+
**Key Format**: `{interface_name}.{index}`
83+
84+
**Example Keys**:
85+
```
86+
VLAN_SUB_INTERFACE|Ethernet4.100
87+
VLAN_SUB_INTERFACE|Ethernet8.200
88+
```
89+
90+
**Fields**:
91+
- `vlan`: VLAN ID for the subinterface
92+
- `NULL`: Placeholder when no VLAN is configured
93+
94+
**Example Data**:
95+
```json
96+
{
97+
"VLAN_SUB_INTERFACE": {
98+
"Ethernet4.100": {
99+
"vlan": "100"
100+
},
101+
"Ethernet8.200": {
102+
"vlan": "200"
103+
}
104+
}
105+
}
106+
```
107+
108+
### INTERFACE Table
109+
110+
**Purpose**: Stores L3 address configuration
111+
112+
**Key Format**: `{interface_name}|{ip_address}/{prefix_length}`
113+
114+
**Example Keys**:
115+
```
116+
INTERFACE|Ethernet4|1.1.0.124/32
117+
INTERFACE|Ethernet8|2001:db8::1/64
118+
```
119+
120+
**Fields**:
121+
- `family`: Address family (IPv4 or IPv6)
122+
123+
**Example Data**:
124+
```json
125+
{
126+
"INTERFACE": {
127+
"Ethernet4|1.1.0.124/32": {
128+
"NULL": "NULL"
129+
},
130+
"Ethernet8|2001:db8::1/64": {
131+
"family": "IPv6"
132+
}
133+
}
134+
}
135+
```
136+
137+
## YANG Model Mapping
138+
139+
### OpenConfig Paths
140+
141+
#### SubInterface Configuration
142+
```
143+
/openconfig-interfaces:interfaces/interface[name=<INTF>]/subinterfaces/subinterface[index=<INDEX>]
144+
```
145+
146+
#### VLAN Configuration
147+
```
148+
/openconfig-interfaces:interfaces/interface[name=<INTF>]/subinterfaces/subinterface[index=<INDEX>]/vlan/config/vlan-id
149+
```
150+
151+
#### IPv4 Address Configuration
152+
```
153+
/openconfig-interfaces:interfaces/interface[name=<INTF>]/subinterfaces/subinterface[index=<INDEX>]/ipv4/addresses/address[ip=<IP>]/config
154+
```
155+
156+
#### IPv6 Address Configuration
157+
```
158+
/openconfig-interfaces:interfaces/interface[name=<INTF>]/subinterfaces/subinterface[index=<INDEX>]/ipv6/addresses/address[ip=<IP>]/config
159+
```
160+
161+
## Transformer Implementation
162+
163+
The L3 SubInterface feature utilizes SONiC's transformer framework to map OpenConfig YANG model to native SONiC database schema. The implementation includes proper validation, database key generation, and atomic transaction handling.
164+
165+
## API Examples
166+
167+
### Create SubInterface with VLAN
168+
169+
**gNMI Command**:
170+
```bash
171+
gnmic -a 192.168.1.1:8080 -u admin -p admin --insecure set \
172+
--update-path "/openconfig-interfaces:interfaces/interface[name=Ethernet4]/subinterfaces/subinterface[index=100]" \
173+
--update-file subintf.json
174+
```
175+
176+
**JSON Payload** (`subintf.json`):
177+
```json
178+
{
179+
"openconfig-interfaces:subinterface": [
180+
{
181+
"index": 100,
182+
"config": {
183+
"index": 100
184+
},
185+
"vlan": {
186+
"config": {
187+
"vlan-id": 100
188+
}
189+
},
190+
"ipv4": {
191+
"addresses": {
192+
"address": [
193+
{
194+
"ip": "1.1.0.124",
195+
"config": {
196+
"ip": "1.1.0.124",
197+
"prefix-length": 32
198+
}
199+
}
200+
]
201+
}
202+
}
203+
}
204+
]
205+
}
206+
```
207+
208+
**Expected Database Result**:
209+
```bash
210+
redis-cli -n 4 HGETALL "VLAN_SUB_INTERFACE|Ethernet4.100"
211+
1) "vlan"
212+
2) "100"
213+
214+
redis-cli -n 4 HGETALL "INTERFACE|Ethernet4|1.1.0.124/32"
215+
1) "NULL"
216+
2) "NULL"
217+
```
218+
219+
### Create IPv6 SubInterface
220+
221+
**gNMI Command**:
222+
```bash
223+
gnmic -a 192.168.1.1:8080 -u admin -p admin --insecure set \
224+
--update-path "/openconfig-interfaces:interfaces/interface[name=Ethernet8]/subinterfaces/subinterface[index=200]" \
225+
--update-file subintf_ipv6.json
226+
```
227+
228+
**JSON Payload** (`subintf_ipv6.json`):
229+
```json
230+
{
231+
"openconfig-interfaces:subinterface": [
232+
{
233+
"index": 200,
234+
"config": {
235+
"index": 200
236+
},
237+
"vlan": {
238+
"config": {
239+
"vlan-id": 200
240+
}
241+
},
242+
"ipv6": {
243+
"addresses": {
244+
"address": [
245+
{
246+
"ip": "2001:db8::1",
247+
"config": {
248+
"ip": "2001:db8::1",
249+
"prefix-length": 64
250+
}
251+
}
252+
]
253+
}
254+
}
255+
}
256+
]
257+
}
258+
```
259+
260+
**Expected Database Result**:
261+
```bash
262+
redis-cli -n 4 HGETALL "VLAN_SUB_INTERFACE|Ethernet8.200"
263+
1) "vlan"
264+
2) "200"
265+
266+
redis-cli -n 4 HGETALL "INTERFACE|Ethernet8|2001:db8::1/64"
267+
1) "family"
268+
2) "IPv6"
269+
```
270+
271+
### Read SubInterface Configuration
272+
273+
**gNMI Command**:
274+
```bash
275+
gnmic -a 192.168.1.1:8080 -u admin -p admin --insecure get \
276+
--path "/openconfig-interfaces:interfaces/interface[name=Ethernet4]/subinterfaces/subinterface[index=100]/vlan/state"
277+
```
278+
279+
**Expected Response**:
280+
```json
281+
{
282+
"openconfig-vlan:state": {
283+
"vlan-id": 100
284+
}
285+
}
286+
```
287+
288+
### Update VLAN ID
289+
290+
**gNMI Command**:
291+
```bash
292+
gnmic -a 192.168.1.1:8080 -u admin -p admin --insecure set \
293+
--update-path "/openconfig-interfaces:interfaces/interface[name=Ethernet4]/subinterfaces/subinterface[index=100]/vlan/config/vlan-id" \
294+
--update-value "150"
295+
```
296+
297+
### Delete IPv4 Address
298+
299+
**gNMI Command**:
300+
```bash
301+
gnmic -a 192.168.1.1:8080 -u admin -p admin --insecure set \
302+
--delete "/openconfig-interfaces:interfaces/interface[name=Ethernet4]/subinterfaces/subinterface[index=100]/ipv4/addresses/address[ip=1.1.0.124]"
303+
```
304+
305+
### Delete VLAN Configuration
306+
307+
**gNMI Command**:
308+
```bash
309+
gnmic -a 192.168.1.1:8080 -u admin -p admin --insecure set \
310+
--delete "/openconfig-interfaces:interfaces/interface[name=Ethernet4]/subinterfaces/subinterface[index=100]/vlan/config/vlan-id"
311+
```
312+
313+
### Delete Entire SubInterface
314+
315+
**gNMI Command**:
316+
```bash
317+
gnmic -a 192.168.1.1:8080 -u admin -p admin --insecure set \
318+
--delete "/openconfig-interfaces:interfaces/interface[name=Ethernet4]/subinterfaces/subinterface[index=100]"
319+
```
320+
321+
## Error Handling
322+
323+
### Common Error Scenarios
324+
325+
#### 1. Parent Interface Not Found
326+
**Error Message**: `Parent interface Ethernet4 does not exist`
327+
**Resolution**: Create the parent interface first in the PORT table
328+
329+
#### 2. Invalid VLAN ID
330+
**Error Message**: `Invalid VLAN ID: must be between 1-4094`
331+
**Resolution**: Provide a valid VLAN ID within the acceptable range
332+
333+
#### 3. Duplicate IP Address
334+
**Error Message**: `IP address 1.1.0.124/32 already exists on interface Ethernet4`
335+
**Resolution**: Use a different IP address or remove the existing configuration
336+
337+
#### 4. Invalid Subinterface Index
338+
**Error Message**: `Invalid subinterface index: must be greater than 0 for VLAN subinterfaces`
339+
**Resolution**: Use index > 0 for VLAN subinterfaces
340+
341+
### Error Response Format
342+
343+
```json
344+
{
345+
"error": {
346+
"code": "INVALID_ARGUMENT",
347+
"message": "Parent interface Ethernet4 does not exist",
348+
"details": {
349+
"path": "/openconfig-interfaces:interfaces/interface[name=Ethernet4]/subinterfaces/subinterface[index=100]",
350+
"field": "interface_name"
351+
}
352+
}
353+
}
354+
```
355+
356+
### Validation Rules
357+
358+
1. **Parent Interface Validation**: Must exist in PORT table
359+
2. **VLAN ID Range**: 1-4094 (standard IEEE 802.1Q range)
360+
3. **IP Address Format**: Valid IPv4/IPv6 format with proper prefix length
361+
4. **Index Constraints**: Index 0 for main interface, index > 0 for subinterfaces
362+
5. **Dependency Checking**: Cannot delete parent interface with active subinterfaces
363+
364+
## Testing
365+
366+
The L3 SubInterface implementation includes comprehensive testing to ensure functionality, reliability, and proper error handling across all supported operations.
367+
368+
## References
369+
370+
### Related Documentation
371+
372+
1. **OpenConfig Interface Model**: [openconfig-interfaces.yang](https://github.com/openconfig/public/tree/master/release/models/interfaces)
373+
2. **OpenConfig VLAN Model**: [openconfig-vlan.yang](https://github.com/openconfig/public/tree/master/release/models/vlan)
374+
3. **SONiC Database Schema**: [SONiC Configuration Database](https://github.com/sonic-net/SONiC/wiki/Configuration)
375+
4. **gNMI Specification**: [gNMI Protocol](https://github.com/openconfig/reference/tree/master/rpc/gnmi)
376+
377+
### Standards Compliance
378+
379+
- **IEEE 802.1Q**: VLAN tagging standards
380+
- **RFC 4291**: IPv6 addressing architecture
381+
- **RFC 791**: IPv4 addressing specification
382+
- **OpenConfig**: Network device configuration standards

0 commit comments

Comments
 (0)