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..500
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. Only available in
Regions with “NodeBalancers” in their capabilities.
NodeBalancers require a port Config with at least one backend Node to start serving requests.
When using the Linode CLI to create a NodeBalancer, first create a NodeBalancer without any Configs. Then, create Configs and Nodes for that NodeBalancer with the respective
Config Create and
Node Create commands.
Authorizations
personalAccessToken
oauth
nodebalancers:read_write
Request Samples
Request Body Schema
client_conn_throttle
[integer]
0..20
Throttle connections per second. Set to 0 (zero) to disable throttling.
configs
[array]
The port Config(s) to create for this NodeBalancer.
Each Config must have a unique port and at least one Node.
firewall_id
[integer]
The ID of the Firewall to assign to the NodeBalancer.
Only one NodeBalancer can be assigned to a Firewall at a time.
Firewalls only apply to inbound TCP traffic to NodeBalancers.
label
[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.
tags
[array]
An array of Tags applied to this object. Tags are for organizational purposes only.
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 Samples
Request Body Schema
client_conn_throttle
[integer]
0..20
Throttle connections per second. Set to 0 (zero) to disable throttling.
label
[string]
3..32
characters
This NodeBalancer’s label. These must be unique on your Account.
tags
[array]
An array of Tags applied to this object. Tags are for organizational purposes only.
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..500
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.
What algorithm this NodeBalancer should use for routing traffic to backends.
check
[string]
Enum:
noneconnectionhttphttp_body
Default:
none
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
Default:
3
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]
Default:
31
How often, in seconds, to check that backends are up and serving requests.
Must be greater than check_timeout.
check_passive
[boolean]
Default:
true
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
Default:
30
How long, in seconds, to wait for a check attempt before considering it failed.
Must be less than check_interval.
cipher_suite
[string]
Enum:
recommendedlegacy
Default:
recommended
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
Default:
80
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:
httphttpstcp
Default:
http
The protocol this port is configured to serve.
The http and tcp protocols do not support ssl_cert and ssl_key.
The https protocol is mutually required with ssl_cert and ssl_key.
Review our guide on
Available Protocols for information on protocol features.
proxy_protocol
[string]
Enum:
nonev1v2
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. Requires tcp protocol.
If set to v2, the binary header format (Version 2) is used. Requires tcp protocol.
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.
Line breaks must be represented as “\n” in the string for requests (but not when using the Linode CLI).
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 for requests (but not when using the Linode CLI).
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:
nonetablehttp_cookie
Default:
none
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.
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.
What algorithm this NodeBalancer should use for routing traffic to backends.
check
[string]
Enum:
noneconnectionhttphttp_body
Default:
none
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
Default:
3
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]
Default:
31
How often, in seconds, to check that backends are up and serving requests.
Must be greater than check_timeout.
check_passive
[boolean]
Default:
true
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
Default:
30
How long, in seconds, to wait for a check attempt before considering it failed.
Must be less than check_interval.
cipher_suite
[string]
Enum:
recommendedlegacy
Default:
recommended
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
Default:
80
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:
httphttpstcp
Default:
http
The protocol this port is configured to serve.
The http and tcp protocols do not support ssl_cert and ssl_key.
The https protocol is mutually required with ssl_cert and ssl_key.
Review our guide on
Available Protocols for information on protocol features.
proxy_protocol
[string]
Enum:
nonev1v2
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. Requires tcp protocol.
If set to v2, the binary header format (Version 2) is used. Requires tcp protocol.
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.
Line breaks must be represented as “\n” in the string for requests (but not when using the Linode CLI).
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 for requests (but not when using the Linode CLI).
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:
nonetablehttp_cookie
Default:
none
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.
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..500
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 Samples
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:
acceptrejectdrainbackup
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.
What algorithm this NodeBalancer should use for routing traffic to backends.
check
[string]
Enum:
noneconnectionhttphttp_body
Default:
none
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
Default:
3
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]
Default:
31
How often, in seconds, to check that backends are up and serving requests.
Must be greater than check_timeout.
check_passive
[boolean]
Default:
true
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
Default:
30
How long, in seconds, to wait for a check attempt before considering it failed.
Must be less than check_interval.
cipher_suite
[string]
Enum:
recommendedlegacy
Default:
recommended
What ciphers to use for SSL connections served by this NodeBalancer.
legacy is considered insecure and should only be used if necessary.
nodes
Required
[array]
The NodeBalancer Node(s) that serve this Config.
Some considerations for Nodes when rebuilding a config:
Current Nodes excluded from the request body will be deleted from the Config.
Current Nodes (identified by their Node ID) will be updated.
New Nodes (included without a Node ID) will be created.
port
[integer]
1..65535
Default:
80
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:
httphttpstcp
Default:
http
The protocol this port is configured to serve.
The http and tcp protocols do not support ssl_cert and ssl_key.
The https protocol is mutually required with ssl_cert and ssl_key.
Review our guide on
Available Protocols for information on protocol features.
proxy_protocol
[string]
Enum:
nonev1v2
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. Requires tcp protocol.
If set to v2, the binary header format (Version 2) is used. Requires tcp protocol.
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.
Line breaks must be represented as “\n” in the string for requests (but not when using the Linode CLI).
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 for requests (but not when using the Linode CLI).
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:
nonetablehttp_cookie
Default:
none
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.
Response Samples
Responses
Firewalls List
GET
https://api.linode.com/v4/nodebalancers/{nodeBalancerId}/firewalls
View information for Firewalls assigned to this NodeBalancer.
Authorizations
personalAccessToken
oauth
nodebalancers:read_only
Path Parameters
nodeBalancerId
[integer]Required
The ID of the NodeBalancer to access.
Request Samples
Response Samples
Responses
NodeBalancer Statistics View
GET
https://api.linode.com/v4/nodebalancers/{nodeBalancerId}/stats
Returns detailed statistics about the requested NodeBalancer.
