Skip to navigation

A Virtual IP (VIP) is a private address in a VPC subnet that isn’t tied to any one VM. You choose the address, and you name the VMs that may answer for it (the announcers). Whichever announcer currently holds the address receives its traffic, so if that VM fails, another announcer can take the address over and your service keeps the same address.

IBEE Virtual IPs are built for MetalLB, the tool that gives Kubernetes LoadBalancer services a stable address on clusters you run yourself on VMs.

When to use a Virtual IP

You want…UseWhy
A stable private address for a Kubernetes LoadBalancer service on VMs (MetalLB)Virtual IP (this page)The address moves between your cluster nodes
A private address for one VMThe VM’s own address in the subnetAssigned when you attach the VM to the VPC
A public address for one VM that you can moveA Reserved IPPublic, attached to one VM at a time
One public address in front of several servers, with health checksA load balancerIBEE runs it for you; no cluster needed

How it works

  1. You reserve the address in a subnet. IBEE marks it as taken, so it is never given to a VM.
  2. You choose the announcer VMs. IBEE allows those VMs, and only those, to use the address on the VPC network.
  3. MetalLB on the announcers takes the address. One node answers for it at a time; if that node fails, MetalLB moves the address to another announcer.
  4. Optionally, you make it public by attaching a Reserved IP (a one-to-one mapping), or by forwarding one NAT gateway port to it.

Before you begin

  • A VPC with Managed NAT Gateway connectivity (NAT, network address translation, lets private VMs share the gateway’s public address). Announcers must be NAT-connected VMs, and making the Virtual IP public needs the VPC’s NAT gateway. See VPC.
  • The announcer VMs attached to the VPC, all in the same subnet as the Virtual IP, with NAT access.
  • A free address in that subnet. Check which addresses are taken on the VPC’s Subnets tab (the private IP ledger).
  • MetalLB installed on your Kubernetes cluster, which runs on those VMs.
  • For public access: an unattached Reserved IP in the VPC’s location.

Reserve a Virtual IP

1

Open the VPC

In the sidebar, under Network & Security, click VPC, then open your VPC. Click the Reserved VIPs tab.

2

Open the dialog

Click Reserve Virtual IP. The button is available once the VPC has a subnet. The dialog says: “Claim a private address for MetalLB and authorize the nodes that may announce it. IPAM will not assign the address to a VM.” (IPAM is the part of IBEE that hands out addresses.)

3

Choose the subnet and address

Choose the Subnet, then enter the Private IP: an unused address inside the subnet, for example 10.144.4.17. These are refused:

AddressWhy
Outside the subnet’s rangeThe Virtual IP must belong to the subnet
The subnet’s first address (network) or last (broadcast)Not usable by any host
The subnet’s gatewayUsed for routing
Already given to a VM or another Virtual IPAlready taken
4

Choose the announcers

Under MetalLB announcer nodes, tick the VMs that may announce the address. Only NAT-connected VMs in this VPC are listed.

5

Reserve

Click Reserve Virtual IP. You see “Virtual IP 10.144.4.17 reserved”. The Reserved VIPs tab lists it with its Private IP, Purpose (MetalLB), Announcers, Attached public IP and Status.

Configure MetalLB

Give MetalLB the same address and tell it to announce on the local network (layer 2 mode). Apply this on your cluster:

apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
name: ibee-vip
namespace: metallb-system
spec:
addresses:
- 10.144.4.17/32
---
apiVersion: metallb.io/v1beta1
kind: L2Advertisement
metadata:
name: ibee-vip
namespace: metallb-system
spec:
ipAddressPools:
- ibee-vip

Then create a Kubernetes service of type LoadBalancer; MetalLB gives it 10.144.4.17. Only the announcer VMs you ticked can use the address. If MetalLB runs on other nodes too, limit the L2Advertisement to the announcers with its nodeSelectors field.

