Node Balancers v4.119.0

NodeBalancers List

GET https://api.linode.com/v4/nodebalancers

Returns a paginated list of NodeBalancers you have access to.

Authorizations

personalAccessToken
oauth	nodebalancers:read_only

Query Parameters

page

Type:: integer >= 1
Default: 1
Default:: 1

The page of a collection to return.

page_size

Type:: integer 25..100
Default: 100
Default:: 100

The number of items to return per page.

Request Samples

Response Samples

Responses

NodeBalancer Create

POST https://api.linode.com/v4/nodebalancers

Creates a NodeBalancer in the requested Region. This NodeBalancer will not start serving requests until it is configured.

Authorizations

personalAccessToken
oauth	nodebalancers:read_write

Request Body Schema

client_conn_throttle	`integer` 0..20 Throttle connections per second. Set to 0 (zero) to disable throttling.
configs	`array` The ports to configure this NodeBalancer with on creation. Each config must have a unique port and at least one Node.
label Filterable	`string` 3..32 characters This NodeBalancer’s label. These must be unique on your Account.
region Required	`string` The ID of the Region to create this NodeBalancer in.

Request Samples

Response Samples

Responses

NodeBalancer Delete

DELETE https://api.linode.com/v4/nodebalancers/{nodeBalancerId}

Deletes a NodeBalancer.

This is a destructive action and cannot be undone.

Deleting a NodeBalancer will also delete all associated Configs and Nodes, although the backend servers represented by the Nodes will not be changed or removed. Deleting a NodeBalancer will cause you to lose access to the IP Addresses assigned to this NodeBalancer.

Authorizations

personalAccessToken
oauth	nodebalancers:read_write

Path Parameters

nodeBalancerId

integer

Required

The ID of the NodeBalancer to access.

Request Samples

Response Samples

Responses

NodeBalancer View

GET https://api.linode.com/v4/nodebalancers/{nodeBalancerId}

Returns a single NodeBalancer you can access.

Authorizations

personalAccessToken
oauth	nodebalancers:read_only

Path Parameters

nodeBalancerId

integer

Required

The ID of the NodeBalancer to access.

Request Samples

Response Samples

Responses

NodeBalancer Update

PUT https://api.linode.com/v4/nodebalancers/{nodeBalancerId}

Updates information about a NodeBalancer you can access.

Authorizations

personalAccessToken
oauth	nodebalancers:read_write

Path Parameters

nodeBalancerId

integer

Required

The ID of the NodeBalancer to access.

Request Body Schema

client_conn_throttle

integer 0..20

Throttle connections per second. Set to 0 (zero) to disable throttling.

label

Filterable

string 3..32 characters

This NodeBalancer’s label. These must be unique on your Account.

Request Samples

Response Samples

Responses

Configs List

GET https://api.linode.com/v4/nodebalancers/{nodeBalancerId}/configs

Returns a paginated list of NodeBalancer Configs associated with this NodeBalancer. NodeBalancer Configs represent individual ports that this NodeBalancer will accept traffic on, one Config per port.

For example, if you wanted to accept standard HTTP traffic, you would need a Config listening on port 80.

Authorizations

personalAccessToken
oauth	nodebalancers:read_only

Path Parameters

nodeBalancerId

integer

Required

The ID of the NodeBalancer to access.

Query Parameters

page

Type:: integer >= 1
Default: 1
Default:: 1

The page of a collection to return.

page_size

Type:: integer 25..100
Default: 100
Default:: 100

The number of items to return per page.

Request Samples

Response Samples

Responses

Config Create

POST https://api.linode.com/v4/nodebalancers/{nodeBalancerId}/configs

Creates a NodeBalancer Config, which allows the NodeBalancer to accept traffic on a new port. You will need to add NodeBalancer Nodes to the new Config before it can actually serve requests.

Authorizations

personalAccessToken
oauth	nodebalancers:read_write

Path Parameters

nodeBalancerId

integer

Required

The ID of the NodeBalancer to access.

Request Body Schema

