API ECMP Deployment

This guide shows you how to use the NetActuate API to deploy multiple virtual machines and configure BGP sessions programmatically. This is the automated equivalent of the portal-based Configuring Anycast guide. When two or more VMs at the same or different locations announce the same prefix over established BGP sessions in one anycast group, upstream routers distribute traffic across them using equal-cost multipath (ECMP). ECMP is a routing outcome of announcing the same prefix from multiple sessions; there is no separate ECMP object or toggle in the API.

Overview

The deployment workflow consists of these steps:

1. Deploy VMs at the target location.
2. Create a BGP group (anycast group) to hold the sessions.
3. Create a BGP session for each VM, attached to that group.
4. Configure the BGP daemon on each VM, start the sessions, and verify.

BGP and server-build calls use API v2. The base URL is https://api.netactuate.com/api/v2 and every call requires your API token in the Authorization header. The API also enforces an IP allowlist; the source IP of your calls must be on your account ACL. See API Access for token and ACL setup.

Step 1: Deploy VMs

Deploy two or more VMs. Each VM becomes an ECMP path. Use the buy-and-build endpoint to purchase a package and build it in one call. The plan is the plan name, location is a location ID, and image is an OS image ID (look these up in the portal API explorer or via /cloud/sizes/{location}, /cloud/locations, and /cloud/images).

curl -X POST "https://api.netactuate.com/api/v2/cloud/server/buy_build" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "VR1x2",
    "location": 42,
    "image": 55,
    "fqdn": "ecmp-node-1.example.com",
    "ssh_key_id": 12
  }'

Response:

{
  "result": "success",
  "message": null,
  "data": {
    "status": "BUILDING",
    "mbpkgid": 98001,
    "build": 45010,
    "id": 45010
  },
  "code": 200
}

Record the mbpkgid value from each response. This is the package ID that identifies the VM in later BGP calls. Repeat the call for each additional node, changing the fqdn.

You can poll the build to completion:

curl -X GET "https://api.netactuate.com/api/v2/cloud/server/build_status/45010" \
  -H "Authorization: Bearer YOUR_API_KEY"

The status field moves through Preparing, Sending, Processing, and finally Complete. For full VM build options (cloud-init, passwords, billing contracts) see Building with Cloud-Init.

Step 2: Create a BGP Group

An anycast group holds the sessions that announce a shared prefix. Create one group for your ECMP deployment. The group_type defaults to anycast.

curl -X POST "https://api.netactuate.com/api/v2/bgp/bgpgroup" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ecmp-group-lax",
    "description": "Anycast ECMP group for LAX workers",
    "group_type": "anycast"
  }'

Note the group ID returned in the response data. You can also list existing groups:

curl -X GET "https://api.netactuate.com/api/v2/bgp/bgpgroups" \
  -H "Authorization: Bearer YOUR_API_KEY"

Step 3: Create BGP Sessions

Create a session for each VM by passing the VM's mbpkgid and the group_id from Step 2. The neighbor router, provider ASN, and peer IPs are assigned automatically by NetActuate based on the VM's location. Set ipv6 to true to create an IPv6 session, and redundant to true to create a session to a second (redundant) router at the location.

curl -X POST "https://api.netactuate.com/api/v2/bgp/bgpcreatesessions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mbpkgid": 98001,
    "group_id": 301,
    "ipv6": false,
    "redundant": false
  }'

Repeat for the second VM, using its mbpkgid:

curl -X POST "https://api.netactuate.com/api/v2/bgp/bgpcreatesessions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mbpkgid": 98002,
    "group_id": 301,
    "ipv6": false,
    "redundant": false
  }'

To confirm the sessions were created and see their assigned neighbor details, list your sessions:

curl -X GET "https://api.netactuate.com/api/v2/bgp/bgpsessions" \
  -H "Authorization: Bearer YOUR_API_KEY"

Each session in data includes id, description, group_name, location, customer_peer_ip, provider_peer_ip, provider_asn, customer_asn, state, and routes_received. Record each session id.

Step 4: Configure VMs, Start Sessions, and Verify

Sessions are created in the Idle state. Before they can establish, configure the BGP daemon on each VM to peer with the NetActuate neighbor. Use the provider_peer_ip, provider_asn, customer_peer_ip, and customer_asn values from the session details as the neighbor and local settings. See the Configuring Anycast guide for a full BIRD2 configuration example.

Start each session (this instructs the NetActuate router to bring the peering up):

curl -X POST "https://api.netactuate.com/api/v2/bgp/bgpsession/5001/start" \
  -H "Authorization: Bearer YOUR_API_KEY"

You can start every session in a group at once with the group start job:

curl -X POST "https://api.netactuate.com/api/v2/bgp/bgpgroup/301/start" \
  -H "Authorization: Bearer YOUR_API_KEY"

After the daemons are running and the sessions are started, verify the state. A single session:

curl -X GET "https://api.netactuate.com/api/v2/bgp/bgpsession/5001" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "result": "success",
  "message": null,
  "data": {
    "id": 5001,
    "group_id": 301,
    "group_name": "ecmp-group-lax",
    "description": "ecmp-node-1",
    "state": "Established",
    "routes_received": 1,
    "routes_hidden": 0,
    "customer_peer_ip": "203.0.113.10",
    "provider_peer_ip": "203.0.113.1",
    "provider_asn": 36236,
    "customer_asn": 65001,
    "location": "Los Angeles, CA",
    "config_status": "active"
  },
  "code": 200
}

The session state moves through Idle, Connect, Active, and finally Established. When every session in the group reads Established and routes_received is 1, all VMs are announcing the prefix and upstream routers will distribute traffic across them via ECMP. For a quick roll-up across all your sessions, use GET /api/v2/bgp/bgpsummary.

Note: There is no API flag that reports "ECMP active." ECMP is the natural result of the same prefix being announced from multiple established sessions. Confirm real-world distribution with an external looking glass or BGP route viewer, and by checking routes_received on each session.

Adding More ECMP Paths

To add another VM to the group:

1. Deploy the VM with POST /cloud/server/buy_build (Step 1) and record its mbpkgid.
2. Create a session with POST /bgp/bgpcreatesessions using the new mbpkgid and the same group_id (Step 3).
3. Configure its BGP daemon and start the session with POST /bgp/bgpsession/{session_id}/start (Step 4).

Removing an ECMP Path

To remove a VM from the group without disrupting the others, stop and then delete its session:

curl -X POST "https://api.netactuate.com/api/v2/bgp/bgpsession/5002/stop" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X POST "https://api.netactuate.com/api/v2/bgp/bgpsession/5002/delete" \
  -H "Authorization: Bearer YOUR_API_KEY"

The remaining established sessions continue to announce the prefix, and upstream routers recalculate the ECMP path set automatically.

Next Steps

• Configuring Anycast -- Portal walkthrough and full BIRD2 configuration
• ECMP Load Balancing -- Understand ECMP distribution behavior and failover
• Mixed Provider Anycast -- Announce from NetActuate alongside other providers
• API v2 Reference -- Full API documentation

---

Need Help?

Contact support@netactuate.com or open a support ticket from the portal.