F OpenNebula/one#6534: Add Shared AR to define Virtual IPs (#503)

Co-authored-by: mattrowe-opennebula <mrowe@opennebula.io>

Author: MarioRobres

content/product/cluster_configuration/networking_system/manage_vnets.md

@@ -69,6 +69,32 @@ AR=[
 ]
 ```
 
+### Shared Address Ranges (Shared AR) for Virtual IPs
+
+Marking an Address Range as `SHARED` converts its IPs into **Virtual IPs**. This allows **multiple VMs** to use the same IP address.
+
+To mark an Address Range as `SHARED`, add the `SHARED` attribute in the AR definition:
+
+```default
+AR=[
+    TYPE   = "IP4",
+    IP     = "10.0.0.211",
+    SIZE   = "3",
+    SHARED = "YES"
+]
+```
+
+The option to create a Shared AR is also available through a checkbox in the Sunstone UI in the **Add Address Range** dialog.
+
+Shared Address Ranges behave slightly differently from regular Address Ranges:
+
+- Same IP, multiple VMs: The same IP address from a Shared AR can be used by more than one VM.
+- Explicit request required: Shared IPs are not assigned automatically. They must be explicitly requested in a NIC or NIC Alias ([more details](#using-virtual-ips)).
+- Attribute `USED_LEASES` shows how many different shared IPs are in use, not how many VMs are using them.
+
+{{< alert title="Important" color="success" >}}
+The `SHARED` attribute of an Address Range can't be changed after creation. The default value is `NO`. {{< /alert >}}
+
 ### Guest Configuration Attributes (Context)
 
 To set up the guest network, the Virtual Network may include additional information to be injected into the VM at boot time. These contextualization attributes may include, for example, network masks, DNS servers, or gateways. For example, to define a gateway and DNS server for the Virtual Machines in the Virtual Network, simply add:
@@ -392,6 +418,30 @@ Any attribute supported by an NIC attribute can be also used in an alias except
 {{< alert title="Important" color="success" >}}
 The [Security Groups]({{% relref "../../virtual_machines_operation/virtual_machines_networking/security_groups#security-groups" %}}) and IP/MAC spoofing filters from the NIC network will be applied to the NIC_ALIAS. Those ones belonging to the NIC_ALIAS network won’t apply.{{< /alert >}}  
 
+### Using Virtual IPs
+
+To request a Virtual IP (VIP) from a [Shared Address Range](#shared-address-ranges-shared-ar-for-virtual-ips) you must explicity request the IP in a `NIC` or `NIC_ALIAS` attribute. The most natural way of using Shared Address Ranges for VIPs is to define a primary NIC in the network with a regular IP and a NIC Alias with the VIP, this way you get a single network interface with two different IPs. The procedure is described below:
+
+1. Define the primary NIC and give it a `NAME` so aliases can refer to it:
+
+```default
+NIC = [ NETWORK = "private", NAME = "main" ]
+```
+
+2. Add a `NIC_ALIAS` that **explicitly requests the shared IP** from the Shared AR (you must include the `IP` attribute):
+
+```default
+NIC_ALIAS = [ NETWORK = "private", PARENT = "main", IP = "10.0.0.211" ]
+```
+
+This will result in the VM having a **single network interface** (the parent NIC) with **two IPs** configured:
+
+- The IP assigned to the main NIC
+- The explicitly requested shared IP from the `NIC_ALIAS`
+
+{{< alert title="Important" color="success" >}}
+Requesting a Shared IP from a Shared AR **without** using `NIC_ALIAS` will create a **new interface** in the VM, with a random MAC assigned by OpenNebula.{{< /alert >}}
+
 ### Configuring the Virtual Machine Network
 
 Hypervisors will set the MAC address for the NIC of the Virtual Machines, but not the IP address. The IP configuration inside the guest is performed by the contextualization process, check the [contextualization guide]({{% relref "../../virtual_machines_operation/virtual_machines/vm_templates#context-overview" %}}) to learn how to prepare your Virtual Machines to automatically configure the network

content/software/release_information/release_notes/whats_new.md

@@ -69,6 +69,7 @@ We encourage you to review the [Known Issues]({{% relref "known_issues" %}}) and
 <!--keeping some examples-->
 - [Transparent proxying](../../../product/virtual_machines_operation/virtual_machines_networking/tproxy) allows VMs to access external services like OneGate without requiring complex networking setup.
 - [Virtual Machine memory encryption](../../../product/virtual_machines_operation/virtual_machines/vm_templates#memory-encryption) allows VM workloads whose memory cannot be read by the hypervisor.
+- [Shared Address Ranges](../../../product/cluster_configuration/networking_system/manage_vnets.md#shared-address-ranges-shared-ar-for-virtual-ips) with [NIC Alias support](../../../product/cluster_configuration/networking_system/manage_vnets.md#using-virtual-ips) to assign Virtual IPs that can be shared across multiple VMs.
 
 ## LXC
 - NIC Hotplugging, recontextualization and NIC PCI passthrough are now available [driver features](../../../product/operation_references/hypervisor_configuration/lxc_driver.md).