API
  1. NodeBalancers
  2. Nodes

Create a node

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

Creates a backend node that can receive traffic for the NodeBalancer configuration. Requests are routed to backend nodes on the specified port based on their status. The configurable fields for the backend node depend on the chosen protocol and whether the node is located within a Linode VPC.

After creating a NodeBalancer backend node, account administrators can add a lock to prevent accidental node deletion by using the Create 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: create_nodebalancer_config_node

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

    • Scopes: nodebalancers:read_write

CLI

TCP, HTTP, HTTPS

linode-cli nodebalancers node-create \
  12345 4567 \
  --address 10.0.0.45:80 \
  --label node54321 \
  --weight 50 \
  --mode accept \
  --subnet_id 1

UDP

linode-cli nodebalancers node-create \
  12345 4567 \
  --address 192.168.210.120:80 \
  --label node54321 \
  --weight 50

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 NodeBalancer config to access.

Body Params

Information about the node the NodeBalancer configuration will direct traffic to. The fields available for the backend node depend on the configuration's protocol, and if the backend node is in a VPC.

Beta A NodeBalancer node represents a single backend serving requests for a single port of a NodeBalancer. Nodes are tied to individual NodeBalancer configurations and route traffic over their private IPv4 address, IPv6 address, or VPC IPv4 address. If the same Linode is serving traffic for more than one port on the same NodeBalancer, one NodeBalancer node is required for each config (port) it should serve requests on. For example, if you have four backends, and each should respond to both UDP and HTTPS requests, you will need two NodeBalancer configs (port 80 and port 443) and four backends each, one for each of the Linodes serving requests for that port.

string

Backend nodes can be Linodes and Linodes within a VPC. The following IP types are supported:

  • For non-VPC backend nodes, the private IPv4 address and port where this backend can be reached.
  • For non-VPC backend nodes, the public IPv6 address and port where this backend can be reached.
  • For backend nodes within a VPC, the IPv4 address and port where this backend can be reached.
string
length between 3 and 32

The label for this node. This is for display purposes only.

integer

Required for VPC backend nodes only. The VPC's subnet. To display information about your VPCs and their subnets, run the List VPCs operation.

integer
1 to 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.

Responses

Response body

A NodeBalancer node represents a single backend serving requests for a single port of a NodeBalancer. Nodes are tied to NodeBalancer configurations, and serve traffic over their private IPv4 address, IPv6 address, or VPC IPv4 address. If the same Linode is serving traffic for more than one port on the same NodeBalancer, one NodeBalancer node is required for each config (port) it should serve requests on. For example, if you have four backends, and each should respond to both HTTP and HTTPS requests, you will need two NodeBalancer configs (port 80 and port 443) and four backends each, one for each of the Linodes serving requests for that port.

string

The address and port where this backend can be reached: either the Linode’s private IPv4, public IPv6, or the VPC's IPv4 address.

integer

Read-only The NodeBalancer Config ID that this Node belongs to.

integer

Read-only This node's unique ID.

string
length between 3 and 32

The label for this node. This is for display purposes only.

string
enum

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.

accept reject drain backup

integer

Read-only The NodeBalancer ID that this Node belongs to.

string
enum

Read-only The current status of this node, based on the configured checks of its NodeBalancer Config.

Unknown UP DOWN

integer | null

Read-only For VPC backends, you can use the vpc_config_id to get VPC IDs and VPC subnet IDs. Returns a null value if the backend is not a VPC node. Included only in {apiVersion} v4beta.

integer
1 to 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.

Updated 3 months ago

Did this page help you?
Language
Credentials

Updated 3 months ago

Did this page help you?