add documentation to wireguard implementation

Author: Eslam-Nawara

pkg/netlight/network.go

@@ -53,10 +53,10 @@ var NDMZGwIP = &net.IPNet{
 var NetworkSchemaLatestVersion = semver.MustParse("0.1.0")
 
 type networker struct {
-	ipamLease  string
-	networkDir string
-	portSet    *set.UIntSet
-	linkDir    string
+	ipamLease   string
+	networkDir  string
+	portSet     *set.UIntSet
+	linkDirPath string
 }
 
 var _ localPkg.NetworkerLight = (*networker)(nil)
@@ -69,17 +69,17 @@ func NewNetworker() (localPkg.NetworkerLight, error) {
 
 	ipamLease := filepath.Join(vd, ipamLeaseDir)
 	runtimeDir := filepath.Join(vd, networkDir)
-	linkDir := filepath.Join(runtimeDir, linkDir)
+	linkDirPath := filepath.Join(runtimeDir, linkDir)
 
-	if err := os.MkdirAll(linkDir, 0755); err != nil {
-		return nil, errors.Wrapf(err, "failed to create directory: '%s'", linkDir)
+	if err := os.MkdirAll(linkDirPath, 0755); err != nil {
+		return nil, errors.Wrapf(err, "failed to create directory: '%s'", linkDirPath)
 	}
 
 	n := networker{
-		ipamLease:  ipamLease,
-		networkDir: runtimeDir,
-		portSet:    set.NewInt(),
-		linkDir:    linkDir,
+		ipamLease:   ipamLease,
+		networkDir:  runtimeDir,
+		portSet:     set.NewInt(),
+		linkDirPath: linkDirPath,
 	}
 
 	if err := n.syncWGPorts(); err != nil {
@@ -620,6 +620,14 @@ func (n *networker) releasePort(port uint16) error {
 	return nil
 }
 
+// setupWireguard configures a Wireguard interface for the network resource
+// by checking for existing network configuration and releasing any previously reserved port.
+// reserves the specified Wireguard listen port.
+// checks if wireguard interface already exists in the namespace, if not it creates the interface in the host namespace.
+// If not, it creates a new Wireguard interface in the host namespace and moves it to the network resource
+// and configures the Wireguard interface with the private key, listen port, and peers using
+// This function handles both initial setup and reconfiguration of existing
+// Wireguard interfaces, ensuring proper port management and interface configuration.
 func (n networker) setupWireguard(name string, net zos.NetworkLight, netr *resource.Resource) error {
 	log.Debug().Msg("setting up wireguard")
 
@@ -687,7 +695,7 @@ func (n *networker) storeNetwork(name string, wl gridtypes.WorkloadID, network z
 	if err := enc.Encode(&network); err != nil {
 		return err
 	}
-	link := filepath.Join(n.linkDir, wl.String())
+	link := filepath.Join(n.linkDirPath, wl.String())
 	if err := os.Symlink(filepath.Join("../", name), link); err != nil && !os.IsExist(err) {
 		return errors.Wrap(err, "failed to create network symlink")
 	}

pkg/netlight/resource/README.md

@@ -0,0 +1,59 @@
+# Network Resource Package
+
+## Overview
+
+This package implements network resource management for ZOS Network Light, providing isolated network namespaces for workloads with mycelium and Wireguard connectivity.
+
+## Network Resource
+
+A network resource consists of:
+
+- Network namespace (`n{name}`)
+- Private network bridge (`r{name}`)
+- Mycelium bridge (`m{name}`)
+- Interfaces (public, private, mycelium, wireguard)
+- NFT rules for proper routing and security
+
+## Creation
+
+`Create()` sets up a network resource by:
+
+1. Creating bridges for private network and mycelium
+2. Creating a network namespace
+3. Setting up veth pairs to connect namespace to bridges
+4. Configuring IP addresses and routing
+5. Applying NFT rules
+
+## Wireguard Integration
+
+To create network resource with wireguard user needs should be
+
+- Providing the subnet for the network resource (e.g., 10.1.3.0/24)
+- Defining the overall IP range for the network (e.g., 10.1.0.0/16)
+- Generating and providing the Wireguard private key
+- Selecting an available port for Wireguard to listen on
+- Configuring the list of peers with their public keys and allowed IPs
+
+### Implementation
+
+Wireguard interfaces are added to a network resource through:
+
+1. `WGName()`: Generates the Wireguard interface name (`w-{name}`)
+2. `SetWireguard()`: Creates Wireguard interface in the host namespace and moves it into the network namespace
+3. `ConfigureWG()`: Sets up the Wireguard interface with:
+   - The user-provided private key
+   - The user-selected listen port
+   - Peer configurations (public keys, allowed IPs, endpoints)
+4. `HasWireguard()`: Checks if the Wireguard interface exists in the namespace
+
+The Wireguard interface is created in the host namespace and then moved into the network resource namespace. Once configured with the user-provided private key, listen port, and peer information, it enables secure communication between network resources across different nodes by establishing encrypted tunnels to other network resources on different nodes, creating a secure mesh network.
+
+## Cleanup
+
+`Delete()`
+
+- Destroys mycelium service
+- Removes network namespace
+- Deletes all created bridges
+
+The cleanup process continues even if some steps fail, collecting all errors for proper reporting.