algorithm	`string` Enum: `roundrobin` `leastconn` `source` What algorithm this NodeBalancer should use for routing traffic to backends.
check	`string` Enum: `none` `connection` `http` `http_body` The type of check to perform against backends to ensure they are serving requests. This is used to determine if backends are up or down. If `none` no check is performed. `connection` requires only a connection to the backend to succeed. `http` and `http_body` rely on the backend serving HTTP, and that the response returned matches what is expected.
check_attempts	`integer` 1..30 How many times to attempt a check before considering a backend to be down.
check_body	`string` This value must be present in the response body of the check in order for it to pass. If this value is not present in the response body of a check request, the backend is considered to be down.
check_interval	`integer` How often, in seconds, to check that backends are up and serving requests.
check_passive	`boolean` If true, any response from this backend with a `5xx` status code will be enough for it to be considered unhealthy and taken out of rotation.
check_path	`string` The URL path to check on each backend. If the backend does not respond to this request it is considered to be down.
check_timeout	`integer` 1..30 How long, in seconds, to wait for a check attempt before considering it failed.
cipher_suite	`string` Enum: `recommended` `legacy` What ciphers to use for SSL connections served by this NodeBalancer. `legacy` is considered insecure and should only be used if necessary.
port	`integer` 1..65535 The port this Config is for. These values must be unique across configs on a single NodeBalancer (you can’t have two configs for port 80, for example). While some ports imply some protocols, no enforcement is done and you may configure your NodeBalancer however is useful to you. For example, while port 443 is generally used for HTTPS, you do not need SSL configured to have a NodeBalancer listening on port 443.
protocol	`string` Enum: `http` `https` `tcp` The protocol this port is configured to serve. If using `http` or `tcp` protocol, `ssl_cert` and `ssl_key` are not supported. If using `https` protocol, `ssl_cert` and `ssl_key` are required.
proxy_protocol	`string` Enum: `none` `v1` `v2` Default: `none` ProxyProtocol is a TCP extension that sends initial TCP connection information such as source/destination IPs and ports to backend devices. This information would be lost otherwise. Backend devices must be configured to work with ProxyProtocol if enabled. If ommited, or set to `none`, the NodeBalancer doesn’t send any auxilary data over TCP connections. This is the default. If set to `v1`, the human-readable header format (Version 1) is used. If set to `v2`, the binary header format (Version 2) is used.
ssl_cert Nullable	`string <ssl-cert>` The PEM-formatted public SSL certificate (or the combined PEM-formatted SSL certificate and Certificate Authority chain) that should be served on this NodeBalancerConfig’s port. The contents of this field will not be shown in any responses that display the NodeBalancerConfig. Instead, `<REDACTED>` will be printed where the field appears. The read-only `ssl_commonname` and `ssl_fingerprint` fields in a NodeBalancerConfig response are automatically derived from your certificate. Please refer to these fields to verify that the appropriate certificate was assigned to your NodeBalancerConfig.
ssl_key Nullable	`string <ssl-key>` The PEM-formatted private key for the SSL certificate set in the `ssl_cert` field. Line breaks must be represented as “\n” in the string. The contents of this field will not be shown in any responses that display the NodeBalancerConfig. Instead, `<REDACTED>` will be printed where the field appears. The read-only `ssl_commonname` and `ssl_fingerprint` fields in a NodeBalancerConfig response are automatically derived from your certificate. Please refer to these fields to verify that the appropriate certificate was assigned to your NodeBalancerConfig.
stickiness	`string` Enum: `none` `table` `http_cookie` Controls how session stickiness is handled on this port. If set to `none` connections will always be assigned a backend based on the algorithm configured. If set to `table` sessions from the same remote address will be routed to the same backend. For HTTP or HTTPS clients, `http_cookie` allows sessions to be routed to the same backend based on a cookie set by the NodeBalancer.

Request Samples

Response Samples

Responses

Config Delete

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

Deletes the Config for a port of this NodeBalancer.

This cannot be undone.

Once completed, this NodeBalancer will no longer respond to requests on the given port. This also deletes all associated NodeBalancerNodes, but the Linodes they were routing traffic to will be unchanged and will not be removed.

Authorizations

personalAccessToken
oauth	nodebalancers:read_write

Path Parameters

nodeBalancerId	`integer` Required The ID of the NodeBalancer to access.
configId	`integer` Required The ID of the config to access.

Request Samples

Response Samples

Responses

Config View

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

Returns configuration information for a single port of this NodeBalancer.

Authorizations

