# Load Balancers

Load balancers distribute incoming traffic across multiple instances to improve availability and performance. AceCloud supports Application Load Balancers (ALB) for HTTP/HTTPS traffic and Network Load Balancers (NLB) for TCP/UDP traffic.

**Command:** `ace load-balancer` **Alias:** `ace lb`

## Architecture

A load balancer has three layers:

```
Load Balancer
  └── Listener (protocol + port)
        └── Pool (backend group + algorithm)
              └── Members (instances)
```

* **Load Balancer** -- the top-level resource with a VIP address on a subnet.
* **Listener** -- accepts traffic on a protocol and port (e.g. HTTP:80).
* **Pool** -- a group of backend instances with a load-balancing algorithm.

***

## Load Balancer Management

### Create a Load Balancer

```bash
ace lb create --name <name> --subnet <subnet-id> [flags]
```

#### Flags

| Flag            | Required | Default | Description                        |
| --------------- | -------- | ------- | ---------------------------------- |
| `--name`        | Yes      |         | Load balancer name                 |
| `--subnet`      | Yes      |         | VIP subnet UUID                    |
| `--type`        | No       | `ALB`   | Load balancer type: `ALB` or `NLB` |
| `--description` | No       |         | Description (max 255 characters)   |

#### Examples

Create an Application Load Balancer:

```bash
ace lb create --name web-lb --subnet <subnet-id>
```

Create a Network Load Balancer:

```bash
ace lb create --name tcp-lb --subnet <subnet-id> --type NLB
```

#### Sample Output

```
Load balancer "web-lb" created.
  ID:              a1b2c3d4-e5f6-7890-abcd-ef1234567890
  VIP Address:     10.0.0.100
  Status:          PENDING_CREATE
  Type:            ALB
```

The load balancer starts in `PENDING_CREATE` status and transitions to `ACTIVE` once provisioning completes. This typically takes 1--2 minutes.

### List Load Balancers

```bash
ace lb list
```

**Alias:** `ace lb ls`

#### Sample Output

```
NAME                      ID                                     VIP ADDRESS        PROV STATUS    OP STATUS    LISTENERS
web-lb                    a1b2c3d4-e5f6-7890-abcd-ef1234567890  10.0.0.100         ACTIVE         ONLINE       2
tcp-lb                    b2c3d4e5-f6a7-8901-bcde-f12345678901  10.0.0.101         ACTIVE         ONLINE       1
```

### Get Load Balancer Details

```bash
ace lb get <lb-id>
```

#### Sample Output

```
  Name:                     web-lb
  ID:                       a1b2c3d4-e5f6-7890-abcd-ef1234567890
  VIP Address:              10.0.0.100
  VIP Subnet:               f6e5d4c3-b2a1-0987-fedc-ba0987654321
  VIP Network:              c3d4e5f6-a7b8-9012-cdef-234567890abc
  Prov. Status:             ACTIVE
  Oper. Status:             ONLINE
  Admin State:              true
  Provider:                 octavia
  Tags:                     ALB
  Listeners:                2
  Pools:                    2
  Created:                  2025-01-15T10:30:00Z
```

### Update a Load Balancer

```bash
ace lb update <lb-id> [flags]
```

#### Flags

| Flag            | Required | Description     |
| --------------- | -------- | --------------- |
| `--name`        | No       | New name        |
| `--description` | No       | New description |

At least one flag must be specified.

#### Example

```bash
ace lb update a1b2c3d4-e5f6-7890-abcd-ef1234567890 --name web-lb-v2
```

```
Load balancer a1b2c3d4-e5f6-7890-abcd-ef1234567890 updated.
```

### Delete Load Balancers

```bash
ace lb delete <lb-id> [lb-id...] [flags]
```

**Alias:** `ace lb rm`

#### Flags

| Flag        | Required | Default | Description                                            |
| ----------- | -------- | ------- | ------------------------------------------------------ |
| `--cascade` | No       | `false` | Delete all child resources (listeners, pools, members) |

Without `--cascade`, the load balancer must have no listeners or pools. Use `--cascade` to delete everything in one step.

