API

Rebuild a config

post
https://api.linode.com//nodebalancers//configs//rebuild

Rebuilds a NodeBalancer config and its nodes that you have permission to modify.

Use this operation to update a NodeBalancer's config and nodes with a single request.

You can't rebuild a NodeBalancer config if it has a cannot_delete_with_subresources lock. Only account administrators can remove locks using the Delete a resource lock operation.

🚧

You can configure UDP on the same NodeBalancer that also uses TCP, HTTP, or HTTPS, but only when managing it through the API. If UDP is configured and you make changes to the TCP, HTTP or HTTPS settings in Cloud Manager, the existing UDP configuration will be overwritten. This is because Cloud Manager doesn't currently support UDP.

Permissions and scopes

To call this operation, you need permissions, based on the model you're using:

  • Identity and access permissions. Your user needs a role with these permissions. Learn more.

    • Permissions: rebuild_nodebalancer_config

  • OAuth scopes. Your user needs these scopes assigned. Learn more.

    • Scopes: nodebalancers:read_write

CLI

HTTPS

linode-cli nodebalancers config-rebuild \
  12345 4567 \
  --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-----
              CERTIFICATE_INFORMATION
              -----END CERTIFICATE-----" \
  --ssl_key "-----BEGIN PRIVATE KEY-----
             PRIVATE_KEY_INFORMATION
             -----END PRIVATE KEY-----" \
  --cipher_suite recommended \
  --nodes.label "node1" --nodes.address "192.168.210.120:80" --nodes.mode "accept" --nodes.weight 50 \
  --nodes '[{"address":"192.168.210.122:80","label":"node2","weight":50,"mode":"accept"}]' \
  --nodes '[{"address":"10.0.0.45:80","label":"vpc-node","weight":10,"mode":"accept","subnet_id:1"}]'

UDP

linode-cli nodebalancers config-rebuild \
   12345 4567 \
   --port 80 \
   --protocol udp \
   --algorithm ring_hash \
   --udp_check_port 80 \
   --nodes.label "node1" --nodes.address "192.168.210.120:80" --nodes.mode "accept" --nodes.weight 50 \
   --nodes '[{"address":"192.168.210.122:80","label":"node2","weight":50}]' \
   --nodes '[{"address":"10.0.0.45:80","label":"vpc-node","weight":10,"mode":"accept","subnet_id:1"}]'

TCP

linode-cli nodebalancers config-rebuild \
  12345 4567 \
  --port 80 \
  --protocol tcp \
  --algorithm roundrobin \
  --stickiness none \
  --proxy_protocol "v2"
  --nodes.label "node1" --nodes.address "192.168.210.120:80" --nodes.mode "accept" --nodes.weight 50 \
  --nodes '[{"address":"192.168.210.122:80","label":"node2","weight":50,"mode":"accept"}]' \
  --nodes '[{"address":"10.0.0.45:80","label":"vpc-node","weight":10,"mode":"accept","subnet_id:1"}]'

HTTP

linode-cli nodebalancers config-rebuild \
  12345 4567 \
  --port 440 \
  --protocol http \
  --algorithm roundrobin \
  --stickiness none \
  --check http_body \
  --check_interval 90 \
  --check_timeout 10 \
  --check_attempts 3 \
  --check_path "/test" \
  --check_body "it works" \
  --nodes.label "node1" --nodes.address "192.168.210.120:80" --nodes.mode "accept" --nodes.weight 50 \
  --nodes '[{"address":"192.168.210.122:80","label":"node2","weight":50,"mode":"accept"}]' \
  --nodes '[{"address":"10.0.0.45:80","label":"vpc-node","weight":10,"mode":"accept","subnet_id:1"}]'

Learn more

Path Params
string
enum
required

Enum Call either the v4 URL, or v4beta for operations still in Beta.

Allowed:
integer
required

The ID of the NodeBalancer.

integer
required

The ID of the Config to access.

Body Params

Information about the NodeBalancer configuration to rebuild.

Beta A NodeBalancer configuration defines the protocol and settings for a specific port on the NodeBalancer. These fields apply to UDP configurations.

string
enum
Defaults to roundrobin

The algorithm this UDP NodeBalancer uses to route traffic to backends.

Allowed:
string
enum
Defaults to none

The type of check to perform against backends to ensure they are serving requests. This determines 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.
Allowed:
integer
1 to 30
Defaults to 3

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 isn't present in the response body of a check request, the backend is considered to be down.

integer
2 to 3600
Defaults to 5

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

Must be greater than check_timeout.

string

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

integer
1 to 30
Defaults to 30

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

Must be less than check_interval.

nodes
array of objects
required

The NodeBalancer nodes 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.
nodes*
integer
1 to 65535
Defaults to 80

This is the port the NodeBalancer listens on for this configuration. Port numbers must be unique across TCP, HTTP, and HTTPS configurations on a single NodeBalancer. However, ports assigned to TCP, HTTP, or HTTPS configurations can also be reused for UDP configurations. For example, Port 80 can simultaneously serve a TCP and a UDP configuration on the same NodeBalancer, but it can't be shared by both a TCP and an HTTP configuration. Although certain ports are traditionally associated with specific protocols, this isn't strictly enforced, and you may configure your NodeBalancer however you find useful.

string
enum
Defaults to http

The protocol the port is configured to serve, udp in this case. Review our guide on Available Protocols for information on protocol features.

Allowed:
string
enum
Defaults to session

Controls how session stickiness is handled on this port.

  • If set to none, connections are assigned a backend server based on the algorithm configured.
  • If set to session, all packets with the same session identifiers are routed to the same backend server. Two packets are considered part of the same session if they share the same source and destination IP addresses or ports, and are received within a short time window.
  • If set to source_ip, the NodeBalancer uses the client's source IP address to route all packets from the same client to the same backend server.
Allowed:
integer
1 to 65535
Defaults to 80

UDP NodeBalancers use TCP and HTTP active health checks to ensure back-end nodes can receive traffic. You can specify the health check port that the backend node listens on, which may differ from the UDP port used to serve traffic.

Responses

Updated 3 months ago

Language
Credentials
LoadingLoading…
Response
Choose an example:
application/json

Updated 3 months ago