> ## 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.

export const resource_0 = "load balancer"

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

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

Commands that act on one {resource_0} 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) — 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]
```

### Flags

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

  <tbody>
    <tr><td><code>{"--org string"}</code></td><td>Organization ID</td></tr>
    <tr><td><code>{"--project string"}</code></td><td>Project ID</td></tr>
    <tr><td><code>{"--region string"}</code></td><td>Region ID</td></tr>
    <tr><td><code>{"--network string"}</code></td><td>Network ID</td></tr>

    <tr>
      <td>
        <code>
          {"--json"}
        </code>
      </td>

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

    <tr>
      <td>
        <code>
          {"-q, --query stringArray"}
        </code>
      </td>

      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Examples

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

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

### Flags

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

  <tbody>
    <tr><td><code>{"--id string"}</code></td><td>Load balancer ID</td></tr>
    <tr><td><code>{"--org string"}</code></td><td>Organization ID</td></tr>

    <tr>
      <td>
        <code>
          {"--json"}
        </code>
      </td>

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

    <tr>
      <td>
        <code>
          {"-q, --query stringArray"}
        </code>
      </td>

      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</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`](/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><code>{"--org string"}</code></td><td>Organization ID</td></tr>
    <tr><td><code>{"-f, --file string"}</code></td><td>Path to a JSON file</td></tr>
    <tr><td><code>{"--stdin"}</code></td><td>Read JSON from standard input</td></tr>
    <tr><td><code>{"--dry-run"}</code></td><td>Preview actions and payload without persisting</td></tr>
    <tr><td><code>{"-y, --yes"}</code></td><td>Automatically confirm load balancer creation</td></tr>

    <tr>
      <td>
        <code>
          {"--json"}
        </code>
      </td>

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

    <tr>
      <td>
        <code>
          {"-q, --query stringArray"}
        </code>
      </td>

      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</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><code>{"--id string"}</code></td><td>Load balancer ID</td></tr>
    <tr><td><code>{"--org string"}</code></td><td>Organization ID</td></tr>
    <tr><td><code>{"-f, --file string"}</code></td><td>Path to a JSON file</td></tr>
    <tr><td><code>{"--stdin"}</code></td><td>Read JSON from standard input</td></tr>
    <tr><td><code>{"--dry-run"}</code></td><td>Preview actions and payload without persisting</td></tr>
    <tr><td><code>{"-y, --yes"}</code></td><td>Automatically confirm load balancer update</td></tr>

    <tr>
      <td>
        <code>
          {"--json"}
        </code>
      </td>

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

    <tr>
      <td>
        <code>
          {"-q, --query stringArray"}
        </code>
      </td>

      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</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> --org <org-id> [flags]
```

### Flags

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

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

### Example

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

***

## Related

<CardGroup cols={2}>
  <Card title="Networks (CLI)" icon="network-wired" href="/docs/cli/networks">
    Every load balancer sits on a network and takes its VIP from the network's CIDR.
  </Card>

  <Card title="VPC networks" icon="earth-europe" href="/docs/network/vpc-networks">
    How VPC networks isolate your resources, and how they are scoped.
  </Card>

  <Card title="Security groups" icon="shield" href="/docs/network/security-groups">
    Control the traffic that reaches your backend instances.
  </Card>
</CardGroup>