View All Products
Compute
Storage
Databases
Networking
Developer Tools
Delivery
Security
Services
Industries
Pricing
Community
Engage With Us
Linode API 4.163.0

Endpoints

NodeBalancers

Nodes List

get
https://api.linode.com/v4/nodebalancers/{nodeBalancerId}/configs/{configId}/nodes

Returns a paginated list of NodeBalancer nodes associated with this Config. These are the backends that will be sent traffic for this port.

Path Parameters

nodeBalancerId
Required
integer

The ID of the NodeBalancer to access.

configId
Required
integer

The ID of the NodeBalancer config to access.

Query Parameters

page
integer > = 1
Default: 1

The page of a collection to return.

page_size
integer [25 .. 500]
Default: 100

The number of items to return per page.

Request Samples

curl -H "Authorization: Bearer $TOKEN" \
    https://api.linode.com/v4/nodebalancers/12345/configs/4567/nodes

Response Samples

{
  "data": [
    {
      "id": "",
      "status": "UP",
      "label": "node54321",
      "weight": 50,
      "address": "192.168.210.120:80",
      "nodebalancer_id": 12345,
      "mode": "accept",
      "config_id": 4567
    }
  ],
  "page": 1,
  "pages": 1,
  "results": 1
}

Responses

200: A paginated list of NodeBalancer nodes.

data
array of objects
id
integer

This node's unique ID.

status
string
Enum: "unknown""UP""DOWN"

The current status of this node, based on the configured checks of its NodeBalancer Config.

label
string[a-zA-Z0-9-_.]{3,32}

The label for this node. This is for display purposes only.

weight
integer

Used when picking a backend to serve a request and is not pinned to a single backend yet. Nodes with a higher weight will receive more traffic.

address
string

The private IP Address where this backend can be reached. This must be a private IP address.

nodebalancer_id
integer

The NodeBalancer ID that this Node belongs to.

mode
string
Enum: "accept""reject""drain""backup"

The mode this NodeBalancer should use when sending traffic to this backend.

  • If set to accept this backend is accepting traffic.
  • If set to reject this backend will not receive traffic.

  • If set to drain this backend will not receive new traffic, but connections already pinned to it will continue to be routed to it.

  • If set to backup, this backend will only receive traffic if all accept nodes are down.

config_id
integer

The NodeBalancer Config ID that this Node belongs to.

page
integer

The current page.

pages
integer

The total number of pages.

results
integer

The total number of results.

default: Error

errors
array of objects
reason
string

What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to open a Support Ticket or perform some other action before you can complete the request successfully.

field
string

The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as "null" if the error is not specific to any single element of the request.

Node Create

post
https://api.linode.com/v4/nodebalancers/{nodeBalancerId}/configs/{configId}/nodes

Creates a NodeBalancer Node, a backend that can accept traffic for this NodeBalancer Config. Nodes are routed requests on the configured port based on their status.

Path Parameters

nodeBalancerId
Required
integer

The ID of the NodeBalancer to access.

configId
Required
integer

The ID of the NodeBalancer config to access.

Request Body Schema

address
Required
string <ip>

The private IP Address where this backend can be reached. This must be a private IP address.

label
Required
string [3 .. 32] characters [a-zA-Z0-9-_.]{3,32}

The label for this node. This is for display purposes only.

mode
string

The mode this NodeBalancer should use when sending traffic to this backend.

  • If set to accept this backend is accepting traffic.
  • If set to reject this backend will not receive traffic.

  • If set to drain this backend will not receive new traffic, but connections already pinned to it will continue to be routed to it.

  • If set to backup, this backend will only receive traffic if all accept nodes are down.

weight
integer

Used when picking a backend to serve a request and is not pinned to a single backend yet. Nodes with a higher weight will receive more traffic.

Request Samples

curl -H "Content-Type: application/json" \
    -H "Authorization: Bearer $TOKEN" \
    -X POST -d '{
      "address": "192.168.210.120:80",
      "label": "node54321",
      "weight": 50,
      "mode": "accept"
    }' \
    https://api.linode.com/v4/nodebalancers/12345/configs/4567/nodes

Response Samples

{
  "status": "UP",
  "id": 1234,
  "label": "node54321",
  "weight": 50,
  "address": "192.168.210.120:80",
  "nodebalancer_id": 12345,
  "mode": "accept",
  "config_id": 4567
}

Responses

200: Node created successfully.

status
string
Enum: "unknown""UP""DOWN"

The current status of this node, based on the configured checks of its NodeBalancer Config.

id
integer

This node's unique ID.

label
string [3 .. 32] characters [a-zA-Z0-9-_.]{3,32}

The label for this node. This is for display purposes only.

weight
integer

Used when picking a backend to serve a request and is not pinned to a single backend yet. Nodes with a higher weight will receive more traffic.

address
string <ip>

The private IP Address where this backend can be reached. This must be a private IP address.

nodebalancer_id
integer

The NodeBalancer ID that this Node belongs to.

mode
string
Enum: "accept""reject""drain""backup"

The mode this NodeBalancer should use when sending traffic to this backend.

  • If set to accept this backend is accepting traffic.
  • If set to reject this backend will not receive traffic.

  • If set to drain this backend will not receive new traffic, but connections already pinned to it will continue to be routed to it.

  • If set to backup, this backend will only receive traffic if all accept nodes are down.

config_id
integer

The NodeBalancer Config ID that this Node belongs to.

default: Error

errors
array of objects
reason
string

What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to open a Support Ticket or perform some other action before you can complete the request successfully.

field
string

The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as "null" if the error is not specific to any single element of the request.