Skip to content

Commit f66fe7d

Browse files
committed
[core] Extend Interface API with LLDP info
Add a `neighbors` field to the Interface status containing LLDP neighbor information derived from TLVs: chassis ID, port ID, system name, and expiration time based on TTL. As per 52eae24, users can annotate or label an interface resource with expected neighbor information. This can be cross-validated against the LLDP data now in status. The status includes a validation field summarizing whether the neighbor could be validated and its result. TTL is excluded from NeighborInfo to avoid continuous reconciliations - instead we compute an ExpirationTime.
1 parent ada4c07 commit f66fe7d

6 files changed

Lines changed: 251 additions & 3 deletions

File tree

‎api/core/v1alpha1/groupversion_info.go‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -76,8 +76,9 @@ const PhysicalInterfaceNeighborLabel = "networking.metal.ironcore.dev/interface-
7676

7777
// PhysicalInterfaceNeighborRawAnnotation stores raw neighbor identification for interfaces
7878
// connected to unmanaged devices (devices without an Interface resource).
79-
// The value format is "chassisID::portID" where:
80-
// - chassisID: The LLDP chassis identifier (MAC address or system name)
79+
// The value format is "(chassisID|sysName)::portID" where:
80+
// - chassisID: The LLDP Chassis ID (e.g. MAC address)
81+
// - sysName: The LLDP System Name (optional TLV)
8182
// - portID: The LLDP port identifier (interface name, alias, or MAC address)
8283
//
8384
// Example: "00:1a:2b:3c:4d:5e::Ethernet1/1" or "spine-switch-01::Ethernet48"
@@ -174,6 +175,18 @@ const (
174175
DuplicateResourceOnDevice = "DuplicateResourceOnDevice"
175176
)
176177

