Skip to main content

Create Load Balancer (ALB or NLB)

Provisions a load balancer appliance (HAProxy). A single endpoint creates both types - the request body shape is what distinguishes them:

  • Application Load Balancer (ALB) - Layer-7 (HTTP/HTTPS). Identified by one or more backends (and no tcp_backend). Supports host/path ACL routing, SSL termination, WebSocket timeouts, and node-based or auto-scaling-group backends. lb_mode is HTTP, HTTPS, or BOTH.

  • Network Load Balancer (NLB) - Layer-4 (TCP). Identified by a single tcp_backend entry (and no backends). lb_mode is TCP and the listening port comes from the tcp_backend entry. ACLs and SSL are not supported.

backends and tcp_backend are mutually exclusive. ACL rules (acl_list / acl_map) are always sent empty at create time and added later via the Update Load Balancer endpoint. On success the appliance is returned in Creating state - poll the Load Balancer Status endpoint until it becomes Running.

POST/api/v1/appliances/load-balancers/

Query parameters

  • project_idQueryintegerrequired

    Identifier of the project to scope the request to. Required integer project ID.

    • required
    • must be a valid integer project ID
    example{{project_id}}
  • apikeyQuerystringrequired

    API key used to authenticate the create request

    • required
    • non-empty string
    example{{api_key}}
  • locationQuerystringrequired

    Region in which the load balancer will be provisioned.

    • required
    • must be a valid region name (e.g., Delhi, Mumbai, Chennai)
    example{{location}}

Request body

application/json

object

Create payload for both load balancer types. Send backends for an ALB (Layer 7) or a single tcp_backend for an NLB (Layer 4) - the two are mutually exclusive and exactly one is required. ALB-only fields (ssl_context, acl_list/acl_map, per-backend http_check / websocket_timeout / backend_ssl) do not apply to an NLB.

plan_namestringrequired

Plan SKU backing the load balancer appliance. Use the name of a plan returned by LB Plans (for example E2E-LB-2).

exampleE2E-LB-2
  • required
  • must reference an existing load balancer plan in the region
lb_namestringrequired

Display name of the load balancer.

exampleLB-ALB-26321-6218
  • required
  • matches ^[A-Za-z0-9_-]+$
  • max length 64 characters
lb_typestringrequiredexternal | internal

Network scheme of the load balancer. external exposes a public IP; internal is reachable only inside the selected VPC(s) and requires vpc_list. (This is the "Scheme/Type" choice in the console; it does not distinguish ALB from NLB - the presence of backends is what makes this an ALB.)

exampleexternal
  • required
  • defaults to external in the console
lb_modestringrequiredHTTP | HTTPS | BOTH…

Frontend protocol. For an ALB: HTTP (port 80 only), HTTPS (443 only), or BOTH (HTTP redirects honour ssl_context.redirect_to_https). For an NLB: always TCP.

exampleBOTH
  • required
  • ALB: HTTP | HTTPS | BOTH (console default BOTH); NLB: TCP
lb_portstringrequired

Primary listening port, sent as a string. The console sets 80 when lb_mode is HTTP and 443 otherwise.

example443
  • required
  • integer 1-65535 (as a string)
  • ports 1-1023 and the reserved ports 8080, 10050, 9101 are rejected unless the value is 80 or 443
node_list_typestringrequiredD

Backend node-list mode. Always D (dynamic) for load balancers created from the console.

exampleD
  • required
  • must be the literal string `D`
connection_timeoutinteger

HAProxy connection timeout, in seconds.

example60
  • minimum 60, maximum 10000
  • console default: 60
client_timeoutinteger

HAProxy client-side inactivity timeout, in seconds.

example60
  • minimum 60, maximum 10000
  • console default: 60
server_timeoutinteger

HAProxy server-side inactivity timeout, in seconds.

example60
  • minimum 60, maximum 10000
  • console default: 60
http_keep_alive_timeoutinteger

HAProxy HTTP keep-alive timeout, in seconds.

example60
  • minimum 60, maximum 10000
  • console default: 60
ssl_contextobject

TLS configuration. Required when lb_mode is HTTPS or BOTH (an SSL certificate must be selected); not used for plain HTTP.

backendsarray

One or more backend groups the ALB routes traffic to. At least one backend is required for an ALB (this is what distinguishes it from an NLB). backends and tcp_backend are mutually exclusive.

  • required for an ALB
  • at least one entry
  • backend names must be unique
default_backendstring

Name of the backend that receives traffic not matched by any ACL. May only be set when backends is non-empty.

examplebackend-group-1
  • optional
  • must match one of the `backends[].name` values
acl_listarray

Layer-7 routing rule definitions. Always sent empty at create time; add rules afterwards via Update Load Balancer.

  • send an empty array at create
acl_maparray

Mapping of ACL rules to backends. Always sent empty at create time.

  • send an empty array at create
tcp_backendarray

The single TCP backend group for an NLB. Provide exactly one entry for an NLB (and leave backends empty); leave this empty for an ALB. backends and tcp_backend are mutually exclusive.

  • required for an NLB (exactly one entry); empty for an ALB
vpc_listarray

VPC(s) the load balancer attaches to. Required when lb_type is internal; optional otherwise.

lb_reserve_ipstring

A previously reserved public IPv4 address to assign to the load balancer. Send an empty string to allocate a fresh IP. Not allowed for internal load balancers.

example
  • optional
  • must be a reserved IPv4 address on the account
  • must be empty when lb_type is internal
is_ipv6_attachedboolean

Whether to attach a public IPv6 address at creation (external load balancers only).

examplefalse
  • defaults to false
enable_bitninjaboolean

Whether to activate the BitNinja security add-on on the appliance.

examplefalse
  • defaults to false
security_group_idinteger

ID of the security group to attach to the load balancer. The console always sends the selected security group.

example81526
  • optional
  • must reference a security group owned by the account
isEncryptionEnabledboolean

Enables disk encryption on the appliance. When true, encryption_passphrase is required.

examplefalse
  • defaults to false
encryption_passphrasestring

Passphrase for disk encryption. Only used when isEncryptionEnabled is true.

exampleApiAuto@24
  • required when isEncryptionEnabled is true
  • 8-12 characters
  • must contain at least one lowercase letter, one uppercase letter, and one special character
cn_idinteger

Committed (reserved) SKU ID, when creating the load balancer on a committed plan. null for standard hourly billing. Use a committed_sku_id from LB Plans.

examplenull
cn_statusstring

Committed-plan renewal status. null for standard hourly billing.

examplenull

Responses

200Successful response
object
codeinteger
example200
dataobject
errorsobject
messagestring
exampleSuccess