> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nscale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Load balancers

> Manage load balancers that spread TCP and UDP traffic across backends on a network.

A load balancer takes a virtual IP (VIP) on one of your [networks](https://docs.nscale.com/docs/cli/networks.md), 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](https://docs.nscale.com/docs/cli/contexts.md).

**Aliases:** `load-balancers`, `loadbalancers`, `lb`

Commands that act on one load balancer take its ID or name 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) — List load balancers
* [get](#get) — Get load balancer details
* [create](#create) — Create a new load balancer
* [update](#update) — Update an existing load balancer
* [delete](#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.

```bash theme={null}
nscale load-balancers list [flags]
```

**Aliases:** `list`, `ls`

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td>`--org string`</td><td>Organization ID or name</td></tr>
    <tr><td>`--project string`</td><td>Project ID or name</td></tr>
    <tr><td>`--region string`</td><td>Region ID or name</td></tr>
    <tr><td>`--network string`</td><td>Network ID or name</td></tr>

    <tr>
      <td>
        `--limit int`
      </td>

      <td>Show at most N results (client-side; every result is still fetched). Cuts before `-q`. `0` for all</td>
    </tr>

    <tr>
      <td>
        `--json`
      </td>

      <td>Emit the full JSON payload (mutually exclusive with `-q`)</td>
    </tr>

    <tr>
      <td>
        `-q, --query stringArray`
      </td>

      <td>jq filter for value extraction (see [Query output with `-q`](https://docs.nscale.com/docs/cli/query-output))</td>
    </tr>
  </tbody>
</table>

### Examples

```bash theme={null}
nscale load-balancers list --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.

```bash theme={null}
nscale load-balancers get <load-balancer-id>
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td>`--id string`</td><td>Load balancer ID or name</td></tr>
    <tr><td>`--org string`</td><td>Organization ID or name</td></tr>

    <tr>
      <td>
        `--json`
      </td>

      <td>Emit the full JSON payload (mutually exclusive with `-q`)</td>
    </tr>

    <tr>
      <td>
        `-q, --query stringArray`
      </td>

      <td>jq filter for value extraction (see [Query output with `-q`](https://docs.nscale.com/docs/cli/query-output))</td>
    </tr>
  </tbody>
</table>

### Example

```bash theme={null}
# 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`](https://docs.nscale.com/docs/cli/networks#list) to find the network ID.

```bash theme={null}
nscale load-balancers create [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td>`--org string`</td><td>Organization ID or name</td></tr>
    <tr><td>`-f, --file string`</td><td>Path to a JSON file</td></tr>
    <tr><td>`--stdin`</td><td>Read JSON from standard input</td></tr>
    <tr><td>`--dry-run`</td><td>Preview actions and payload without persisting</td></tr>
    <tr><td>`-y, --yes`</td><td>Automatically confirm load balancer creation</td></tr>

    <tr>
      <td>
        `--json`
      </td>

      <td>Emit the full JSON payload (mutually exclusive with `-q`)</td>
    </tr>

    <tr>
      <td>
        `-q, --query stringArray`
      </td>

      <td>jq filter for value extraction (see [Query output with `-q`](https://docs.nscale.com/docs/cli/query-output))</td>
    </tr>
  </tbody>
</table>

### Payload

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

```json loadbalancer.json theme={null}
{
  "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

```bash theme={null}
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.

```bash theme={null}
nscale load-balancers update <load-balancer-id> [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td>`--id string`</td><td>Load balancer ID or name</td></tr>
    <tr><td>`--org string`</td><td>Organization ID or name</td></tr>
    <tr><td>`-f, --file string`</td><td>Path to a JSON file</td></tr>
    <tr><td>`--stdin`</td><td>Read JSON from standard input</td></tr>
    <tr><td>`--dry-run`</td><td>Preview actions and payload without persisting</td></tr>
    <tr><td>`-y, --yes`</td><td>Automatically confirm load balancer update</td></tr>

    <tr>
      <td>
        `--json`
      </td>

      <td>Emit the full JSON payload (mutually exclusive with `-q`)</td>
    </tr>

    <tr>
      <td>
        `-q, --query stringArray`
      </td>

      <td>jq filter for value extraction (see [Query output with `-q`](https://docs.nscale.com/docs/cli/query-output))</td>
    </tr>
  </tbody>
</table>

### Examples

```bash theme={null}
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.

```bash theme={null}
nscale load-balancers delete <load-balancer-id> [flags]
```

**Aliases:** `delete`, `rm`, `remove`

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td>`--id string`</td><td>Load balancer ID or name</td></tr>
    <tr><td>`--org string`</td><td>Organization ID or name</td></tr>
    <tr><td>`--dry-run`</td><td>Preview actions and payload without persisting</td></tr>
    <tr><td>`-y, --yes`</td><td>Automatically confirm load balancer delete</td></tr>
  </tbody>
</table>

### Example

```bash theme={null}
nscale load-balancers delete <load-balancer-id> --yes
```

***

## Related

> [card] [Networks (CLI)](https://docs.nscale.com/docs/cli/networks.md)
>
> Every load balancer sits on a network and takes its VIP from the network's CIDR.

> [card] [VPC networks](https://docs.nscale.com/docs/network/vpc-networks.md)
>
> How VPC networks isolate your resources, and how they are scoped.

> [card] [Security groups](https://docs.nscale.com/docs/network/security-groups.md)
>
> Control the traffic that reaches your backend instances.