personalAccessToken
oauth	nodebalancers:read_only

Path Parameters

nodeBalancerId	`integer` Required The ID of the NodeBalancer to access.
configId	`integer` Required The ID of the config to access.

Request Samples

Response Samples

Responses

Config Update

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

Updates the configuration for a single port on a NodeBalancer.

Authorizations

personalAccessToken
oauth	nodebalancers:read_write

Path Parameters

nodeBalancerId	`integer` Required The ID of the NodeBalancer to access.
configId	`integer` Required The ID of the config to access.

Request Body Schema

algorithm	`string` Enum: `roundrobin` `leastconn` `source` What algorithm this NodeBalancer should use for routing traffic to backends.
check	`string` Enum: `none` `connection` `http` `http_body` The type of check to perform against backends to ensure they are serving requests. This is used to determine if backends are up or down. If `none` no check is performed. `connection` requires only a connection to the backend to succeed. `http` and `http_body` rely on the backend serving HTTP, and that the response returned matches what is expected.
check_attempts	`integer` 1..30 How many times to attempt a check before considering a backend to be down.
check_body	`string` This value must be present in the response body of the check in order for it to pass. If this value is not present in the response body of a check request, the backend is considered to be down.
check_interval	`integer` How often, in seconds, to check that backends are up and serving requests.
check_passive	`boolean` If true, any response from this backend with a `5xx` status code will be enough for it to be considered unhealthy and taken out of rotation.
check_path	`string` The URL path to check on each backend. If the backend does not respond to this request it is considered to be down.
check_timeout	`integer` 1..30 How long, in seconds, to wait for a check attempt before considering it failed.
cipher_suite	`string` Enum: `recommended` `legacy` What ciphers to use for SSL connections served by this NodeBalancer. `legacy` is considered insecure and should only be used if necessary.
port	`integer` 1..65535 The port this Config is for. These values must be unique across configs on a single NodeBalancer (you can’t have two configs for port 80, for example). While some ports imply some protocols, no enforcement is done and you may configure your NodeBalancer however is useful to you. For example, while port 443 is generally used for HTTPS, you do not need SSL configured to have a NodeBalancer listening on port 443.
protocol	`string` Enum: `http` `https` `tcp` The protocol this port is configured to serve. If using `http` or `tcp` protocol, `ssl_cert` and `ssl_key` are not supported. If using `https` protocol, `ssl_cert` and `ssl_key` are required.
proxy_protocol	`string` Enum: `none` `v1` `v2` Default: `none` ProxyProtocol is a TCP extension that sends initial TCP connection information such as source/destination IPs and ports to backend devices. This information would be lost otherwise. Backend devices must be configured to work with ProxyProtocol if enabled. If ommited, or set to `none`, the NodeBalancer doesn’t send any auxilary data over TCP connections. This is the default. If set to `v1`, the human-readable header format (Version 1) is used. If set to `v2`, the binary header format (Version 2) is used.
ssl_cert Nullable	`string <ssl-cert>` The PEM-formatted public SSL certificate (or the combined PEM-formatted SSL certificate and Certificate Authority chain) that should be served on this NodeBalancerConfig’s port. The contents of this field will not be shown in any responses that display the NodeBalancerConfig. Instead, `<REDACTED>` will be printed where the field appears. The read-only `ssl_commonname` and `ssl_fingerprint` fields in a NodeBalancerConfig response are automatically derived from your certificate. Please refer to these fields to verify that the appropriate certificate was assigned to your NodeBalancerConfig.
ssl_key Nullable	`string <ssl-key>` The PEM-formatted private key for the SSL certificate set in the `ssl_cert` field. Line breaks must be represented as “\n” in the string. The contents of this field will not be shown in any responses that display the NodeBalancerConfig. Instead, `<REDACTED>` will be printed where the field appears. The read-only `ssl_commonname` and `ssl_fingerprint` fields in a NodeBalancerConfig response are automatically derived from your certificate. Please refer to these fields to verify that the appropriate certificate was assigned to your NodeBalancerConfig.
stickiness	`string` Enum: `none` `table` `http_cookie` Controls how session stickiness is handled on this port. If set to `none` connections will always be assigned a backend based on the algorithm configured. If set to `table` sessions from the same remote address will be routed to the same backend. For HTTP or HTTPS clients, `http_cookie` allows sessions to be routed to the same backend based on a cookie set by the NodeBalancer.

