Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
MarioRobres wants to merge 4 commits into
base: master
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
97ea9a9
F OpenNebula/one#6534: add shared AR documentation
MarioRobres Jan 12, 2026
de6c0e7
F OpenNebula/one#6534: add release notes
MarioRobres Jan 12, 2026
b4fe121
F OpenNebula/one#6534: update Shared AR documentation
MarioRobres Jan 27, 2026
1bc0681
M #-: update docs
MarioRobres Feb 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 70 additions & 0 deletions content/product/cluster_configuration/networking_system/manage_vnets.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,52 @@ 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"
]
```

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.
- No MAC addresses: Leases from a Shared AR do not include a MAC address.
- Explicit request required: Shared IPs are not assigned automatically. They must be explicitly requested using [`NIC ALIAS`](#request-virtual-ips-with-nic-alias).
- Attribute `USED_LEASES` shows how many different shared IPs are in use, not how many VMs are using them.

For example, a Virtual Network with a no shared AR (`ID=0`) and a shared AR (`ID=1`):

```default
ADDRESS RANGE POOL
AR 0
SIZE : 51
LEASES : 4

RANGE FIRST LAST
MAC 02:00:c0:a8:96:64 02:00:c0:a8:96:c7
IP 10.0.0.150 10.0.0.201

AR 1
SIZE : 3
LEASES : 1

RANGE FIRST LAST
MAC 00:00:00:00:00:00 00:00:00:00:00:00
IP 10.0.0.211 10.0.0.213
```

{{< alert title="Important" color="success" >}}
The Sharedness of an Address Range can not be changed. {{< /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:
Expand Down Expand Up @@ -392,6 +438,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 >}}

### Request Virtual IPs with NIC Alias

To request a Virtual IP from a [Shared Address Range](#shared-address-ranges-shared-ar) follow these steps:

1. Define the primary NIC and give it a `NAME` so aliases can refer to it

```default
NIC = [ NETWORK = "private", NAME = "virtual" ]
```

2. Add a `NIC_ALIAS` that **explicity requests the shared IP** from the Shared AR (you must include the `IP` attribute)

```default
NIC_ALIAS = [ NETWORK = "private", PARENT = "virtual", 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. For this reason, the recommended approach is to use `NIC_ALIAS`.{{< /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
Expand Down
1 change: 1 addition & 0 deletions content/software/release_information/release_notes/whats_new.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,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.
- Add [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#request-virtual-ips-with-nic-alias) 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).
Expand Down