cisco-nxos-provider: enable vPC

This commit enables configuring Virtual Port Channels (`vPC`s) on Cisco
NXOS devices. It supports the following configuration (and other
features not show here):

```
feature vpc

vpc domain 1
peer-switch
peer-keepalive destination 10.201.182.26 source 10.201.182.25
peer-gateway

interface port-channel10
vpc peer-link

interface port-channel20
vpc 20
```

which can be achieved with:
```
vpcCfg, err := vpc.NewVPC(
  1,
  vpc.WithPeerLink(vpc.PeerLinkConfig{
    PortChannel:    "po10",
    KeepAliveDstIP: "10.201.182.26",
    KeepAliveSrcIP: "10.201.182.25",
  }),
  vpc.WithMembers([]vpc.Member{
    {PortChannel: "po20", VPCID: 20},
  }),
)
```

Author: nikatza

internal/provider/cisco/nxos/vpc/vpc.go

@@ -0,0 +1,279 @@
+// SPDX-FileCopyrightText: 2025 SAP SE or an SAP affiliate company and IronCore contributors
+// SPDX-License-Identifier: Apache-2.0
+
+// The vpc package provides functionality to configure Virtual Port Channels (vPC) on Cisco NX-OS devices.
+//
+// References:
+//   - [Cisco vPC] https://www.cisco.com/c/en/us/td/docs/dcn/nx-os/nexus9000/104x/configuration/interfaces/cisco-nexus-9000-series-nx-os-interfaces-configuration-guide-release-104x/m_configuring_vpcs_9x.html
+package vpc
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/netip"
+
+	"github.com/openconfig/ygot/ygot"
+
+	nxos "github.com/ironcore-dev/network-operator/internal/provider/cisco/nxos/genyang"
+	"github.com/ironcore-dev/network-operator/internal/provider/cisco/nxos/gnmiext"
+	"github.com/ironcore-dev/network-operator/internal/provider/cisco/nxos/iface"
+)
+
+var (
+	// Operation error: for failed actions due to underlying errors, i.e., gNMI Get.
+	ErrVPCOperation = func(field string, err error) error {
+		return fmt.Errorf("vpc: failed to get %s from remote device: %w", field, err)
+	}
+	// Resource error: for missing resources or invalid resource state
+	ErrVPCResource = func(reason string) error {
+		return fmt.Errorf("vpc: condition failed: %s", reason)
+	}
+	// Validation error: for invalid input parameters
+	ErrVPCValidation = func(field string, reason error) error {
+		return fmt.Errorf("vpc: invalid %s: %w", field, reason)
+	}
+)
+
+// VPC represents a Virtual Port Channel (vPC). New instances must be created using the `NewVPC()` function .
+type VPC struct {
+	domainID            uint16
+	peerLinkPortChannel string
+	keepaliveDstIP      *netip.Addr
+	keepaliveSrcIP      *netip.Addr
+	keepaliveVRF        string
+	members             map[string]memberInfo
+	peerSwitch          bool
+	peerGateway         bool
+}
+
+type memberInfo struct {
+	VPCID uint16
+}
+
+type Option func(*VPC) error
+
+// NewVPC creates a new VPC instance with the given domain ID and options. The domain ID must be between 1 and 1000.
+func NewVPC(domainID int, opts ...Option) (*VPC, error) {
+	if domainID < 1 || domainID > 1000 {
+		return nil, ErrVPCValidation("domain ID", errors.New("must be between 1 and 1000"))
+	}
+	v := &VPC{
+		domainID: uint16(domainID),
+		members:  make(map[string]memberInfo),
+	}
+	for _, opt := range opts {
+		if err := opt(v); err != nil {
+			return nil, err
+		}
+	}
+	// Check that peerLinkPortChannel is not included in members
+	if v.peerLinkPortChannel != "" {
+		if _, exists := v.members[v.peerLinkPortChannel]; exists {
+			return nil, ErrVPCValidation("peer-link port-channel", errors.New("port-channel is included in the vPC members list"))
+		}
+	}
+	return v, nil
+}
+
+type PeerLinkConfig struct {
+	// peerLink is the name of port-channel to be used as the vPC peer-link. It must be configured
+	// as a trunk port-channel interface.
+	PortChannel string
+	// KeepAliveDstIP must be a valid IPv4 or IPv6 address to use as destination for the peer-keepalive link.
+	KeepAliveDstIP string
+	// KeepAliveSrcIP must be a valid IP address for the peer-keepalive link source. Must use the same version as the destination IP.
+	// If nil, the device will use its default.
+	KeepAliveSrcIP *string
+	// KeepAliveVRF is the VRF to be used for the peer-keepalive link. If nil, the device will use the default VRF.
+	KeepAliveVRF *string
+}
+
+// WithPeerLink configures the vPC peer-link and the peer-keepalive configuration.
+func WithPeerLink(cfg PeerLinkConfig) Option {
+	return func(v *VPC) error {
+		errs := []error{}
+		shortName, err := iface.ShortNamePortChannel(cfg.PortChannel)
+		if err != nil {
+			errs = append(errs, ErrVPCValidation("peer-link port-channel name", err))
+		} else {
+			v.peerLinkPortChannel = shortName
+		}
+
+		dst, err := netip.ParseAddr(cfg.KeepAliveDstIP)
+		switch {
+		case err != nil:
+			errs = append(errs, ErrVPCValidation("keep-alive link destination IP address", err))
+		case !dst.IsValid():
+			errs = append(errs, ErrVPCValidation("keep-alive link destination IP address", errors.New("must be a valid IPv4 or IPv6 address")))
+		default:
+			v.keepaliveDstIP = &dst
+		}
+
+		if cfg.KeepAliveSrcIP != nil && v.keepaliveDstIP != nil && v.keepaliveDstIP.IsValid() {
+			src, err := netip.ParseAddr(*cfg.KeepAliveSrcIP)
+			switch {
+			case err != nil:
+				errs = append(errs, ErrVPCValidation("keep-alive link source IP address", err))
+			case !src.IsValid():
+				errs = append(errs, ErrVPCValidation("keep-alive link source IP address", errors.New("must be a valid IPv4 or IPv6 address")))
+			default:
+				v.keepaliveSrcIP = &src
+			}
+		}
+
+		if cfg.KeepAliveVRF != nil {
+			if *cfg.KeepAliveVRF == "" {
+				errs = append(errs, ErrVPCValidation("keep-alive link VRF", errors.New("VRF cannot be empty")))
+			} else {
+				v.keepaliveVRF = *cfg.KeepAliveVRF
+			}
+		}
+
+		if len(errs) > 0 {
+			return errors.Join(errs...)
+		}
+		return nil
+	}
+}
+
+type Member struct {
+	PortChannel string
+	VPCID       uint16
+}
+
+// WithMembers configures the members of this vPC. The list must contain at least one member. Each port-channel
+// in the provided list must have a valid name and vPC ID (between 1 and 4096). Duplicate vPC IDs are not allowed.
+func WithMembers(members []Member) Option {
+	return func(v *VPC) error {
+		if len(members) == 0 {
+			return ErrVPCValidation("members list", errors.New("members list cannot be empty"))
+		}
+
+		v.members = make(map[string]memberInfo, len(members))
+		seenVPCIDs := make(map[uint16]struct{}, len(members))
+
+		errs := []error{}
+		for _, pc := range members {
+			shortName, err := iface.ShortNamePortChannel(pc.PortChannel)
+			if err != nil {
+				errs = append(errs, ErrVPCValidation("member port-channel name", err))
+				continue
+			}
+
+			if _, exists := v.members[shortName]; exists {
+				errs = append(errs, ErrVPCValidation("member port-channel", fmt.Errorf("port-channel %q is used more than once", shortName)))
+				continue
+			}
+
+			if pc.VPCID < 1 || pc.VPCID > 4096 {
+				errs = append(errs, ErrVPCValidation("member vPC ID", errors.New("must be between 1 and 4096")))
+				continue
+			}
+
+			if _, exists := seenVPCIDs[pc.VPCID]; exists {
+				errs = append(errs, ErrVPCValidation("member vPC ID", fmt.Errorf("vPC ID %d is used more than once", pc.VPCID)))
+				continue
+			}
+			seenVPCIDs[pc.VPCID] = struct{}{}
+
+			v.members[shortName] = memberInfo{VPCID: pc.VPCID}
+		}
+		if len(errs) > 0 {
+			v.members = nil
+			return errors.Join(errs...)
+		}
+		return nil
+	}
+}
+
+// EnablePeerSwitchFeature enables the peer-switch feature on the vPC. See [Cisco vPC] for details.
+func EnablePeerSwitchFeature() Option {
+	return func(v *VPC) error {
+		v.peerSwitch = true
+		return nil
+	}
+}
+
+// EnablePeerGatewayFeature enables the peer-gateway feature on the vPC. See [Cisco vPC] for details.
+func EnablePeerGatewayFeature() Option {
+	return func(v *VPC) error {
+		v.peerGateway = true
+		return nil
+	}
+}
+
+var _ gnmiext.DeviceConf = (*VPC)(nil)
+
+// ToYGOT enables the vPC feature and configures the vPC domain, peer-link, and member port-channels.
+// It gets config from remote file to validate that the peer-link port-channel is set and configured as an L2 trunk.
+// If validation succeeds it will also enables the vPC feature
+func (v *VPC) ToYGOT(ctx context.Context, c gnmiext.Client) ([]gnmiext.Update, error) {
+	val := &nxos.Cisco_NX_OSDevice_System_VpcItems_InstItems_DomItems{
+		Id:      ygot.Uint16(v.domainID),
+		AdminSt: nxos.Cisco_NX_OSDevice_Nw_AdminSt_enabled,
+	}
+
+	if v.peerLinkPortChannel != "" {
+		// Check if the port-channel exists and is configured as an L2 trunk
+		pc := &nxos.Cisco_NX_OSDevice_System_IntfItems_AggrItems_AggrIfList{}
+		if err := c.Get(ctx, "System/intf-items/aggr-items/AggrIf-list[id="+v.peerLinkPortChannel+"]", pc); err != nil {
+			return nil, ErrVPCOperation("port-channel '"+v.peerLinkPortChannel+"'", err)
+		}
+		if pc.Layer != nxos.Cisco_NX_OSDevice_L1_Layer_AggrIfLayer_Layer2 || pc.Mode != nxos.Cisco_NX_OSDevice_L1_Mode_trunk {
+			return nil, ErrVPCResource("peer-link port-channel must be configured as an L2 trunk")
+		}
+		val.GetOrCreateKeepaliveItems().GetOrCreatePeerlinkItems().Id = ygot.String(v.peerLinkPortChannel)
+
+		// Keepalive link configuration
+		if v.keepaliveDstIP != nil {
+			val.GetOrCreateKeepaliveItems().DestIp = ygot.String(v.keepaliveDstIP.String())
+			if v.keepaliveSrcIP != nil {
+				val.GetOrCreateKeepaliveItems().SrcIp = ygot.String(v.keepaliveSrcIP.String())
+			}
+			if v.keepaliveVRF != "" {
+				val.GetOrCreateKeepaliveItems().Vrf = ygot.String(v.keepaliveVRF)
+			}
+		}
+	}
+
+	for member, info := range v.members {
+		isConfigured, err := iface.Exists(ctx, c, member)
+		if err != nil {
+			return nil, ErrVPCOperation("port-channel '"+member+"'", err)
+		}
+		if !isConfigured {
+			return nil, ErrVPCResource("member port-channel " + member + " does not exist on the device")
+		}
+		val.GetOrCreateIfItems().GetOrCreateIfList(info.VPCID).GetOrCreateRsvpcConfItems().TDn = ygot.String("/System/intf-items/aggr-items/AggrIf-list[id='" + member + "']")
+	}
+
+	if v.peerSwitch {
+		val.PeerSwitch = nxos.Cisco_NX_OSDevice_Nw_AdminSt_enabled
+	}
+
+	if v.peerGateway {
+		val.PeerGw = nxos.Cisco_NX_OSDevice_Nw_AdminSt_enabled
+	}
+
+	return []gnmiext.Update{
+		gnmiext.EditingUpdate{
+			XPath: "System/fm-items/vpc-items",
+			Value: &nxos.Cisco_NX_OSDevice_System_FmItems_VpcItems{
+				AdminSt: nxos.Cisco_NX_OSDevice_Fm_AdminState_enabled,
+			},
+		},
+		gnmiext.ReplacingUpdate{
+			XPath: "System/vpc-items/inst-items/dom-items",
+			Value: val,
+		},
+	}, nil
+}
+
+func (v *VPC) Reset(_ context.Context, _ gnmiext.Client) ([]gnmiext.Update, error) {
+	return []gnmiext.Update{
+		gnmiext.DeletingUpdate{
+			XPath: "System/vpc-items/inst-items/dom-items",
+		},
+	}, nil
+}