Verify

  1. On the Reserved VIPs tab, the Virtual IP’s Status is available.

  2. In Kubernetes, kubectl get svc shows 10.144.4.17 under EXTERNAL-IP for your service.

  3. From another VM in the same VPC, connect to the service:

    curl -m 5 http://10.144.4.17/

    -m 5 makes curl give up after 5 seconds if nothing answers.

  4. To test failover, run this loop on the other VM, which tries once every 1 second, and stop the node that currently holds the address:

    while true; do curl -s -m 5 http://10.144.4.17/ >/dev/null && echo ok || echo fail; sleep 1; done

    After a few fail lines, it prints ok again once MetalLB has moved the address to another announcer.

Expose a Virtual IP publicly

A Virtual IP is private. There are two ways to reach it from the internet. The VPC needs an available NAT gateway for either.

With a Reserved IP (all ports):

  1. On the Reserved VIPs tab, click Attach on the Virtual IP’s row.
  2. In Attach Reserved IP (“Create a one-to-one public mapping for MetalLB VIP 10.144.4.17.”), choose an unattached Reserved IP in the VPC’s location.
  3. Click Attach Reserved IP.

Traffic to the Reserved IP now reaches the Virtual IP, and replies go out through it. To stop public access, click Detach on the row and confirm Detach Reserved IP. The Virtual IP stays reserved, and the Reserved IP goes back to your list.

With a port forward (one port): add a NAT port forwarding rule with Destination type MetalLB VIP, and choose the Virtual IP.

In both cases, the announcers’ firewall groups must accept the service’s port.

Release a Virtual IP

Remove the address from your MetalLB configuration first. After release, IBEE can give the address to a VM, and two machines answering for one address breaks both.

  1. Detach any Reserved IP from the Virtual IP.
  2. Delete any port forwarding rule that targets it.
  3. On the Reserved VIPs tab, click the delete icon on its row, then Delete Reservation in the Delete Virtual IP Reservation dialog. You see “Virtual IP 10.144.4.17 released”.

Use the API

The public API has no Virtual IP operations yet. Reserve, attach, detach and release Virtual IPs in the portal. The one exception: a NAT port forwarding rule can target an existing Virtual IP with "target_type": "vip" and the announcers in target_vm_ids (POST /networking/vpcs/VPC-ID/nat-gateways/NAT-GATEWAY-ID/port-forwarding-rules).

Limits

ItemLimit
AddressOne private IPv4 address inside a subnet of the VPC
Announcers1 to 32 NAT-connected VMs, all in the Virtual IP’s subnet
Public access1 Reserved IP per Virtual IP, or NAT port forwarding rules
Purpose in the portalMetalLB
APINot available yet, except as a port forwarding target
Failover timeSet by MetalLB, not by IBEE

Troubleshooting

You seeWhat it meansWhat to do
Reserve Virtual IP is greyed outThe VPC has no subnetAdd a subnet on the Subnets tab.
”No NAT-connected nodes are available in this VPC.”No VM is attached to this VPC with NAT accessAttach the VMs with NAT access first. See Attach a VM.
”Select at least one NAT-connected announcer node.”No announcer is tickedTick at least one VM.
”Virtual IP must belong to the selected VPC subnet”The address is outside the subnet’s rangeEnter an address inside the subnet shown under Subnet.
”Virtual IP cannot be a subnet network, gateway, or broadcast address”You picked a reserved addressChoose another address.
”Private IP 10.144.4.17 is already reserved in this VPC”A VM or another Virtual IP has the addressCheck the private IP ledger on the Subnets tab and pick a free one.
”Virtual IP and all announcer VMs must use the same VPC subnet”An announcer is in another subnetChoose announcers from the Virtual IP’s subnet.
”An available NAT gateway is required before exposing a virtual IP in this VPC”The VPC has no working NAT gatewayCreate the NAT gateway on the VPC’s Overview tab, then attach the Reserved IP.
”Detach the Reserved IP before deleting this reservation.”A Reserved IP is still attachedDetach it, then delete.
”Delete port-forwarding rules that target this virtual IP first”A port forwarding rule still points at itDelete that rule, then delete.
The service doesn’t answer on the addressMetalLB isn’t announcing it, or runs on a VM that isn’t an announcerCheck the MetalLB pool and that the speaker runs on an announcer VM.