Request Samples

Response Samples

Responses

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.

Authorizations

personalAccessToken
oauth	nodebalancers:read_only

Path Parameters

nodeBalancerId	`integer` Required The ID of the NodeBalancer to access.
configId	`integer` Required The ID of the NodeBalancer config to access.

Query Parameters

page

Type:: integer >= 1
Default: 1
Default:: 1

The page of a collection to return.

page_size

Type:: integer 25..100
Default: 100
Default:: 100

The number of items to return per page.

Request Samples

Response Samples

Responses

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.

Authorizations

personalAccessToken
oauth	nodebalancers:read_write

Path Parameters

nodeBalancerId	`integer` Required The ID of the NodeBalancer to access.
configId	`integer` Required 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 The label for this node. This is for display purposes only.
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.
weight	`integer` 1..255 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

Response Samples

Responses

Node Delete

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

Deletes a Node from this Config. This backend will no longer receive traffic for the configured port of this NodeBalancer.

This does not change or remove the Linode whose address was used in the creation of this Node.

Authorizations

personalAccessToken
oauth	nodebalancers:read_write

Path Parameters

nodeBalancerId	`integer` Required The ID of the NodeBalancer to access.
configId	`integer` Required The ID of the Config to access
nodeId	`integer` Required The ID of the Node to access

Request Samples

Response Samples

Responses

Node View

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

Returns information about a single Node, a backend for this NodeBalancer’s configured port.

Authorizations

personalAccessToken
oauth	nodebalancers:read_write

Path Parameters

nodeBalancerId	`integer` Required The ID of the NodeBalancer to access.
configId	`integer` Required The ID of the Config to access
nodeId	`integer` Required The ID of the Node to access

Request Samples

Response Samples

Responses

Node Update

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

Updates information about a Node, a backend for this NodeBalancer’s configured port.

Authorizations

personalAccessToken
oauth	nodebalancers:read_write

Path Parameters

nodeBalancerId	`integer` Required The ID of the NodeBalancer to access.
configId	`integer` Required The ID of the Config to access
nodeId	`integer` Required The ID of the Node to access

Request Body Schema

address	`string <ip>` The private IP Address where this backend can be reached. This must be a private IP address.
label	`string` 3..32 characters The label for this node. This is for display purposes only.
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.
weight	`integer` 1..255 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

Response Samples

Responses

Config Rebuild

POST https://api.linode.com/v4/nodebalancers/{nodeBalancerId}/configs/{configId}/rebuild

Rebuilds a NodeBalancer Config and its Nodes that you have permission to modify.

Authorizations

personalAccessToken
oauth	nodebalancers:read_write

Path Parameters

nodeBalancerId	`integer` Required The ID of the NodeBalancer to access.
configId	`integer` Required The ID of the Config to access.

Request Body Schema

algorithm

string

Enum: roundrobin leastconn source

What algorithm this NodeBalancer should use for routing traffic to backends.

check

string

Enum: none connection http http_body

The type of check to perform against backends to ensure they are serving requests. This is used to determine if backends are up or down.

If none no check is performed.
connection requires only a connection to the backend to succeed.
http and http_body rely on the backend serving HTTP, and that the response returned matches what is expected.

check_attempts

integer 1..30

How many times to attempt a check before considering a backend to be down.

check_body

string

This value must be present in the response body of the check in order for it to pass. If this value is not present in the response body of a check request, the backend is considered to be down.

check_interval

integer

How often, in seconds, to check that backends are up and serving requests.

check_passive

boolean

If true, any response from this backend with a 5xx status code will be enough for it to be considered unhealthy and taken out of rotation.

check_path

string

The URL path to check on each backend. If the backend does not respond to this request it is considered to be down.

check_timeout

integer 1..30

How long, in seconds, to wait for a check attempt before considering it failed.

cipher_suite

string

Enum: recommended legacy

What ciphers to use for SSL connections served by this NodeBalancer.

legacy is considered insecure and should only be used if necessary.

nodes

array of objects

The NodeBalancer Node(s) that serve this port. At least one Node is required per configured port.

Some considerations for Nodes when rebuilding a config:

