Skip to navigation
Network & SecurityVPC & IP management

Virtual IPs

A Virtual IP (VIP) is a private address that you choose from a VPC subnet and reserve as a floating endpoint. Unlike a VM’s private address — which the platform auto-assigns when a node attaches to a subnet — a Virtual IP is not bound to any single VM’s interface. Instead, you authorize one or more NAT-connected nodes to announce it, so traffic for that address is served by whichever announcer is healthy.

This is the mechanism behind bare-metal MetalLB and Kubernetes LoadBalancer services: MetalLB advertises the reserved private address from the announcer nodes, giving your service a stable in-VPC IP.

A Virtual IP claims an address for MetalLB and authorizes the nodes that may announce it. IPAM will not assign the address to a VM, so the same address is never handed out as a node’s interface IP.

Prerequisites

  • A VPC with at least one NAT-connected node to act as an announcer. Announcers are the VMs that advertise the Virtual IP.
  • The subnet you want the address to live in (any subnet of the VPC).

Choose the private IP

You pick the exact address. It must be a host address inside the selected subnet’s CIDR that is currently free. The backend validates the address and rejects it when it is:

RejectedReason
Outside the subnet CIDRThe address must be a host in the chosen subnet’s range.
The subnet gatewayThe gateway address is reserved for routing.
The network or broadcast addressNeither is a usable host address.
Already allocatedAnother node or Virtual IP already holds it.

List the subnet’s existing allocations with GET /networking/vpcs/{vpc_id}/network-allocations?workspace_id=607005 to see which host addresses are already taken before choosing one.

Reserve a Virtual IP

1

Pick a subnet and a free host address

Choose the subnet and an unused host address inside its CIDR (for example 10.144.4.17).

2

Choose the announcer nodes

Select the NAT-connected VMs that may announce the address. Provide their VM IDs in announcer_vm_ids.

3

Reserve the address

curl -X POST \
  "https://api.ibee.ai/v1/networking/vpcs/vpc-example/virtual-ips?workspace_id=607005" \
  -H "Authorization: Bearer $IBEE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subnet_id": "subnet-example",
    "private_ip": "10.144.4.17",
    "purpose": "metallb",
    "announcer_vm_ids": ["vm-example-a", "vm-example-b"]
  }'

Request fields

FieldRequiredDescription
subnet_idYesSubnet of the VPC that the address belongs to.
private_ipYesThe specific, unused host address to reserve, inside the subnet CIDR.
purposeYesmetallb for a MetalLB / Kubernetes LoadBalancer Virtual IP.
announcer_vm_idsYesOne or more VM IDs of NAT-connected nodes authorized to announce the address.

List and inspect

# List every Virtual IP in the VPC
curl "https://api.ibee.ai/v1/networking/vpcs/vpc-example/virtual-ips?workspace_id=607005" \
  -H "Authorization: Bearer $IBEE_TOKEN"
# Inspect a single Virtual IP
curl "https://api.ibee.ai/v1/networking/vpcs/vpc-example/virtual-ips/vip-example?workspace_id=607005" \
  -H "Authorization: Bearer $IBEE_TOKEN"

Each Virtual IP reports its private_ip, subnet_id, purpose, and the announcer_vm_ids currently authorized to advertise it.

Expose a Virtual IP publicly

A Virtual IP is private by design. To make the service it fronts reachable from the internet, attach a Reserved IP to it. The Reserved (public) address then forwards to the Virtual IP, while the announcers continue to serve the traffic inside the VPC.

Release a Virtual IP

Releasing a Virtual IP returns the private address to the subnet pool. Any Reserved IP attached to it must be detached first.

curl -X DELETE \
  "https://api.ibee.ai/v1/networking/vpcs/vpc-example/virtual-ips/vip-example?workspace_id=607005" \
  -H "Authorization: Bearer $IBEE_TOKEN"

Errors

StatusWhen
400 Bad RequestThe address is outside the subnet CIDR, or is the gateway, network, or broadcast address.
404 Not FoundThe VPC, subnet, or Virtual IP ID does not exist in this workspace.
409 ConflictThe address is already allocated to another node or Virtual IP.