Load Balancers¶

In the Networking section of your Project, select Load Balancers.

Click Create a Load Balancer.

First, select the Metro where your load balancer will live and enter a hostname in the field. The IP address will be assigned automatically when it is created.

Then, assign a Listening Port by specifying which protocol and port the load balancer should listen for and on. Currently only TCP traffic is supported.

Then, optionally, add a pool to handle the traffic. If you don't have any pools, you can create an origin pool here during the load balancer creation process or at any time before or after creating a load balancer from the Manage Pools tab.

If you need the load balancer to listen on multiple ports, click Add Listener Ports to repeat the process of assigning a Listening Port protocol, port, and optionally an origin pool.

When you are happy with your initial Load Balancer set up, click Deploy Load Balancer to provision it.

Once the load balancer is provisioned, it is listed by hostname on your Load Balancers tab, showing it's type, location, listening ports, origin pools, status, and IP address. The load balancers status will depend on if you assigned any origin pools at provision time.

Note: The Load Balancer API is still in Beta. While most features are complete, the API endpoints are subject to change until generally available.

To create a load balancer in the API you will need:

• to create the load balancer itself.
• and to create a listener port.

After a load balancer and its listener ports are provisioned, you can create and attach origin pools to the listener ports.

To create a load balancer, send a POST request to the lb.metalctrl.io/v1/projects/{id}/loadbalancers endpoint.

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: bearer <ACCESS_TOKEN>" \
https://lb.metalctrl.io/v1/projects/{id}/loadbalancers \
-d '{
    "name": "<string>",
    "location_id": "<location_id>"
}'

Body Parameters:

• "name" (required) - The name of the load balancer.
• "location_id" (required) - The ID of the location of the load balancer. Currently, it must be one of:
  • AM - lctnloc-1ttCRz-P8aY0rda9BxOiL
  • DA - lctnloc--uxs0GLeAELHKV8GxO_AI
  • NY - lctnloc-Vy-1Qpw31mPi6RJQwVf9A
  • SV - lctnloc-H5rl2M2VL5dcFmdxhbEKx
  • SG - lctnloc-AxCxpIrNUaaoGBkM02uuw
  • DC - lctnloc-1lJjVT6Zp_Fs4UpW5LWQu
• "provider_id" (optional) - The ID of the provider or type of load balancer. Currently, only a single provider is supported so the provider ID defaults to loadpvd-gOB_-byp5ebFo7A3LHv2B.
• "port_ids" (optional) - Array of listener port ID's to be added to the load balancer. If this is your first load balancer, you will probably create the listening ports after the load balancer, as the next step.

To create a listener port for your load balancer, send a POST request to the lb.metalctrl.io/v1/loadbalancers/{id}/ports endpoint, specifying the port the load balancer listens on in the body of the request.

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: bearer <ACCESS_TOKEN>" \
https://lb.metalctrl.io/v1/loadbalancers/{id}/ports 
-d '{ 
    "name": "<string>", 
    "number": <int>
}'

Body Parameters:

• "name" (required) - The name of the listener port.
• "number" (required) - The port number that the listener should listen on.

You can create Origin Pools at any time from the Manage Pools tab in the Load Balancers section of your Project. Click Create Origin Pool.

The process is the same whether you are on the fly when creating your load balancer or creating a new pool from the Manage Pools tab.

First, give your origin pool a name. Then in the Add Origin(s) section, select the origin type.

Select the server and its IP address or an IP Block and its IP address that you would like to add to the pool. Specify the port and the weight. he higher the weight, the more traffic will be handled by this origin. Click Save to add it to the Origins list.

To add more origins to the origin pool, click +, and repeat the process.

When you have added all your origins to the origin pool, click Create.

Note: The Load Balancer API is still in Beta. While most features are complete, the API endpoints are subject to change until generally available.

To create an origin pool in the API, you will need to create the origin pool and then define the origins that fill the pool. To create the origin pool, send a POST request to the lb.metalctrl.io/v1/projects/{id}/loadbalancers/pools endpoint.

