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

Endpoints

NodeBalancers

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.

Path Parameters

nodeBalancerId
Required
integer

The ID of the NodeBalancer to access.

Query Parameters

page
integer > = 1
Default: 1

The page of a collection to return.

page_size
integer [25 .. 500]
Default: 100

The number of items to return per page.

Request Samples

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

Response Samples

{
  "data": [
    {
      "id": "",
      "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": "none",
      "cipher_suite": "recommended",
      "nodebalancer_id": 12345,
      "ssl_commonname": "www.example.com",
      "ssl_fingerprint": "00:01:02:03:04:05:06:07:08:09:0A:0B:0C:0D:0E:0F:10:11:12:13",
      "ssl_cert": "<REDACTED>",
      "ssl_key": "<REDACTED>",
      "nodes_status": {
        "up": 4,
        "down": ""
      }
    }
  ],
  "page": 1,
  "pages": 1,
  "results": 1
}

Responses

200: A paginted list of NodeBalancer Configs

data
array of objects
id
integer

This config's unique ID

port
integer

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

protocol
string
Enum: "http""https""tcp"

The protocol this port is configured to serve.

  • 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.

algorithm
string
Enum: "roundrobin""leastconn""source"

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

stickiness
string
Enum: "none""table""http_cookie"

Controls how session stickiness is handled on this port.

  • If set to none connections will always be assigned a backend based on the algorithm configured.

  • If set to table sessions from the same remote address will be routed to the same backend.

  • For HTTP or HTTPS clients, http_cookie allows sessions to be routed to the same backend based on a cookie set by the NodeBalancer.

check
string
Enum: "none""connection""http""http_body"

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

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

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

Must be greater than check_timeout.

check_timeout
integer

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

Must be less than check_interval.

check_attempts
integer

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

check_path
string^[a-zA-Z0-9\/\-%?&=.]*$

The URL path to check on each backend. If the backend does not respond to this request it is considered 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_passive
boolean

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

proxy_protocol
string
Enum: "none""v1""v2"

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.
cipher_suite
string
Enum: "recommended""legacy"

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

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

The ID for the NodeBalancer this config belongs to.

ssl_commonname
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.

ssl_fingerprint
string

The read-only SHA1-encoded 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.

ssl_cert
Nullable
string

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).

Diffie-Hellman Parameters can be included in this value to enable forward secrecy.

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

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.

nodes_status
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.

up
integer

The number of backends considered to be "UP" and healthy, and that are serving requests.

down
integer

The number of backends considered to be "DOWN" and unhealthy. These are not in rotation, and not serving requests.

page
integer

The current page.

pages
integer

The total number of pages.

results
integer

The total number of results.

default: Error

errors
array of objects
reason
string

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

field
string

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

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.

Path Parameters

nodeBalancerId
Required
integer

The ID of the NodeBalancer to access.

Request Body Schema

algorithm
string
Enum: "roundrobin""leastconn""source"

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

check
string
Enum: "none""connection""http""http_body"

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

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

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

check_body
string

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

check_interval
integer

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

Must be greater than check_timeout.

check_passive
boolean

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

check_path
string ^[a-zA-Z0-9\/\-%?&=.]*$

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

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

Must be less than check_interval.

cipher_suite
string
Enum: "recommended""legacy"

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

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

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

protocol
string
Enum: "http""https""tcp"

The protocol this port is configured to serve.

  • 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: "none""v1""v2"

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).

Diffie-Hellman Parameters can be included in this value to enable forward secrecy.

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: "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

curl -H "Content-Type: application/json" \
    -H "Authorization: Bearer $TOKEN" \
    -X POST -d '{
      "port": 443,
      "protocol": "https",
      "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": "none",
      "ssl_cert": "-----BEGIN CERTIFICATE-----\nCERTIFICATE_INFORMATION\n-----END CERTIFICATE-----",
      "ssl_key": "-----BEGIN PRIVATE KEY-----\nPRIVATE_KEY_INFORMATION\n-----END PRIVATE KEY-----",
      "cipher_suite": "recommended"
    }' \
    https://api.linode.com/v4/nodebalancers/12345/configs

Response Samples

{
  "id": 1234,
  "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": "none",
  "cipher_suite": "recommended",
  "nodebalancer_id": 12345,
  "ssl_commonname": "www.example.com",
  "ssl_fingerprint": "00:01:02:03:04:05:06:07:08:09:0A:0B:0C:0D:0E:0F:10:11:12:13",
  "ssl_cert": "<REDACTED>",
  "ssl_key": "<REDACTED>",
  "nodes_status": {
    "up": 4,
    "down": 0
  }
}

Responses

200: Config created successfully.

id
integer

This config's unique ID

port
integer

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

protocol
string
Enum: "http""https""tcp"

The protocol this port is configured to serve.

  • 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.

algorithm
string
Enum: "roundrobin""leastconn""source"

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

stickiness
string
Enum: "none""table""http_cookie"

Controls how session stickiness is handled on this port.

  • If set to none connections will always be assigned a backend based on the algorithm configured.

  • If set to table sessions from the same remote address will be routed to the same backend.

  • For HTTP or HTTPS clients, http_cookie allows sessions to be routed to the same backend based on a cookie set by the NodeBalancer.

check
string
Enum: "none""connection""http""http_body"

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

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

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

Must be greater than check_timeout.

check_timeout
integer

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

Must be less than check_interval.

check_attempts
integer

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

check_path
string ^[a-zA-Z0-9\/\-%?&=.]*$

The URL path to check on each backend. If the backend does not respond to this request it is considered 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_passive
boolean

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

proxy_protocol
string
Enum: "none""v1""v2"

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.
cipher_suite
string
Enum: "recommended""legacy"

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

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

The ID for the NodeBalancer this config belongs to.

ssl_commonname
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.

ssl_fingerprint
string

The read-only SHA1-encoded 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.

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).

Diffie-Hellman Parameters can be included in this value to enable forward secrecy.

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.

nodes_status
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.

up
integer

The number of backends considered to be "UP" and healthy, and that are serving requests.

down
integer

The number of backends considered to be "DOWN" and unhealthy. These are not in rotation, and not serving requests.

default: Error

errors
array of objects
reason
string

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

field
string

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