#### Examples

```bash
# Delete with all child resources
ace lb delete a1b2c3d4-e5f6-7890-abcd-ef1234567890 --cascade

# Delete (must have no children)
ace lb delete a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

```
Deleted 1 load balancer(s).
```

***

## Listener Management

Listeners define the protocol and port on which the load balancer accepts incoming connections.

### Create a Listener

```bash
ace lb listener create --name <name> --lb <lb-id> [flags]
```

#### Flags

| Flag         | Required | Default | Description                                                 |
| ------------ | -------- | ------- | ----------------------------------------------------------- |
| `--name`     | Yes      |         | Listener name                                               |
| `--lb`       | Yes      |         | Load balancer UUID                                          |
| `--protocol` | No       | `HTTP`  | Protocol: `HTTP`, `HTTPS`, `TCP`, `UDP`, `TERMINATED_HTTPS` |
| `--port`     | No       | `80`    | Protocol port (1--65535)                                    |

#### Examples

HTTP listener on port 80:

```bash
ace lb listener create --name http-listener --protocol HTTP --port 80 --lb <lb-id>
```

HTTPS listener on port 443:

```bash
ace lb listener create --name https-listener --protocol HTTPS --port 443 --lb <lb-id>
```

TCP listener for a database proxy:

```bash
ace lb listener create --name pg-listener --protocol TCP --port 5432 --lb <lb-id>
```

#### Sample Output

```
Listener "http-listener" created.
  Listener ID:     c3d4e5f6-a7b8-9012-cdef-234567890abc
```

### List Listeners

```bash
ace lb listener list [flags]
```

**Alias:** `ace lb listener ls`

#### Flags

| Flag   | Required | Description                |
| ------ | -------- | -------------------------- |
| `--lb` | No       | Filter by load balancer ID |

#### Examples

List all listeners:

```bash
ace lb listener list
```

List listeners for a specific load balancer:

```bash
ace lb listener list --lb a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

#### Sample Output

```
NAME                      ID                                     PROTOCOL   PORT   STATUS       DEFAULT POOL
http-listener             c3d4e5f6-a7b8-9012-cdef-234567890abc  HTTP       80     ACTIVE       d4e5f6a7-b...
https-listener            d4e5f6a7-b8c9-0123-def0-456789abcdef  HTTPS      443    ACTIVE       e5f6a7b8-c...
```

### Get Listener Details

```bash
ace lb listener get <listener-id>
```

#### Sample Output

```
  Name:                     http-listener
  ID:                       c3d4e5f6-a7b8-9012-cdef-234567890abc
  Protocol:                 HTTP
  Port:                     80
  Prov. Status:             ACTIVE
  Oper. Status:             ONLINE
  Admin State:              true
  Default Pool:             d4e5f6a7-b8c9-0123-def0-456789abcdef
  Created:                  2025-01-15T10:35:00Z
```

### Delete Listeners

```bash
ace lb listener delete <listener-id> [listener-id...]
```

**Alias:** `ace lb listener rm`

#### Example

```bash
ace lb listener delete c3d4e5f6-a7b8-9012-cdef-234567890abc
```

```
Deleted 1 listener(s).
```

***

## Pool Management

Pools define the group of backend instances and the algorithm used to distribute traffic.

### Create a Pool

```bash
ace lb pool create --name <name> [flags]
```

#### Flags

| Flag          | Required | Default       | Description                                                 |
| ------------- | -------- | ------------- | ----------------------------------------------------------- |
| `--name`      | Yes      |               | Pool name                                                   |
| `--protocol`  | No       | `HTTP`        | Protocol: `HTTP`, `HTTPS`, `TCP`, `UDP`, `PROXY`, `PROXYV2` |
| `--algorithm` | No       | `ROUND_ROBIN` | Algorithm: `ROUND_ROBIN`, `LEAST_CONNECTIONS`, `SOURCE_IP`  |
| `--listener`  | No       |               | Listener UUID (provide `--listener` or `--lb`)              |
| `--lb`        | No       |               | Load balancer UUID (provide `--lb` or `--listener`)         |