Current Nodes excluded from the request body will be deleted.
Current Nodes (identified by their ID) will be updated.
New Nodes (included without an ID) will be created.

address	`string <ip>` The private IP Address where this backend can be reached. This must be a private IP address.
label	`string` 3..32 characters The label for this node. This is for display purposes only.
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.
weight	`integer` 1..255 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.

port

integer 1..65535

The port this Config is for. These values must be unique across configs on a single NodeBalancer (you can’t have two configs for port 80, for example). While some ports imply some protocols, no enforcement is done and you may configure your NodeBalancer however is useful to you. For example, while port 443 is generally used for HTTPS, you do not need SSL configured to have a NodeBalancer listening on port 443.

protocol

string

Enum: http https tcp

The protocol this port is configured to serve.

If using http or tcp protocol, ssl_cert and ssl_key are not supported.
If using https protocol, ssl_cert and ssl_key are required.

proxy_protocol

string

Enum: none v1 v2 Default: none

ProxyProtocol is a TCP extension that sends initial TCP connection information such as source/destination IPs and ports to backend devices. This information would be lost otherwise. Backend devices must be configured to work with ProxyProtocol if enabled.

If ommited, or set to none, the NodeBalancer doesn’t send any auxilary data over TCP connections. This is the default.
If set to v1, the human-readable header format (Version 1) is used.
If set to v2, the binary header format (Version 2) is used.

ssl_cert

Nullable

string <ssl-cert>

The PEM-formatted public SSL certificate (or the combined PEM-formatted SSL certificate and Certificate Authority chain) that should be served on this NodeBalancerConfig’s port.

The contents of this field will not be shown in any responses that display the NodeBalancerConfig. Instead, <REDACTED> will be printed where the field appears.

The read-only ssl_commonname and ssl_fingerprint fields in a NodeBalancerConfig response are automatically derived from your certificate. Please refer to these fields to verify that the appropriate certificate was assigned to your NodeBalancerConfig.

ssl_key

Nullable

string <ssl-key>

The PEM-formatted private key for the SSL certificate set in the ssl_cert field.

Line breaks must be represented as “\n” in the string.

The contents of this field will not be shown in any responses that display the NodeBalancerConfig. Instead, <REDACTED> will be printed where the field appears.

stickiness

string

Enum: none table http_cookie

Controls how session stickiness is handled on this port.

If set to none connections will always be assigned a backend based on the algorithm configured.
If set to table sessions from the same remote address will be routed to the same backend.
For HTTP or HTTPS clients, http_cookie allows sessions to be routed to the same backend based on a cookie set by the NodeBalancer.

Request Samples

Response Samples

Responses

NodeBalancer Statistics View

GET https://api.linode.com/v4/nodebalancers/{nodeBalancerId}/stats

Returns detailed statistics about the requested NodeBalancer.

Authorizations

personalAccessToken
oauth	nodebalancers:read_only

Path Parameters

nodeBalancerId

integer

Required

The ID of the NodeBalancer to access.

Search Results

No Results

Filters

Node Balancers v4.119.0

NodeBalancers List

Authorizations

Query Parameters

Request Samples

Response Samples

Responses

NodeBalancer Create

Authorizations

Request Body Schema

Request Samples

Response Samples

Responses

NodeBalancer Delete

Authorizations

Path Parameters

Request Samples

Response Samples

Responses

NodeBalancer View

Authorizations

Path Parameters

Request Samples

Response Samples

Responses

NodeBalancer Update

Authorizations

Path Parameters

Request Body Schema

Request Samples

Response Samples

Responses

Configs List

Authorizations

Path Parameters

Query Parameters

Request Samples

Response Samples

Responses

Config Create

Authorizations

Path Parameters

Request Body Schema

Request Samples

Response Samples

Responses

Config Delete

Authorizations

Path Parameters

Request Samples

Response Samples

Responses

Config View

Authorizations

Path Parameters

Request Samples

Response Samples

Responses

Config Update

Authorizations

Path Parameters

Request Body Schema

Request Samples

Response Samples

Responses

Nodes List

Authorizations

Path Parameters

Query Parameters

Request Samples

Response Samples

Responses

Node Create

Authorizations

Path Parameters

Request Body Schema

Request Samples