> For the complete documentation index, see [llms.txt](https://docs.acecloud.ai/knowledge-base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.acecloud.ai/knowledge-base/cli/networking/load-balancers.md). # 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 --subnet [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 ``` Create a Network Load Balancer: ```bash ace lb create --name tcp-lb --subnet --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 ``` #### 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 [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...] [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 --lb [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 ``` HTTPS listener on port 443: ```bash ace lb listener create --name https-listener --protocol HTTPS --port 443 --lb ``` TCP listener for a database proxy: ```bash ace lb listener create --name pg-listener --protocol TCP --port 5432 --lb ``` #### 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 ``` #### 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...] ``` **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 [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 ``` Create a pool attached directly to a load balancer: ```bash ace lb pool create --name tcp-pool \ --protocol TCP \ --algorithm LEAST_CONNECTIONS \ --lb ``` #### 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 ``` #### 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...] ``` **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 --type ALB # 2. Create an HTTP listener on port 80 ace lb listener create --name http-80 --protocol HTTP --port 80 --lb # 3. Create a pool with round-robin distribution ace lb pool create --name web-pool \ --protocol HTTP \ --algorithm ROUND_ROBIN \ --listener # 4. (Add members via the AceCloud portal or API) # 5. Verify the setup ace lb get ace lb listener list --lb 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 ` | Get load balancer details | | `ace lb update ` | Update a load balancer | | `ace lb delete ` | Delete load balancer(s) | | `ace lb listener create` | Create a listener | | `ace lb listener list` | List listeners | | `ace lb listener get ` | Get listener details | | `ace lb listener delete ` | Delete listener(s) | | `ace lb pool create` | Create a pool | | `ace lb pool list` | List pools | | `ace lb pool get ` | Get pool details | | `ace lb pool delete ` | Delete pool(s) |