You must specify either `--listener` or `--lb` (or both). When attached to a listener, the pool becomes that listener's default pool.

#### Load-Balancing Algorithms

| Algorithm           | Description                                                        |
| ------------------- | ------------------------------------------------------------------ |
| `ROUND_ROBIN`       | Distributes requests evenly across all members                     |
| `LEAST_CONNECTIONS` | Sends new connections to the member with fewest active connections |
| `SOURCE_IP`         | Routes requests from the same source IP to the same member         |

#### Examples

Create a pool attached to a listener:

```bash
ace lb pool create --name web-pool \
  --protocol HTTP \
  --algorithm ROUND_ROBIN \
  --listener <listener-id>
```

Create a pool attached directly to a load balancer:

```bash
ace lb pool create --name tcp-pool \
  --protocol TCP \
  --algorithm LEAST_CONNECTIONS \
  --lb <lb-id>
```

#### Sample Output

```
Pool "web-pool" created.
  Pool ID:         d4e5f6a7-b8c9-0123-def0-456789abcdef
```

### List Pools

```bash
ace lb pool list
```

**Alias:** `ace lb pool ls`

#### Sample Output

```
NAME                      ID                                     PROTOCOL   ALGORITHM        STATUS       MEMBERS
web-pool                  d4e5f6a7-b8c9-0123-def0-456789abcdef  HTTP       ROUND_ROBIN      ACTIVE       3
tcp-pool                  e5f6a7b8-c9d0-1234-ef01-56789abcdef0  TCP        LEAST_CONNECTIONS ACTIVE       2
```

### Get Pool Details

```bash
ace lb pool get <pool-id>
```

#### Sample Output

```
  Name:                     web-pool
  ID:                       d4e5f6a7-b8c9-0123-def0-456789abcdef
  Protocol:                 HTTP
  Algorithm:                ROUND_ROBIN
  Prov. Status:             ACTIVE
  Oper. Status:             ONLINE
  Admin State:              true
  Members:                  3
  Health Monitor:           f6a7b8c9-d0e1-2345-f678-90abcdef0123
  Created:                  2025-01-15T10:40:00Z
```

### Delete Pools

```bash
ace lb pool delete <pool-id> [pool-id...]
```

**Alias:** `ace lb pool rm`

#### Example

```bash
ace lb pool delete d4e5f6a7-b8c9-0123-def0-456789abcdef
```

```
Deleted 1 pool(s).
```

***

## End-to-End Example

Set up a complete HTTP load balancer for a web application:

```bash
# 1. Create the load balancer
ace lb create --name web-lb --subnet <subnet-id> --type ALB

# 2. Create an HTTP listener on port 80
ace lb listener create --name http-80 --protocol HTTP --port 80 --lb <lb-id>

# 3. Create a pool with round-robin distribution
ace lb pool create --name web-pool \
  --protocol HTTP \
  --algorithm ROUND_ROBIN \
  --listener <listener-id>

# 4. (Add members via the AceCloud portal or API)

# 5. Verify the setup
ace lb get <lb-id>
ace lb listener list --lb <lb-id>
ace lb pool list
```

***

## Command Summary

| Command                       | Description               |
| ----------------------------- | ------------------------- |
| `ace lb create`               | Create a load balancer    |
| `ace lb list`                 | List all load balancers   |
| `ace lb get <id>`             | Get load balancer details |
| `ace lb update <id>`          | Update a load balancer    |
| `ace lb delete <id>`          | Delete load balancer(s)   |
| `ace lb listener create`      | Create a listener         |
| `ace lb listener list`        | List listeners            |
| `ace lb listener get <id>`    | Get listener details      |
| `ace lb listener delete <id>` | Delete listener(s)        |
| `ace lb pool create`          | Create a pool             |
| `ace lb pool list`            | List pools                |
| `ace lb pool get <id>`        | Get pool details          |
| `ace lb pool delete <id>`     | Delete pool(s)            |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.acecloud.ai/knowledge-base/cli/networking/load-balancers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.