Skip to main content

API ECMP Deployment

This guide shows you how to use the NetActuate API to deploy multiple virtual machines and configure ECMP BGP sessions programmatically. This is the automated equivalent of the portal-based Configuring Anycast guide.

Overview​

The deployment workflow consists of four steps:

  1. Deploy VMs at the target location
  2. Create BGP sessions for each VM
  3. Assign sessions to an anycast group
  4. Verify ECMP is active

All API calls use the base URL https://api.netactuate.com/api/v3 and require your API key in the Authorization header.

Step 1: Deploy VMs​

Deploy two or more VMs at the same location. Each VM will serve as an ECMP path.

curl -X POST "https://api.netactuate.com/api/v3/cloud/server" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "ecmp-node-1",
    "location_id": 42,
    "plan_id": 101,
    "image_id": 55,
    "ssh_key_id": 12
  }'

Response:

{
  "status": "success",
  "data": {
    "id": 98001,
    "label": "ecmp-node-1",
    "status": "provisioning",
    "primary_ip": "203.0.113.10",
    "location": {
      "id": 42,
      "name": "Los Angeles, CA"
    }
  }
}

Repeat for additional nodes, changing the label field each time:

curl -X POST "https://api.netactuate.com/api/v3/cloud/server" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "ecmp-node-2",
    "location_id": 42,
    "plan_id": 101,
    "image_id": 55,
    "ssh_key_id": 12
  }'

Step 2: Create BGP Sessions​

Once the VMs are deployed and running, create a BGP session for each one.

curl -X POST "https://api.netactuate.com/api/v3/bgp/session" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": 98001,
    "asn": 65001,
    "prefix": "192.0.2.0/24"
  }'

Response:

{
  "status": "success",
  "data": {
    "id": 5001,
    "server_id": 98001,
    "asn": 65001,
    "neighbor_ip": "203.0.113.1",
    "neighbor_asn": 13830,
    "state": "idle",
    "prefix": "192.0.2.0/24"
  }
}

Create a session for the second VM:

curl -X POST "https://api.netactuate.com/api/v3/bgp/session" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": 98002,
    "asn": 65001,
    "prefix": "192.0.2.0/24"
  }'

Step 3: Create an Anycast Group​

Group the BGP sessions into an anycast group so the prefix is announced from all members.

curl -X POST "https://api.netactuate.com/api/v3/bgp/anycast-group" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "ecmp-group-lax",
    "session_ids": [5001, 5002]
  }'

Response:

{
  "status": "success",
  "data": {
    "id": 301,
    "label": "ecmp-group-lax",
    "sessions": [
      {"id": 5001, "server_id": 98001, "state": "idle"},
      {"id": 5002, "server_id": 98002, "state": "idle"}
    ]
  }
}

Step 4: Configure VMs and Verify​

SSH into each VM and configure the BGP daemon (see the Configuring Anycast guide for BIRD2 configuration).

After configuration, verify the sessions are established:

curl -X GET "https://api.netactuate.com/api/v3/bgp/anycast-group/301" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "status": "success",
  "data": {
    "id": 301,
    "label": "ecmp-group-lax",
    "sessions": [
      {"id": 5001, "server_id": 98001, "state": "established"},
      {"id": 5002, "server_id": 98002, "state": "established"}
    ],
    "prefix": "192.0.2.0/24",
    "ecmp_active": true,
    "ecmp_paths": 2
  }
}

When ecmp_active is true and ecmp_paths matches the number of sessions, ECMP is operational. Traffic to the prefix is now distributed across both VMs.

Adding More ECMP Paths​

To add a third (or Nth) VM to the ECMP group:

  1. Deploy the VM at the same location.
  2. Create a BGP session for it.
  3. Add the session to the existing anycast group:
curl -X PUT "https://api.netactuate.com/api/v3/bgp/anycast-group/301" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "add_session_ids": [5003]
  }'

Removing an ECMP Path​

To remove a VM from the ECMP group without disrupting the others:

curl -X PUT "https://api.netactuate.com/api/v3/bgp/anycast-group/301" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "remove_session_ids": [5002]
  }'

The remaining sessions continue to handle traffic. ECMP paths are recalculated automatically.

Next Steps​

Need Help?​

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