From d22ff57cc7eb3b0cbc465cb7d17734968f7693b0 Mon Sep 17 00:00:00 2001 From: Maarten Date: Tue, 24 Feb 2026 19:14:28 +0100 Subject: [PATCH] Add language tags to untagged code blocks in aether-help-texts Co-Authored-By: Claude Opus 4.6 --- notes/aether-help-texts.md | 6010 ++++++++++++++++++------------------ 1 file changed, 3005 insertions(+), 3005 deletions(-) diff --git a/notes/aether-help-texts.md b/notes/aether-help-texts.md index c8391db..12a14d3 100644 --- a/notes/aether-help-texts.md +++ b/notes/aether-help-texts.md @@ -875,7 +875,7 @@ Cluster groups directly influence where new instances are created. Understanding When creating or moving an instance, you can target a specific cluster group using the `@` prefix. For example, on the command line: -``` +```bash `# Launch an instance on any member of the "gpu" group incus launch images:debian/12 my-instance --target=@gpu @@ -2182,7 +2182,7 @@ For local storage drivers, the pool must be configured on **each cluster member For example, creating a ZFS pool across a three-member cluster via the CLI: -``` +```bash `# Step 1: Define per-member configuration incus storage create my-pool zfs source=/dev/sdX size=10GiB --target=server1 incus storage create my-pool zfs source=/dev/sdX size=15GiB --target=server2 @@ -3648,7 +3648,7 @@ Snapshots capture the state of a volume at a point in time. They are useful for Snapshots can be created manually via the CLI: -``` +```bash `incus storage volume snapshot create []` ``` @@ -3679,7 +3679,7 @@ snapshots.pattern = {{ creation_date|date:'2006-01-02_15-04-05' }}` To restore a volume to a previous snapshot state: -``` +```bash `incus storage volume snapshot restore ` ``` @@ -3694,7 +3694,7 @@ To restore a volume to a previous snapshot state: Instead of overwriting the current volume, you can restore a snapshot into a brand new volume: -``` +```bash `incus storage volume copy // /` ``` @@ -3808,7 +3808,7 @@ How volumes behave in a cluster depends on the storage driver: Copy a custom volume from one pool to another (or within the same pool with a different name): -``` +```bash `incus storage volume copy / /` ``` @@ -3829,7 +3829,7 @@ Flags: #### Move or Rename a Volume -``` +```bash `incus storage volume move / /` ``` @@ -3850,7 +3850,7 @@ Flags: For local storage drivers, you can copy or move volumes between cluster members: -``` +```bash `incus storage volume copy / / --target= --destination-target=` ``` @@ -3865,7 +3865,7 @@ This does not apply to shared drivers (Ceph, CephFS, etc.) where volumes are alr Copy or move volumes between completely separate Incus servers: -``` +```bash `incus storage volume copy :/ :/` ``` @@ -3880,7 +3880,7 @@ Transfer modes via `--mode`: `pull` (default), `push`, or `relay`. To move an instance (and its root volume) to a different storage pool: -``` +```bash `incus move --storage ` ``` @@ -3900,7 +3900,7 @@ For offline backup or transfer between environments, you can export volumes to a #### Export a Volume -``` +```bash `incus storage volume export []` ``` @@ -3923,7 +3923,7 @@ Flags: #### Import a Volume -``` +```bash `incus storage volume import []` ``` @@ -4351,7 +4351,7 @@ ISO attachment is done from the **Instances** tab. When editing or creating a VM Incus CLI equivalent: -``` +```bash `incus config device add my-vm install-media disk pool=default source=ubuntu-24.04 io.bus=virtio` ``` @@ -4924,7 +4924,7 @@ Before applications can connect to buckets on **local storage pools** (dir, btrf This is a server-level configuration done via CLI: -``` +```bash `incus config set core.storage_buckets_address :8555` ``` @@ -5057,7 +5057,7 @@ After creating a bucket and obtaining your access key and secret key, you can co #### MinIO Client (mc) -``` +```bash `# Set up a connection alias mc alias set incus https://:8555 --api S3v4 --insecure @@ -5078,7 +5078,7 @@ mc mirror ./localdir incus//` #### AWS CLI -``` +```bash `# Configure credentials (enter access key, secret key, region: us-east-1) aws configure @@ -5099,7 +5099,7 @@ aws --endpoint-url https://:8555 s3 sync ./localdir s3:/// #### s3cmd -``` +```bash `# Create ~/.s3cfg with: [default] access_key = @@ -5121,7 +5121,7 @@ s3cmd get s3:///myfile.txt` #### rclone -``` +```bash `# Add to ~/.config/rclone/rclone.conf: [incus] type = s3 @@ -5577,7 +5577,7 @@ Devices are identified by their **unique name**. If the same device name appears To prevent an instance from inheriting a device from a profile without providing a replacement, you can use a device of type `none` with the same name (via CLI): -``` +```bash `incus config device add myinstance eth0 none` ``` @@ -5592,7 +5592,7 @@ The `none` type creates nothing inside the instance — it purely blocks inherit To see the final computed configuration after all profile merging and overrides, use the CLI: -``` +```bash `incus config show --expanded` ``` @@ -6210,7 +6210,7 @@ Cloud-init is an industry-standard tool for automating the initial setup of clou ###### Example: Vendor Data in a Profile -``` +```yaml `#cloud-config package_upgrade: true packages: @@ -9020,7 +9020,7 @@ This is essential for **multi-user environments** where you want to prevent proj **Granular control via CLI:** While AETHER provides the master restricted toggle, individual restriction categories can be fine-tuned via the Incus CLI. For example, you can enable restrictions overall but allow nesting for Docker use cases: -``` +```bash `incus project set my-project restricted=true incus project set my-project restricted.containers.nesting=allow` ``` @@ -10360,7 +10360,7 @@ The **Delete** button permanently removes an instance and all its snapshots. Thi For critical production instances, you can set `security.protection.delete=true` in the instance configuration. This prevents the instance from being deleted until the protection is explicitly removed. This is configured via the Incus CLI: -``` +```bash `incus config set security.protection.delete=true` ``` @@ -11156,1033 +11156,1033 @@ Use the search box to filter jobs by any column value. *Source: `/static/healthhelp.html`* -AETHER Health Page Guide - - - - +AETHER Health Page Guide + + + + ## AETHER Infrastructure Health Page Guide - + -This guide explains how to interpret the values displayed on the AETHER Infrastructure Health page. The health page provides a real-time overview of your INCUS clusters, HAProxy load balancers, and storage pools. - +This guide explains how to interpret the values displayed on the AETHER Infrastructure Health page. The health page provides a real-time overview of your INCUS clusters, HAProxy load balancers, and storage pools. + ### Summary Cards (Top Row) - + -The five summary cards at the top provide a quick overview of your infrastructure health: - +The five summary cards at the top provide a quick overview of your infrastructure health: + - + -| - Card | - Format | - Description | - +| + Card | + Format | + Description | -| - **CLUSTERS** | - `X/Y` | - X = clusters with all members online, Y = total clusters | - -| - **HAPROXY INFRA** | - `X/Y` | - X = HAProxy pairs with both instances running, Y = total pairs | - +| + **CLUSTERS** | + `X/Y` | + X = clusters with all members online, Y = total clusters | -| - **HAPROXY SERVICES** | - `X/Y` | - X = services with at least 1 backend responding, Y = total services (clickable - see below) | - -| - **STORAGE** | - `X/Y` | - X = storage pools with status OK and usage below 85%, Y = total pools | - +| + **HAPROXY INFRA** | + `X/Y` | + X = HAProxy pairs with both instances running, Y = total pairs | + + +| + **HAPROXY SERVICES** | + `X/Y` | + X = services with at least 1 backend responding, Y = total services (clickable - see below) | + + +| + **STORAGE** | + `X/Y` | + X = storage pools with status OK and usage below 85%, Y = total pools | + + +| + **ANSIBLE** | + `X/Y` | + X = Ansible/AWX endpoints that are reachable, Y = total endpoints | -| - **ANSIBLE** | - `X/Y` | - X = Ansible/AWX endpoints that are reachable, Y = total endpoints | - - - + + #### Card Color Coding - + - + -| - Color | - Meaning | - Condition | - +| + Color | + Meaning | + Condition | -| - Green | - All healthy | - X equals Y (100% healthy) | - -| - Orange | - Some issues | - X is greater than half of Y | - +| + Green | + All healthy | + X equals Y (100% healthy) | + + +| + Orange | + Some issues | + X is greater than half of Y | + + +| + Red | + Critical | + X is less than or equal to half of Y | -| - Red | - Critical | - X is less than or equal to half of Y | - - - + + ### HAProxy Services Card - + -The **HAPROXY SERVICES** summary card (one of the five cards at the top of the page) shows a summary of all HAProxy services: - +The **HAPROXY SERVICES** summary card (one of the five cards at the top of the page) shows a summary of all HAProxy services: + -- **Format:** `X/Y` +- **Format:** `X/Y` -- **X** = Services that are operational (have at least 1 backend responding) +- **X** = Services that are operational (have at least 1 backend responding) -- **Y** = Total number of services across all HAProxy infrastructures - - - **Tip:** This card is clickable! Click on the HAPROXY SERVICES card to open a detailed pop-up modal showing each service with its backends and their individual health status. - - +- **Y** = Total number of services across all HAProxy infrastructures + + + **Tip:** This card is clickable! Click on the HAPROXY SERVICES card to open a detailed pop-up modal showing each service with its backends and their individual health status. + + #### Services Modal Columns - + - + -| - Column | - Description | - +| + Column | + Description | -| - **Service** | - Name of the HAProxy service | - -| - **VIP:Port** | - The service VIP address and listen port (e.g., `10.0.0.50:443`) | - +| + **Service** | + Name of the HAProxy service | -| - **LB VIP** | - The OVN Load Balancer VIP address with port 443 (e.g., `192.168.1.100:443`) | - -| - **Backends** | - Individual backend servers with their health status badges | - +| + **VIP:Port** | + The service VIP address and listen port (e.g., `10.0.0.50:443`) | + + +| + **LB VIP** | + The OVN Load Balancer VIP address with port 443 (e.g., `192.168.1.100:443`) | + + +| + **Backends** | + Individual backend servers with their health status badges | + + +| + **Status** | + Overall service status showing backends up/total (e.g., `3/4`) | -| - **Status** | - Overall service status showing backends up/total (e.g., `3/4`) | - - - + + #### LB VIP Color Coding - + -The LB VIP column shows the OVN Load Balancer VIP reachability: +The LB VIP column shows the OVN Load Balancer VIP reachability: - + -| - Color | - Meaning | - +| + Color | + Meaning | -| - Green | - LB VIP is reachable (TCP connect to port 443 successful) | - -| - Red | - LB VIP is unreachable (TCP connect to port 443 failed) | - +| + Green | + LB VIP is reachable (TCP connect to port 443 successful) | + + +| + Red | + LB VIP is unreachable (TCP connect to port 443 failed) | + - - - **Note:** The LB VIP reachability test is performed from one of the running HAProxy instances by attempting a TCP connection to port 443 on the OVN Load Balancer VIP. - - + + + **Note:** The LB VIP reachability test is performed from one of the running HAProxy instances by attempting a TCP connection to port 443 on the OVN Load Balancer VIP. + + ### INCUS Clusters Table - + -The clusters table shows detailed information for each INCUS cluster: - +The clusters table shows detailed information for each INCUS cluster: + - + -| - Column | - Description | - +| + Column | + Description | -| - **Cluster** | - Name of the INCUS cluster (sorted alphabetically) | - -| - **Members** | - Online members / Total members in the cluster | - +| + **Cluster** | + Name of the INCUS cluster (sorted alphabetically) | -| - **CPU** | - Total CPU cores across all cluster members (aggregated) | - -| - **Memory** | - Used / Total memory across all cluster members with usage bar | - +| + **Members** | + Online members / Total members in the cluster | -| - **HAProxy** | - HAProxy load balancers deployed on this cluster (see below) | - -| - **Status** | - Cluster health status: Healthy, Degraded, or Down | - +| + **CPU** | + Total CPU cores across all cluster members (aggregated) | + + +| + **Memory** | + Used / Total memory across all cluster members with usage bar | + + +| + **HAProxy** | + HAProxy load balancers deployed on this cluster (see below) | + + +| + **Status** | + Cluster health status: Healthy, Degraded, or Down | + - - + + #### Members Badge - + - + -| - Color | - Meaning | - +| + Color | + Meaning | -| - Green | - All members online (e.g., `8/8`) | - -| - Orange | - Some members offline but cluster still operational (e.g., `7/8`) | - +| + Green | + All members online (e.g., `8/8`) | + + +| + Orange | + Some members offline but cluster still operational (e.g., `7/8`) | + + +| + Red | + All members offline (e.g., `0/8`) | -| - Red | - All members offline (e.g., `0/8`) | - - - - **Tip:** The members badge is clickable! Click on it to open a detailed pop-up modal showing each cluster member with its status, roles, and current message. - - + + + **Tip:** The members badge is clickable! Click on it to open a detailed pop-up modal showing each cluster member with its status, roles, and current message. + + #### Members Modal - + -When you click on the members badge, a modal opens showing detailed information about each cluster member: +When you click on the members badge, a modal opens showing detailed information about each cluster member: - + -| - Column | - Description | - +| + Column | + Description | -| - **Server** | - Name of the cluster member server | - -| - **Status** | - Current status of the member (Online, Offline, Evacuated, Blocked) | - +| + **Server** | + Name of the cluster member server | -| - **Roles** | - Cluster roles assigned to this member (database, database-leader, stand-by) | - -| - **Message** | - Current status message from INCUS (e.g., "Fully operational", "No heartbeat since...") | - +| + **Status** | + Current status of the member (Online, Offline, Evacuated, Blocked) | + + +| + **Roles** | + Cluster roles assigned to this member (database, database-leader, stand-by) | + + +| + **Message** | + Current status message from INCUS (e.g., "Fully operational", "No heartbeat since...") | + - - + + ##### Member Status Colors - - - - -| - Status | - Color | - Meaning | - - -| - Online | - Green | - Member is healthy and responding to heartbeats | - - -| - Offline | - Red | - Member is unreachable (no heartbeat received) | - - -| - Evacuated | - Yellow | - Member has been intentionally drained of workloads | - - -| - Blocked | - Gray | - Member is blocked from receiving new workloads | - - - - - -##### Member Roles - - - - -| - Role | - Description | - - -| - **database-leader** | - This member is the current leader of the distributed database (highlighted in blue) | - - -| - **database** | - This member participates in the distributed database (voter) | - - -| - **stand-by** | - This member does not participate in the database (non-voter, runs workloads only) | - - - - - **Note:** In INCUS clusters, typically 3 members have the database role for quorum. Additional members are stand-by nodes that run workloads but don't vote on database writes. If a database member fails, it is NOT automatically replaced by a stand-by member - this requires manual intervention. - - - -#### Cluster Status - - - - -| - Status | - Meaning | - - -| - Healthy | - All cluster members are online | - - -| - Degraded | - Some members are offline but cluster is still operational | - - -| - Down | - No members are online or cluster is unreachable | - - - - - -### HAProxy Column (In Clusters Table) - + -Each HAProxy load balancer deployed on a cluster is displayed as a compact badge: - + +| + Status | + Color | + Meaning | + + +| + Online | + Green | + Member is healthy and responding to heartbeats | + + +| + Offline | + Red | + Member is unreachable (no heartbeat received) | + + +| + Evacuated | + Yellow | + Member has been intentionally drained of workloads | + + +| + Blocked | + Gray | + Member is blocked from receiving new workloads | + + + + + +##### Member Roles + + + + +| + Role | + Description | + + +| + **database-leader** | + This member is the current leader of the distributed database (highlighted in blue) | + + +| + **database** | + This member participates in the distributed database (voter) | + + +| + **stand-by** | + This member does not participate in the database (non-voter, runs workloads only) | + + + + + **Note:** In INCUS clusters, typically 3 members have the database role for quorum. Additional members are stand-by nodes that run workloads but don't vote on database writes. If a database member fails, it is NOT automatically replaced by a stand-by member - this requires manual intervention. + + + +#### Cluster Status + + + + +| + Status | + Meaning | + + +| + Healthy | + All cluster members are online | + + +| + Degraded | + Some members are offline but cluster is still operational | + + +| + Down | + No members are online or cluster is unreachable | + + + + + +### HAProxy Column (In Clusters Table) + + + +Each HAProxy load balancer deployed on a cluster is displayed as a compact badge: + ``` `shortname [instance-dots] X/Y services, A/B backends` ``` - - + + #### Components - + - + -| - Component | - Description | - +| + Component | + Description | -| - **shortname** | - Shortened HAProxy pair name (e.g., `ffsdn-haproxy`) | - -| - **Instance dots** | - Two dots showing instance status (see below) | - +| + **shortname** | + Shortened HAProxy pair name (e.g., `ffsdn-haproxy`) | -| - **X/Y services** | - X = services with at least 1 backend up, Y = total services | - -| - **A/B backends** | - A = backends responding (UP), B = total backends | - +| + **Instance dots** | + Two dots showing instance status (see below) | + + +| + **X/Y services** | + X = services with at least 1 backend up, Y = total services | + + +| + **A/B backends** | + A = backends responding (UP), B = total backends | + - - + + #### Status Indicators (Dots) - + -Three indicators show the status of the HAProxy pair: +Three indicators show the status of the HAProxy pair: - + -| - Indicator | - Description | - Bright = OK | - Dark = Problem | - +| + Indicator | + Description | + Bright = OK | + Dark = Problem | -| - **Dot 1** | - HAProxy instance 01 status | - Instance running | - Instance stopped/unreachable | - -| - **Dot 2** | - HAProxy instance 02 status | - Instance running | - Instance stopped/unreachable | - +| + **Dot 1** | + HAProxy instance 01 status | + Instance running | + Instance stopped/unreachable | + + +| + **Dot 2** | + HAProxy instance 02 status | + Instance running | + Instance stopped/unreachable | + + +| + **V** | + OVN VIP reachability | + VIP accepts TCP connection on port 443 | + VIP unreachable | -| - **V** | - OVN VIP reachability | - VIP accepts TCP connection on port 443 | - VIP unreachable | - - - - **Note:** The VIP reachability test is performed by a TCP connect to port 443 on the OVN VIP from one of the running HAProxy instances. This confirms the load balancer is accepting connections. - - + + + **Note:** The VIP reachability test is performed by a TCP connect to port 443 on the OVN VIP from one of the running HAProxy instances. This confirms the load balancer is accepting connections. + + #### HAProxy Badge Color - + - + -| - Color | - Meaning | - Condition | - +| + Color | + Meaning | + Condition | -| - Green | - Healthy | - Both instances running AND VIP reachable AND all backends UP | - -| - Yellow | - Degraded | - Both instances running AND VIP reachable BUT some backends are down (services still functional) | - +| + Green | + Healthy | + Both instances running AND VIP reachable AND all backends UP | -| - Orange | - Warning | - One HAProxy instance down (failover active), but VIP still reachable | - -| - Red | - Critical | - Both instances down, OR VIP unreachable, OR any service has all backends down | - +| + Yellow | + Degraded | + Both instances running AND VIP reachable BUT some backends are down (services still functional) | + + +| + Orange | + Warning | + One HAProxy instance down (failover active), but VIP still reachable | + + +| + Red | + Critical | + Both instances down, OR VIP unreachable, OR any service has all backends down | + - - + + #### Examples - + - + -| - Display | - Interpretation | - +| + Display | + Interpretation | -| - myapp-haproxy 1/1 service, 4/4 backends | - Healthy: 1 service up, all 4 backends responding | - -| - myapp-haproxy 1/1 service, 3/4 backends | - Degraded (yellow): Service is up but 1 backend is not responding | - +| + myapp-haproxy 1/1 service, 4/4 backends | + Healthy: 1 service up, all 4 backends responding | -| - myapp-haproxy 2/2 services, 8/8 backends | - Healthy: 2 services, all 8 backends responding | - -| - myapp-haproxy 2/2 services, 7/8 backends | - Degraded (yellow): Both services up, but 1 backend not responding | - +| + myapp-haproxy 1/1 service, 3/4 backends | + Degraded (yellow): Service is up but 1 backend is not responding | -| - myapp-haproxy 1/1 service, 4/4 backends | - Warning (orange): One HAProxy instance is down (failover active) | - -| - myapp-haproxy 1/2 services, 2/8 backends | - Critical: 1 service has all backends down | - +| + myapp-haproxy 2/2 services, 8/8 backends | + Healthy: 2 services, all 8 backends responding | + + +| + myapp-haproxy 2/2 services, 7/8 backends | + Degraded (yellow): Both services up, but 1 backend not responding | + + +| + myapp-haproxy 1/1 service, 4/4 backends | + Warning (orange): One HAProxy instance is down (failover active) | + + +| + myapp-haproxy 1/2 services, 2/8 backends | + Critical: 1 service has all backends down | + - - - - **Note:** A cluster without HAProxy infrastructure will show `-` in the HAProxy column. - - + + + + **Note:** A cluster without HAProxy infrastructure will show `-` in the HAProxy column. + + ### Storage Pools Table - + -The storage table shows all storage pools across all clusters (sorted by cluster name, then pool name): - +The storage table shows all storage pools across all clusters (sorted by cluster name, then pool name): + - + -| - Column | - Description | - +| + Column | + Description | -| - **Cluster** | - Name of the INCUS cluster this pool belongs to | - -| - **Pool** | - Name of the storage pool | - +| + **Cluster** | + Name of the INCUS cluster this pool belongs to | -| - **Driver** | - Storage driver type (e.g., zfs, lvm, btrfs, dir) | - -| - **Usage** | - Visual bar showing used/total space with percentage | - +| + **Pool** | + Name of the storage pool | + + +| + **Driver** | + Storage driver type (e.g., zfs, lvm, btrfs, dir) | + + +| + **Usage** | + Visual bar showing used/total space with percentage | + + +| + **Status** | + Pool status from INCUS (typically "Created") | -| - **Status** | - Pool status from INCUS (typically "Created") | - - - + + #### Usage Bar Colors - + - + -| - Color | - Meaning | - Threshold | - Navigation Impact | - +| + Color | + Meaning | + Threshold | + Navigation Impact | -| - Green | - Healthy | - Below 85% | - No indicator | - -| - Yellow | - Degraded | - 85% - 89% | - AETHER Health link turns yellow | - +| + Green | + Healthy | + Below 85% | + No indicator | -| - Orange | - Warning | - 90% - 94% | - AETHER Health link turns orange | - -| - Red | - Critical | - 95% and above | - AETHER Health link turns red | - +| + Yellow | + Degraded | + 85% - 89% | + AETHER Health link turns yellow | + + +| + Orange | + Warning | + 90% - 94% | + AETHER Health link turns orange | + + +| + Red | + Critical | + 95% and above | + AETHER Health link turns red | + - - - - **Warning:** Storage pools at 85% or above usage require attention. Pools at 95% or above are critical and may cause service disruption if not addressed immediately. - - + + + + **Warning:** Storage pools at 85% or above usage require attention. Pools at 95% or above are critical and may cause service disruption if not addressed immediately. + + ### Memory Usage Bar - + -Memory usage in the clusters table follows the same color thresholds as storage: +Memory usage in the clusters table follows the same color thresholds as storage: - + -| - Color | - Meaning | - Threshold | - Navigation Impact | - +| + Color | + Meaning | + Threshold | + Navigation Impact | -| - Green | - Healthy | - Below 85% | - No indicator | - -| - Yellow | - Degraded | - 85% - 89% | - AETHER Health link turns yellow | - +| + Green | + Healthy | + Below 85% | + No indicator | -| - Orange | - Warning | - 90% - 94% | - AETHER Health link turns orange | - -| - Red | - Critical | - 95% and above | - AETHER Health link turns red | - +| + Yellow | + Degraded | + 85% - 89% | + AETHER Health link turns yellow | + + +| + Orange | + Warning | + 90% - 94% | + AETHER Health link turns orange | + + +| + Red | + Critical | + 95% and above | + AETHER Health link turns red | + - - - - **Warning:** Clusters at 85% memory usage or above may experience performance degradation. Clusters at 95% or above are critical and may cause out-of-memory conditions. - - + + + + **Warning:** Clusters at 85% memory usage or above may experience performance degradation. Clusters at 95% or above are critical and may cause out-of-memory conditions. + + ### CPU Load Bar - + -CPU load in the clusters table shows the 5-minute load average as a percentage of total CPU cores: +CPU load in the clusters table shows the 5-minute load average as a percentage of total CPU cores: - + -| - Color | - Meaning | - Threshold | - Navigation Impact | - +| + Color | + Meaning | + Threshold | + Navigation Impact | -| - Green | - Healthy | - Below 70% | - No indicator | - -| - Yellow | - Degraded | - 70% - 79% | - AETHER Health link turns yellow | - +| + Green | + Healthy | + Below 70% | + No indicator | -| - Orange | - Warning | - 80% - 94% | - AETHER Health link turns orange | - -| - Red | - Critical | - 95% and above | - AETHER Health link turns red | - +| + Yellow | + Degraded | + 70% - 79% | + AETHER Health link turns yellow | + + +| + Orange | + Warning | + 80% - 94% | + AETHER Health link turns orange | + + +| + Red | + Critical | + 95% and above | + AETHER Health link turns red | + - - - - **Warning:** Clusters at 70% CPU load or above may experience performance issues. Clusters at 95% or above are critical and may cause service degradation. - - + + + + **Warning:** Clusters at 70% CPU load or above may experience performance issues. Clusters at 95% or above are critical and may cause service degradation. + + ### Navigation Health Indicator - + -The **AETHER Health** link in the sidebar navigation automatically changes color to indicate infrastructure issues. This runs as a background check every 5 minutes (or as configured) and at application startup. - +The **AETHER Health** link in the sidebar navigation automatically changes color to indicate infrastructure issues. This runs as a background check every 5 minutes (or as configured) and at application startup. + - + -| - Color | - Status | - Triggering Conditions | - +| + Color | + Status | + Triggering Conditions | -| - Normal (no highlight) | - Healthy | - All systems operating normally | - -| - Yellow | - Degraded | - - - -- Aether server disk usage 85-89% - - | - +| + Normal (no highlight) | + Healthy | + All systems operating normally | -| - Orange | - Warning | - - - -- Cluster member offline but cluster still operational (e.g., 2/3 members online) - -- One HAProxy instance down (failover active) - -- Some Ansible/AWX endpoints unreachable - -- Some HAProxy service backends down (services still functional) - -- Storage pool usage not OK (85-94%) - -- CPU load 80-94% - -- Memory usage 90-94% - -- Aether server disk usage 90-94% - - | - -| - Red | - Critical | - - +| + Yellow | + Degraded | + + -- All cluster members offline +- Aether server disk usage 85-89% + + | + + +| + Orange | + Warning | + + -- Both HAProxy instances down +- Cluster member offline but cluster still operational (e.g., 2/3 members online) -- VIP unreachable +- One HAProxy instance down (failover active) -- LB service completely down (all backends down) +- Some Ansible/AWX endpoints unreachable -- All Ansible/AWX endpoints down +- Some HAProxy service backends down (services still functional) -- CPU load 95% or above +- Storage pool usage not OK (85-94%) -- Memory usage 95% or above +- CPU load 80-94% -- Storage pool usage 95% or above - - | - +- Memory usage 90-94% + +- Aether server disk usage 90-94% + + | + + +| + Red | + Critical | + + + +- All cluster members offline + +- Both HAProxy instances down + +- VIP unreachable + +- LB service completely down (all backends down) + +- All Ansible/AWX endpoints down + +- CPU load 95% or above + +- Memory usage 95% or above + +- Storage pool usage 95% or above + + | + - - - - **Note:** The navigation indicator shows the *worst* condition across all monitored infrastructure. The indicator updates when you navigate to any page or refresh. For real-time updates, visit the Health page directly. - - + + + + **Note:** The navigation indicator shows the *worst* condition across all monitored infrastructure. The indicator updates when you navigate to any page or refresh. For real-time updates, visit the Health page directly. + + ### Ansible Endpoints Table - + -The Ansible endpoints table shows all configured AWX/Ansible automation endpoints: - +The Ansible endpoints table shows all configured AWX/Ansible automation endpoints: + - + -| - Column | - Description | - +| + Column | + Description | -| - **Name** | - Configured name of the Ansible endpoint | - -| - **URL** | - Base URL of the AWX/Ansible Tower server (clickable link) | - +| + **Name** | + Configured name of the Ansible endpoint | -| - **Version** | - AWX version number if the endpoint is reachable | - -| - **Status** | - Endpoint health status | - +| + **URL** | + Base URL of the AWX/Ansible Tower server (clickable link) | + + +| + **Version** | + AWX version number if the endpoint is reachable | + + +| + **Status** | + Endpoint health status | + - - + + #### Ansible Endpoint Status - + - + -| - Status | - Meaning | - +| + Status | + Meaning | -| - Healthy | - Endpoint is reachable and responding to API requests | - -| - Down | - Endpoint is unreachable or not responding | - +| + Healthy | + Endpoint is reachable and responding to API requests | + + +| + Down | + Endpoint is unreachable or not responding | + - - - - **Note:** Ansible endpoint health is checked by making an authenticated API request to the AWX server. A failed connection or authentication error will show the endpoint as Down. - - + + + + **Note:** Ansible endpoint health is checked by making an authenticated API request to the AWX server. A failed connection or authentication error will show the endpoint as Down. + + ### Health Event Logging - + -The health monitoring system automatically logs state changes to the **Web UI Log**. Only actual changes are logged (not every check cycle), providing a clear audit trail of infrastructure events. - +The health monitoring system automatically logs state changes to the **Web UI Log**. Only actual changes are logged (not every check cycle), providing a clear audit trail of infrastructure events. + #### Log Levels - + - + -| - Level | - Color Trigger | - Example Events | - +| + Level | + Color Trigger | + Example Events | -| - **INFO** | - Yellow (degraded) or Recovery (back to green) | - - - -- Backend recovered: DOWN -> UP - -- Storage pool usage changed: 80% -> 86% - -- LB Service recovered: DOWN -> UP - - | - -| - **WARN** | - Orange (warning) | - - +| + **INFO** | + Yellow (degraded) or Recovery (back to green) | + + -- Ansible endpoint became unreachable +- Backend recovered: DOWN -> UP -- CPU load entered warning range +- Storage pool usage changed: 80% -> 86% -- Storage/Memory usage 90-94% - - | - +- LB Service recovered: DOWN -> UP + + | -| - **ERROR** | - Red (critical) | - - + +| + **WARN** | + Orange (warning) | + + -- Backend changed: UP -> DOWN +- Ansible endpoint became unreachable -- HAProxy instance changed: Running -> Stopped +- CPU load entered warning range -- LB Service changed: UP -> DOWN +- Storage/Memory usage 90-94% + + | + + +| + **ERROR** | + Red (critical) | + + -- Cluster member went offline +- Backend changed: UP -> DOWN -- VIP became unreachable - - | - +- HAProxy instance changed: Running -> Stopped + +- LB Service changed: UP -> DOWN + +- Cluster member went offline + +- VIP became unreachable + + | + - - + + #### Log Message Format - + -Log messages include identifiable information for easy searching: +Log messages include identifiable information for easy searching: ``` -`[Health] Backend web-server-01 (10.0.1.5) in service my-app on cluster Production changed: UP -> DOWN -[Health] LB Service my-app on cluster Production changed: UP -> DOWN -[Health] HAProxy instance prod-haproxy-01 on cluster Production changed: Running -> Stopped -[Health] Storage pool default on cluster Production changed: 84% -> 91% +`[Health] Backend web-server-01 (10.0.1.5) in service my-app on cluster Production changed: UP -> DOWN +[Health] LB Service my-app on cluster Production changed: UP -> DOWN +[Health] HAProxy instance prod-haproxy-01 on cluster Production changed: Running -> Stopped +[Health] Storage pool default on cluster Production changed: 84% -> 91% [Health] Backend web-server-01 (10.0.1.5) in service my-app on cluster Production recovered: DOWN -> UP` ``` - - - - **Note:** Health events are logged under the username "SYSTEM". You can filter the Web UI Log by this username to see all automated health events. - - + + + + **Note:** Health events are logged under the username "SYSTEM". You can filter the Web UI Log by this username to see all automated health events. + + ### Auto-Refresh - + -Use the auto-refresh dropdown to automatically update the health data: - +Use the auto-refresh dropdown to automatically update the health data: + -- **Off:** Manual refresh only (click the Refresh button) +- **Off:** Manual refresh only (click the Refresh button) -- **30s / 60s / 2m / 5m:** Automatic refresh at the selected interval - +- **30s / 60s / 2m / 5m:** Automatic refresh at the selected interval + -Your preference is saved in your browser and will persist across sessions. - +Your preference is saved in your browser and will persist across sessions. + ### Data Sources - + -The health page queries data directly from: - +The health page queries data directly from: + -- **INCUS API:** Cluster members (`/1.0/cluster/members`), resources (`/1.0/resources`), storage pools (`/1.0/storage-pools`) +- **INCUS API:** Cluster members (`/1.0/cluster/members`), resources (`/1.0/resources`), storage pools (`/1.0/storage-pools`) -- **HAProxy stats:** Via INCUS exec running `show stat` on the HAProxy admin socket +- **HAProxy stats:** Via INCUS exec running `show stat` on the HAProxy admin socket -- **AWX API:** Ansible endpoint health and version information +- **AWX API:** Ansible endpoint health and version information -- **FFSDN Database:** HAProxy infrastructure configuration, service definitions, and AWX endpoint settings - - - +- **FFSDN Database:** HAProxy infrastructure configuration, service definitions, and AWX endpoint settings + + + **Note:** CPU and memory values are aggregated totals from all online cluster members. If a member is offline, its resources are not included in the total. @@ -12192,267 +12192,267 @@ The health page queries data directly from: *Source: `/static/traceflowhelp.html`* -Trace Network Flow - Help - - - - +Trace Network Flow - Help + + + + ## Trace Network Flow - Help - - + + ### What is Trace Network Flow? - + -The Trace Network Flow feature allows you to test and visualize which firewall rules (ACLs) would match a specific network flow between two IP addresses. This is useful for: - +The Trace Network Flow feature allows you to test and visualize which firewall rules (ACLs) would match a specific network flow between two IP addresses. This is useful for: + -- Verifying that traffic between two instances will be allowed or blocked +- Verifying that traffic between two instances will be allowed or blocked -- Troubleshooting connectivity issues by identifying which ACL rule is being applied +- Troubleshooting connectivity issues by identifying which ACL rule is being applied -- Testing firewall rules before deploying changes to production +- Testing firewall rules before deploying changes to production -- Understanding how your ACL configuration affects specific traffic patterns - - +- Understanding how your ACL configuration affects specific traffic patterns + + ### How to Use the Form - + -The Trace Network Flow form requires you to specify the details of the network flow you want to trace: - +The Trace Network Flow form requires you to specify the details of the network flow you want to trace: + #### Source IP Address - - + + -- **Description**: The IP address where the network traffic originates from. +- **Description**: The IP address where the network traffic originates from. -- **Format**: A valid IPv4 address (e.g., `192.168.1.100`). +- **Format**: A valid IPv4 address (e.g., `192.168.1.100`). -- **Example**: If you want to test traffic from a web server at `10.105.232.35`, enter that IP here. - - +- **Example**: If you want to test traffic from a web server at `10.105.232.35`, enter that IP here. + + #### Destination IP Address - - + + -- **Description**: The IP address where the network traffic is going to. +- **Description**: The IP address where the network traffic is going to. -- **Format**: A valid IPv4 address (e.g., `8.8.8.8`). +- **Format**: A valid IPv4 address (e.g., `8.8.8.8`). -- **Example**: If you want to test traffic going to a database server at `10.0.5.20`, enter that IP here. - - +- **Example**: If you want to test traffic going to a database server at `10.0.5.20`, enter that IP here. + + #### Protocol - - + + -- **Description**: The network protocol used for the traffic. +- **Description**: The network protocol used for the traffic. -- **Options**: - +- **Options**: + -- `TCP` - Transmission Control Protocol, used for most application traffic (HTTP, HTTPS, SSH, databases, etc.) +- `TCP` - Transmission Control Protocol, used for most application traffic (HTTP, HTTPS, SSH, databases, etc.) -- `UDP` - User Datagram Protocol, used for DNS, streaming, gaming, etc. +- `UDP` - User Datagram Protocol, used for DNS, streaming, gaming, etc. -- `ICMP` - Internet Control Message Protocol, used for ping and network diagnostics - - - - - **Note:** When you select ICMP, the Port field is automatically disabled because ICMP does not use ports. - - +- `ICMP` - Internet Control Message Protocol, used for ping and network diagnostics + + + + + **Note:** When you select ICMP, the Port field is automatically disabled because ICMP does not use ports. + + #### Port - - + + -- **Description**: The destination port number for TCP or UDP traffic. +- **Description**: The destination port number for TCP or UDP traffic. -- **Format**: A number between 1 and 65535. +- **Format**: A number between 1 and 65535. -- **Examples**: - +- **Examples**: + -- `80` - HTTP +- `80` - HTTP -- `443` - HTTPS +- `443` - HTTPS -- `22` - SSH +- `22` - SSH -- `5432` - PostgreSQL +- `5432` - PostgreSQL -- `3306` - MySQL - - - - - **Note:** The Port field is only required when using TCP or UDP protocols. It is disabled for ICMP. - - +- `3306` - MySQL + + + + + **Note:** The Port field is only required when using TCP or UDP protocols. It is disabled for ICMP. + + ### Understanding the Results - + -After submitting the form, a popup will display the trace results. Here is what each field means: - +After submitting the form, a popup will display the trace results. Here is what each field means: + - + -| - Field | - Description | - +| + Field | + Description | -| - **INCUS/OVN Cluster Name** | - The name of the INCUS cluster where the source or destination instance resides. | - -| - **Source Instance Name** | - The name of the INCUS instance that matches the source IP address (if found). | - +| + **INCUS/OVN Cluster Name** | + The name of the INCUS cluster where the source or destination instance resides. | -| - **Destination Instance Name** | - The name of the INCUS instance that matches the destination IP address (if found). This only appears when both source and destination are managed instances. | - -| - **NIC Name** | - The network interface card name on the instance that has the matching IP address. | - +| + **Source Instance Name** | + The name of the INCUS instance that matches the source IP address (if found). | -| - **OVN Network Name** | - The name of the OVN network that the instance's NIC is connected to. | - -| - **Name of ACL that this flow hits** | - The name of the Access Control List (ACL) that contains the matching rule. ACL names follow the format `FFSDNIO--` for local rules or `FFSDNIOGLB--` for global rules. | - +| + **Destination Instance Name** | + The name of the INCUS instance that matches the destination IP address (if found). This only appears when both source and destination are managed instances. | -| - **First Matching Rule** | - Details of the first firewall rule that matches the traced flow, including: - + +| + **NIC Name** | + The network interface card name on the instance that has the matching IP address. | + + +| + **OVN Network Name** | + The name of the OVN network that the instance's NIC is connected to. | + + +| + **Name of ACL that this flow hits** | + The name of the Access Control List (ACL) that contains the matching rule. ACL names follow the format `FFSDNIO--` for local rules or `FFSDNIOGLB--` for global rules. | + + +| + **First Matching Rule** | + Details of the first firewall rule that matches the traced flow, including: + -- **Direction**: Ingress (incoming) or Egress (outgoing) +- **Direction**: Ingress (incoming) or Egress (outgoing) -- **Action**: ALLOW, DROP, or REJECT +- **Action**: ALLOW, DROP, or REJECT -- **Protocol**: TCP, UDP, or ICMPv4 +- **Protocol**: TCP, UDP, or ICMPv4 -- **Source/Destination**: The IP addresses or ranges in the rule +- **Source/Destination**: The IP addresses or ranges in the rule -- **Port**: The port number (or N/A for ICMP) - - | - +- **Port**: The port number (or N/A for ICMP) + + | + - - + + ### Example Use Cases - - + + #### Testing Web Server Access - + -To verify that external clients can reach your web server on port 443: +To verify that external clients can reach your web server on port 443: ``` -`Source IP: 0.0.0.0 (or any external IP) -Destination IP: 10.105.232.35 (your web server) -Protocol: TCP +`Source IP: 0.0.0.0 (or any external IP) +Destination IP: 10.105.232.35 (your web server) +Protocol: TCP Port: 443` ``` - - + + #### Testing Database Connectivity - + -To check if your application server can connect to your PostgreSQL database: +To check if your application server can connect to your PostgreSQL database: ``` -`Source IP: 10.0.1.50 (application server) -Destination IP: 10.0.5.20 (database server) -Protocol: TCP +`Source IP: 10.0.1.50 (application server) +Destination IP: 10.0.5.20 (database server) +Protocol: TCP Port: 5432` ``` - - + + #### Testing ICMP/Ping - + -To verify that ping is allowed between two instances: +To verify that ping is allowed between two instances: ``` -`Source IP: 192.168.1.10 -Destination IP: 192.168.1.20 -Protocol: ICMP +`Source IP: 192.168.1.10 +Destination IP: 192.168.1.20 +Protocol: ICMP Port: (disabled)` ``` - - + + ### Troubleshooting - - + + - + -| - Issue | - Possible Cause | - Solution | - +| + Issue | + Possible Cause | + Solution | -| - Invalid Source/Destination IP address error | - The IP address format is incorrect | - Ensure you enter a valid IPv4 address in the format `xxx.xxx.xxx.xxx` where each octet is between 0 and 255 | - -| - Port must be a number between 1 and 65535 | - Invalid port number entered | - Enter a valid port number between 1 and 65535 | - +| + Invalid Source/Destination IP address error | + The IP address format is incorrect | + Ensure you enter a valid IPv4 address in the format `xxx.xxx.xxx.xxx` where each octet is between 0 and 255 | -| - No instance found for the IP | - The IP address does not belong to any managed INCUS instance | - Verify the IP address is correct and belongs to an instance in a managed cluster | - -| - Default rule shown | - No specific ACL rule matches the flow | - The flow is hitting the network's default action (allow or drop). Create a specific ACL rule if you need different behavior | - +| + Port must be a number between 1 and 65535 | + Invalid port number entered | + Enter a valid port number between 1 and 65535 | + + +| + No instance found for the IP | + The IP address does not belong to any managed INCUS instance | + Verify the IP address is correct and belongs to an instance in a managed cluster | + + +| + Default rule shown | + No specific ACL rule matches the flow | + The flow is hitting the network's default action (allow or drop). Create a specific ACL rule if you need different behavior | + + + + - - - **Important:** The Trace Network Flow feature shows which rule *would* match the specified flow based on current ACL configuration. It does not send actual network traffic. Use this tool for planning and troubleshooting, not as a connectivity test. @@ -12462,602 +12462,602 @@ Port: (disabled)` *Source: `/static/newACL.html`* -Creating a New Firewall Rule in AETHER - - - - +Creating a New Firewall Rule in AETHER + + + + ## Creating a New Firewall Rule in SDN Controller - + -This guide explains how to fill in the "Create new SDN Firewall Rules for this Cluster" form in the SDN Controller web UI after clicking the "Create" button under "Manage Cluster". Firewall rules define traffic control for an INCUS cluster, applied to instances or OVN networks. These are **local cluster ACLs**, specific to one cluster. For organization-wide rules, see Local Cluster ACLs vs. Global ACLs. - +This guide explains how to fill in the "Create new SDN Firewall Rules for this Cluster" form in the SDN Controller web UI after clicking the "Create" button under "Manage Cluster". Firewall rules define traffic control for an INCUS cluster, applied to instances or OVN networks. These are **local cluster ACLs**, specific to one cluster. For organization-wide rules, see Local Cluster ACLs vs. Global ACLs. + ### Prerequisites - - + + -- You must be logged into the SDN Controller web UI as a user with access to manage the specific cluster (either `admin` or a user with cluster access). +- You must be logged into the SDN Controller web UI as a user with access to manage the specific cluster (either `admin` or a user with cluster access). -- Navigate to "Clusters" > "Manage" for your cluster, then click "Create" under "Create new SDN Firewall Rules for this Cluster". +- Navigate to "Clusters" > "Manage" for your cluster, then click "Create" under "Create new SDN Firewall Rules for this Cluster". -- Basic understanding of network protocols (TCP, UDP, ICMP) and firewall rules. - - +- Basic understanding of network protocols (TCP, UDP, ICMP) and firewall rules. + + ### Local Cluster ACLs vs. Global ACLs - + -The SDN Controller supports two types of Access Control Lists (ACLs): **local cluster ACLs** and **global ACLs**. Understanding their differences is crucial for effective firewall rule management. - +The SDN Controller supports two types of Access Control Lists (ACLs): **local cluster ACLs** and **global ACLs**. Understanding their differences is crucial for effective firewall rule management. + -- **Local Cluster ACLs**: - +- **Local Cluster ACLs**: + -- **Scope**: Apply only to a specific INCUS cluster (e.g., `MyCluster`). +- **Scope**: Apply only to a specific INCUS cluster (e.g., `MyCluster`). -- **Where Created**: In the "Manage Cluster" page, under "Create new SDN Firewall Rules for this Cluster" (this guide). +- **Where Created**: In the "Manage Cluster" page, under "Create new SDN Firewall Rules for this Cluster" (this guide). -- **Storage**: Stored in the `FFSDNIO_rules` database table with a `cluster_id`. +- **Storage**: Stored in the `FFSDNIO_rules` database table with a `cluster_id`. -- **Naming**: Named as `FFSDNIO--` (e.g., `FFSDNIO-129-egress`). +- **Naming**: Named as `FFSDNIO--` (e.g., `FFSDNIO-129-egress`). -- **Use Case**: For cluster-specific policies, such as allowing HTTP traffic only in one cluster's production environment. +- **Use Case**: For cluster-specific policies, such as allowing HTTP traffic only in one cluster's production environment. -- **Access**: Available to `admin` or users with access to the cluster (via "Cluster Access"). - - +- **Access**: Available to `admin` or users with access to the cluster (via "Cluster Access"). + -- **Global ACLs**: - + +- **Global ACLs**: + -- **Scope**: Apply to **all INCUS clusters** managed by the SDN Controller. +- **Scope**: Apply to **all INCUS clusters** managed by the SDN Controller. -- **Where Created**: In the "Global ACLs" page (accessible via the navigation menu, admin-only). +- **Where Created**: In the "Global ACLs" page (accessible via the navigation menu, admin-only). -- **Storage**: Stored in the `ffsdnioglb_rules` database table, without a `cluster_id`. +- **Storage**: Stored in the `ffsdnioglb_rules` database table, without a `cluster_id`. -- **Naming**: Named as `FFSDNIOGLB--` (e.g., `FFSDNIOGLB-2-egress`). +- **Naming**: Named as `FFSDNIOGLB--` (e.g., `FFSDNIOGLB-2-egress`). -- **Use Case**: For organization-wide policies, such as allowing DNS traffic from all production instances across all clusters. +- **Use Case**: For organization-wide policies, such as allowing DNS traffic from all production instances across all clusters. -- **Access**: Restricted to `admin` users only. - - - - - **Note:** Use local cluster ACLs for targeted control within a single cluster. Use global ACLs for consistent rules across all clusters, but ensure they don't conflict with local rules, as both are applied to instances or networks. Check the "Global ACLs" page for existing global rules before creating local ones. - - +- **Access**: Restricted to `admin` users only. + + + + + **Note:** Use local cluster ACLs for targeted control within a single cluster. Use global ACLs for consistent rules across all clusters, but ensure they don't conflict with local rules, as both are applied to instances or networks. Check the "Global ACLs" page for existing global rules before creating local ones. + + ### Step 1: Understand the Form Layout - + -This form creates **local cluster ACLs** for the selected cluster. For global ACLs, navigate to "Global ACLs" (admin-only). The form includes: - +This form creates **local cluster ACLs** for the selected cluster. For global ACLs, navigate to "Global ACLs" (admin-only). The form includes: + -- **Rule Fields** (one or more rows): - +- **Rule Fields** (one or more rows): + -- `Direction`: IN/OUT (both), Ingress/In (inbound), or Egress/Out (outbound). +- `Direction`: IN/OUT (both), Ingress/In (inbound), or Egress/Out (outbound). -- `Source`: Source IP, CIDR, or instance tag condition. +- `Source`: Source IP, CIDR, or instance tag condition. -- `Destination`: Destination IP, CIDR, or instance tag condition. +- `Destination`: Destination IP, CIDR, or instance tag condition. -- `Protocol`: TCP, UDP, or ICMP. +- `Protocol`: TCP, UDP, or ICMP. -- `Port`: Port numbers or ranges (for TCP/UDP only). +- `Port`: Port numbers or ranges (for TCP/UDP only). -- `Action`: Allow, Drop, or Reject. +- `Action`: Allow, Drop, or Reject. -- `Description`: A text description of the rule. - - +- `Description`: A text description of the rule. + -- **Buttons**: "Add another FW rule" and "Review firewall rules". - - + +- **Buttons**: "Add another FW rule" and "Review firewall rules". + + ### Step 2: Define Firewall Rules - + -Each rule row specifies a firewall rule for the current cluster. Start with one row and add more as needed using "Add another FW rule". - +Each rule row specifies a firewall rule for the current cluster. Start with one row and add more as needed using "Add another FW rule". + #### Direction - - + + -- **Options**: `IN/OUT` (both directions), `Ingress/In` (inbound traffic), `Egress/Out` (outbound traffic). +- **Options**: `IN/OUT` (both directions), `Ingress/In` (inbound traffic), `Egress/Out` (outbound traffic). -- **Validation**: Must select one (cannot be empty). +- **Validation**: Must select one (cannot be empty). -- **Example**: `Ingress/In` for incoming web traffic. - - +- **Example**: `Ingress/In` for incoming web traffic. + + #### Source and Destination - - + + -- **Format**: - +- **Format**: + -- IPv4 address (e.g., `192.168.1.10`). +- IPv4 address (e.g., `192.168.1.10`). -- CIDR notation (e.g., `192.168.1.0/24` or `0.0.0.0/0` for ANY). +- CIDR notation (e.g., `192.168.1.0/24` or `0.0.0.0/0` for ANY). -- Instance tag formula with operators (see Instance Tag Operators below). +- Instance tag formula with operators (see Instance Tag Operators below). -- Comma-separated mix of the above (e.g., `0.0.0.0/0,10.34.2.1/24,env=prod OR (app=web AND env=acc),10.6.5.32`). - - +- Comma-separated mix of the above (e.g., `0.0.0.0/0,10.34.2.1/24,env=prod OR (app=web AND env=acc),10.6.5.32`). + -- **Validation**: - - -- Cannot be empty (use `0.0.0.0/0` to represent ANY source or destination). - -- IPv4: Must match `xxx.xxx.xxx.xxx` where each octet is 0-255. - -- CIDR: Must be `xxx.xxx.xxx.xxx/yy` where subnet mask `yy` is 0-32. - -- Instance tags: Must contain an operator (`=`, `=^`, or `=*`), and use valid logical operators (`AND`, `OR`) with parentheses if complex. - -- Comma-separated: Each part must be a valid IPv4, CIDR, or instance tag formula, separated by commas (no spaces after commas). - -- Invalid examples: `256.1.2.3`, `10.0.0.1/33`, `role` (no operator), `10.0.0.1, role=web` (space after comma), empty field. - - -- **Example**: +- **Validation**: + + +- Cannot be empty (use `0.0.0.0/0` to represent ANY source or destination). + +- IPv4: Must match `xxx.xxx.xxx.xxx` where each octet is 0-255. + +- CIDR: Must be `xxx.xxx.xxx.xxx/yy` where subnet mask `yy` is 0-32. + +- Instance tags: Must contain an operator (`=`, `=^`, or `=*`), and use valid logical operators (`AND`, `OR`) with parentheses if complex. + +- Comma-separated: Each part must be a valid IPv4, CIDR, or instance tag formula, separated by commas (no spaces after commas). + +- Invalid examples: `256.1.2.3`, `10.0.0.1/33`, `role` (no operator), `10.0.0.1, role=web` (space after comma), empty field. + + + +- **Example**: ``` -`Source: 192.168.1.0/24,10.0.3.1,env=prod +`Source: 192.168.1.0/24,10.0.3.1,env=prod Destination: role=webserver,10.6.5.32,(app=web AND env=acc)` ``` - + ``` -`Source: 0.0.0.0/0 +`Source: 0.0.0.0/0 Destination: role=webserver` ``` - - - - - **Note:** To allow traffic from or to any IP address, explicitly enter `0.0.0.0/0` in the `Source` or `Destination` field. Leaving these fields empty is not allowed and will prompt a validation error. - - + + + + + **Note:** To allow traffic from or to any IP address, explicitly enter `0.0.0.0/0` in the `Source` or `Destination` field. Leaving these fields empty is not allowed and will prompt a validation error. + + #### Instance Tag Operators - + -Instance tag formulas allow you to dynamically match instances based on their INCUS instance tags. The SDN Controller supports three matching operators: - +Instance tag formulas allow you to dynamically match instances based on their INCUS instance tags. The SDN Controller supports three matching operators: - - -| - Operator | - Syntax | - Description | - Example | - Matches | - - -| - **Equals** | - `=` | - Exact match - tag value must equal the specified value exactly | - `env=prod` | - Instances where `env` is exactly `prod` | - - -| - **Starts With** | - `=^` | - Prefix match - tag value must start with the specified value | - `env=^prod` | - Instances where `env` starts with `prod` (e.g., `prod`, `prod-eu`, `production`) | - - -| - **Contains** | - `=*` | - Substring match - tag value must contain the specified value anywhere | - `env=*test` | - Instances where `env` contains `test` (e.g., `test`, `testing`, `pre-test-env`) | - - - + + +| + Operator | + Syntax | + Description | + Example | + Matches | + + +| + **Equals** | + `=` | + Exact match - tag value must equal the specified value exactly | + `env=prod` | + Instances where `env` is exactly `prod` | + + +| + **Starts With** | + `=^` | + Prefix match - tag value must start with the specified value | + `env=^prod` | + Instances where `env` starts with `prod` (e.g., `prod`, `prod-eu`, `production`) | + + +| + **Contains** | + `=*` | + Substring match - tag value must contain the specified value anywhere | + `env=*test` | + Instances where `env` contains `test` (e.g., `test`, `testing`, `pre-test-env`) | + + + + ##### Instance Tag Formula Examples - + -**Simple conditions:** +**Simple conditions:** ``` -`# Exact match - instances with role exactly equal to "webserver" -role=webserver - -# Starts with - instances with app starting with "BANK" -app=^BANK - -# Contains - instances with tier containing "PROD" +`# Exact match - instances with role exactly equal to "webserver" +role=webserver + +# Starts with - instances with app starting with "BANK" +app=^BANK + +# Contains - instances with tier containing "PROD" tier=*PROD` ``` - - + + -**Complex conditions with AND/OR:** +**Complex conditions with AND/OR:** ``` -`# Instances in production environment AND with database role -(env=prod AND role=db) - -# Instances with app starting with "BANK" OR in the DMZ -(app=^BANK OR zone=dmz) - -# Complex: (production databases) OR (any app containing "critical") -(env=prod AND role=db) OR (app=*critical) - -# Nested: Instances in prod with apps starting with APP or WEB +`# Instances in production environment AND with database role +(env=prod AND role=db) + +# Instances with app starting with "BANK" OR in the DMZ +(app=^BANK OR zone=dmz) + +# Complex: (production databases) OR (any app containing "critical") +(env=prod AND role=db) OR (app=*critical) + +# Nested: Instances in prod with apps starting with APP or WEB (env=prod AND (app=^APP OR app=^WEB))` ``` - - + + ##### Multi-Value Instance Tags - + -Instance tags can contain multiple values separated by `|||` (triple-pipe). When matching, the operators check against each individual value in the list. - +Instance tags can contain multiple values separated by `|||` (triple-pipe). When matching, the operators check against each individual value in the list. + -**Example:** If an instance has the tag `tags=web|||prod|||critical`, then: - +**Example:** If an instance has the tag `tags=web|||prod|||critical`, then: + -- `tags=prod` → matches (exact match on "prod") +- `tags=prod` → matches (exact match on "prod") -- `tags=^pro` → matches ("prod" starts with "pro") +- `tags=^pro` → matches ("prod" starts with "pro") -- `tags=*rit` → matches ("critical" contains "rit") +- `tags=*rit` → matches ("critical" contains "rit") -- `tags=dev` → does NOT match (no value equals "dev") - - - +- `tags=dev` → does NOT match (no value equals "dev") + + + **Note:** You can set multi-value instance tags in INCUS using: - + `incus config set user.tags "web|||prod|||critical"` - - The system handles the `user.` prefix internally. - - - - **Migration from NSX:** If you're migrating rules from VMware NSX, the SDN Controller automatically translates NSX security group dynamic membership criteria to these operators: - + + The system handles the `user.` prefix internally. + + + + **Migration from NSX:** If you're migrating rules from VMware NSX, the SDN Controller automatically translates NSX security group dynamic membership criteria to these operators: + -- NSX `equals` → SDN Controller `=` +- NSX `equals` → SDN Controller `=` -- NSX `starts_with` → SDN Controller `=^` +- NSX `starts_with` → SDN Controller `=^` -- NSX `contains` → SDN Controller `=*` - - Complex NSX security groups with multiple criteria (Match: Any/All) are converted to equivalent AND/OR expressions. - - +- NSX `contains` → SDN Controller `=*` + + Complex NSX security groups with multiple criteria (Match: Any/All) are converted to equivalent AND/OR expressions. + + #### Protocol - - + + -- **Options**: `TCP`, `UDP`, `ICMP`. +- **Options**: `TCP`, `UDP`, `ICMP`. -- **Validation**: Must select one (cannot be empty). +- **Validation**: Must select one (cannot be empty). -- **Example**: `TCP` for HTTP traffic. - - +- **Example**: `TCP` for HTTP traffic. + + #### Port - - + + -- **Format**: - +- **Format**: + -- Single port (e.g., `80`). +- Single port (e.g., `80`). -- Port ranges (e.g., `2000-3000`). +- Port ranges (e.g., `2000-3000`). -- Comma-separated mix of single ports and ranges (e.g., `80,443,1002-1009,5432`). +- Comma-separated mix of single ports and ranges (e.g., `80,443,1002-1009,5432`). -- Empty (matches ANY ports, 1-65535, for TCP/UDP). - - +- Empty (matches ANY ports, 1-65535, for TCP/UDP). + -- **Validation**: - - -- Optional for `TCP` or `UDP`; if empty, matches all ports (1-65535). - -- Disabled and ignored for `ICMP`. - -- Must be integers between 1 and 65535, separated by commas (no spaces). - -- Invalid examples: `0`, `70000`, `80, 443` (space). - - -- **Example**: `80,443` for web traffic; leave empty for all ports (1-65535). - - - **Note:** Omitting the `Port` field for `TCP` or `UDP` protocols will result in the rule applying to ALL ports (1-65535). Explicitly specify ports to restrict the rule's scope. - - +- **Validation**: + + +- Optional for `TCP` or `UDP`; if empty, matches all ports (1-65535). + +- Disabled and ignored for `ICMP`. + +- Must be integers between 1 and 65535, separated by commas (no spaces). + +- Invalid examples: `0`, `70000`, `80, 443` (space). + + + +- **Example**: `80,443` for web traffic; leave empty for all ports (1-65535). + + + **Note:** Omitting the `Port` field for `TCP` or `UDP` protocols will result in the rule applying to ALL ports (1-65535). Explicitly specify ports to restrict the rule's scope. + + #### Action - - + + -- **Options**: `ALLOW`, `DROP`, `REJECT`. +- **Options**: `ALLOW`, `DROP`, `REJECT`. -- **Validation**: Must select one (cannot be empty). +- **Validation**: Must select one (cannot be empty). -- **Example**: `ALLOW` to permit traffic. - - +- **Example**: `ALLOW` to permit traffic. + + #### Description - - + + -- **Format**: Free-text description of the rule's purpose. +- **Format**: Free-text description of the rule's purpose. -- **Validation**: Optional (can be empty). +- **Validation**: Optional (can be empty). -- **Example**: `Allow HTTP/HTTPS traffic to webservers`. - - +- **Example**: `Allow HTTP/HTTPS traffic to webservers`. + + #### How INCUS Processes Rules - + -The order in which INCUS applies local and global ACL rules depends on the network's default action: - +The order in which INCUS applies local and global ACL rules depends on the network's default action: + -- **For Networks with Default Action "Drop"**: +- **For Networks with Default Action "Drop"**: -INCUS combines all local (`FFSDNIO-`) and global (`FFSDNIOGLB-`) rules applied to a port, applies all `DROP`/`REJECT` rules first, followed by `ALLOW` rules, and finally the default `DROP`. - +INCUS combines all local (`FFSDNIO-`) and global (`FFSDNIOGLB-`) rules applied to a port, applies all `DROP`/`REJECT` rules first, followed by `ALLOW` rules, and finally the default `DROP`. -- **For Networks with Default Action "Allow"**: + +- **For Networks with Default Action "Allow"**: -INCUS combines all local and global rules, applies all `ALLOW` rules first, followed by `DROP`/`REJECT` rules, and finally the default `ALLOW`. - - - - **Note:** Rule order matters within this framework. Ensure your `ALLOW` and `DROP`/`REJECT` rules are prioritized correctly based on the network's default action and check for global ACLs that might override local ones. - - +INCUS combines all local and global rules, applies all `ALLOW` rules first, followed by `DROP`/`REJECT` rules, and finally the default `ALLOW`. + + + + **Note:** Rule order matters within this framework. Ensure your `ALLOW` and `DROP`/`REJECT` rules are prioritized correctly based on the network's default action and check for global ACLs that might override local ones. + + ### Step 3: Add More Rules (Optional) - + -Click "Add another FW rule" to create additional local rules for this cluster. Repeat Step 2 for each new row. - +Click "Add another FW rule" to create additional local rules for this cluster. Repeat Step 2 for each new row. + -- **Minimum**: At least one valid rule is required. +- **Minimum**: At least one valid rule is required. -- **Delete**: Use the "Delete" button on a row to remove it (disabled if only one rule remains). - - +- **Delete**: Use the "Delete" button on a row to remove it (disabled if only one rule remains). + + ### Step 4: Review and Submit - + -Click "Review firewall rules" to validate and preview: - +Click "Review firewall rules" to validate and preview: + -- **Validation Check**: - +- **Validation Check**: + -- Rules: Each has valid `Direction`, `Protocol`, `Action`, non-empty `Source` and `Destination`, and optional `Port` and `Description` per rules above. - - +- Rules: Each has valid `Direction`, `Protocol`, `Action`, non-empty `Source` and `Destination`, and optional `Port` and `Description` per rules above. + -- **Review Dialog**: A popup shows each rule's details, including resolved instance tags (e.g., instance names and IPs within the cluster), allowing you to "Commit" or "Cancel". -- **Success**: After committing, redirects to the cluster management page with a confirmation message (e.g., "Firewall rule(s) created successfully"). +- **Review Dialog**: A popup shows each rule's details, including resolved instance tags (e.g., instance names and IPs within the cluster), allowing you to "Commit" or "Cancel". -- **Failure**: Displays an error (e.g., "Invalid source in rule 1: 256.1.2.3"). - - +- **Success**: After committing, redirects to the cluster management page with a confirmation message (e.g., "Firewall rule(s) created successfully"). + +- **Failure**: Displays an error (e.g., "Invalid source in rule 1: 256.1.2.3"). + + ### Example Firewall Rules - + -Below are examples of local and global ACLs to illustrate their differences and the use of metadata operators: - +Below are examples of local and global ACLs to illustrate their differences and the use of metadata operators: + -**Local ACL with exact match (for cluster `MyCluster`):** +**Local ACL with exact match (for cluster `MyCluster`):** ``` -`Rule 1: - Direction: Ingress/In - Source: 0.0.0.0/0 - Destination: role=webserver - Protocol: TCP - Port: 80,443 - Action: ALLOW +`Rule 1: + Direction: Ingress/In + Source: 0.0.0.0/0 + Destination: role=webserver + Protocol: TCP + Port: 80,443 + Action: ALLOW Description: Allow HTTP/HTTPS traffic to webservers in MyCluster` ``` - - + + -**Local ACL with "starts with" operator:** +**Local ACL with "starts with" operator:** ``` -`Rule 1: - Direction: Ingress/In - Source: app=^BANK - Destination: tier=^DB - Protocol: TCP - Port: 5432,3306 - Action: ALLOW +`Rule 1: + Direction: Ingress/In + Source: app=^BANK + Destination: tier=^DB + Protocol: TCP + Port: 5432,3306 + Action: ALLOW Description: Allow BANK* apps to connect to DB* tier instances` ``` - - + + -**Local ACL with "contains" operator:** +**Local ACL with "contains" operator:** ``` -`Rule 1: - Direction: Egress/Out - Source: env=*prod - Destination: 10.0.0.0/8 - Protocol: TCP - Port: 443 - Action: ALLOW +`Rule 1: + Direction: Egress/Out + Source: env=*prod + Destination: 10.0.0.0/8 + Protocol: TCP + Port: 443 + Action: ALLOW Description: Allow any production-related instances to reach internal network via HTTPS` ``` - - + + -**Complex ACL with multiple operators and AND/OR logic:** +**Complex ACL with multiple operators and AND/OR logic:** ``` -`Rule 1: - Direction: Ingress/In - Source: (env=prod AND zone=dmz) OR (app=^PUBLIC) - Destination: (role=api AND tier=^backend) - Protocol: TCP - Port: 8080,8443 - Action: ALLOW +`Rule 1: + Direction: Ingress/In + Source: (env=prod AND zone=dmz) OR (app=^PUBLIC) + Destination: (role=api AND tier=^backend) + Protocol: TCP + Port: 8080,8443 + Action: ALLOW Description: Allow DMZ prod instances and PUBLIC* apps to reach backend API servers` ``` - - + + -**Global ACL (applies to all clusters):** +**Global ACL (applies to all clusters):** ``` -`Rule 1: - Direction: Egress/Out - Source: env=*prod - Destination: 8.8.8.8,8.8.4.4 - Protocol: UDP - Port: 53 - Action: ALLOW +`Rule 1: + Direction: Egress/Out + Source: env=*prod + Destination: 8.8.8.8,8.8.4.4 + Protocol: UDP + Port: 53 + Action: ALLOW Description: Allow DNS queries to Google DNS from any production-related instances across all clusters` ``` - - + + ### Troubleshooting - - + + -- **Error: "Please fill out this field"**: Ensure `Source` and `Destination` are not empty (use `0.0.0.0/0` for ANY). +- **Error: "Please fill out this field"**: Ensure `Source` and `Destination` are not empty (use `0.0.0.0/0` for ANY). -- **Error: "Please select a value"**: Ensure `Direction`, `Protocol`, and `Action` are selected. +- **Error: "Please select a value"**: Ensure `Direction`, `Protocol`, and `Action` are selected. -- **Error: "Invalid port value"**: Check that ports are between 1-65535 and comma-separated (e.g., `80,443`, not `80 443`). +- **Error: "Invalid port value"**: Check that ports are between 1-65535 and comma-separated (e.g., `80,443`, not `80 443`). -- **Error: "Invalid source/destination"**: Verify each comma-separated part is a valid IPv4, CIDR, or instance tag syntax (e.g., `env=prod`). +- **Error: "Invalid source/destination"**: Verify each comma-separated part is a valid IPv4, CIDR, or instance tag syntax (e.g., `env=prod`). -- **Error: "Invalid condition format"**: Ensure instance tag conditions use valid operators (`=`, `=^`, or `=*`) and have non-empty values after the operator. +- **Error: "Invalid condition format"**: Ensure instance tag conditions use valid operators (`=`, `=^`, or `=*`) and have non-empty values after the operator. -- **Rules Not Applying as Expected**: - +- **Rules Not Applying as Expected**: + -- Check the network's default action (viewable in "Manage Cluster" under OVN networks) and adjust rule order. +- Check the network's default action (viewable in "Manage Cluster" under OVN networks) and adjust rule order. -- Verify global ACLs in the "Global ACLs" page, as they may override or conflict with local ACLs. +- Verify global ACLs in the "Global ACLs" page, as they may override or conflict with local ACLs. -- If using instance tags, ensure they resolve to IPs (visible in the review popup); empty IP resolutions result in the rule not being applied. +- If using instance tags, ensure they resolve to IPs (visible in the review popup); empty IP resolutions result in the rule not being applied. -- For `=^` (starts with) and `=*` (contains) operators, verify that your instance tag values actually match the pattern you specified. - - - - +- For `=^` (starts with) and `=*` (contains) operators, verify that your instance tag values actually match the pattern you specified. + + + + ### Quick Reference: Instance Tag Operator Syntax - + - + -| - Use Case | - Syntax | - Example | - +| + Use Case | + Syntax | + Example | -| - Match exact value | - `key=value` | - `env=prod` | - -| - Match values starting with prefix | - `key=^prefix` | - `app=^BANK` | - +| + Match exact value | + `key=value` | + `env=prod` | -| - Match values containing substring | - `key=*substring` | - `tier=*PROD` | - -| - AND - both conditions must match | - `(cond1 AND cond2)` | - `(env=prod AND role=db)` | - +| + Match values starting with prefix | + `key=^prefix` | + `app=^BANK` | -| - OR - either condition can match | - `(cond1 OR cond2)` | - `(env=prod OR env=staging)` | - -| - Complex nested conditions | - `((cond1 AND cond2) OR cond3)` | - `((env=prod AND role=web) OR app=^PUBLIC)` | - +| + Match values containing substring | + `key=*substring` | + `tier=*PROD` | + + +| + AND - both conditions must match | + `(cond1 AND cond2)` | + `(env=prod AND role=db)` | + + +| + OR - either condition can match | + `(cond1 OR cond2)` | + `(env=prod OR env=staging)` | + + +| + Complex nested conditions | + `((cond1 AND cond2) OR cond3)` | + `((env=prod AND role=web) OR app=^PUBLIC)` | + + + + - - - **Note:** Instance tag formulas (e.g., `role=webserver`) match instance tags set in INCUS (e.g., via `incus config set user.role webserver`). The system handles the `user.` prefix internally. For global ACLs, instance tags apply across all clusters, so ensure consistency in tag naming. @@ -13067,2485 +13067,2485 @@ Below are examples of local and global ACLs to illustrate their differences and *Source: `/static/OVNHAproxyLB.html`* -HAProxy Load Balancer Management Guide - AETHER - - - - +HAProxy Load Balancer Management Guide - AETHER + + + + ## HAProxy Load Balancer Management Guide - + -This guide explains how to use the HAProxy Load Balancer Management page in AETHER. HAProxy provides high-availability load balancing for your applications running on INCUS clusters with OVN networking. - - +This guide explains how to use the HAProxy Load Balancer Management page in AETHER. HAProxy provides high-availability load balancing for your applications running on INCUS clusters with OVN networking. + + #### Table of Contents - - + + -- 1. Overview and Architecture +- 1. Overview and Architecture -- 2. Prerequisites +- 2. Prerequisites -- 3. Accessing the HAProxy Management Page +- 3. Accessing the HAProxy Management Page -- 4. Managing HAProxy Base Images - +- 4. Managing HAProxy Base Images + -- 4.1 Building a New Image +- 4.1 Building a New Image -- 4.2 Pushing Images to Clusters +- 4.2 Pushing Images to Clusters -- 4.3 Managing Image Versions - - +- 4.3 Managing Image Versions + -- 5. Deploying HAProxy Infrastructure - - -- 5.1 Deployment Process - -- 5.2 Deployment Fields Explained - -- 5.3 Deleting Infrastructure - - -- 6. Managing VIP Addresses - +- 5. Deploying HAProxy Infrastructure + -- 6.1 Adding a VIP +- 5.1 Deployment Process -- 6.2 Deleting a VIP - - +- 5.2 Deployment Fields Explained + +- 5.3 Deleting Infrastructure + -- 7. Configuring Services - + +- 6. Managing VIP Addresses + -- 7.1 Creating a Service +- 6.1 Adding a VIP -- 7.2 Service Fields Explained +- 6.2 Deleting a VIP + + + +- 7. Configuring Services + -- 7.3 Understanding Service Modes +- 7.1 Creating a Service -- 7.4 Load Balancing Methods +- 7.2 Service Fields Explained -- 7.5 Health Checks +- 7.3 Understanding Service Modes -- 7.6 Sticky Sessions +- 7.4 Load Balancing Methods -- 7.7 Configuring Backend Servers +- 7.5 Health Checks -- 7.8 Editing a Service +- 7.6 Sticky Sessions -- 7.9 Deleting a Service +- 7.7 Configuring Backend Servers -- 7.10 Monitoring Service Health and Statistics +- 7.8 Editing a Service -- 7.11 Advanced Options - +- 7.9 Deleting a Service + +- 7.10 Monitoring Service Health and Statistics + +- 7.11 Advanced Options + -- 7.11.1 Security Options +- 7.11.1 Security Options -- 7.11.2 Performance Options +- 7.11.2 Performance Options -- 7.11.3 Rate Limiting +- 7.11.3 Rate Limiting -- 7.11.4 Access Control - - - - +- 7.11.4 Access Control + + + -- 8. Example Configurations -- 9. Troubleshooting +- 8. Example Configurations -- 10. Glossary - - - +- 9. Troubleshooting + +- 10. Glossary + + + ### 1. Overview and Architecture - + + + +The AETHER HAProxy Load Balancer provides enterprise-grade load balancing for applications running on INCUS clusters. It automatically deploys and manages a highly available HAProxy setup with the following architecture: + + + Internet / Client Traffic + | + v + +-------------------------+ + | OVN Load Balancer | + | (Virtual IP - VIP) | + +-------------------------+ + / \ + / \ + v v + +----------------+ +----------------+ + | HAProxy 01 | | HAProxy 02 | + | (Instance 1) | | (Instance 2) | + +----------------+ +----------------+ + \ / + \ / + v v + +-------+ +-------+ +-------+ + |Backend| |Backend| |Backend| + | 1 | | 2 | | 3 | + +-------+ +-------+ +-------+ -The AETHER HAProxy Load Balancer provides enterprise-grade load balancing for applications running on INCUS clusters. It automatically deploys and manages a highly available HAProxy setup with the following architecture: - - - Internet / Client Traffic - | - v - +-------------------------+ - | OVN Load Balancer | - | (Virtual IP - VIP) | - +-------------------------+ - / \ - / \ - v v - +----------------+ +----------------+ - | HAProxy 01 | | HAProxy 02 | - | (Instance 1) | | (Instance 2) | - +----------------+ +----------------+ - \ / - \ / - v v - +-------+ +-------+ +-------+ - |Backend| |Backend| |Backend| - | 1 | | 2 | | 3 | - +-------+ +-------+ +-------+ - - #### Key Components: - - + + -- **OVN Load Balancer (VIP)**: The entry point for all traffic. The Virtual IP (VIP) is the address clients connect to. OVN distributes traffic between the two HAProxy instances for high availability. +- **OVN Load Balancer (VIP)**: The entry point for all traffic. The Virtual IP (VIP) is the address clients connect to. OVN distributes traffic between the two HAProxy instances for high availability. -- **HAProxy Instances**: Two identical HAProxy containers (01 and 02) run on your cluster. If one fails, the other continues serving traffic seamlessly. +- **HAProxy Instances**: Two identical HAProxy containers (01 and 02) run on your cluster. If one fails, the other continues serving traffic seamlessly. -- **Backend Servers**: Your actual application servers that HAProxy forwards traffic to based on your configured rules. - - - - **Note:** Each INCUS cluster can have one HAProxy infrastructure deployment. Multiple services can share this infrastructure using different VIPs and ports. - - +- **Backend Servers**: Your actual application servers that HAProxy forwards traffic to based on your configured rules. + + + + **Note:** Each INCUS cluster can have one HAProxy infrastructure deployment. Multiple services can share this infrastructure using different VIPs and ports. + + ### 2. Prerequisites - + -Before you can use the HAProxy Load Balancer functionality, ensure the following: - +Before you can use the HAProxy Load Balancer functionality, ensure the following: + #### Permissions Required - - + + -- **AETHER Full Admin** or **AETHER LB Admin** role is required to: - +- **AETHER Full Admin** or **AETHER LB Admin** role is required to: + -- Build and manage HAProxy base images +- Build and manage HAProxy base images -- Deploy or delete HAProxy infrastructure +- Deploy or delete HAProxy infrastructure -- Add or delete VIPs +- Add or delete VIPs -- Create, edit, or delete services - - - - +- Create, edit, or delete services + + + + #### Technical Requirements - - + + -- An INCUS cluster must be registered in AETHER +- An INCUS cluster must be registered in AETHER -- The cluster must have at least one OVN network configured +- The cluster must have at least one OVN network configured -- Internet access from the cluster is required to build HAProxy images (for package downloads) +- Internet access from the cluster is required to build HAProxy images (for package downloads) -- Available IP addresses on the OVN network for the HAProxy instances and VIP(s) - - +- Available IP addresses on the OVN network for the HAProxy instances and VIP(s) + + ### 3. Accessing the HAProxy Management Page - + -To access the HAProxy Load Balancer management page: - +To access the HAProxy Load Balancer management page: + -- Log in to the AETHER web interface +- Log in to the AETHER web interface -- Navigate to **"HAProxy"** in the main navigation menu +- Navigate to **"HAProxy"** in the main navigation menu -- The page displays: - +- The page displays: + -- **HAProxy Base Images** section (admin only) - for managing HAProxy container images +- **HAProxy Base Images** section (admin only) - for managing HAProxy container images -- **Select Cluster to manage LB** dropdown - to choose which cluster to configure +- **Select Cluster to manage LB** dropdown - to choose which cluster to configure -- **Infrastructure, VIPs, and Services** sections - appear after selecting a cluster with deployed infrastructure - - - - +- **Infrastructure, VIPs, and Services** sections - appear after selecting a cluster with deployed infrastructure + + + + ### 4. Managing HAProxy Base Images - + -Before deploying HAProxy infrastructure, you need a HAProxy base image available on your target cluster. The base image is a pre-configured container image with HAProxy installed. - +Before deploying HAProxy infrastructure, you need a HAProxy base image available on your target cluster. The base image is a pre-configured container image with HAProxy installed. + #### 4.1 Building a New Image - + -To build a new HAProxy base image: - +To build a new HAProxy base image: + -- Click the **"Build New Image"** button in the HAProxy Base Images section +- Click the **"Build New Image"** button in the HAProxy Base Images section -- Select the **Build on Cluster** - choose any cluster with internet access +- Select the **Build on Cluster** - choose any cluster with internet access -- Enter a **Version** number (e.g., "1.0.0", "2.1.0") +- Enter a **Version** number (e.g., "1.0.0", "2.1.0") -- Click **"Build Image"** - - - - **Warning:** The build process takes 5-10 minutes as it downloads and installs packages. Do not close the browser during this process. The build progress is displayed in real-time. - - +- Click **"Build Image"** -The build process: - + + **Warning:** The build process takes 5-10 minutes as it downloads and installs packages. Do not close the browser during this process. The build progress is displayed in real-time. + + + + +The build process: + -- Creates a temporary container on the selected cluster +- Creates a temporary container on the selected cluster -- Installs HAProxy and required packages +- Installs HAProxy and required packages -- Configures the base HAProxy settings +- Configures the base HAProxy settings -- Creates an image from the container +- Creates an image from the container -- Stores the image in the AETHER database +- Stores the image in the AETHER database -- Cleans up the temporary container - - +- Cleans up the temporary container + + #### 4.2 Pushing Images to Clusters - + -After building an image, you must push it to each cluster where you want to deploy HAProxy infrastructure: - +After building an image, you must push it to each cluster where you want to deploy HAProxy infrastructure: + -- In the images table, find the version you want to push +- In the images table, find the version you want to push -- Click **"Push to Cluster"** +- Click **"Push to Cluster"** -- Select the **Target Cluster** from the dropdown +- Select the **Target Cluster** from the dropdown -- Click **"Push Image"** - - - - **Note:** An image must be pushed to a cluster before you can deploy HAProxy infrastructure on that cluster. The cluster selection dropdown will indicate "(No Image)" for clusters without the HAProxy image. - - +- Click **"Push Image"** + + + + **Note:** An image must be pushed to a cluster before you can deploy HAProxy infrastructure on that cluster. The cluster selection dropdown will indicate "(No Image)" for clusters without the HAProxy image. + + #### 4.3 Managing Image Versions - + -The images table shows all available HAProxy images with the following actions: - +The images table shows all available HAProxy images with the following actions: + - + -| - Action | - Description | - +| + Action | + Description | -| - **Set Current** | - Marks this version as the default for new deployments. Only one version can be "Current" at a time. | - -| - **Push to Cluster** | - Copies the image to a specific cluster's image store. | - +| + **Set Current** | + Marks this version as the default for new deployments. Only one version can be "Current" at a time. | + + +| + **Push to Cluster** | + Copies the image to a specific cluster's image store. | + + +| + **Delete** | + Removes the image from the AETHER database. Does not affect already-deployed HAProxy instances. | -| - **Delete** | - Removes the image from the AETHER database. Does not affect already-deployed HAProxy instances. | - - - + + ### 5. Deploying HAProxy Infrastructure - + -HAProxy infrastructure consists of two HAProxy container instances and an OVN load balancer that provides failover between them. - +HAProxy infrastructure consists of two HAProxy container instances and an OVN load balancer that provides failover between them. + #### 5.1 Deployment Process - - + + -- Select a cluster from the **"Select Cluster to manage LB"** dropdown +- Select a cluster from the **"Select Cluster to manage LB"** dropdown -- If no infrastructure exists, you'll see a message with a **"Deploy HAProxy Infrastructure"** button +- If no infrastructure exists, you'll see a message with a **"Deploy HAProxy Infrastructure"** button -- Click the button to open the deployment form +- Click the button to open the deployment form -- Fill in all required fields (explained below) +- Fill in all required fields (explained below) + +- Click **"Deploy"** + + + + **What happens during deployment:** -- Click **"Deploy"** - - - - **What happens during deployment:** - -- Two HAProxy container instances are created (ffsdn-haproxy-[clusterID]-01 and -02) +- Two HAProxy container instances are created (ffsdn-haproxy-[clusterID]-01 and -02) -- Both instances are started and configured with a base HAProxy configuration +- Both instances are started and configured with a base HAProxy configuration -- An OVN load balancer is created to distribute traffic to both instances +- An OVN load balancer is created to distribute traffic to both instances -- Firewall rules are automatically configured to allow traffic +- Firewall rules are automatically configured to allow traffic -- A default VIP is created for your services - - - +- A default VIP is created for your services + + + #### 5.2 Deployment Fields Explained - - + + ##### OVN Network - - + + -Select the OVN network where the HAProxy instances will be deployed. This should be a network that: - +Select the OVN network where the HAProxy instances will be deployed. This should be a network that: + -- Has connectivity to your backend servers +- Has connectivity to your backend servers -- Has available IP addresses for the HAProxy instances and VIP(s) +- Has available IP addresses for the HAProxy instances and VIP(s) -- Is accessible from where your clients will connect - +- Is accessible from where your clients will connect + -**Example:** `ovn-production`, `ovn-dmz` - - +**Example:** `ovn-production`, `ovn-dmz` + + ##### Load Balancer VIP - - + + -The Virtual IP address that clients will connect to. This IP is managed by the OVN load balancer and routes traffic to the HAProxy instances. - +The Virtual IP address that clients will connect to. This IP is managed by the OVN load balancer and routes traffic to the HAProxy instances. + -- Select an available IP from the **dropdown menu** +- Select an available IP from the **dropdown menu** -- The dropdown shows unused IP addresses from the configured VIP range on the selected OVN network +- The dropdown shows unused IP addresses from the configured VIP range on the selected OVN network -- This becomes the "front door" for your load-balanced services - - - **Note:** The available IPs are automatically detected from the OVN network's VIP range configuration. No manual IP entry is required. - - - +- This becomes the "front door" for your load-balanced services + + + **Note:** The available IPs are automatically detected from the OVN network's VIP range configuration. No manual IP entry is required. + + + ##### HAProxy 01 IP and HAProxy 02 IP - - + + -The IP addresses assigned to each HAProxy container instance. These are internal addresses used by the OVN load balancer. - +The IP addresses assigned to each HAProxy container instance. These are internal addresses used by the OVN load balancer. + -- Select available IPs from the **dropdown menus** +- Select available IPs from the **dropdown menus** -- The dropdowns show unused IP addresses from the selected OVN network +- The dropdowns show unused IP addresses from the selected OVN network -- Each HAProxy instance must have a unique IP address +- Each HAProxy instance must have a unique IP address -- Both IPs should be different from the VIP address - - - **Note:** Available IPs are automatically detected from the OVN network. Simply select different IPs for each HAProxy instance from the dropdown menus. - - - +- Both IPs should be different from the VIP address + + + **Note:** Available IPs are automatically detected from the OVN network. Simply select different IPs for each HAProxy instance from the dropdown menus. + + + ##### CPU Limit - - + + -The number of CPU cores allocated to each HAProxy instance. - +The number of CPU cores allocated to each HAProxy instance. + -- Default: `2` +- Default: `2` -- For high-traffic environments, consider increasing this value +- For high-traffic environments, consider increasing this value -- HAProxy is very CPU-efficient; 2 cores handle most workloads - - - +- HAProxy is very CPU-efficient; 2 cores handle most workloads + + + ##### Memory Limit - - + + -The amount of RAM allocated to each HAProxy instance. - +The amount of RAM allocated to each HAProxy instance. + -- Default: `1GB` +- Default: `1GB` -- For environments with many concurrent connections, consider `2GB` or more +- For environments with many concurrent connections, consider `2GB` or more -- Format: Use suffix like `512MB`, `1GB`, `2GB` - - - +- Format: Use suffix like `512MB`, `1GB`, `2GB` + + + #### 5.3 Deleting Infrastructure - + -To completely remove HAProxy infrastructure from a cluster: - +To completely remove HAProxy infrastructure from a cluster: + -- Select the cluster from the dropdown +- Select the cluster from the dropdown -- Click the **"Delete Infrastructure"** button (red) +- Click the **"Delete Infrastructure"** button (red) + +- Confirm the deletion in the popup dialog + + + + **Warning:** Deleting infrastructure will: -- Confirm the deletion in the popup dialog - - - - **Warning:** Deleting infrastructure will: - -- Stop and delete both HAProxy container instances +- Stop and delete both HAProxy container instances -- Remove all VIPs and their OVN load balancers +- Remove all VIPs and their OVN load balancers -- Delete all configured services +- Delete all configured services -- Remove associated firewall rules - +- Remove associated firewall rules + -This action cannot be undone. All traffic to your services will be interrupted immediately. - - +This action cannot be undone. All traffic to your services will be interrupted immediately. + + ### 6. Managing VIP Addresses - + -A VIP (Virtual IP) is the address that clients connect to. You can have multiple VIPs on a single HAProxy infrastructure, allowing you to serve different applications or environments. - +A VIP (Virtual IP) is the address that clients connect to. You can have multiple VIPs on a single HAProxy infrastructure, allowing you to serve different applications or environments. + #### 6.1 Adding a VIP - + -After deploying infrastructure, you can add additional VIPs: - +After deploying infrastructure, you can add additional VIPs: + -- In the **VIP Addresses** section, click **"+ Add VIP"** +- In the **VIP Addresses** section, click **"+ Add VIP"** -- Enter a **VIP Name** - a descriptive name (e.g., "Production HTTPS", "API Gateway") +- Enter a **VIP Name** - a descriptive name (e.g., "Production HTTPS", "API Gateway") -- Enter the **IP Address** - must be unused on the OVN network +- Enter the **IP Address** - must be unused on the OVN network + +- Click **"Add VIP"** + + + + **When to use multiple VIPs:** -- Click **"Add VIP"** - - - - **When to use multiple VIPs:** - -- Separating production and staging traffic +- Separating production and staging traffic -- Different external IP addresses for different applications +- Different external IP addresses for different applications -- Isolating traffic for security or compliance reasons +- Isolating traffic for security or compliance reasons -- Different SSL certificates for different domains - - - +- Different SSL certificates for different domains + + + #### 6.2 Deleting a VIP - - + + -- Find the VIP in the **VIP Addresses** table +- Find the VIP in the **VIP Addresses** table -- Click the **"Delete"** button +- Click the **"Delete"** button -- Confirm the deletion - - - - **Warning:** Deleting a VIP will also delete all services associated with that VIP. Ensure you have migrated or backed up any important configurations first. - - +- Confirm the deletion + + + + **Warning:** Deleting a VIP will also delete all services associated with that VIP. Ensure you have migrated or backed up any important configurations first. + + ### 7. Configuring Services - + -Services define how traffic is handled by HAProxy. Each service listens on a specific VIP and port combination and forwards traffic to one or more backend servers. - +Services define how traffic is handled by HAProxy. Each service listens on a specific VIP and port combination and forwards traffic to one or more backend servers. + #### 7.1 Creating a Service - - + + -- In the **Services** section, click **"+ Add Service"** +- In the **Services** section, click **"+ Add Service"** -- Fill in the service configuration (explained in detail below) +- Fill in the service configuration (explained in detail below) -- Add at least one backend server +- Add at least one backend server -- Click **"Create Service"** - - +- Click **"Create Service"** + + #### 7.2 Service Fields Explained - - + + ##### Service Name - - + + -A unique, descriptive name for the service. This appears in the HAProxy configuration and logs. - +A unique, descriptive name for the service. This appears in the HAProxy configuration and logs. + -- Use lowercase letters, numbers, and hyphens +- Use lowercase letters, numbers, and hyphens -- Should be descriptive of what the service does +- Should be descriptive of what the service does -- Must be unique within the infrastructure - +- Must be unique within the infrastructure + -**Examples:** `customer-web`, `api-gateway`, `internal-db-proxy` - - +**Examples:** `customer-web`, `api-gateway`, `internal-db-proxy` + + ##### Description - - + + -Optional free-text description of the service's purpose. Helpful for documentation and team communication. +Optional free-text description of the service's purpose. Helpful for documentation and team communication. -**Example:** "Main customer-facing website load balancer" - - +**Example:** "Main customer-facing website load balancer" + + ##### VIP - - + + -Select which VIP this service should listen on. The dropdown shows all VIPs configured for this infrastructure. +Select which VIP this service should listen on. The dropdown shows all VIPs configured for this infrastructure. -Multiple services can share the same VIP if they use different ports or hostnames. - - +Multiple services can share the same VIP if they use different ports or hostnames. + + ##### Listen Port - - + + -The TCP port that HAProxy will listen on for this service. - +The TCP port that HAProxy will listen on for this service. + -- Common ports: 80 (HTTP), 443 (HTTPS), 8080, 8443 +- Common ports: 80 (HTTP), 443 (HTTPS), 8080, 8443 -- Must be unique per VIP (unless using hostname-based routing) +- Must be unique per VIP (unless using hostname-based routing) -- Range: 1-65535 (ports below 1024 are typically reserved) - +- Range: 1-65535 (ports below 1024 are typically reserved) + -**Examples:** `443`, `8080`, `3306` - - +**Examples:** `443`, `8080`, `3306` + + ##### Hostname (SNI/Host header) - - + + -Optional hostname for routing traffic based on the requested domain name. This enables multiple services to share the same VIP and port. - +Optional hostname for routing traffic based on the requested domain name. This enables multiple services to share the same VIP and port. + -- For HTTPS Passthrough mode: Routes based on SNI (Server Name Indication) +- For HTTPS Passthrough mode: Routes based on SNI (Server Name Indication) -- For HTTP mode: Routes based on the Host header +- For HTTP mode: Routes based on the Host header -- Leave empty if not using hostname-based routing - +- Leave empty if not using hostname-based routing + -**Examples:** `www.example.com`, `api.example.com`, `*.example.com` - - +**Examples:** `www.example.com`, `api.example.com`, `*.example.com` + + #### 7.3 Understanding Service Modes - + -The **Mode** determines how HAProxy processes traffic. Choose the appropriate mode based on your application's requirements: - +The **Mode** determines how HAProxy processes traffic. Choose the appropriate mode based on your application's requirements: + - + -| - Mode | - Layer | - Use Case | - SSL/TLS Handling | - +| + Mode | + Layer | + Use Case | + SSL/TLS Handling | -| - **TCP (Layer 4)** | - Transport | - Database connections, generic TCP services, any non-HTTP protocol | - Passed through unchanged | - -| - **HTTP** | - Application | - Plain HTTP websites, internal APIs without encryption | - Not applicable (no SSL) | - +| + **TCP (Layer 4)** | + Transport | + Database connections, generic TCP services, any non-HTTP protocol | + Passed through unchanged | -| - **HTTPS Passthrough (SNI routing)** | - Transport | - HTTPS where backend servers handle SSL termination | - Passed through to backend (HAProxy reads SNI only) | - -| - **HTTPS Termination** | - Application | - HTTPS where HAProxy handles SSL certificates | - Terminated at HAProxy (requires certificate upload) | - +| + **HTTP** | + Application | + Plain HTTP websites, internal APIs without encryption | + Not applicable (no SSL) | + + +| + **HTTPS Passthrough (SNI routing)** | + Transport | + HTTPS where backend servers handle SSL termination | + Passed through to backend (HAProxy reads SNI only) | + + +| + **HTTPS Termination** | + Application | + HTTPS where HAProxy handles SSL certificates | + Terminated at HAProxy (requires certificate upload) | + - - + + ##### TCP (Layer 4) - Detailed Explanation - - + + -In TCP mode, HAProxy operates at the transport layer and forwards raw TCP connections without inspecting the content. +In TCP mode, HAProxy operates at the transport layer and forwards raw TCP connections without inspecting the content. -**Best for:** - +**Best for:** + -- Database load balancing (MySQL, PostgreSQL, MongoDB) +- Database load balancing (MySQL, PostgreSQL, MongoDB) -- Message queues (RabbitMQ, Kafka) +- Message queues (RabbitMQ, Kafka) -- Custom TCP protocols +- Custom TCP protocols -- Any application where HAProxy shouldn't modify the traffic - +- Any application where HAProxy shouldn't modify the traffic + -**Limitations:** Cannot route based on HTTP headers or URLs. - - +**Limitations:** Cannot route based on HTTP headers or URLs. + + ##### HTTP - Detailed Explanation - - + + -In HTTP mode, HAProxy understands HTTP protocol and can make routing decisions based on headers, URLs, and cookies. +In HTTP mode, HAProxy understands HTTP protocol and can make routing decisions based on headers, URLs, and cookies. -**Best for:** - +**Best for:** + -- Internal HTTP APIs +- Internal HTTP APIs -- Development/testing environments +- Development/testing environments -- Services behind a separate SSL termination point - +- Services behind a separate SSL termination point + -**Features available:** URL-based routing, header manipulation, cookie-based persistence. - - +**Features available:** URL-based routing, header manipulation, cookie-based persistence. + + ##### HTTPS Passthrough (SNI Routing) - Detailed Explanation - - + + -HAProxy reads the SNI (Server Name Indication) from the TLS handshake to route traffic, but does not decrypt it. The SSL/TLS connection is passed through to the backend server. +HAProxy reads the SNI (Server Name Indication) from the TLS handshake to route traffic, but does not decrypt it. The SSL/TLS connection is passed through to the backend server. -**Best for:** - +**Best for:** + -- When backend servers must handle their own SSL certificates +- When backend servers must handle their own SSL certificates -- End-to-end encryption requirements +- End-to-end encryption requirements -- Multiple HTTPS sites on the same IP/port with different certificates - +- Multiple HTTPS sites on the same IP/port with different certificates + -**How it works:** When a client connects, HAProxy reads the hostname from the SNI extension (sent in cleartext during TLS handshake), routes to the appropriate backend, and the backend completes the TLS handshake. - - +**How it works:** When a client connects, HAProxy reads the hostname from the SNI extension (sent in cleartext during TLS handshake), routes to the appropriate backend, and the backend completes the TLS handshake. + + ##### HTTPS Termination - Detailed Explanation - - + + -HAProxy terminates the SSL/TLS connection, decrypts the traffic, and can then forward it as HTTP or re-encrypt it to backends. +HAProxy terminates the SSL/TLS connection, decrypts the traffic, and can then forward it as HTTP or re-encrypt it to backends. -**Best for:** - +**Best for:** + -- Centralized certificate management +- Centralized certificate management -- When you need to inspect or modify HTTPS traffic +- When you need to inspect or modify HTTPS traffic -- Offloading SSL processing from backend servers - +- Offloading SSL processing from backend servers + -**Requires:** SSL certificate and private key to be uploaded when creating the service. - - +**Requires:** SSL certificate and private key to be uploaded when creating the service. + + #### 7.4 Load Balancing Methods - + -The **Balance Method** determines how HAProxy distributes requests among backend servers: - +The **Balance Method** determines how HAProxy distributes requests among backend servers: + - + -| - Method | - Algorithm | - Best For | - +| + Method | + Algorithm | + Best For | -| - **Round Robin** | - Distributes requests sequentially to each backend in turn | - General purpose, when all backends have similar capacity | - -| - **Least Connections** | - Sends new requests to the backend with fewest active connections | - Long-lived connections, varying request complexity | - +| + **Round Robin** | + Distributes requests sequentially to each backend in turn | + General purpose, when all backends have similar capacity | -| - **Source IP Hash** | - Routes requests from the same client IP to the same backend | - Simple session affinity without cookies | - -| - **First Available** | - Uses the first backend with available connection slots | - Minimizing the number of active backends | - +| + **Least Connections** | + Sends new requests to the backend with fewest active connections | + Long-lived connections, varying request complexity | + + +| + **Source IP Hash** | + Routes requests from the same client IP to the same backend | + Simple session affinity without cookies | + + +| + **First Available** | + Uses the first backend with available connection slots | + Minimizing the number of active backends | + - - + + ##### Round Robin - When to Use - - + + -The default and most common method. Each backend receives requests in sequence. - +The default and most common method. Each backend receives requests in sequence. + -- Ideal when all backend servers have equal capacity +- Ideal when all backend servers have equal capacity -- Works well for stateless applications +- Works well for stateless applications -- Simple and predictable distribution - +- Simple and predictable distribution + -**Example:** 3 backends receive requests in order: 1, 2, 3, 1, 2, 3, ... - - +**Example:** 3 backends receive requests in order: 1, 2, 3, 1, 2, 3, ... + + ##### Least Connections - When to Use - - + + -Dynamically routes to the backend handling the fewest requests. - +Dynamically routes to the backend handling the fewest requests. + -- Best for requests with varying processing times +- Best for requests with varying processing times -- Prevents overloading slower backends +- Prevents overloading slower backends -- Ideal for WebSocket or long-polling connections - +- Ideal for WebSocket or long-polling connections + -**Example:** If Backend 1 has 10 connections and Backend 2 has 5, new requests go to Backend 2. - - +**Example:** If Backend 1 has 10 connections and Backend 2 has 5, new requests go to Backend 2. + + ##### Source IP Hash - When to Use - - + + -Creates a hash of the client's IP address to consistently route them to the same backend. - +Creates a hash of the client's IP address to consistently route them to the same backend. + -- Provides session persistence without cookies +- Provides session persistence without cookies -- Useful when you can't use application-level session management +- Useful when you can't use application-level session management -- Note: Adding/removing backends will redistribute some clients - +- Note: Adding/removing backends will redistribute some clients + -**Example:** Client 192.168.1.100 always goes to Backend 2 (based on hash). - - +**Example:** Client 192.168.1.100 always goes to Backend 2 (based on hash). + + ##### First Available - When to Use - - + + -Fills the first backend to capacity before using the next one. - +Fills the first backend to capacity before using the next one. + -- Useful for minimizing resource usage +- Useful for minimizing resource usage -- Allows backends to be powered down when not needed +- Allows backends to be powered down when not needed -- Not recommended for even load distribution - - - +- Not recommended for even load distribution + + + #### 7.5 Health Checks - + -When **Health Check** is enabled, HAProxy periodically verifies that backend servers are healthy and removes unhealthy ones from rotation. - - - **Recommendation:** Always enable health checks in production environments. This ensures traffic is only sent to working backends. - - +When **Health Check** is enabled, HAProxy periodically verifies that backend servers are healthy and removes unhealthy ones from rotation. + + + **Recommendation:** Always enable health checks in production environments. This ensures traffic is only sent to working backends. -Health check behavior: - + + +Health check behavior: + -- HAProxy sends periodic probes to each backend (default: every 5 seconds) +- HAProxy sends periodic probes to each backend (default: every 5 seconds) -- For TCP mode: Verifies the port accepts connections +- For TCP mode: Verifies the port accepts connections -- For HTTP/HTTPS modes: Can verify specific paths return expected responses +- For HTTP/HTTPS modes: Can verify specific paths return expected responses -- Unhealthy backends are temporarily removed from rotation +- Unhealthy backends are temporarily removed from rotation -- Backends are automatically re-added when they recover - - +- Backends are automatically re-added when they recover + + #### 7.6 Sticky Sessions (Session Persistence) - + -When **Sticky Sessions** is enabled, HAProxy ensures that requests from the same client are sent to the same backend server. - - - - -| - Feature | - Description | - - -| - **How it works** | - HAProxy inserts a cookie into the response that identifies the backend server | - - -| - **Cookie name** | - SERVERID (automatically managed) | - - -| - **Duration** | - Session-based (expires when browser closes) or configurable | - - - - +When **Sticky Sessions** is enabled, HAProxy ensures that requests from the same client are sent to the same backend server. + -**When to use sticky sessions:** - -- Applications that store session data locally (not in shared storage) +| + Feature | + Description | -- Shopping carts, login sessions, multi-step forms -- When backend affinity improves cache hit rates - - - - **Warning:** Sticky sessions can lead to uneven load distribution if some clients generate more traffic than others. Consider using shared session storage (Redis, database) instead when possible. - - +| + **How it works** | + HAProxy inserts a cookie into the response that identifies the backend server | + + +| + **Cookie name** | + SERVERID (automatically managed) | + + +| + **Duration** | + Session-based (expires when browser closes) or configurable | + + + + + + +**When to use sticky sessions:** + + +- Applications that store session data locally (not in shared storage) + +- Shopping carts, login sessions, multi-step forms + +- When backend affinity improves cache hit rates + + + + **Warning:** Sticky sessions can lead to uneven load distribution if some clients generate more traffic than others. Consider using shared session storage (Redis, database) instead when possible. + + #### 7.7 Configuring Backend Servers - + -Backend servers are the actual application servers that receive traffic from HAProxy. Each service must have at least one backend. - +Backend servers are the actual application servers that receive traffic from HAProxy. Each service must have at least one backend. + ##### Backend Fields: - - + + - + -| - Field | - Description | - Example | - +| + Field | + Description | + Example | -| - **Backend Name** | - Unique identifier for this backend within the service. Used in logs and statistics. | - `web-server-1`, `api-node-a` | - -| - **IP Address** | - The IP address of the backend server. Must be reachable from the HAProxy instances. | - `10.50.1.100` | - +| + **Backend Name** | + Unique identifier for this backend within the service. Used in logs and statistics. | + `web-server-1`, `api-node-a` | -| - **Port** | - The port on the backend server where the application listens. | - `8080`, `3000`, `443` | - -| - **Weight** | - Relative weight for load distribution. Higher weight = more traffic. Default: 100. | - `100` (normal), `200` (double traffic), `50` (half traffic) | - +| + **IP Address** | + The IP address of the backend server. Must be reachable from the HAProxy instances. | + `10.50.1.100` | + + +| + **Port** | + The port on the backend server where the application listens. | + `8080`, `3000`, `443` | + + +| + **Weight** | + Relative weight for load distribution. Higher weight = more traffic. Default: 100. | + `100` (normal), `200` (double traffic), `50` (half traffic) | + - - + + ##### Adding Multiple Backends - - + + -- Click **"+ Add Backend Server"** to add another backend row +- Click **"+ Add Backend Server"** to add another backend row -- Fill in the backend details +- Fill in the backend details -- Repeat for each backend server +- Repeat for each backend server -- Use the **"x"** button to remove a backend row - - +- Use the **"x"** button to remove a backend row + + ##### Weight Examples - - + + -Weights are relative, not absolute percentages: - +Weights are relative, not absolute percentages: + -- **Equal distribution:** All backends with weight 100 +- **Equal distribution:** All backends with weight 100 -- **2:1 ratio:** Backend A: 200, Backend B: 100 (A gets twice the traffic) +- **2:1 ratio:** Backend A: 200, Backend B: 100 (A gets twice the traffic) -- **Gradual rollout:** Old server: 90, New server: 10 (10% to new server) +- **Gradual rollout:** Old server: 90, New server: 10 (10% to new server) -- **Drain server:** Set weight to 0 (no new connections, existing ones continue) - - - +- **Drain server:** Set weight to 0 (no new connections, existing ones continue) + + + #### 7.8 Editing a Service - - + + -- Find the service card in the **Services** section +- Find the service card in the **Services** section -- Click the **"Edit"** button +- Click the **"Edit"** button -- Modify the desired fields +- Modify the desired fields -- Add, remove, or modify backend servers as needed +- Add, remove, or modify backend servers as needed -- Click **"Save Changes"** - - - - **Note:** The VIP cannot be changed when editing a service. To move a service to a different VIP, delete it and create a new one. - - +- Click **"Save Changes"** + + + + **Note:** The VIP cannot be changed when editing a service. To move a service to a different VIP, delete it and create a new one. + + #### 7.9 Deleting a Service - - + + -- Find the service card in the **Services** section +- Find the service card in the **Services** section -- Click the **"Delete"** button (red) +- Click the **"Delete"** button (red) -- Confirm the deletion in the popup dialog - - - - **Warning:** Deleting a service immediately stops traffic routing. Ensure you have communicated the change to affected users/systems. - - +- Confirm the deletion in the popup dialog + + + + **Warning:** Deleting a service immediately stops traffic routing. Ensure you have communicated the change to affected users/systems. + + #### 7.10 Monitoring Service Health and Statistics - + -Each service has a **"Health & Stats"** button that opens a detailed monitoring popup. This provides real-time visibility into service health, traffic statistics, and HAProxy node resource usage. - +Each service has a **"Health & Stats"** button that opens a detailed monitoring popup. This provides real-time visibility into service health, traffic statistics, and HAProxy node resource usage. + ##### Accessing the Health & Stats Modal - - + + -- Find the service card in the **Services** section +- Find the service card in the **Services** section -- Click the **"Health & Stats"** button +- Click the **"Health & Stats"** button -- The modal displays four sections of information (described below) +- The modal displays four sections of information (described below) -- Click **"Refresh"** to update the data, or **"Close"** to exit - - +- Click **"Refresh"** to update the data, or **"Close"** to exit + + ##### Section 1: HAProxy Backend Server Statistics - - + + -This section shows the health status of each backend server **as determined by HAProxy's health checks**. This is the authoritative source for whether HAProxy considers a backend healthy and is routing traffic to it. - +This section shows the health status of each backend server **as determined by HAProxy's health checks**. This is the authoritative source for whether HAProxy considers a backend healthy and is routing traffic to it. + - + -| - Column | - Description | - +| + Column | + Description | -| - **Server** | - The backend server name as configured | - -| - **Address** | - The IP address and port of the backend server (e.g., 10.50.1.10:8080) | - +| + **Server** | + The backend server name as configured | -| - **Status** | - HAProxy's health verdict: **UP** (healthy, receiving traffic) or **DOWN** (unhealthy, removed from rotation) | - -| - **Sessions** | - Current active sessions / maximum sessions seen | - +| + **Address** | + The IP address and port of the backend server (e.g., 10.50.1.10:8080) | -| - **Bytes In/Out** | - Total traffic received from and sent to this backend | - -| - **Weight** | - The configured weight for load distribution | - +| + **Status** | + HAProxy's health verdict: **UP** (healthy, receiving traffic) or **DOWN** (unhealthy, removed from rotation) | + + +| + **Sessions** | + Current active sessions / maximum sessions seen | + + +| + **Bytes In/Out** | + Total traffic received from and sent to this backend | + + +| + **Weight** | + The configured weight for load distribution | + + +| + **Last Check** | + Result of the most recent health check and response time in milliseconds | -| - **Last Check** | - Result of the most recent health check and response time in milliseconds | - - - - - **Note:** A backend showing **DOWN** means HAProxy's configured health check failed. The backend will not receive new traffic until it passes health checks again. - - - + + + + **Note:** A backend showing **DOWN** means HAProxy's configured health check failed. The backend will not receive new traffic until it passes health checks again. + + + ##### Section 2: HAProxy Statistics - - + + -This section shows traffic statistics from HAProxy's perspective, split into Frontend and Backend summaries. - +This section shows traffic statistics from HAProxy's perspective, split into Frontend and Backend summaries. + ###### Frontend Statistics - + -Shows statistics for the HAProxy frontend listener on this service's port. - - - **Important:** If multiple services share the same port (using hostname-based routing), the Frontend statistics show **combined traffic for all services on that port**, not just this specific service. - - +Shows statistics for the HAProxy frontend listener on this service's port. + - - -| - Metric | - Description | - - -| - **Current Sessions** | - Number of active client connections right now | - - -| - **Max Sessions** | - Highest number of concurrent sessions seen | - - -| - **Total Sessions** | - Cumulative number of sessions since HAProxy started | - - -| - **Session Rate** | - New sessions per second | - - -| - **Bytes In/Out** | - Total traffic received from clients and sent to clients | - + **Important:** If multiple services share the same port (using hostname-based routing), the Frontend statistics show **combined traffic for all services on that port**, not just this specific service. - - + + + + +| + Metric | + Description | + + +| + **Current Sessions** | + Number of active client connections right now | + + +| + **Max Sessions** | + Highest number of concurrent sessions seen | + + +| + **Total Sessions** | + Cumulative number of sessions since HAProxy started | + + +| + **Session Rate** | + New sessions per second | + + +| + **Bytes In/Out** | + Total traffic received from clients and sent to clients | + + + + ###### Backend Summary - + -Shows aggregated statistics for this specific service's backend group only. - +Shows aggregated statistics for this specific service's backend group only. + - + -| - Metric | - Description | - +| + Metric | + Description | -| - **Status** | - Overall backend status (UP if at least one server is healthy) | - -| - **Current Sessions** | - Active connections to backend servers | - +| + **Status** | + Overall backend status (UP if at least one server is healthy) | -| - **Total Sessions** | - Cumulative sessions handled by this backend | - -| - **Bytes In/Out** | - Traffic to and from backend servers | - +| + **Current Sessions** | + Active connections to backend servers | + + +| + **Total Sessions** | + Cumulative sessions handled by this backend | + + +| + **Bytes In/Out** | + Traffic to and from backend servers | + + +| + **Downtime** | + Total time the backend has been unavailable | -| - **Downtime** | - Total time the backend has been unavailable | - - - - + + + ##### Section 3: HAProxy Node Resources - - + + -This section displays CPU and memory usage for both HAProxy container instances (HAProxy 01 and HAProxy 02). This helps you monitor whether the HAProxy nodes have sufficient resources. - +This section displays CPU and memory usage for both HAProxy container instances (HAProxy 01 and HAProxy 02). This helps you monitor whether the HAProxy nodes have sufficient resources. + - + -| - Metric | - Description | - +| + Metric | + Description | -| - **CPUs Assigned** | - Number of CPU cores allocated to the instance | - -| - **CPU Usage** | - Current CPU utilization percentage | - +| + **CPUs Assigned** | + Number of CPU cores allocated to the instance | -| - **Memory Assigned** | - Amount of RAM allocated to the instance | - -| - **Memory Usage** | - Current memory utilization (amount and percentage) | - +| + **CPU Usage** | + Current CPU utilization percentage | + + +| + **Memory Assigned** | + Amount of RAM allocated to the instance | + + +| + **Memory Usage** | + Current memory utilization (amount and percentage) | + - - + + ###### Resource Usage Color Thresholds - + -CPU and memory usage are color-coded to help you quickly identify resource constraints: - +CPU and memory usage are color-coded to help you quickly identify resource constraints: + - + -| - Color | - Usage Range | - Interpretation | - +| + Color | + Usage Range | + Interpretation | -| - **Green** | - Below 50% | - Healthy - plenty of headroom | - -| - **Orange** | - 50% - 79% | - Moderate - monitor for increases | - +| + **Green** | + Below 50% | + Healthy - plenty of headroom | + + +| + **Orange** | + 50% - 79% | + Moderate - monitor for increases | + + +| + **Red** | + 80% and above | + High - consider increasing resources | -| - **Red** | - 80% and above | - High - consider increasing resources | - - - - - **Tip:** If you consistently see orange or red resource usage, consider increasing the CPU or memory limits for the HAProxy infrastructure. This can be done by deleting and redeploying the infrastructure with higher resource allocations. - - - + + + + **Tip:** If you consistently see orange or red resource usage, consider increasing the CPU or memory limits for the HAProxy infrastructure. This can be done by deleting and redeploying the infrastructure with higher resource allocations. + + + #### 7.11 Advanced Options - + + + +The Advanced Options section provides additional features for security hardening, performance optimization, rate limiting, and access control. These options are available when creating or editing a service and are found in a collapsible section below the basic service configuration. + + + **Note:** Advanced Options only apply to services using **HTTP** or **HTTPS Termination** modes. They have no effect on TCP or HTTPS Passthrough services, as those modes operate at Layer 4 without inspecting HTTP content. -The Advanced Options section provides additional features for security hardening, performance optimization, rate limiting, and access control. These options are available when creating or editing a service and are found in a collapsible section below the basic service configuration. - - - **Note:** Advanced Options only apply to services using **HTTP** or **HTTPS Termination** modes. They have no effect on TCP or HTTPS Passthrough services, as those modes operate at Layer 4 without inspecting HTTP content. - - ##### 7.11.1 Security Options - + -Security options help protect your applications from common web attacks and enforce security best practices through HTTP headers. - +Security options help protect your applications from common web attacks and enforce security best practices through HTTP headers. + - + -| - Option | - Description | - When to Use | - +| + Option | + Description | + When to Use | -| - **Force HTTPS Redirect** | - Automatically redirects HTTP requests to HTTPS using a 301 (permanent) redirect. | - Enable on HTTP services that should only be accessed via HTTPS. Ensures users always use the encrypted version. | - -| - **Enable HSTS** | - Adds the `Strict-Transport-Security` header, instructing browsers to only connect via HTTPS for a specified duration. | - Enable for production HTTPS services to prevent protocol downgrade attacks and cookie hijacking. | - +| + **Force HTTPS Redirect** | + Automatically redirects HTTP requests to HTTPS using a 301 (permanent) redirect. | + Enable on HTTP services that should only be accessed via HTTPS. Ensures users always use the encrypted version. | -| - **Clickjacking Protection** | - Adds the `X-Frame-Options: SAMEORIGIN` header, preventing your site from being embedded in iframes on other domains. | - Enable for web applications to prevent clickjacking attacks where attackers overlay invisible frames. | - -| - **Prevent MIME Sniffing** | - Adds the `X-Content-Type-Options: nosniff` header, preventing browsers from guessing content types. | - Enable to prevent MIME confusion attacks where malicious files are executed as scripts. | - +| + **Enable HSTS** | + Adds the `Strict-Transport-Security` header, instructing browsers to only connect via HTTPS for a specified duration. | + Enable for production HTTPS services to prevent protocol downgrade attacks and cookie hijacking. | + + +| + **Clickjacking Protection** | + Adds the `X-Frame-Options: SAMEORIGIN` header, preventing your site from being embedded in iframes on other domains. | + Enable for web applications to prevent clickjacking attacks where attackers overlay invisible frames. | + + +| + **Prevent MIME Sniffing** | + Adds the `X-Content-Type-Options: nosniff` header, preventing browsers from guessing content types. | + Enable to prevent MIME confusion attacks where malicious files are executed as scripts. | + - - + + ###### Force HTTPS Redirect - Detailed - - + + -When enabled, any request arriving over plain HTTP will receive a `301 Moved Permanently` response redirecting to the HTTPS version of the URL. +When enabled, any request arriving over plain HTTP will receive a `301 Moved Permanently` response redirecting to the HTTPS version of the URL. -**Example:** +**Example:** ``` -`Request: GET http://example.com/page +`Request: GET http://example.com/page Response: 301 Redirect to https://example.com/page` ``` - - - **Warning:** Only enable this on services where HTTPS is properly configured. Enabling on a plain HTTP-only service will create a redirect loop. - - - + + + **Warning:** Only enable this on services where HTTPS is properly configured. Enabling on a plain HTTP-only service will create a redirect loop. + + + ###### HSTS (HTTP Strict Transport Security) - Detailed - - + + -HSTS tells browsers to remember that your site should only be accessed via HTTPS. Once a browser receives the HSTS header, it will automatically convert any HTTP links to HTTPS before making the request. +HSTS tells browsers to remember that your site should only be accessed via HTTPS. Once a browser receives the HSTS header, it will automatically convert any HTTP links to HTTPS before making the request. -**Duration Options:** +**Duration Options:** - + -| - Setting | - Duration | - Recommended Use | - +| + Setting | + Duration | + Recommended Use | -| - 1 year (recommended) | - 31,536,000 seconds | - Production services with stable HTTPS configuration | - -| - 6 months | - 15,768,000 seconds | - Production services, slightly more conservative | - +| + 1 year (recommended) | + 31,536,000 seconds | + Production services with stable HTTPS configuration | -| - 30 days | - 2,592,000 seconds | - Staging environments or services with changing configurations | - -| - 1 day (testing) | - 86,400 seconds | - Testing HSTS before committing to longer durations | - +| + 6 months | + 15,768,000 seconds | + Production services, slightly more conservative | + + +| + 30 days | + 2,592,000 seconds | + Staging environments or services with changing configurations | + + +| + 1 day (testing) | + 86,400 seconds | + Testing HSTS before committing to longer durations | + - - - **Important:** Once HSTS is enabled with a long duration, browsers will refuse to connect via HTTP until the timer expires. Start with shorter durations to test, then increase for production. - - - + + + **Important:** Once HSTS is enabled with a long duration, browsers will refuse to connect via HTTP until the timer expires. Start with shorter durations to test, then increase for production. + + + ###### Clickjacking Protection - Detailed - - + + -Clickjacking is an attack where a malicious site embeds your site in an invisible iframe and tricks users into clicking hidden buttons. The `X-Frame-Options: SAMEORIGIN` header prevents this by only allowing your site to be framed by pages on the same domain. +Clickjacking is an attack where a malicious site embeds your site in an invisible iframe and tricks users into clicking hidden buttons. The `X-Frame-Options: SAMEORIGIN` header prevents this by only allowing your site to be framed by pages on the same domain. -**Effect:** - +**Effect:** + -- Your site CAN be embedded in iframes on your own domain +- Your site CAN be embedded in iframes on your own domain -- Your site CANNOT be embedded in iframes on other domains - - - +- Your site CANNOT be embedded in iframes on other domains + + + ###### MIME Sniffing Protection - Detailed - - + + -Some browsers try to "guess" the content type of a response, which can be exploited to execute malicious content. The `X-Content-Type-Options: nosniff` header prevents this behavior. +Some browsers try to "guess" the content type of a response, which can be exploited to execute malicious content. The `X-Content-Type-Options: nosniff` header prevents this behavior. -**Example attack prevented:** An attacker uploads a file named `image.jpg` that actually contains JavaScript. Without this protection, the browser might execute it as a script. - - +**Example attack prevented:** An attacker uploads a file named `image.jpg` that actually contains JavaScript. Without this protection, the browser might execute it as a script. + + ##### 7.11.2 Performance Options - + -Performance options help reduce bandwidth usage, improve response times, and provide better debugging information to backend servers. - +Performance options help reduce bandwidth usage, improve response times, and provide better debugging information to backend servers. + - + -| - Option | - Description | - When to Use | - +| + Option | + Description | + When to Use | -| - **Enable Compression (gzip)** | - Compresses text-based responses (HTML, CSS, JavaScript, JSON, XML) before sending to clients. | - Enable for web applications serving text content. Can significantly reduce bandwidth usage. | - -| - **Forward Client IP** | - Adds `X-Real-IP`, `X-Forwarded-For`, and `X-Forwarded-Proto` headers containing the original client's information. | - Enable when your backend applications need to know the real client IP address for logging, geo-location, or security purposes. | - +| + **Enable Compression (gzip)** | + Compresses text-based responses (HTML, CSS, JavaScript, JSON, XML) before sending to clients. | + Enable for web applications serving text content. Can significantly reduce bandwidth usage. | + + +| + **Forward Client IP** | + Adds `X-Real-IP`, `X-Forwarded-For`, and `X-Forwarded-Proto` headers containing the original client's information. | + Enable when your backend applications need to know the real client IP address for logging, geo-location, or security purposes. | + + +| + **Hide Server Version Info** | + Removes the `Server` and `X-Powered-By` headers from responses. | + Enable to hide information about your server software from potential attackers. | -| - **Hide Server Version Info** | - Removes the `Server` and `X-Powered-By` headers from responses. | - Enable to hide information about your server software from potential attackers. | - - - + + ###### Compression - Detailed - - + + -When enabled, HAProxy will compress responses using gzip for the following content types: - +When enabled, HAProxy will compress responses using gzip for the following content types: + -- `text/html` - HTML pages +- `text/html` - HTML pages -- `text/plain` - Plain text files +- `text/plain` - Plain text files -- `text/css` - Stylesheets +- `text/css` - Stylesheets -- `text/javascript` and `application/javascript` - JavaScript files +- `text/javascript` and `application/javascript` - JavaScript files -- `application/json` - JSON API responses +- `application/json` - JSON API responses -- `application/xml` - XML documents - +- `application/xml` - XML documents + -**Typical bandwidth savings:** 60-80% for text-based content. - - **Note:** Images, videos, and already-compressed files (ZIP, PDF) are not compressed as they wouldn't benefit from additional compression. - - - +**Typical bandwidth savings:** 60-80% for text-based content. + + **Note:** Images, videos, and already-compressed files (ZIP, PDF) are not compressed as they wouldn't benefit from additional compression. + + + ###### Forward Client IP - Detailed - - + + -When traffic passes through a load balancer, backend servers see HAProxy's IP address instead of the client's real IP. This option adds headers to preserve the original client information. +When traffic passes through a load balancer, backend servers see HAProxy's IP address instead of the client's real IP. This option adds headers to preserve the original client information. -**Headers Added:** +**Headers Added:** - + -| - Header | - Value | - Example | - +| + Header | + Value | + Example | -| - `X-Real-IP` | - Client's IP address | - `203.0.113.50` | - -| - `X-Forwarded-For` | - Client's IP address (chain of proxies) | - `203.0.113.50` | - +| + `X-Real-IP` | + Client's IP address | + `203.0.113.50` | + + +| + `X-Forwarded-For` | + Client's IP address (chain of proxies) | + `203.0.113.50` | + + +| + `X-Forwarded-Proto` | + Original protocol (http or https) | + `https` | -| - `X-Forwarded-Proto` | - Original protocol (http or https) | - `https` | - - - - **Backend Configuration:** Your application needs to be configured to read these headers. Most web frameworks have settings for "trust proxy" or "forwarded headers". - - - + + + **Backend Configuration:** Your application needs to be configured to read these headers. Most web frameworks have settings for "trust proxy" or "forwarded headers". + + + ###### Hide Server Info - Detailed - - + + -By default, web servers include headers identifying the software and version (e.g., `Server: nginx/1.18.0`). Attackers can use this information to target known vulnerabilities. +By default, web servers include headers identifying the software and version (e.g., `Server: nginx/1.18.0`). Attackers can use this information to target known vulnerabilities. -**Headers Removed:** - +**Headers Removed:** + -- `Server` - Identifies web server software +- `Server` - Identifies web server software -- `X-Powered-By` - Identifies application framework (e.g., PHP, ASP.NET) - +- `X-Powered-By` - Identifies application framework (e.g., PHP, ASP.NET) + -This is a "security through obscurity" measure - it makes reconnaissance slightly harder but shouldn't be your only security measure. - - +This is a "security through obscurity" measure - it makes reconnaissance slightly harder but shouldn't be your only security measure. + + ##### 7.11.3 Rate Limiting - + -Rate limiting protects your services from abuse, denial-of-service attacks, and runaway clients by limiting how many requests a single IP address can make. - +Rate limiting protects your services from abuse, denial-of-service attacks, and runaway clients by limiting how many requests a single IP address can make. + - + -| - Option | - Description | - +| + Option | + Description | -| - **Enable Rate Limiting** | - Activates request rate tracking and limiting per client IP address. | - -| - **Max Requests per 10 Seconds** | - The maximum number of requests allowed from a single IP address within a 10-second window. Default: 100. Range: 1-10,000. | - +| + **Enable Rate Limiting** | + Activates request rate tracking and limiting per client IP address. | + + +| + **Max Requests per 10 Seconds** | + The maximum number of requests allowed from a single IP address within a 10-second window. Default: 100. Range: 1-10,000. | + - - + + ###### How Rate Limiting Works - - + + -HAProxy tracks the request rate for each client IP address using a sliding window of 10 seconds. When a client exceeds the configured limit, they receive a `429 Too Many Requests` response. +HAProxy tracks the request rate for each client IP address using a sliding window of 10 seconds. When a client exceeds the configured limit, they receive a `429 Too Many Requests` response. -**Example with 100 requests per 10 seconds:** - +**Example with 100 requests per 10 seconds:** + -- Client makes 100 requests in 5 seconds - All succeed +- Client makes 100 requests in 5 seconds - All succeed -- Client makes request #101 at second 6 - Receives 429 error +- Client makes request #101 at second 6 - Receives 429 error -- After second 10, the counter resets based on the sliding window - - - +- After second 10, the counter resets based on the sliding window + + + ###### Choosing the Right Limit - - + + - + -| - Limit | - Equivalent Rate | - Suitable For | - +| + Limit | + Equivalent Rate | + Suitable For | -| - 10 | - ~1 req/sec | - API endpoints with strict limits, login pages | - -| - 100 (default) | - ~10 req/sec | - Standard web applications, moderate API usage | - +| + 10 | + ~1 req/sec | + API endpoints with strict limits, login pages | -| - 500 | - ~50 req/sec | - High-traffic web pages with many assets | - -| - 1,000 | - ~100 req/sec | - CDN-like usage, API-heavy applications | - +| + 100 (default) | + ~10 req/sec | + Standard web applications, moderate API usage | + + +| + 500 | + ~50 req/sec | + High-traffic web pages with many assets | + + +| + 1,000 | + ~100 req/sec | + CDN-like usage, API-heavy applications | + + +| + 10,000 | + ~1,000 req/sec | + Very high traffic, internal services | -| - 10,000 | - ~1,000 req/sec | - Very high traffic, internal services | - - - - **Warning:** Setting limits too low may block legitimate users, especially if multiple users share a single IP address (corporate networks, NAT). Start with higher limits and reduce based on monitoring. - - - + + + **Warning:** Setting limits too low may block legitimate users, especially if multiple users share a single IP address (corporate networks, NAT). Start with higher limits and reduce based on monitoring. + + + ##### 7.11.4 Access Control - + -Access control options allow you to block requests based on URL paths or User-Agent headers, providing a simple layer of protection against unwanted traffic. - +Access control options allow you to block requests based on URL paths or User-Agent headers, providing a simple layer of protection against unwanted traffic. + - + -| - Option | - Description | - Format | - +| + Option | + Description | + Format | -| - **Block Paths** | - Denies access to requests matching specified URL path prefixes. | - Comma-separated list of paths (e.g., `/admin, /wp-admin, /.git`) | - -| - **Block User Agents** | - Denies access to requests with User-Agent headers containing specified strings. | - Comma-separated list of strings (e.g., `crawler, badbot, scanner`) | - +| + **Block Paths** | + Denies access to requests matching specified URL path prefixes. | + Comma-separated list of paths (e.g., `/admin, /wp-admin, /.git`) | + + +| + **Block User Agents** | + Denies access to requests with User-Agent headers containing specified strings. | + Comma-separated list of strings (e.g., `crawler, badbot, scanner`) | + - - + + ###### Blocked Paths - Detailed - - + + -Requests to blocked paths receive a `403 Forbidden` response. The matching is based on path prefix, so blocking `/admin` will also block `/admin/users`, `/admin/settings`, etc. +Requests to blocked paths receive a `403 Forbidden` response. The matching is based on path prefix, so blocking `/admin` will also block `/admin/users`, `/admin/settings`, etc. -**Common paths to block:** - - - -| - Path | - Reason | - - -| - `/admin` | - Administrative interfaces (if not needed publicly) | - - -| - `/wp-admin`, `/wp-login.php` | - WordPress admin areas (frequent attack target) | - - -| - `/.git` | - Git repository data (should never be public) | - - -| - `/.env` | - Environment configuration files | - - -| - `/phpmyadmin` | - Database management interface | - - -| - `/config` | - Configuration directories | - - - +**Common paths to block:** -**Example configuration:** `/admin, /wp-admin, /.git, /.env, /backup` - - + +| + Path | + Reason | + + +| + `/admin` | + Administrative interfaces (if not needed publicly) | + + +| + `/wp-admin`, `/wp-login.php` | + WordPress admin areas (frequent attack target) | + + +| + `/.git` | + Git repository data (should never be public) | + + +| + `/.env` | + Environment configuration files | + + +| + `/phpmyadmin` | + Database management interface | + + +| + `/config` | + Configuration directories | + + + + + +**Example configuration:** `/admin, /wp-admin, /.git, /.env, /backup` + + ###### Blocked User Agents - Detailed - - + + -Requests from clients with User-Agent strings containing any of the specified strings will receive a `403 Forbidden` response. The matching is case-insensitive and checks if the string appears anywhere in the User-Agent. +Requests from clients with User-Agent strings containing any of the specified strings will receive a `403 Forbidden` response. The matching is case-insensitive and checks if the string appears anywhere in the User-Agent. -**Common user agents to block:** - - - -| - String | - Reason | - - -| - `sqlmap` | - SQL injection scanning tool | - - -| - `nikto` | - Web vulnerability scanner | - - -| - `nmap` | - Network scanner | - - -| - `masscan` | - Port scanner | - - -| - `ZmEu` | - Known malicious scanner | - - -| - `wget`, `curl` | - Command-line tools (block if not needed for legitimate API access) | - - - +**Common user agents to block:** -**Example configuration:** `sqlmap, nikto, nmap, ZmEu, masscan` - - **Warning:** User-Agent strings can easily be spoofed. This is a deterrent against casual/automated attacks, not a security guarantee. Sophisticated attackers will use legitimate-looking User-Agents. - - - + +| + String | + Reason | + + +| + `sqlmap` | + SQL injection scanning tool | + + +| + `nikto` | + Web vulnerability scanner | + + +| + `nmap` | + Network scanner | + + +| + `masscan` | + Port scanner | + + +| + `ZmEu` | + Known malicious scanner | + + +| + `wget`, `curl` | + Command-line tools (block if not needed for legitimate API access) | + + + + + +**Example configuration:** `sqlmap, nikto, nmap, ZmEu, masscan` + + **Warning:** User-Agent strings can easily be spoofed. This is a deterrent against casual/automated attacks, not a security guarantee. Sophisticated attackers will use legitimate-looking User-Agents. + + + ###### Access Control Best Practices - - - + + + -- **Defense in depth:** Don't rely solely on HAProxy access control. Also configure your application and firewall. +- **Defense in depth:** Don't rely solely on HAProxy access control. Also configure your application and firewall. -- **Test before production:** Verify blocked paths don't affect legitimate functionality. +- **Test before production:** Verify blocked paths don't affect legitimate functionality. -- **Monitor logs:** Review blocked requests to identify attack patterns and adjust rules. +- **Monitor logs:** Review blocked requests to identify attack patterns and adjust rules. -- **Keep it simple:** Start with a small set of critical paths and expand as needed. - - - +- **Keep it simple:** Start with a small set of critical paths and expand as needed. + + + ### 8. Example Configurations - - + + #### Example 1: Simple Web Application (HTTP) - + ``` -`Service Name: company-website -Description: Main company website -VIP: 192.168.1.200 -Listen Port: 80 -Mode: HTTP -Balance Method: Round Robin -Health Check: Enabled -Sticky Sessions: Disabled - -Backends: - - web-server-1: 10.50.1.10:8080 (weight: 100) - - web-server-2: 10.50.1.11:8080 (weight: 100) +`Service Name: company-website +Description: Main company website +VIP: 192.168.1.200 +Listen Port: 80 +Mode: HTTP +Balance Method: Round Robin +Health Check: Enabled +Sticky Sessions: Disabled + +Backends: + - web-server-1: 10.50.1.10:8080 (weight: 100) + - web-server-2: 10.50.1.11:8080 (weight: 100) - web-server-3: 10.50.1.12:8080 (weight: 100)` ``` - - + + #### Example 2: HTTPS Website with SSL Passthrough - + ``` -`Service Name: secure-portal -Description: Customer portal with end-to-end encryption -VIP: 192.168.1.200 -Listen Port: 443 -Hostname: portal.example.com -Mode: HTTPS Passthrough (SNI routing) -Balance Method: Least Connections -Health Check: Enabled -Sticky Sessions: Enabled - -Backends: - - portal-node-1: 10.50.2.20:443 (weight: 100) +`Service Name: secure-portal +Description: Customer portal with end-to-end encryption +VIP: 192.168.1.200 +Listen Port: 443 +Hostname: portal.example.com +Mode: HTTPS Passthrough (SNI routing) +Balance Method: Least Connections +Health Check: Enabled +Sticky Sessions: Enabled + +Backends: + - portal-node-1: 10.50.2.20:443 (weight: 100) - portal-node-2: 10.50.2.21:443 (weight: 100)` ``` - - + + #### Example 3: Database Load Balancing (TCP) - + ``` -`Service Name: mysql-cluster -Description: MySQL read replicas for reporting -VIP: 192.168.1.201 -Listen Port: 3306 -Mode: TCP (Layer 4) -Balance Method: Least Connections -Health Check: Enabled -Sticky Sessions: Disabled - -Backends: - - mysql-replica-1: 10.50.3.30:3306 (weight: 100) - - mysql-replica-2: 10.50.3.31:3306 (weight: 100) +`Service Name: mysql-cluster +Description: MySQL read replicas for reporting +VIP: 192.168.1.201 +Listen Port: 3306 +Mode: TCP (Layer 4) +Balance Method: Least Connections +Health Check: Enabled +Sticky Sessions: Disabled + +Backends: + - mysql-replica-1: 10.50.3.30:3306 (weight: 100) + - mysql-replica-2: 10.50.3.31:3306 (weight: 100) - mysql-replica-3: 10.50.3.32:3306 (weight: 50) # Less powerful server` ``` - - + + #### Example 4: API Gateway with Gradual Rollout - + ``` -`Service Name: api-v2-rollout -Description: API with gradual traffic shift to v2 -VIP: 192.168.1.200 -Listen Port: 8443 -Hostname: api.example.com -Mode: HTTPS Passthrough (SNI routing) -Balance Method: Round Robin -Health Check: Enabled -Sticky Sessions: Disabled - -Backends: - - api-v1-node-1: 10.50.4.40:8443 (weight: 45) - - api-v1-node-2: 10.50.4.41:8443 (weight: 45) +`Service Name: api-v2-rollout +Description: API with gradual traffic shift to v2 +VIP: 192.168.1.200 +Listen Port: 8443 +Hostname: api.example.com +Mode: HTTPS Passthrough (SNI routing) +Balance Method: Round Robin +Health Check: Enabled +Sticky Sessions: Disabled + +Backends: + - api-v1-node-1: 10.50.4.40:8443 (weight: 45) + - api-v1-node-2: 10.50.4.41:8443 (weight: 45) - api-v2-node-1: 10.50.4.50:8443 (weight: 10) # 10% of traffic to new version` ``` - - + + #### Example 5: Multiple Services on Same VIP - + ``` -`VIP: 192.168.1.200 - -Service 1: website-http - Listen Port: 80 - Mode: HTTP - Backends: web-1:8080, web-2:8080 - -Service 2: website-https - Listen Port: 443 - Mode: HTTPS Passthrough - Backends: web-1:8443, web-2:8443 - -Service 3: api-service - Listen Port: 8080 - Mode: HTTP +`VIP: 192.168.1.200 + +Service 1: website-http + Listen Port: 80 + Mode: HTTP + Backends: web-1:8080, web-2:8080 + +Service 2: website-https + Listen Port: 443 + Mode: HTTPS Passthrough + Backends: web-1:8443, web-2:8443 + +Service 3: api-service + Listen Port: 8080 + Mode: HTTP Backends: api-1:3000, api-2:3000, api-3:3000` ``` - - + + #### Example 6: Security-Hardened Web Application with Advanced Options - + ``` -`Service Name: secure-webapp -Description: Production web application with full security hardening -VIP: 192.168.1.200 -Listen Port: 443 -Hostname: app.example.com -Mode: HTTPS Termination -Balance Method: Least Connections -Health Check: Enabled -Sticky Sessions: Enabled - -Advanced Options - Security: - Force HTTPS Redirect: Enabled - HSTS: Enabled (1 year) - Clickjacking Protection: Enabled - MIME Sniffing Protection: Enabled - -Advanced Options - Performance: - Compression: Enabled - Forward Client IP: Enabled - Hide Server Info: Enabled - -Advanced Options - Rate Limiting: - Rate Limiting: Enabled - Max Requests per 10 seconds: 200 - -Advanced Options - Access Control: - Block Paths: /admin, /.git, /.env, /backup, /config - Block User Agents: sqlmap, nikto, ZmEu, masscan - -Backends: - - app-node-1: 10.50.5.10:8080 (weight: 100) - - app-node-2: 10.50.5.11:8080 (weight: 100) +`Service Name: secure-webapp +Description: Production web application with full security hardening +VIP: 192.168.1.200 +Listen Port: 443 +Hostname: app.example.com +Mode: HTTPS Termination +Balance Method: Least Connections +Health Check: Enabled +Sticky Sessions: Enabled + +Advanced Options - Security: + Force HTTPS Redirect: Enabled + HSTS: Enabled (1 year) + Clickjacking Protection: Enabled + MIME Sniffing Protection: Enabled + +Advanced Options - Performance: + Compression: Enabled + Forward Client IP: Enabled + Hide Server Info: Enabled + +Advanced Options - Rate Limiting: + Rate Limiting: Enabled + Max Requests per 10 seconds: 200 + +Advanced Options - Access Control: + Block Paths: /admin, /.git, /.env, /backup, /config + Block User Agents: sqlmap, nikto, ZmEu, masscan + +Backends: + - app-node-1: 10.50.5.10:8080 (weight: 100) + - app-node-2: 10.50.5.11:8080 (weight: 100) - app-node-3: 10.50.5.12:8080 (weight: 100)` ``` - - + + #### Example 7: API Gateway with Rate Limiting - + ``` -`Service Name: public-api -Description: Public API with rate limiting protection -VIP: 192.168.1.202 -Listen Port: 443 -Hostname: api.example.com -Mode: HTTPS Termination -Balance Method: Round Robin -Health Check: Enabled -Sticky Sessions: Disabled - -Advanced Options - Security: - HSTS: Enabled (1 year) - MIME Sniffing Protection: Enabled - -Advanced Options - Performance: - Compression: Enabled (for JSON responses) - Forward Client IP: Enabled - Hide Server Info: Enabled - -Advanced Options - Rate Limiting: - Rate Limiting: Enabled - Max Requests per 10 seconds: 100 (10 req/sec average) - -Advanced Options - Access Control: - Block Paths: /internal, /debug, /health/detailed - Block User Agents: curl, wget (if blocking CLI tools) - -Backends: - - api-server-1: 10.50.6.20:3000 (weight: 100) +`Service Name: public-api +Description: Public API with rate limiting protection +VIP: 192.168.1.202 +Listen Port: 443 +Hostname: api.example.com +Mode: HTTPS Termination +Balance Method: Round Robin +Health Check: Enabled +Sticky Sessions: Disabled + +Advanced Options - Security: + HSTS: Enabled (1 year) + MIME Sniffing Protection: Enabled + +Advanced Options - Performance: + Compression: Enabled (for JSON responses) + Forward Client IP: Enabled + Hide Server Info: Enabled + +Advanced Options - Rate Limiting: + Rate Limiting: Enabled + Max Requests per 10 seconds: 100 (10 req/sec average) + +Advanced Options - Access Control: + Block Paths: /internal, /debug, /health/detailed + Block User Agents: curl, wget (if blocking CLI tools) + +Backends: + - api-server-1: 10.50.6.20:3000 (weight: 100) - api-server-2: 10.50.6.21:3000 (weight: 100)` ``` - - + + ### 9. Troubleshooting - - + + #### Common Issues and Solutions - - + + ##### Issue: "HAProxy base image not available on cluster" - - + + -**Cause:** The HAProxy image hasn't been pushed to the selected cluster. +**Cause:** The HAProxy image hasn't been pushed to the selected cluster. -**Solution:** - +**Solution:** + -- Go to the "HAProxy Base Images" section +- Go to the "HAProxy Base Images" section -- Click "Push to Cluster" on the desired image version +- Click "Push to Cluster" on the desired image version -- Select the target cluster and push the image +- Select the target cluster and push the image -- Wait for the push to complete, then retry deployment - - - +- Wait for the push to complete, then retry deployment + + + ##### Issue: "Failed to create HAProxy instance" - - + + -**Possible causes:** - +**Possible causes:** + -- IP address already in use +- IP address already in use -- Insufficient resources on the cluster +- Insufficient resources on the cluster -- Network connectivity issues - +- Network connectivity issues + -**Solution:** - +**Solution:** + -- Verify the IP addresses are not already assigned to other instances +- Verify the IP addresses are not already assigned to other instances -- Check cluster resource availability (CPU, memory) +- Check cluster resource availability (CPU, memory) -- Verify the OVN network is properly configured - - - +- Verify the OVN network is properly configured + + + ##### Issue: Service is created but traffic is not reaching backends - - + + -**Troubleshooting steps:** - +**Troubleshooting steps:** + -- Verify the HAProxy instances are running (check status badges) +- Verify the HAProxy instances are running (check status badges) -- Confirm backend servers are running and accessible on the specified ports +- Confirm backend servers are running and accessible on the specified ports -- Check that firewall rules allow traffic from HAProxy IPs to backend IPs +- Check that firewall rules allow traffic from HAProxy IPs to backend IPs -- Verify the VIP is correctly configured in DNS or client applications +- Verify the VIP is correctly configured in DNS or client applications -- Use "Reload Config" button to ensure configuration is applied - - - +- Use "Reload Config" button to ensure configuration is applied + + + ##### Issue: Health checks failing - - + + -**Possible causes:** - +**Possible causes:** + -- Backend server is down or not responding +- Backend server is down or not responding -- Firewall blocking health check traffic from HAProxy instances +- Firewall blocking health check traffic from HAProxy instances -- Incorrect backend port configuration +- Incorrect backend port configuration -- Application taking too long to respond - +- Application taking too long to respond + -**Solution:** - +**Solution:** + -- Test connectivity from the cluster network to the backend +- Test connectivity from the cluster network to the backend -- Verify the backend application is listening on the configured port +- Verify the backend application is listening on the configured port -- Check backend server logs for errors +- Check backend server logs for errors -- Ensure ACLs allow traffic from HAProxy IPs to backend servers - - - +- Ensure ACLs allow traffic from HAProxy IPs to backend servers + + + ##### Issue: Sticky sessions not working - - + + -**Possible causes:** - +**Possible causes:** + -- Client not accepting cookies +- Client not accepting cookies -- Using TCP mode (cookies only work in HTTP/HTTPS modes) +- Using TCP mode (cookies only work in HTTP/HTTPS modes) -- Multiple levels of proxies stripping cookies - +- Multiple levels of proxies stripping cookies + -**Solution:** - +**Solution:** + -- Verify the service is using HTTP or HTTPS mode (not TCP) +- Verify the service is using HTTP or HTTPS mode (not TCP) -- Check that client browsers accept cookies +- Check that client browsers accept cookies -- If using HTTPS Passthrough, sticky sessions use different mechanisms - - - +- If using HTTPS Passthrough, sticky sessions use different mechanisms + + + ##### Issue: Build image process fails - - + + -**Possible causes:** - +**Possible causes:** + -- No internet access from the cluster +- No internet access from the cluster -- Package repository unavailable +- Package repository unavailable -- Insufficient disk space - +- Insufficient disk space + -**Solution:** - +**Solution:** + -- Verify the cluster has outbound internet access +- Verify the cluster has outbound internet access -- Try building on a different cluster +- Try building on a different cluster -- Check cluster storage availability - - - +- Check cluster storage availability + + + ##### Issue: Advanced Options not taking effect - - + + -**Possible causes:** - +**Possible causes:** + -- Service is using TCP or HTTPS Passthrough mode (Advanced Options only work with HTTP/HTTPS Termination modes) +- Service is using TCP or HTTPS Passthrough mode (Advanced Options only work with HTTP/HTTPS Termination modes) -- Configuration hasn't been reloaded - +- Configuration hasn't been reloaded + -**Solution:** - +**Solution:** + -- Verify the service mode is "HTTP" or "HTTPS Termination" +- Verify the service mode is "HTTP" or "HTTPS Termination" -- Click "Reload Config" to apply the latest configuration +- Click "Reload Config" to apply the latest configuration -- Check the service card to confirm Advanced Options are saved - - - +- Check the service card to confirm Advanced Options are saved + + + ##### Issue: Legitimate users getting 429 Too Many Requests - - + + -**Possible causes:** - +**Possible causes:** + -- Rate limit set too low +- Rate limit set too low -- Multiple users sharing one IP address (corporate NAT, VPN) +- Multiple users sharing one IP address (corporate NAT, VPN) -- Single page making many requests (heavy JavaScript, many images) - +- Single page making many requests (heavy JavaScript, many images) + -**Solution:** - +**Solution:** + -- Increase the "Max requests per 10 seconds" value +- Increase the "Max requests per 10 seconds" value -- Consider the expected request pattern: a page with 20 images generates 21 requests +- Consider the expected request pattern: a page with 20 images generates 21 requests -- Monitor typical usage before setting strict limits - - - +- Monitor typical usage before setting strict limits + + + ##### Issue: Blocked path is needed for legitimate access - - + + -**Solution:** - +**Solution:** + -- Edit the service and remove the path from the "Block Paths" field +- Edit the service and remove the path from the "Block Paths" field -- Be more specific with blocked paths (e.g., use `/.git` instead of `/.`) +- Be more specific with blocked paths (e.g., use `/.git` instead of `/.`) -- Consider using path-based routing to a separate service with different security settings - - - +- Consider using path-based routing to a separate service with different security settings + + + ##### Issue: HSTS causing problems after disabling HTTPS - - + + -**Problem:** After enabling HSTS, browsers remember to use HTTPS. If you later disable HTTPS, users cannot access the site. +**Problem:** After enabling HSTS, browsers remember to use HTTPS. If you later disable HTTPS, users cannot access the site. -**Solution:** - +**Solution:** + -- For affected users: Clear browser cache and HSTS data for the domain +- For affected users: Clear browser cache and HSTS data for the domain -- In Chrome: Visit `chrome://net-internals/#hsts` and delete the domain +- In Chrome: Visit `chrome://net-internals/#hsts` and delete the domain -- In Firefox: Clear "Site Preferences" or all history +- In Firefox: Clear "Site Preferences" or all history -- Prevention: Use short HSTS duration (1 day) for testing before committing to longer values - - - +- Prevention: Use short HSTS duration (1 day) for testing before committing to longer values + + + ##### Issue: Compression not reducing response sizes - - + + -**Possible causes:** - +**Possible causes:** + -- Content is already compressed (images, videos, PDFs) +- Content is already compressed (images, videos, PDFs) -- Responses are too small to benefit from compression +- Responses are too small to benefit from compression -- Client doesn't advertise gzip support - +- Client doesn't advertise gzip support + -**Solution:** - +**Solution:** + -- Compression only works for text-based content (HTML, CSS, JS, JSON, XML) +- Compression only works for text-based content (HTML, CSS, JS, JSON, XML) -- Verify the client sends `Accept-Encoding: gzip` header +- Verify the client sends `Accept-Encoding: gzip` header -- Check response headers for `Content-Encoding: gzip` - - - +- Check response headers for `Content-Encoding: gzip` + + + ### 10. Glossary - - + + - + -| - Term | - Definition | - +| + Term | + Definition | -| - **VIP (Virtual IP)** | - A floating IP address that clients connect to. Managed by OVN and routes to HAProxy instances. | - -| - **Backend** | - A server that receives traffic from HAProxy. Also called "upstream server" or "real server". | - +| + **VIP (Virtual IP)** | + A floating IP address that clients connect to. Managed by OVN and routes to HAProxy instances. | -| - **Frontend** | - The HAProxy component that accepts client connections (VIP + port + rules). | - -| - **SNI (Server Name Indication)** | - A TLS extension that allows clients to specify the hostname they're connecting to, enabling multiple HTTPS sites on one IP. | - +| + **Backend** | + A server that receives traffic from HAProxy. Also called "upstream server" or "real server". | -| - **SSL Termination** | - The process of decrypting SSL/TLS traffic at the load balancer, allowing it to inspect and modify HTTP content. | - -| - **SSL Passthrough** | - Forwarding encrypted traffic directly to backends without decryption at the load balancer. | - +| + **Frontend** | + The HAProxy component that accepts client connections (VIP + port + rules). | -| - **Health Check** | - Periodic test to verify a backend server is functioning correctly. | - -| - **Sticky Session** | - A mechanism ensuring requests from the same client go to the same backend server. | - +| + **SNI (Server Name Indication)** | + A TLS extension that allows clients to specify the hostname they're connecting to, enabling multiple HTTPS sites on one IP. | -| - **Round Robin** | - A load balancing algorithm that distributes requests evenly in sequence. | - -| - **OVN (Open Virtual Network)** | - Software-defined networking system used by INCUS for network virtualization. | - +| + **SSL Termination** | + The process of decrypting SSL/TLS traffic at the load balancer, allowing it to inspect and modify HTTP content. | -| - **Layer 4** | - Transport layer (TCP/UDP) - load balancing based on IP and port. | - -| - **Layer 7** | - Application layer (HTTP) - load balancing based on content, headers, URLs. | - +| + **SSL Passthrough** | + Forwarding encrypted traffic directly to backends without decryption at the load balancer. | -| - **HSTS** | - HTTP Strict Transport Security - a security header that tells browsers to only connect via HTTPS. | - -| - **Rate Limiting** | - Restricting the number of requests a client can make within a time period to prevent abuse. | - +| + **Health Check** | + Periodic test to verify a backend server is functioning correctly. | -| - **X-Frame-Options** | - HTTP header that controls whether a page can be displayed in an iframe, preventing clickjacking attacks. | - -| - **X-Content-Type-Options** | - HTTP header that prevents browsers from MIME-sniffing a response away from the declared content type. | - +| + **Sticky Session** | + A mechanism ensuring requests from the same client go to the same backend server. | -| - **X-Forwarded-For** | - HTTP header containing the original client IP address when requests pass through proxies. | - -| - **Gzip Compression** | - A compression algorithm that reduces the size of text-based HTTP responses to save bandwidth. | - +| + **Round Robin** | + A load balancing algorithm that distributes requests evenly in sequence. | -| - **429 Too Many Requests** | - HTTP status code returned when a client exceeds the configured rate limit. | - -| - **403 Forbidden** | - HTTP status code returned when access to a resource is denied (e.g., blocked path or user agent). | - +| + **OVN (Open Virtual Network)** | + Software-defined networking system used by INCUS for network virtualization. | + + +| + **Layer 4** | + Transport layer (TCP/UDP) - load balancing based on IP and port. | + + +| + **Layer 7** | + Application layer (HTTP) - load balancing based on content, headers, URLs. | + + +| + **HSTS** | + HTTP Strict Transport Security - a security header that tells browsers to only connect via HTTPS. | + + +| + **Rate Limiting** | + Restricting the number of requests a client can make within a time period to prevent abuse. | + + +| + **X-Frame-Options** | + HTTP header that controls whether a page can be displayed in an iframe, preventing clickjacking attacks. | + + +| + **X-Content-Type-Options** | + HTTP header that prevents browsers from MIME-sniffing a response away from the declared content type. | + + +| + **X-Forwarded-For** | + HTTP header containing the original client IP address when requests pass through proxies. | + + +| + **Gzip Compression** | + A compression algorithm that reduces the size of text-based HTTP responses to save bandwidth. | + + +| + **429 Too Many Requests** | + HTTP status code returned when a client exceeds the configured rate limit. | + + +| + **403 Forbidden** | + HTTP status code returned when access to a resource is denied (e.g., blocked path or user agent). | + + + + - - - **Need more help?** Contact your AETHER administrator or refer to the official HAProxy documentation at haproxy.org for advanced configuration options.