Load balancers

A load balancer takes a virtual IP (VIP) on one of your networks, and optionally a public IP, and forwards traffic from its listeners to a pool of backend members. Every command acts in the organization given by --org, or the one saved in your context. Aliases: load-balancers, loadbalancers, lb Commands that act on one load balancer take its ID either as a positional argument or with --id. If you omit it, the CLI opens an interactive picker, so always pass it in scripts.

Subcommands

list — List load balancers
get — Get load balancer details
create — Create a new load balancer
update — Update an existing load balancer
delete — Delete an existing load balancer

list

List load balancers, optionally filtered by project, region, or network. The table shows each load balancer’s ID, name, VIP, public IP, and number of listeners.

nscale load-balancers list [flags]

Flags

Flag	Description
Organization ID
Project ID
Region ID
Network ID
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Examples

nscale load-balancers list --org <org-id> --network <network-id>

# Print each load balancer's ID and provisioned VIP
nscale lb list -q '.[].metadata.id' -q '.[].status.vipAddress'

get

Get details for a specific load balancer, including its listeners and the VIP and public IP it was given.

nscale load-balancers get <load-balancer-id> --org <org-id>

Flags

Flag	Description
Load balancer ID
Organization ID
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Example

# List each listener as name protocol/port
nscale load-balancers get <load-balancer-id> \
  -q '.spec.listeners[] | "\(.name) \(.protocol)/\(.port)"'

create

Create a new load balancer. Accepts input from a JSON file or stdin. With neither, the CLI prompts for the name, description, network, whether to allocate a public IP, and an optional VIP, then opens a listener editor where you add each listener and its pool members. The load balancer belongs to the project and region of the network you attach it to. Use nscale networks list to find the network ID.

nscale load-balancers create [flags]

Flags

Flag	Description
Organization ID
Path to a JSON file
Read JSON from standard input
Preview actions and payload without persisting
Automatically confirm load balancer creation
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Payload

This example has two listeners: TCP port 80 with a health check, open to any source, and UDP port 53.

loadbalancer.json

{
  "metadata": {
    "name": "demo-load-balancer",
    "description": "Demo load balancer"
  },
  "spec": {
    "networkId": "efe3c4ba-636c-403b-a073-770fb6fcc132",
    "publicIP": true,
    "listeners": [
      {
        "name": "http",
        "protocol": "tcp",
        "port": 80,
        "idleTimeoutSeconds": 120,
        "allowedCidrs": ["0.0.0.0/0"],
        "pool": {
          "healthCheck": {
            "intervalSeconds": 10,
            "timeoutSeconds": 5,
            "healthyThreshold": 3,
            "unhealthyThreshold": 3
          },
          "members": [
            {
              "address": "10.0.0.10",
              "port": 8080
            }
          ]
        }
      },
      {
        "name": "dns",
        "protocol": "udp",
        "port": 53,
        "pool": {
          "members": [
            {
              "address": "10.0.0.21",
              "port": 53
            }
          ]
        }
      }
    ]
  }
}

Field	Required	Description
`metadata.name`	Yes	Load balancer name: lower-case letters, digits, and hyphens, not starting or ending with a hyphen
`metadata.description`	No	Free-text description
`spec.networkId`	Yes	Network to place the load balancer on. Cannot be changed later.
`spec.vipAddress`	No	IPv4 address to request as the VIP. It must fall within the network’s CIDR. If omitted, one is picked from the network. Cannot be changed later.
`spec.publicIP`	No	Allocate a public IP address for the load balancer
`spec.listeners`	Yes	At least one listener
`listeners[].name`	Yes	Listener name, unique within the load balancer
`listeners[].protocol`	Yes	`tcp` or `udp`
`listeners[].port`	Yes	Port the load balancer listens on (1 to 65535)
`listeners[].idleTimeoutSeconds`	No	Seconds before an idle connection is closed (1 to 86400). TCP only; defaults to 60.
`listeners[].allowedCidrs`	No	IPv4 CIDRs allowed to connect. If omitted, any source can connect.
`listeners[].pool.members`	Yes	Backends, each an IPv4 `address` and a `port` (1 to 65535). The array is required but can be empty.
`listeners[].pool.healthCheck`	No	`intervalSeconds` and `timeoutSeconds` (1 to 300), `healthyThreshold` and `unhealthyThreshold` (1 to 10)
`listeners[].pool.proxyProtocolV2`	No	Prefix each connection with a PROXY protocol v2 header carrying the client address

Some constraints aren’t obvious from the payload:

Listener names are DNS labels. They start with a lower-case letter, contain only lower-case letters, digits, and hyphens, don’t end with a hyphen, and are at most 63 characters (^[a-z]([-a-z0-9]*[a-z0-9])?$).
Two listeners can’t share a protocol and port. TCP 53 and UDP 53 can coexist; two TCP 80 listeners can’t.
idleTimeoutSeconds is not supported for UDP listeners. Leave it out of UDP listeners.
allowedCidrs and member addresses are IPv4 only.
The network and requested VIP are fixed at creation. To move a load balancer to another network or VIP, create a new one.

Examples

nscale load-balancers create --file loadbalancer.json
nscale load-balancers create --stdin < loadbalancer.json
cat loadbalancer.json | nscale load-balancers create --stdin

# Preview the request without creating anything
nscale load-balancers create --file loadbalancer.json --dry-run

update

Update an existing load balancer. Accepts input from a JSON file or stdin. With neither, the CLI prompts for the name, description, and public IP, then opens the listener editor, all pre-filled from the load balancer as it stands. The payload replaces the load balancer’s metadata, publicIP, and listeners, so include every listener you want to keep. It accepts only metadata, spec.publicIP, and spec.listeners. The network and requested VIP are fixed at creation, and the CLI rejects a payload that contains spec.networkId or spec.vipAddress, so remove them from a create payload before you reuse it.

nscale load-balancers update <load-balancer-id> [flags]

Flags

Flag	Description
Load balancer ID
Organization ID
Path to a JSON file
Read JSON from standard input
Preview actions and payload without persisting
Automatically confirm load balancer update
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Examples

nscale load-balancers update <load-balancer-id> --file loadbalancer.json
nscale load-balancers update <load-balancer-id> --stdin < loadbalancer.json

# Reuse a create payload: drop the create-only fields first
jq 'del(.spec.networkId, .spec.vipAddress)' loadbalancer.json \
  | nscale load-balancers update <load-balancer-id> --stdin

delete

Delete an existing load balancer.

nscale load-balancers delete <load-balancer-id> --org <org-id> [flags]

Flags

Flag	Description
Load balancer ID
Organization ID
Preview actions and payload without persisting
Automatically confirm load balancer delete

Example

nscale load-balancers delete <load-balancer-id> --yes

Networks (CLI)

Every load balancer sits on a network and takes its VIP from the network’s CIDR.

VPC networks

How VPC networks isolate your resources, and how they are scoped.

Security groups

Control the traffic that reaches your backend instances.

​Subcommands

​list

​Flags

​Examples

​get

​Flags

​Example

​create

​Flags

​Payload

​Examples

​update

​Flags

​Examples

​delete

​Flags

​Example

​Related

Networks (CLI)

VPC networks

Security groups

Subcommands

list

Flags

Examples

get

Flags

Example

create

Flags

Payload

Examples

update

Flags

Examples

delete

Flags

Example

Related