curl -X POST  \
-H "Content-Type: application/json" \
-H "Authorization: bearer <ACCESS_TOKEN>" \
https://lb.metalctrl.io/v1/projects/{id}/loadbalancers/pools \
-d '{ 
    "name": "<string>", 
    "protocol": "tcp",
    "port_ids": [<"port_id">, <"port_id">],
    "origin_ids": [<"origin_id">, <"origin_id">]
}'

Body Parameters:

• "name" (required) - Friendly name of the pool.
• "protocol" (required) - Specify the type of traffic the pool is handling. Currently only TCP traffic is supported.
• "port_ids" (optional) - An array of listener port ID's to attach to the origin pools to. You can also assign the origin pools to a listener port as a separate step.
• "origin_ids" (optional) - An array of origin ID's to attach to the origin pool. If you do not have any origins, you can omit this parameter and create an empty pool.

To define an origin, send a POST request to the lb.metalctrl.io/v1/loadbalancers/pools/{id}/origins endpoint. Specify the origin pool for the origin as a path parameter. Define the origin in the body of the request.

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: bearer <ACCESS_TOKEN>" \
https://lb.metalctrl.io/v1/loadbalancers/pools/{id}/origins \
-d '{ 
    "name": "<string>", 
    "target": "<ip_address>", 
    "port_number": <int>,
    "weight": <int>,
    "active": <boolean>
}'

Body Parameters:

• "name" (required) - The name of the origin.
• "target" (required) - The origin's IP Address. Currently only public IPv4 endpoints hosted on Equinix Metal are supported. These can be the public IP addresses of your Metal servers or a reserved public IPv4 in the same Project and Metro as your load balancer.
• "port_number" (required) - The origin's port number.
• "weight" (required) - Integer weight between 1 and 256. The higher the weight, the more traffic will be handled by this origin.
• "active" (required) - Boolean field to set the origin as active or inactive.

All the information about your origin pools is available on the Manage Pools tab of the Load Balancers page of your Project.

You an update the name and manage the origins in the pool by clicking the Manage icon of an Origin Pool.

Note: The Load Balancer API is still in Beta. While most features are complete, the API endpoints are subject to change until generally available.

To get a list of all the origin pools in your Project from the API, send a GET request to the lb.metalctrl.io/v1/projects/{id}/loadbalancers/pools endpoint.

curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: bearer <ACCESS_TOKEN>" \ 
https://lb.metalctrl.io/v1/projects/{id}/loadbalancers/pools

To get the details of an individual origin pool, send a GET request to the lb.metalctrl.io/v1/loadbalancers/pools/{id} endpoint.

curl -X GET \
-H 'Content-Type: application/json' \
-H "Authorization: bearer <ACCESS_TOKEN>" \
https://lb.metalctrl.io/v1/loadbalancers/pools/{id}

To update an Origin Pool, send a PATCH request to the lb.metalctrl.io/v1/loadbalancers/pools/{id} endpoint, using the fields you would like to update in the body of the request. All fields are optional, so they can be updated independently.

curl -X PATCH \
-H 'Content-Type: application/json' \
-H "Authorization: bearer <ACCESS_TOKEN>" \
https://lb.metalctrl.io/v1/loadbalancers/pools/{id} \
-d '{
    "name": "<string>",
    "protocol": "tcp",
    "add_port_ids": [
        "<string>"
    ],
    "remove_port_ids": [
        "<string>"
    ],
    "clear_ports": <boolean>,
    "add_origin_ids": [
        "<string>"
    ],
    "remove_origin_ids": [
        "<string>"
    ],
    "clear_origins": <boolean>
}'

Body Parameters:

• "name" - Name of the Origin Pool.
• "protocol" - Protocol to use for Origin Pool, currently only tcp is supported.
• "add_port_ids" - An array of Listener Ports to assign this Origin Pool to.
• "remove_port_ids" - An array of Listener Ports to remove this Origin Pool from.
• `"clear_ports" - A boolean that removes this Origin Pool from all Listening Ports.
• "add_origin_ids" - An array of Origins to add to this Origin Pool.
• "remove_origin_ids" - An array of Origins to remove from this Origin Pool.
• "clear_origins" - A boolean that removes all Origins from this Origin Pool.

To add an origin to a pool, click Manage, and from the Manage Pool slide out, click +.

Fill out the fields to define the origin, then click Update to add the origin to the pool. For the weight, the higher the weight, the more traffic will be handled by this origin.

Note: The Load Balancer API is still in Beta. While most features are complete, the API endpoints are subject to change until generally available.

To create and add an origin to a pool, send a POST request to the lb.metalctrl.io/v1/loadbalancers/pools/{id}/origins endpoint. Specify the origin pool for the origin as a path parameter. Define the origin in the body of the request.

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: bearer <ACCESS_TOKEN>" \
https://lb.metalctrl.io/v1/loadbalancers/pools/{id}/origins 
-d '{ 
    "name": "<string>", 
    "target": "<ip_address>", 
    "port_number": <int>,
    "weight": <int>,
    "active": <boolean>
}'

Body Parameters:

• "name" (required) - The name of the origin.
• "target" (required) - The origin's IP Address. Currently only public IPv4 endpoints hosted on Equinix Metal are supported. These can be the public IP addresses of your Metal servers or a reserved public IPv4 in the same Project and Metro as your load balancer.
• "port_number" (required) - The origin's port number.
• "weight" (required) - Integer weight between 1 and 256. The higher the weight, the more traffic will be handled by this origin.
• "active" (required) - Boolean field to set the origin as active or inactive.

To add already existing origins to an origin pool, send a PATCH request to the lb.metalctrl.io/v1/loadbalancers/pools/{id} endpoint with the origin IDs specified in the body of the request.

curl -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: bearer <ACCESS_TOKEN>" \
https://lb.metalctrl.io/v1/loadbalancers/pools/{id}
-d '{ 
    "add_origin_ids": [<"origin_id">, <"origin_id">]
}'

All Origins in a Pool are listed in the Manage Pool panel of an Origin Pool.

To modify an origin, click Manage next to the origin you want to update. Change the fields under Edit Origin to the new values and click Save to save the changes.

Note: The Load Balancer API is still in Beta. While most features are complete, the API endpoints are subject to change until generally available.

To list all the Origins in a pool, send a GET request to the lb.metalctrl.io/v1/loadbalancers/pools/{id}/origins endpoint.

curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: bearer <ACCESS_TOKEN>" \
https://lb.metalctrl.io/v1/loadbalancers/pools/{id}/origins

To update an Origin, send a PATCH request to the lb.metalctrl.io/v1/loadbalancers/pools/origins/{id} endpoint, using the fields you would like to update in the body of the request. All fields are optional, so they can be updated independently.

curl -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: bearer <ACCESS_TOKEN>" \
https://lb.metalctrl.io/v1/loadbalancers/pools/origins/{id}
-d '{ 
    "name": "<string>", 
    "target": "<ip_address>", 
    "port_number": <int>,
    "weight": <int>,
    "active": <boolean>
}'

Body Parameters:

• "name" - A name for the Origin.
• "target" - The origin's IP Address. Currently only public IPv4 endpoints hosted on Equinix Metal are supported. These can be the public IP addresses of your Metal servers or a reserved public IPv4 in the same Project and Metro as your load balancer.
• "port_number" - The origin's port number.
• "weight" - Integer weight between 1 and 256. The higher the weight, the more traffic will be handled by this origin.
• "active" - Boolean field to set the origin as active or inactive.

To delete an Origin, send a DELETE request to the lb.metalctrl.io/v1/loadbalancers/pools/origins/{id} endpoint.

curl -X DELETE \
-H "Content-Type: application/json" \
-H "Authorization: bearer <ACCESS_TOKEN>" \
https://lb.metalctrl.io/v1/loadbalancers/pools/origins/{id}

To remove an origin from an origin pool, open the Manage Pool panel, and click Delete next to the origin you want to remove from the pool.

Note - this also deletes the origin.

Note: The Load Balancer API is still in Beta. While most features are complete, the API endpoints are subject to change until generally available.

To remove an origin from a pool, send a send a PATCH request to the lb.metalctrl.io/v1/loadbalancers/pools/{id} endpoint with the origin IDs specified in the body of the request.

curl -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: bearer <ACCESS_TOKEN>" \
https://lb.metalctrl.io/v1/loadbalancers/pools/{id}
-d '{ 
    "remove_origin_ids": [<"origin_id">, <"origin_id">]
}'

Alternatively, you can set an origin as inactive instead of removing it. Send a PATCH request to the lb.metalctrl.io/v1/loadbalancers/pools/origins/{id} endpoint with "active" set to false in the body of the request.

curl -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: bearer <ACCESS_TOKEN>" \
https://lb.metalctrl.io/v1/loadbalancers/pools/origins/{id}
-d '{ 
    "active": false
}'

This does not delete the origin. If you need to reactivate this origin in the pool you can use the same request with "active" set to true.

To delete an entire Origin Pool, click Delete next to the Origin Pool you would like to delete.

Note: The Load Balancer API is still in Beta. While most features are complete, the API endpoints are subject to change until generally available.

To delete an Origin Pool, send a DELETE request to the lb.metalctrl.io/v1/loadbalancers/pools/{id} endpoint.

curl -X DELETE \
-H "Content-Type: application/json" \
-H "Authorization: bearer <ACCESS_TOKEN>" \
https://lb.metalctrl.io/v1/loadbalancers/pools/{id}

Whether you have one load balancer or many load balancers, they are listed on your Project's Load Balancers page.

Click on a load balancer to view its details.

You can manage your load balancer's listening ports and origin pools on the Lister Ports tab.

Note: The Load Balancer API is still in Beta. While most features are complete, the API endpoints are subject to change until generally available.

To list all the load balancers in a Project, send a GET request to the lb.metalctrl.io/v1/projects/{id}/loadbalancers endpoint.

curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: bearer <ACCESS_TOKEN>" \
https://lb.metalctrl.io/v1/projects/{id}/loadbalancers

To get the details of a specific load balancer, send a GET request to the lb.metalctrl.io/v1/loadbalancers/{id} endpoint.

curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: bearer <ACCESS_TOKEN>" \ 
https://lb.metalctrl.io/v1/loadbalancers/{id}

To update a load balancer, send a PATCH request to the lb.metalctrl.io/v1/loadbalancers/{id} endpoint, using the fields you would like to update in the body of the request. All fields are optional, so the can be updated independently. Listener port management is covered in more detail in the following sections.

curl -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: bearer <ACCESS_TOKEN>" \
https://lb.metalctrl.io/v1/loadbalancers/{id}
-d '{ 
    "name": "<string>",
    "add_port_ids": [<"port_id">, <"port_id">],
    "remove_port_ids": [<"port_id">, <"port_id">],
    "clear_ports": <boolean>
}'

Body Parameters:

• "name" - The name of the load balancer.
• "add_port_ids" - An array of listening port ID's to be added to load balancer.
• "remove_port_ids" - An array of listening port ID's to be removed from load balancer.
• "clear_ports" - Boolean indicating whether all listening ports should be removed from load balancer.

A load balancer's lister ports are listed on its Listener Ports tab.

Click on a port to expand its details, including a list of the Origin Pools, their status, and a link to manage the pools.

To add a Listener Port, click + Add New. Specify the port number in the Port field. Select the pool or pools to handle traffic from this port, or click + Create a pool to create a new pool for the listener port.

Click Add to add the Listener Port to the Load Balancer.

To update the port that the listener port listens on, open the Manage Listener Port slide out. Enter the new port number in the Port field. Click Save to save your changes.

To remove a Listener Port from a load balancer, click the Delete icon next to the listener port on the Listener Ports tab.

Note: The Load Balancer API is still in Beta. While most features are complete, the API endpoints are subject to change until generally available.

To get a list of all the Listener Ports on a load balancer, send a GET request to the lb.metalctrl.io/v1/loadbalancers/{id}/ports/ endpoint.

curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: bearer <ACCESS_TOKEN>" 
https://lb.metalctrl.io/v1/loadbalancers/{id}/ports/

To get the details of a specific Listener Port, send a GET request to the lb.metalctrl.io/v1/loadbalancers/{id}/ports/ endpoint.

curl -H 'Content-Type: application/json' -H "Authorization: bearer <ACCESS_TOKEN>" https://lb.metalctrl.io/v1/loadbalancers/{id}/ports/{port_number}

To add a listener port to your load balancer, send a POST request to the lb.metalctrl.io/v1/loadbalancers/{id}/ports endpoint, specifying the port the load balancer listens on in the body of the request.

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: bearer <ACCESS_TOKEN>" \
https://lb.metalctrl.io/v1/loadbalancers/{id}/ports 
-d '{ 
    "name": "<string>", 
    "number": <int>,
    "pool_ids": ["<pool_id>, <pool_id>"]
}'

Body Parameters:

• "name" (required) - The name of the listener port.
• "number" (required) - The port number that the listener should listen on.
• "pool_ids" (optional) - An array of origin pool IDs to attach the listener port, if you have already created origin pools. Or you can create and assign origin pools to your listener port at a later time.

To update a Listener Port, send a PATCH request to the lb.metalctrl.io/v1/loadbalancers/ports/{id} endpoint. All fields are optional, so the can be updated independently.

curl -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: bearer <ACCESS_TOKEN>" \
https://lb.metalctrl.io/v1/loadbalancers/ports/{id}
-d '{ 
    "name": "<string>", 
    "number": <int>,
    "add_pool_ids": [<"pool_id">, <"pool_id">],
    "remove_pool_ids": [<"pool_id">, <"pool_id">]
}'

Body Parameters:

• "name" - The name of the listener port.
• "number" - The port number that the listener should listen on.
• "add_pool_ids" - Array of origin pools to add to this listener port.
• "remove_pool_ids" - Array of origin pools to remove from this listener port.

To delete a Listener Port, send a DELETE request to the lb.metalctrl.io/v1/loadbalancers/ports/{id} endpoint.

curl -X DELETE \
-H "Content-Type: application/json" \
-H "Authorization: bearer <ACCESS_TOKEN>" 
https://lb.metalctrl.io/v1/loadbalancers/ports/{id}

To add an Origin Pool to a Listener Port, click Manage, and from the Manage Listener Port slide out, click + in the Manage Origin Pools section. You can add an existing pool from the drop-down menu or create a new one. Click Save to save your changes.

To remove an Origin Pool from the Listener Port, click the Delete icon next to the Origin Pool you would like to remove. Click Save to save the change.

Removing an Origin Pool from a Listener Port does not delete it.

Note: The Load Balancer API is still in Beta. While most features are complete, the API endpoints are subject to change until generally available.

To add an Origin Pool to a Listener Port, send a PATCH request to the lb.metalctrl.io/v1/loadbalancers/ports/{id} endpoint, specifying the origin pools by ID in the body of the request.

curl -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: bearer <ACCESS_TOKEN>" \
https://lb.metalctrl.io/v1/loadbalancers/ports/{id}
-d '{ 
    "add_pool_ids": [<"pool_id">, <"pool_id">]
}'

To remove an Origin Pool from a Listener Port, send a PATCH request to the lb.metalctrl.io/v1/loadbalancers/ports/{id} endpoint, specifying the origin pools to remove by ID in the body of the request.

curl -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: bearer <ACCESS_TOKEN>" \
https://lb.metalctrl.io/v1/loadbalancers/ports/{id}
-d '{ 
    "remove_pool_ids": [<"pool_id">, <"pool_id">]
}'

You can delete a load balancer from the list on the Project's Load Balancers page. Select the load balancer (or load balancers) and click Delete.

Note: The Load Balancer API is still in Beta. While most features are complete, the API endpoints are subject to change until generally available.

To delete a load balancer, send a DELETE request to the lb.metalctrl.io/v1/loadbalancers/{id} endpoint.

curl -X DELETE \
-H "Content-Type: application/json" \
-H "Authorization: bearer <ACCESS_TOKEN>" \
https://lb.metalctrl.io/v1/loadbalancers/{id}