NodeBalancers

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.

Use this command to update a NodeBalancer's Config and Nodes with a single request.

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

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

check

string

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

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

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

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

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

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.

stickiness

string

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.

nodes

array

The NodeBalancer Node(s) that serve this Config.

Some considerations for Nodes when rebuilding a config:

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

Request Samples

Shell
CLI

curl -H "Content-Type: application/json" \
    -H "Authorization: Bearer $TOKEN" \
    -X POST -d '{
      "port": 1234,
      "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",
      "cipher_suite": "recommended",
      "ssl_cert": "-----BEGIN CERTIFICATE-----\nCERTIFICATE_INFORMATION\n-----END CERTIFICATE-----",
      "ssl_key": "-----BEGIN PRIVATE KEY-----\nPRIVATE_KEY_INFORMATION\n-----END PRIVATE KEY-----",
      "nodes": [
        {
          "id": 54321,
          "address": "192.168.210.120:80",
          "label": "node1",
          "weight": 50,
          "mode": "accept"
        },
        {
          "address": "192.168.210.122:81",
          "label": "node2",
          "weight": 50,
          "mode": "accept"
        }
      ]
    }' \
    https://api.linode.com/v4/nodebalancers/12345/configs/4567/rebuild

Response Samples

200
default

{
  "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: NodeBalancer created successfully.

integer

This config's unique ID

port

integer

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"

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.

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.

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.

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.

Compute

Storage

Databases

Networking

Developer Tools

Delivery

Security

Services

Industries

Pricing

Community

Engage With Us

NodeBalancers

Config Rebuild

Path Parameters

Request Body Schema

Request Samples

Response Samples

Responses