Node Balancers
v4.83.1 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
>= 1Default:
1
Default: 1 The page of a collection to return.
page_size Type: integer
25..100Default:
100
Default: 100 The number of items to return per page.
Request Samples
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
linode-cli nodebalancers list
Response Samples
200
default
{
"data" : [
{
"client_conn_throttle" : 0 ,
"created" : "2018-01-01T00:01:01" ,
"hostname" : "nb-207-192-68-16.newark.nodebalancer.linode.com" ,
"id" : 12345 ,
"ipv4" : "12.34.56.78" ,
"ipv6" : null ,
"label" : "balancer12345" ,
"region" : "us-east" ,
"tags" : [
"example tag" ,
"another example"
],
"transfer" : {
"in" : 28.91200828552246 ,
"out" : 3.5487728118896484 ,
"total" : 32.46078109741211
},
"updated" : "2018-03-01T00:01:01"
}
],
"page" : 1 ,
"pages" : 1 ,
"results" : 1
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
A paginated list of NodeBalancers.
array of objects
integer
0..20
Throttle connections per second. Set to 0 (zero) to disable throttling.
string <date-time>
When this NodeBalancer was created.
string
This NodeBalancer’s hostname, ending with .nodebalancer.linode.com
integer
This NodeBalancer’s unique ID.
string <ip>
This NodeBalancer’s public IPv4 address.
string <ip>
This NodeBalancer’s public IPv6 address.
string
3..32
characters
This NodeBalancer’s label. These must be unique on your Account.
string
The Region where this NodeBalancer is located. NodeBalancers only support backends in the same Region.
array of strings
An array of Tags applied to this object. Tags are for organizational purposes only.
object
Information about the amount of transfer this NodeBalancer has had so far this month.
number
The total outbound transfer, in MB, used for this NodeBalancer this month.
number
The total inbound transfer, in MB, used for this NodeBalancer this month.
number
The total transfer, in MB, used by this NodeBalancer this month.
string <date-time>
When this NodeBalancer was last updated.
integer
integer
integer
Error
array of objects
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.
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.
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 integer
0..20
Throttle connections per second. Set to 0 (zero) to disable throttling.
array
The ports to configure this NodeBalancer with on creation. Each config must have a unique port and at least one Node.
string
3..32
characters
This NodeBalancer’s label. These must be unique on your Account.
string
The ID of the Region to create this NodeBalancer in.
Request Samples
Shell
CLI
curl -H "Content-Type: application/json" \
"Authorization: Bearer $TOKEN " \
'{
"region": "us-east",
"label": "balancer12345",
"client_conn_throttle": 0
}' \
linode-cli nodebalancers create \
\
\
0
Response Samples
200
default
{
"client_conn_throttle" : 0 ,
"created" : "2018-01-01T00:01:01" ,
"hostname" : "nb-207-192-68-16.newark.nodebalancer.linode.com" ,
"id" : 12345 ,
"ipv4" : "12.34.56.78" ,
"ipv6" : null ,
"label" : "balancer12345" ,
"region" : "us-east" ,
"tags" : [
"example tag" ,
"another example"
],
"transfer" : {
"in" : 28.91200828552246 ,
"out" : 3.5487728118896484 ,
"total" : 32.46078109741211
},
"updated" : "2018-03-01T00:01:01"
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
NodeBalancer created successfully.
integer
0..20
Throttle connections per second. Set to 0 (zero) to disable throttling.
string <date-time>
When this NodeBalancer was created.
string
This NodeBalancer’s hostname, ending with .nodebalancer.linode.com
integer
This NodeBalancer’s unique ID.
string <ip>
This NodeBalancer’s public IPv4 address.
string <ip>
This NodeBalancer’s public IPv6 address.
string
3..32
characters
This NodeBalancer’s label. These must be unique on your Account.
string
The Region where this NodeBalancer is located. NodeBalancers only support backends in the same Region.
array of strings
An array of Tags applied to this object. Tags are for organizational purposes only.
object
Information about the amount of transfer this NodeBalancer has had so far this month.
number
The total outbound transfer, in MB, used for this NodeBalancer this month.
number
The total inbound transfer, in MB, used for this NodeBalancer this month.
number
The total transfer, in MB, used by this NodeBalancer this month.
string <date-time>
When this NodeBalancer was last updated.
Error
array of objects
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.
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.
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
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
\
linode-cli nodebalancers delete 12345
Response Samples
200
default
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
NodeBalancer deleted successfully.
Error
array of objects
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.
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.
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
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
linode-cli nodebalancers view 12345
Response Samples
200
default
{
"client_conn_throttle" : 0 ,
"created" : "2018-01-01T00:01:01" ,
"hostname" : "nb-207-192-68-16.newark.nodebalancer.linode.com" ,
"id" : 12345 ,
"ipv4" : "12.34.56.78" ,
"ipv6" : null ,
"label" : "balancer12345" ,
"region" : "us-east" ,
"tags" : [
"example tag" ,
"another example"
],
"transfer" : {
"in" : 28.91200828552246 ,
"out" : 3.5487728118896484 ,
"total" : 32.46078109741211
},
"updated" : "2018-03-01T00:01:01"
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
The requested NodeBalancer object.
integer
0..20
Throttle connections per second. Set to 0 (zero) to disable throttling.
string <date-time>
When this NodeBalancer was created.
string
This NodeBalancer’s hostname, ending with .nodebalancer.linode.com
integer
This NodeBalancer’s unique ID.
string <ip>
This NodeBalancer’s public IPv4 address.
string <ip>
This NodeBalancer’s public IPv6 address.
string
3..32
characters
This NodeBalancer’s label. These must be unique on your Account.
string
The Region where this NodeBalancer is located. NodeBalancers only support backends in the same Region.
array of strings
An array of Tags applied to this object. Tags are for organizational purposes only.
object
Information about the amount of transfer this NodeBalancer has had so far this month.
number
The total outbound transfer, in MB, used for this NodeBalancer this month.
number
The total inbound transfer, in MB, used for this NodeBalancer this month.
number
The total transfer, in MB, used by this NodeBalancer this month.
string <date-time>
When this NodeBalancer was last updated.
Error
array of objects
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.
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.
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 integer
0..20
Throttle connections per second. Set to 0 (zero) to disable throttling.
string
3..32
characters
This NodeBalancer’s label. These must be unique on your Account.
array of strings
An array of Tags applied to this object. Tags are for organizational purposes only.
object
Information about the amount of transfer this NodeBalancer has had so far this month.
Request Samples
Shell
CLI
curl -H "Content-Type: application/json" \
"Authorization: Bearer $TOKEN " \
'{
"label": "balancer12345",
"client_conn_throttle": 0
}' \
linode-cli nodebalancers update 12345 \
\
0
Response Samples
200
default
{
"client_conn_throttle" : 0 ,
"created" : "2018-01-01T00:01:01" ,
"hostname" : "nb-207-192-68-16.newark.nodebalancer.linode.com" ,
"id" : 12345 ,
"ipv4" : "12.34.56.78" ,
"ipv6" : null ,
"label" : "balancer12345" ,
"region" : "us-east" ,
"tags" : [
"example tag" ,
"another example"
],
"transfer" : {
"in" : 28.91200828552246 ,
"out" : 3.5487728118896484 ,
"total" : 32.46078109741211
},
"updated" : "2018-03-01T00:01:01"
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
NodeBalancer updated successfully.
integer
0..20
Throttle connections per second. Set to 0 (zero) to disable throttling.
string <date-time>
When this NodeBalancer was created.
string
This NodeBalancer’s hostname, ending with .nodebalancer.linode.com
integer
This NodeBalancer’s unique ID.
string <ip>
This NodeBalancer’s public IPv4 address.
string <ip>
This NodeBalancer’s public IPv6 address.
string
3..32
characters
This NodeBalancer’s label. These must be unique on your Account.
string
The Region where this NodeBalancer is located. NodeBalancers only support backends in the same Region.
array of strings
An array of Tags applied to this object. Tags are for organizational purposes only.
object
Information about the amount of transfer this NodeBalancer has had so far this month.
number
The total outbound transfer, in MB, used for this NodeBalancer this month.
number
The total inbound transfer, in MB, used for this NodeBalancer this month.
number
The total transfer, in MB, used by this NodeBalancer this month.
string <date-time>
When this NodeBalancer was last updated.
Error
array of objects
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.
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.
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
>= 1Default:
1
Default: 1 The page of a collection to return.
page_size Type: integer
25..100Default:
100
Default: 100 The number of items to return per page.
Request Samples
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
linode-cli nodebalancers configs-list 12345
Response Samples
200
default
{
"data" : [
{
"algorithm" : "roundrobin" ,
"check" : "http_body" ,
"check_attempts" : 3 ,
"check_body" : "it works" ,
"check_interval" : 90 ,
"check_passive" : true ,
"check_path" : "/test" ,
"check_timeout" : 10 ,
"cipher_suite" : "recommended" ,
"id" : 4567 ,
"nodebalancer_id" : 12345 ,
"nodes_status" : {
"down" : 0 ,
"up" : 4
},
"port" : 80 ,
"protocol" : "http" ,
"proxy_protocol" : "none" ,
"ssl_cert" : null ,
"ssl_commonname" : null ,
"ssl_fingerprint" : null ,
"ssl_key" : null ,
"stickiness" : "http_cookie"
}
],
"page" : 1 ,
"pages" : 1 ,
"results" : 1
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
A paginted list of NodeBalancer Configs
array of objects
stringEnum:
roundrobin
leastconn
source
What algorithm this NodeBalancer should use for routing traffic to backends.
stringEnum:
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.integer
1..30
How many times to attempt a check before considering a backend to be down.
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.
integer
How often, in seconds, to check that backends are up and serving requests.
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.
string
The URL path to check on each backend. If the backend does not respond to this request it is considered to be down.
integer
1..30
How long, in seconds, to wait for a check attempt before considering it failed.
stringEnum:
recommended
legacy
What ciphers to use for SSL connections served by this NodeBalancer.
legacy is considered insecure and should only be used if necessary.integer
This config’s unique ID
integer
The ID for the NodeBalancer this config belongs to.
object
A structure containing information about the health of the backends for this port. This information is updated periodically as checks are performed against backends.
integer
The number of backends considered to be “DOWN” and unhealthy. These are not in rotation, and not serving requests.
integer
The number of backends considered to be “UP” and healthy, and that are serving requests.
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.
stringEnum:
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. stringEnum:
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. 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.
string
The read-only common name automatically derived from the SSL certificate assigned to this NodeBalancerConfig. Please refer to this field to verify that the appropriate certificate is assigned to your NodeBalancerConfig.
string
The read-only fingerprint automatically derived from the SSL certificate assigned to this NodeBalancerConfig. Please refer to this field to verify that the appropriate certificate is assigned to your NodeBalancerConfig.
string <ssl-key>
The PEM-formatted private key for the SSL certificate set in the ssl_cert field.
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.
stringEnum:
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.
integer
integer
integer
Error
array of objects
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.
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.
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 stringEnum:
roundrobin
leastconn
source
What algorithm this NodeBalancer should use for routing traffic to backends.
stringEnum:
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.integer
1..30
How many times to attempt a check before considering a backend to be down.
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.
integer
How often, in seconds, to check that backends are up and serving requests.
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.
string
The URL path to check on each backend. If the backend does not respond to this request it is considered to be down.
integer
1..30
How long, in seconds, to wait for a check attempt before considering it failed.
stringEnum:
recommended
legacy
What ciphers to use for SSL connections served by this NodeBalancer.
legacy is considered insecure and should only be used if necessary.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.
stringEnum:
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. stringEnum:
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. 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.
string <ssl-key>
The PEM-formatted private key for the SSL certificate set in the ssl_cert field.
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.
stringEnum:
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
Shell
CLI
curl -H "Content-Type: application/json" \
"Authorization: Bearer $TOKEN " \
'{
"port": 80,
"protocol": "http",
"algorithm": "roundrobin",
"stickiness": "http_cookie",
"check": "http_body",
"check_interval": 90,
"check_timeout": 10,
"check_attempts": 3,
"check_path": "/test",
"check_body": "it works",
"check_passive": true,
"proxy_protocol": "v1",
"cipher_suite": "recommended"
}' \
linode-cli nodebalancers config-create 12345 \
80 \
\
\
\
\
90 \
10 \
3 \
"/test" \
"it works" \
true \
"v1" \
Response Samples
200
default
{
"algorithm" : "roundrobin" ,
"check" : "http_body" ,
"check_attempts" : 3 ,
"check_body" : "it works" ,
"check_interval" : 90 ,
"check_passive" : true ,
"check_path" : "/test" ,
"check_timeout" : 10 ,
"cipher_suite" : "recommended" ,
"id" : 4567 ,
"nodebalancer_id" : 12345 ,
"nodes_status" : {
"down" : 0 ,
"up" : 4
},
"port" : 80 ,
"protocol" : "http" ,
"proxy_protocol" : "none" ,
"ssl_cert" : null ,
"ssl_commonname" : null ,
"ssl_fingerprint" : null ,
"ssl_key" : null ,
"stickiness" : "http_cookie"
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
Config created successfully.
stringEnum:
roundrobin
leastconn
source
What algorithm this NodeBalancer should use for routing traffic to backends.
stringEnum:
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.integer
1..30
How many times to attempt a check before considering a backend to be down.
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.
integer
How often, in seconds, to check that backends are up and serving requests.
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.
string
The URL path to check on each backend. If the backend does not respond to this request it is considered to be down.
integer
1..30
How long, in seconds, to wait for a check attempt before considering it failed.
stringEnum:
recommended
legacy
What ciphers to use for SSL connections served by this NodeBalancer.
legacy is considered insecure and should only be used if necessary.integer
This config’s unique ID
integer
The ID for the NodeBalancer this config belongs to.
object
A structure containing information about the health of the backends for this port. This information is updated periodically as checks are performed against backends.
integer
The number of backends considered to be “DOWN” and unhealthy. These are not in rotation, and not serving requests.
integer
The number of backends considered to be “UP” and healthy, and that are serving requests.
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.
stringEnum:
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. stringEnum:
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. 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.
string
The read-only common name automatically derived from the SSL certificate assigned to this NodeBalancerConfig. Please refer to this field to verify that the appropriate certificate is assigned to your NodeBalancerConfig.
string
The read-only fingerprint automatically derived from the SSL certificate assigned to this NodeBalancerConfig. Please refer to this field to verify that the appropriate certificate is assigned to your NodeBalancerConfig.
string <ssl-key>
The PEM-formatted private key for the SSL certificate set in the ssl_cert field.
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.
stringEnum:
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.
Error
array of objects
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.
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.
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
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
\
linode-cli nodebalancers config-delete \
12345 4567
Response Samples
200
default
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
NodeBalancer Config deleted successfully.
Error
array of objects
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.
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.
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
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
linode-cli nodebalancers config-view \
12345 4567
Response Samples
200
default
{
"algorithm" : "roundrobin" ,
"check" : "http_body" ,
"check_attempts" : 3 ,
"check_body" : "it works" ,
"check_interval" : 90 ,
"check_passive" : true ,
"check_path" : "/test" ,
"check_timeout" : 10 ,
"cipher_suite" : "recommended" ,
"id" : 4567 ,
"nodebalancer_id" : 12345 ,
"nodes_status" : {
"down" : 0 ,
"up" : 4
},
"port" : 80 ,
"protocol" : "http" ,
"proxy_protocol" : "none" ,
"ssl_cert" : null ,
"ssl_commonname" : null ,
"ssl_fingerprint" : null ,
"ssl_key" : null ,
"stickiness" : "http_cookie"
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
The requested NodeBalancer config.
stringEnum:
roundrobin
leastconn
source
What algorithm this NodeBalancer should use for routing traffic to backends.
stringEnum:
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.integer
1..30
How many times to attempt a check before considering a backend to be down.
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.
integer
How often, in seconds, to check that backends are up and serving requests.
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.
string
The URL path to check on each backend. If the backend does not respond to this request it is considered to be down.
integer
1..30
How long, in seconds, to wait for a check attempt before considering it failed.
stringEnum:
recommended
legacy
What ciphers to use for SSL connections served by this NodeBalancer.
legacy is considered insecure and should only be used if necessary.integer
This config’s unique ID
integer
The ID for the NodeBalancer this config belongs to.
object
A structure containing information about the health of the backends for this port. This information is updated periodically as checks are performed against backends.
integer
The number of backends considered to be “DOWN” and unhealthy. These are not in rotation, and not serving requests.
integer
The number of backends considered to be “UP” and healthy, and that are serving requests.
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.
stringEnum:
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. stringEnum:
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. 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.
string
The read-only common name automatically derived from the SSL certificate assigned to this NodeBalancerConfig. Please refer to this field to verify that the appropriate certificate is assigned to your NodeBalancerConfig.
string
The read-only fingerprint automatically derived from the SSL certificate assigned to this NodeBalancerConfig. Please refer to this field to verify that the appropriate certificate is assigned to your NodeBalancerConfig.
string <ssl-key>
The PEM-formatted private key for the SSL certificate set in the ssl_cert field.
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.
stringEnum:
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.
Error
array of objects
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.
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.
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 stringEnum:
roundrobin
leastconn
source
What algorithm this NodeBalancer should use for routing traffic to backends.
stringEnum:
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.integer
1..30
How many times to attempt a check before considering a backend to be down.
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.
integer
How often, in seconds, to check that backends are up and serving requests.
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.
string
The URL path to check on each backend. If the backend does not respond to this request it is considered to be down.
integer
1..30
How long, in seconds, to wait for a check attempt before considering it failed.
stringEnum:
recommended
legacy
What ciphers to use for SSL connections served by this NodeBalancer.
legacy is considered insecure and should only be used if necessary.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.
stringEnum:
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. stringEnum:
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. 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.
string <ssl-key>
The PEM-formatted private key for the SSL certificate set in the ssl_cert field.
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.
stringEnum:
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
Shell
CLI
curl -H "Content-Type: application/json" \
"Authorization: Bearer $TOKEN " \
'{
"port": 80,
"protocol": "http",
"algorithm": "roundrobin",
"stickiness": "http_cookie",
"check": "http_body",
"check_interval": 90,
"check_timeout": 10,
"check_attempts": 3,
"check_path": "/test",
"check_body": "it works",
"check_passive": true,
"proxy_protocol": "v1",
"cipher_suite": "recommended"
}' \
linode-cli nodebalancers config-update \
12345 4567 \
80 \
\
\
\
\
90 \
10 \
3 \
"/test" \
"it works" \
true \
"v1" \
Response Samples
200
default
{
"algorithm" : "roundrobin" ,
"check" : "http_body" ,
"check_attempts" : 3 ,
"check_body" : "it works" ,
"check_interval" : 90 ,
"check_passive" : true ,
"check_path" : "/test" ,
"check_timeout" : 10 ,
"cipher_suite" : "recommended" ,
"id" : 4567 ,
"nodebalancer_id" : 12345 ,
"nodes_status" : {
"down" : 0 ,
"up" : 4
},
"port" : 80 ,
"protocol" : "http" ,
"proxy_protocol" : "none" ,
"ssl_cert" : null ,
"ssl_commonname" : null ,
"ssl_fingerprint" : null ,
"ssl_key" : null ,
"stickiness" : "http_cookie"
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
Config updated successfully.
stringEnum:
roundrobin
leastconn
source
What algorithm this NodeBalancer should use for routing traffic to backends.
stringEnum:
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.integer
1..30
How many times to attempt a check before considering a backend to be down.
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.
integer
How often, in seconds, to check that backends are up and serving requests.
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.
string
The URL path to check on each backend. If the backend does not respond to this request it is considered to be down.
integer
1..30
How long, in seconds, to wait for a check attempt before considering it failed.
stringEnum:
recommended
legacy
What ciphers to use for SSL connections served by this NodeBalancer.
legacy is considered insecure and should only be used if necessary.integer
This config’s unique ID
integer
The ID for the NodeBalancer this config belongs to.
object
A structure containing information about the health of the backends for this port. This information is updated periodically as checks are performed against backends.
integer
The number of backends considered to be “DOWN” and unhealthy. These are not in rotation, and not serving requests.
integer
The number of backends considered to be “UP” and healthy, and that are serving requests.
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.
stringEnum:
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. stringEnum:
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. 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.
string
The read-only common name automatically derived from the SSL certificate assigned to this NodeBalancerConfig. Please refer to this field to verify that the appropriate certificate is assigned to your NodeBalancerConfig.
string
The read-only fingerprint automatically derived from the SSL certificate assigned to this NodeBalancerConfig. Please refer to this field to verify that the appropriate certificate is assigned to your NodeBalancerConfig.
string <ssl-key>
The PEM-formatted private key for the SSL certificate set in the ssl_cert field.
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.
stringEnum:
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.
Error
array of objects
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.
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.
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
>= 1Default:
1
Default: 1 The page of a collection to return.
page_size Type: integer
25..100Default:
100
Default: 100 The number of items to return per page.
Request Samples
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
linode-cli nodebalancers nodes-list 12345 4567
Response Samples
200
default
{
"data" : [
{
"address" : "192.168.210.120:80" ,
"config_id" : 4567 ,
"id" : 54321 ,
"label" : "node54321" ,
"mode" : "accept" ,
"nodebalancer_id" : 12345 ,
"status" : "UP" ,
"weight" : 50
}
],
"page" : 1 ,
"pages" : 1 ,
"results" : 1
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
A paginated list of NodeBalancer nodes.
array of objects
string <ip>
The private IP Address where this backend can be reached. This must be a private IP address.
integer
The NodeBalancer Config ID that this Node belongs to.
integer
This node’s unique ID.
string
3..32
characters
The label for this node. This is for display purposes only.
stringEnum:
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.
integer
The NodeBalancer ID that this Node belongs to.
stringEnum:
unknown
UP
DOWN
The current status of this node, based on the configured checks of its NodeBalancer Config.
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.
integer
integer
integer
Error
array of objects
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.
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.
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 string <ip>
The private IP Address where this backend can be reached. This must be a private IP address.
string
3..32
characters
The label for this node. This is for display purposes only.
stringEnum:
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.
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
Shell
CLI
curl -H "Content-Type: application/json" \
"Authorization: Bearer $TOKEN " \
'{
"address": "192.168.210.120:80",
"label": "node54321",
"weight": 50,
"mode": "accept"
}' \
linode-cli nodebalancers node-create \
12345 4567 \
\
\
50 \
Response Samples
200
default
{
"address" : "192.168.210.120:80" ,
"config_id" : 4567 ,
"id" : 54321 ,
"label" : "node54321" ,
"mode" : "accept" ,
"nodebalancer_id" : 12345 ,
"status" : "UP" ,
"weight" : 50
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
Node created successfully.
string <ip>
The private IP Address where this backend can be reached. This must be a private IP address.
integer
The NodeBalancer Config ID that this Node belongs to.
integer
This node’s unique ID.
string
3..32
characters
The label for this node. This is for display purposes only.
stringEnum:
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.
integer
The NodeBalancer ID that this Node belongs to.
stringEnum:
unknown
UP
DOWN
The current status of this node, based on the configured checks of its NodeBalancer Config.
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.
Error
array of objects
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.
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.
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
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
\
linode-cli nodebalancers node-delete \
12345 4567 54321
Response Samples
200
default
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
Node deleted successfully.
Error
array of objects
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.
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.
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
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
linode-cli nodebalancers node-view 12345 4567 54321
Response Samples
200
default
{
"address" : "192.168.210.120:80" ,
"config_id" : 4567 ,
"id" : 54321 ,
"label" : "node54321" ,
"mode" : "accept" ,
"nodebalancer_id" : 12345 ,
"status" : "UP" ,
"weight" : 50
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
A paginated list of NodeBalancer nodes.
string <ip>
The private IP Address where this backend can be reached. This must be a private IP address.
integer
The NodeBalancer Config ID that this Node belongs to.
integer
This node’s unique ID.
string
3..32
characters
The label for this node. This is for display purposes only.
stringEnum:
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.
integer
The NodeBalancer ID that this Node belongs to.
stringEnum:
unknown
UP
DOWN
The current status of this node, based on the configured checks of its NodeBalancer Config.
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.
Error
array of objects
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.
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.
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 string <ip>
The private IP Address where this backend can be reached. This must be a private IP address.
string
3..32
characters
The label for this node. This is for display purposes only.
stringEnum:
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.
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
Shell
CLI
curl -H "Content-Type: application/json" \
"Authorization: Bearer $TOKEN " \
'{
"address": "192.168.210.120:80",
"label": "node54321",
"weight": 50,
"mode": "accept"
}' \
linode-cli nodebalancers node-create \
12345 4567 54321 \
\
\
50 \
Response Samples
200
default
{
"address" : "192.168.210.120:80" ,
"config_id" : 4567 ,
"id" : 54321 ,
"label" : "node54321" ,
"mode" : "accept" ,
"nodebalancer_id" : 12345 ,
"status" : "UP" ,
"weight" : 50
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
Node updated successfully.
string <ip>
The private IP Address where this backend can be reached. This must be a private IP address.
integer
The NodeBalancer Config ID that this Node belongs to.
integer
This node’s unique ID.
string
3..32
characters
The label for this node. This is for display purposes only.
stringEnum:
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.
integer
The NodeBalancer ID that this Node belongs to.
stringEnum:
unknown
UP
DOWN
The current status of this node, based on the configured checks of its NodeBalancer Config.
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.
Error
array of objects
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.
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.
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 array
Each config must have a unique port and at least one Node. Additionally:
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.
Request Samples
Shell
CLI
curl -H "Content-Type: application/json" \
"Authorization: Bearer $TOKEN " \
'{
"port": 80,
"protocol": "http",
"algorithm": "roundrobin",
"stickiness": "http_cookie",
"check": "http_body",
"check_interval": 90,
"check_timeout": 10,
"check_attempts": 3,
"check_path": "/test",
"check_body": "it works",
"check_passive": true,
"proxy_protocol": "v1",
"cipher_suite": "recommended",
"nodes": [
{
"id": 543231,
"address": "192.168.210.120:80",
"label": "node54321",
"weight": 50,
"mode": "accept"
},
{
"address": "192.168.210.122:81",
"label": "thenewnode",
"weight": 50,
"mode": "accept"
},
]
}' \
linode-cli nodebalancers config-rebuild \
12345 4567 \
80 \
\
\
\
\
90 \
10 \
3 \
"/test" \
"it works" \
true \
"v1" \
Response Samples
200
default
{
"client_conn_throttle" : 0 ,
"created" : "2018-01-01T00:01:01" ,
"hostname" : "nb-207-192-68-16.newark.nodebalancer.linode.com" ,
"id" : 12345 ,
"ipv4" : "12.34.56.78" ,
"ipv6" : null ,
"label" : "balancer12345" ,
"region" : "us-east" ,
"tags" : [
"example tag" ,
"another example"
],
"transfer" : {
"in" : 28.91200828552246 ,
"out" : 3.5487728118896484 ,
"total" : 32.46078109741211
},
"updated" : "2018-03-01T00:01:01"
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
NodeBalancer created successfully.
integer
0..20
Throttle connections per second. Set to 0 (zero) to disable throttling.
string <date-time>
When this NodeBalancer was created.
string
This NodeBalancer’s hostname, ending with .nodebalancer.linode.com
integer
This NodeBalancer’s unique ID.
string <ip>
This NodeBalancer’s public IPv4 address.
string <ip>
This NodeBalancer’s public IPv6 address.
string
3..32
characters
This NodeBalancer’s label. These must be unique on your Account.
string
The Region where this NodeBalancer is located. NodeBalancers only support backends in the same Region.
array of strings
An array of Tags applied to this object. Tags are for organizational purposes only.
object
Information about the amount of transfer this NodeBalancer has had so far this month.
number
The total outbound transfer, in MB, used for this NodeBalancer this month.
number
The total inbound transfer, in MB, used for this NodeBalancer this month.
number
The total transfer, in MB, used by this NodeBalancer this month.
string <date-time>
When this NodeBalancer was last updated.
Error
array of objects
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.
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.
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.
Response Samples
200
default
{
"data" : {
"connections" : [
null
],
"traffic" : {
"in" : [
null
],
"out" : [
null
]
}
},
"title" : "linode.com - balancer12345 (12345) - day (5 min avg)"
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
The requested stats.
object
The data returned about this NodeBalancers.
array of numbers
An array of key/value pairs representing unix timestamp and reading for connections to this NodeBalancer.
object
Traffic statistics for this NodeBalancer.
array of numbers
An array of key/value pairs representing unix timestamp and reading for inbound traffic.
array of numbers
An array of key/value pairs representing unix timestamp and reading for outbound traffic.
string
The title for the statistics generated in this response.
Error
array of objects
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.
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.