178+
// Conditions that are specific to [Interface] objects.
179+
const (
180+
// NeighborAdjacencyCondition indicates whether the controller has verified the neighbor adjacency for a physical interface.
181+
NeighborAdjacencyCondition = "NeighborAdjacency"
182+
183+
NeighborVerifiedReason = "NeighborVerified"
184+
185+
NeighborValidationIncorrectRemoteDeviceReason = "NeighborValidationIncorrectRemoteDevice"
186+
187+
NeighborValidationIncorrectRemoteInterfaceReason = "NeighborValidationIncorrectRemoteInterface"
188+
)
189+
177190
// Reasons that are specific to [Interface] objects.
178191
const (
179192
// InterfaceNotFoundReason indicates that a referenced interface was not found.
@@ -196,6 +209,9 @@ const (
196209

197210
// VRFNotFoundReason indicates that a referenced VRF was not found.
198211
VRFNotFoundReason = "VRFNotFound"
212+
213+
// NeighborAdjacencyNotFoundReason indicates that the neighbor adjacency for a physical interface could not be verified.
214+
NeighborAdjacencyNotFoundReason = "MissingInterface"
199215
)
200216

201217
// Reasons that are specific to [Device] objects.

‎api/core/v1alpha1/interface_types.go‎

Lines changed: 43 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -328,8 +328,50 @@ type InterfaceStatus struct {
328328
// This field only applies to physical interfaces that are part of an aggregate interface.
329329
// +optional
330330
MemberOf *LocalObjectReference `json:"memberOf,omitempty"`
331+
332+
// Neighbors contains a list of neighbor interfaces connected to this interface and discovered with LLDP.
333+
// +optional
334+
Neighbors []Neighbor `json:"neighbors,omitempty"`
335+
}
336+
337+
// Neighbor represents an LLDP neighbor discovered on an interface.
338+
type Neighbor struct {
339+
// NeighborInfo contains the information about the LLDP neighbor discovered on this interface.
340+
NeighborInfo `json:",inline"`
341+
// ExpirationTime is the time when the LLDP neighbor information expires.
342+
// It is calculated based on the TTL.
343+
ExpirationTime *metav1.Time `json:"expirationTime,omitempty"`
344+
// Validation indicates whether the LLDP neighbor information matches the information in the label or annotations of the interface.
345+
Validation NeighborValidation `json:"validation"`
346+
}
347+
348+
// NeighborInfo represents the information retrieved via LLDP.
349+
// Values that change like TTL are excluded to avoid reconcile loops.
350+
type NeighborInfo struct {
351+
SystemName string `json:"systemName,omitempty"`
352+
SystemDescription string `json:"systemDescription,omitempty"`
353+
ChassisID string `json:"chassisId,omitempty"`
354+
ChassisIDType uint8 `json:"chassisIdType,omitempty"`
355+
PortID string `json:"portId,omitempty"`
356+
PortIDType uint8 `json:"portIdType,omitempty"`
357+
PortDescription string `json:"portDescription,omitempty"`
331358
}
332359

360+
type NeighborValidation string
361+
362+
const (
363+
// NeighborValidationUndefined indicates that there is not a label or annotation with the necessary information to validate the LLDP neighbor information against, or that the validation has not been performed yet.
364+
NeighborValidationUndefined NeighborValidation = "Undefined"
365+
// NeighborValidationError indicates that an error occurred while trying to validate the LLDP neighbor information against the interface labels or annotations.
366+
NeighborValidationError NeighborValidation = "Error"
367+
// NeighborVerified indicates that the LLDP neighbor information has been verified and matches the expected values.
368+
NeighborVerified NeighborValidation = "Verified"
369+
// NeighborDeviceMismatch indicates that the LLDP neighbor information does not match the expected values, indicating a potential misconfiguration or unexpected neighbor.
370+
NeighborDeviceMismatch NeighborValidation = "DeviceMismatch"
371+
// NeighborInterfaceMismatch indicates that the LLDP neighbor information does not match the expected interface information, indicating a potential misconfiguration or unexpected neighbor.
372+
NeighborInterfaceMismatch NeighborValidation = "PortMismatch"
373+
)
374+
333375
// +kubebuilder:object:root=true
334376
// +kubebuilder:subresource:status
335377
// +kubebuilder:resource:path=interfaces
@@ -345,8 +387,8 @@ type InterfaceStatus struct {
345387
// +kubebuilder:printcolumn:name="Configured",type=string,JSONPath=`.status.conditions[?(@.type=="Configured")].status`,priority=1
346388
// +kubebuilder:printcolumn:name="Operational",type=string,JSONPath=`.status.conditions[?(@.type=="Operational")].status`,priority=1
347389
// +kubebuilder:printcolumn:name="Paused",type=string,JSONPath=`.status.conditions[?(@.type=="Paused")].status`,priority=1
390+
// +kubebuilder:printcolumn:name="Neighbor Verified",type=string,JSONPath=`.status.neighbor.verified`,priority=1
348391
// +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"
349-
350392
// Interface is the Schema for the interfaces API.
351393
type Interface struct {
352394
metav1.TypeMeta `json:",inline"`

‎api/core/v1alpha1/zz_generated.deepcopy.go‎

Lines changed: 42 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎charts/network-operator/templates/crd/interfaces.networking.metal.ironcore.dev.yaml‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,10 @@ spec:
5555
name: Paused
5656
priority: 1
5757
type: string
58+
- jsonPath: .status.neighbor.verified
59+
name: Neighbor Verified
60+
priority: 1
61+
type: string
5862
- jsonPath: .metadata.creationTimestamp
5963
name: Age
6064
type: date
@@ -554,6 +558,42 @@ spec:
554558
- name
555559
type: object
556560
x-kubernetes-map-type: atomic
561+
neighbors:
562+
description: Neighbors contains a list of neighbor interfaces connected
563+
to this interface and discovered with LLDP.
564+
items:
565+
description: Neighbor represents an LLDP neighbor discovered on
566+
an interface.
567+
properties:
568+
chassisId:
569+
type: string
570+
chassisIdType:
571+
type: integer
572+
expirationTime:
573+
description: |-
574+
ExpirationTime is the time when the LLDP neighbor information expires.
575+
It is calculated based on the TTL.
576+
format: date-time
577+
type: string
578+
portDescription:
579+
type: string
580+
portId:
581+
type: string
582+
portIdType:
583+
type: integer
584+
systemDescription:
585+
type: string
586+
systemName:
587+
type: string
588+
validation:
589+
description: Validation indicates whether the LLDP neighbor
590+
information matches the information in the label or annotations
591+
of the interface.
592+
type: string
593+
required:
594+
- validation
595+
type: object
596+
type: array
557597
type: object
558598
required:
559599
- spec

‎config/crd/bases/networking.metal.ironcore.dev_interfaces.yaml‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,10 @@ spec:
5252
name: Paused
5353
priority: 1
5454
type: string
55+
- jsonPath: .status.neighbor.verified
56+
name: Neighbor Verified
57+
priority: 1
58+
type: string
5559
- jsonPath: .metadata.creationTimestamp
5660
name: Age
5761
type: date
@@ -551,6 +555,42 @@ spec:
551555
- name
552556
type: object
553557
x-kubernetes-map-type: atomic
558+
neighbors:
559+
description: Neighbors contains a list of neighbor interfaces connected
560+
to this interface and discovered with LLDP.
561+
items:
562+
description: Neighbor represents an LLDP neighbor discovered on
563+
an interface.
564+
properties:
565+
chassisId:
566+
type: string
567+
chassisIdType:
568+
type: integer
569+
expirationTime:
570+
description: |-
571+
ExpirationTime is the time when the LLDP neighbor information expires.
572+
It is calculated based on the TTL.
573+
format: date-time
574+
type: string
575+
portDescription:
576+
type: string
577+
portId:
578+
type: string
579+
portIdType:
580+
type: integer
581+
systemDescription:
582+
type: string
583+
systemName:
584+
type: string
585+
validation:
586+
description: Validation indicates whether the LLDP neighbor
587+
information matches the information in the label or annotations
588+
of the interface.
589+
type: string
590+
required:
591+
- validation
592+
type: object
593+
type: array
554594
type: object
555595
required:
556596
- spec

‎docs/api-reference/index.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1429,6 +1429,7 @@ _Appears in:_
14291429
| --- | --- | --- | --- |
14301430
| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#condition-v1-meta) array_ | The conditions are a list of status objects that describe the state of the Interface. | | Optional: \{\} <br /> |
14311431
| `memberOf` _[LocalObjectReference](#localobjectreference)_ | MemberOf references the aggregate interface this interface is a member of, if any.<br />This field only applies to physical interfaces that are part of an aggregate interface. | | Optional: \{\} <br /> |
1432+
| `neighbors` _[Neighbor](#neighbor) array_ | Neighbors contains a list of neighbor interfaces connected to this interface and discovered with LLDP. | | Optional: \{\} <br /> |
14321433

14331434

14341435
#### InterfaceType
@@ -1829,6 +1830,73 @@ _Appears in:_
18291830
| `vrfName` _string_ | The name of the vrf used to communicate with the DNS server. | | MaxLength: 63 <br />MinLength: 1 <br />Optional: \{\} <br /> |
18301831

18311832

1833+
#### Neighbor
1834+
1835+
1836+
1837+
Neighbor represents an LLDP neighbor discovered on an interface.
1838+
1839+
1840+
1841+
_Appears in:_
1842+
- [InterfaceStatus](#interfacestatus)
1843+
1844+
| Field | Description | Default | Validation |
1845+
| --- | --- | --- | --- |
1846+
| `systemName` _string_ | | | |
1847+
| `systemDescription` _string_ | | | |
1848+
| `chassisId` _string_ | | | |
1849+
| `chassisIdType` _integer_ | | | |
1850+
| `portId` _string_ | | | |
1851+
| `portIdType` _integer_ | | | |
1852+
| `portDescription` _string_ | | | |
1853+
| `expirationTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta)_ | ExpirationTime is the time when the LLDP neighbor information expires.<br />It is calculated based on the TTL. | | |
1854+
| `validation` _[NeighborValidation](#neighborvalidation)_ | Validation indicates whether the LLDP neighbor information matches the information in the label or annotations of the interface. | | |
1855+
1856+
1857+
#### NeighborInfo
1858+
1859+
1860+
1861+
NeighborInfo represents the information retrieved via LLDP.
1862+
Values that change like TTL are excluded to avoid reconcile loops.
1863+
1864+
1865+
1866+
_Appears in:_
1867+
- [Neighbor](#neighbor)
1868+
1869+
| Field | Description | Default | Validation |
1870+
| --- | --- | --- | --- |
1871+
| `systemName` _string_ | | | |
1872+
| `systemDescription` _string_ | | | |
1873+
| `chassisId` _string_ | | | |
1874+
| `chassisIdType` _integer_ | | | |
1875+
| `portId` _string_ | | | |
1876+
| `portIdType` _integer_ | | | |
1877+
| `portDescription` _string_ | | | |
1878+
1879+
1880+
#### NeighborValidation
1881+
1882+
_Underlying type:_ _string_
1883+
1884+
1885+
1886+
1887+
1888+
_Appears in:_
1889+
- [Neighbor](#neighbor)
1890+
1891+
| Field | Description |
1892+
| --- | --- |
1893+
| `Undefined` | NeighborValidationUndefined indicates that there is not a label or annotation with the necessary information to validate the LLDP neighbor information against, or that the validation has not been performed yet.<br /> |
1894+
| `Error` | NeighborValidationError indicates that an error occurred while trying to validate the LLDP neighbor information against the interface labels or annotations.<br /> |
1895+
| `Verified` | NeighborVerified indicates that the LLDP neighbor information has been verified and matches the expected values.<br /> |
1896+
| `DeviceMismatch` | NeighborDeviceMismatch indicates that the LLDP neighbor information does not match the expected values, indicating a potential misconfiguration or unexpected neighbor.<br /> |
1897+
| `PortMismatch` | NeighborInterfaceMismatch indicates that the LLDP neighbor information does not match the expected interface information, indicating a potential misconfiguration or unexpected neighbor.<br /> |
1898+
1899+
18321900
#### NetworkVirtualizationEdge
18331901

18341902

0 commit comments

Comments
 (0)