From 001e6f6f8cf264d26e844e11241de44b6e3453be Mon Sep 17 00:00:00 2001 From: Ned Petrov Date: Tue, 10 Mar 2026 08:27:53 +0200 Subject: [PATCH 1/3] Enhance documentation for VIP networks and NIC grouping support --- content/network-interface-groups.md | 1 + content/networks.md | 56 +++++++++++++++++++++++++++-- 2 files changed, 55 insertions(+), 2 deletions(-) diff --git a/content/network-interface-groups.md b/content/network-interface-groups.md index dd2b14a8..a1ea2227 100644 --- a/content/network-interface-groups.md +++ b/content/network-interface-groups.md @@ -6,6 +6,7 @@ The `nic_group` feature allows multiple BOSH networks to be bound to the same ph - **Dual Stack Networking**: Binding IPv4 and IPv6 networks to the same interface (see [Dual Stack Networks](dual-stack-networks.md)) - **Prefix Delegation**: Attaching a prefix delegation network alongside a primary management network (see [Prefix Delegation](prefix-delegation-networks.md)) +- **Elastic IP on a Specific NIC**: Directing a VIP network (e.g. an AWS Elastic IP) to the correct network interface when an instance has multiple NICs (see [VIP Networks in Multi-NIC Configurations](networks.md#vip)) ## Infrastructure diff --git a/content/networks.md b/content/networks.md index 31f0f058..265cf192 100644 --- a/content/networks.md +++ b/content/networks.md @@ -17,6 +17,7 @@ Each type of network supports one or both IP reservation types: | Automatic IP assignment | Supported, default | Supported | Supported | --- + ## General Structure {: #general } Networking configuration is usually done in three steps: @@ -69,6 +70,7 @@ instance_groups: See how to define each network type below. --- + ## Manual Networks {: #manual } Manual networking allows you to specify one or more subnets and let the Director choose available IPs from one of the subnet ranges. A subnet definition specifies the CIDR range and, optionally, the gateway and DNS servers. In addition, certain IPs can be blacklisted (the Director will not use these IPs) via the `reserved` property. @@ -134,7 +136,6 @@ instance_groups: !!! note If an instance group uses static IP reservation, all instances must be given static IPs. - ### Prefix Delegation {: #prefix-delegation } Starting with Director release `v282.1.0` and stemcell `Ubuntu Jammy v1.943`, BOSH supports prefix delegation. The concepts of static IP addresses and reserved addresses remain as described above. @@ -251,6 +252,7 @@ networks: ``` --- + ## Virtual IP (VIP) Networks {: #vip } Virtual IP networking enables the association of an IP address that is not backed by any particular NIC. This flexibility enables users to remap a virtual IP to a different instance in cases of a failure. For IaaS specific implementation details, see the respective cloud provider docs. @@ -381,8 +383,54 @@ instance_groups: - name: my-vip-network ``` +### VIP Networks in Multi-NIC Configurations + +!!! note + Available as of BOSH Director version TBD and AWS CPI version TBD. + +When deploying instances with multiple NICs, you can specify `nic_group` on a VIP network entry in the deployment manifest to control which network interface receives the virtual IP (e.g. an Elastic IP on AWS). + +The `nic_group` value on the VIP network should match the `nic_group` assigned to the manual network that represents the target interface. The CPI uses this to associate the virtual IP with the correct NIC. + +!!! note + This requires CPI support. See [CPI Limitations](#cpi-limitations) for availability. +Example deployment manifest: + +```yaml +# cloud-config.yml --- +networks: +- name: primary-network + type: manual + subnets: [...] + +- name: secondary-network + type: manual + subnets: [...] + +- name: my-vip-network + type: vip + +# deployment.yml +--- +instance_groups: +- name: my-instance-group + ... + networks: + - name: primary-network + nic_group: nic0 # First NIC + - name: secondary-network + nic_group: nic1 # Second NIC + - name: my-vip-network + static_ips: [54.47.189.8] + nic_group: nic1 # Associate the Elastic IP with the second NIC +``` + +When `nic_group` is not specified on a VIP network, the CPI defaults to associating the virtual IP with the primary NIC (device_index 0). If `nic_group` is set on the VIP network but does not match any manual or dynamic network's `nic_group`, the CPI also falls back to device_index 0. + +--- + ## Multi-homed VMs {: #multi-homed } An instance group can be configured to have multiple IP addresses (multiple NICs) by being on multiple networks. Given that there are multiple network settings available for an instance group, the Agent needs to decide which network's DNS settings to use and which network's gateway should be the default gateway on the VM. Agent performs such selection based on the network's `default` property specified in the instance group. @@ -433,13 +481,14 @@ In the above example, VM allocated to `my-multi-homed-instance-group` instance g See [rakutentech/bosh-routing-release](https://github.com/rakutentech/bosh-routing-release) if you are looking for even more specific routing configuration. --- + ## CPI Limitations {: #cpi-limitations } The Director does not enforce how many networks can be assigned to each instance; however, each CPI might impose custom requirements either due to the IaaS limitations or simply because support was not yet implemented. | | manual network | dynamic network | vip network | nic grouping supported for network type | prefix delegation supported for network type | |-----------|-----------------------------------------------------------------|-----------------------------|--------------------------------------|-----------------------------------------|----------------------------------------------| -| AWS | Multiple per instance group1 (from v107.0.0) | Single per instance group | Single, corresponds to an elastic IP |manual2 | manual3 | +| AWS | Multiple per instance group1 (from v107.0.0) | Single per instance group | Single, corresponds to an elastic IP |manual2, vip4 | manual3 | | Azure | Multiple per instance group | Multiple per instance group | Single, corresponds to a reserved IP | | | | OpenStack | [Multiple per instance group](openstack-multiple-networks.md) | Single per instance group | Single, corresponds to a floating IP | | | | vSphere | Multiple per instance group | Not supported | Not supported | | | @@ -450,7 +499,10 @@ The Director does not enforce how many networks can be assigned to each instance 3 = Find the currently supported prefix sizes [here](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-prefix-eni.html) +4 = When `nic_group` is set on a VIP network, the AWS CPI maps the value to the corresponding NIC's device index to associate the Elastic IP with the correct network interface. Requires BOSH Director `vTBD+` and AWS CPI `vTBD+`. + --- + ## CPI Specific `cloud_properties` {: #cloud-properties } - [See AWS CPI network cloud properties](aws-cpi.md#networks) From 67efd6201e121b5cd4c319ef14cb3d75d6cdf8d2 Mon Sep 17 00:00:00 2001 From: Ned Petrov Date: Tue, 10 Mar 2026 08:29:36 +0200 Subject: [PATCH 2/3] Version requirments documented above --- content/networks.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/content/networks.md b/content/networks.md index 265cf192..6e061ec6 100644 --- a/content/networks.md +++ b/content/networks.md @@ -488,7 +488,7 @@ The Director does not enforce how many networks can be assigned to each instance | | manual network | dynamic network | vip network | nic grouping supported for network type | prefix delegation supported for network type | |-----------|-----------------------------------------------------------------|-----------------------------|--------------------------------------|-----------------------------------------|----------------------------------------------| -| AWS | Multiple per instance group1 (from v107.0.0) | Single per instance group | Single, corresponds to an elastic IP |manual2, vip4 | manual3 | +| AWS | Multiple per instance group1 (from v107.0.0) | Single per instance group | Single, corresponds to an elastic IP |manual2, vip | manual3 | | Azure | Multiple per instance group | Multiple per instance group | Single, corresponds to a reserved IP | | | | OpenStack | [Multiple per instance group](openstack-multiple-networks.md) | Single per instance group | Single, corresponds to a floating IP | | | | vSphere | Multiple per instance group | Not supported | Not supported | | | @@ -499,8 +499,6 @@ The Director does not enforce how many networks can be assigned to each instance 3 = Find the currently supported prefix sizes [here](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-prefix-eni.html) -4 = When `nic_group` is set on a VIP network, the AWS CPI maps the value to the corresponding NIC's device index to associate the Elastic IP with the correct network interface. Requires BOSH Director `vTBD+` and AWS CPI `vTBD+`. - --- ## CPI Specific `cloud_properties` {: #cloud-properties } From d735dc9fda6fed33d4121cef311f2817706efd23 Mon Sep 17 00:00:00 2001 From: Ned Petrov <71276794+neddp@users.noreply.github.com> Date: Wed, 11 Mar 2026 07:16:22 +0200 Subject: [PATCH 3/3] Set director version --- content/networks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/networks.md b/content/networks.md index 6e061ec6..1d65d689 100644 --- a/content/networks.md +++ b/content/networks.md @@ -386,7 +386,7 @@ instance_groups: ### VIP Networks in Multi-NIC Configurations !!! note - Available as of BOSH Director version TBD and AWS CPI version TBD. + Available as of BOSH Director version v282.1.3 and AWS CPI version TBD. When deploying instances with multiple NICs, you can specify `nic_group` on a VIP network entry in the deployment manifest to control which network interface receives the virtual IP (e.g. an Elastic IP on AWS).