NodeBalancers

View Config

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

Returns configuration information for a single port of this NodeBalancer.

Authorizations

Personal Access Token
OAuth: ( nodebalancers:read_only)

Path Parameters

nodeBalancerId
Required
integer

The ID of the NodeBalancer to access.

configId
Required
integer

The ID of the config to access.

Request Samples

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

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,
  "cipher_suite": "recommended",
  "nodebalancer_id": 12345,
  "ssl_commonname": "",
  "ssl_fingerprint": "",
  "ssl_cert": "",
  "ssl_key": "",
  "nodes_status": [
    {
      "up": 4,
      "down": ""
    }
  ]
}

Responses

200: The requested NodeBalancer config.

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.

  • If this is set to https you must include an ssl_cert and an ssl_key.
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.

check_timeout
integer

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

check_attempts
integer

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

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

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

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.

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.

Update Config

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

Updates the configuration for a single port on a NodeBalancer.

Authorizations

Personal Access Token
OAuth: ( nodebalancers:read_write)

Path Parameters

nodeBalancerId
Required
integer

The ID of the NodeBalancer to access.

configId
Required
integer

The ID of the config to access.

Request Body Schema

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

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

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

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

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

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

check_body
string

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

check_interval
integer

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

check_passive
boolean

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

check_path
string

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

check_timeout
integer

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

cipher_suite
string
Enum: "recommended""legacy"

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

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

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

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

The protocol this port is configured to serve.

  • If this is set to https you must include an ssl_cert and an ssl_key.
ssl_cert
Nullable
string <ssl-cert>

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

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

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

ssl_key
Nullable
string <ssl-key>

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

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 PUT -d '{
      "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,
      "cipher_suite": "recommended"
    }' \
    https://api.linode.com/v4/nodebalancers/12345/configs/4567

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,
  "cipher_suite": "recommended",
  "nodebalancer_id": 12345,
  "ssl_commonname": "",
  "ssl_fingerprint": "",
  "ssl_cert": "",
  "ssl_key": "",
  "nodes_status": [
    {
      "up": 4,
      "down": ""
    }
  ]
}

Responses

200: Config updated 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.

  • If this is set to https you must include an ssl_cert and an ssl_key.
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.

check_timeout
integer

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

check_attempts
integer

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

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

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

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.

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.

Delete Config

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

Personal Access Token
OAuth: ( nodebalancers:read_write)

Path Parameters

nodeBalancerId
Required
integer

The ID of the NodeBalancer to access.

configId
Required
integer

The ID of the config to access.

Request Samples

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

Response Samples

{}

Responses

200: NodeBalancer Config deleted successfully.

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.