LoadBalancer

A LoadbalancerInstance (LBI) is a managed HAProxy load balancer in Polycrate with a dedicated public IP from IPAM, deployed multi-site across regions via the block rollout system. This page covers features, architecture, conditions, setup, metrics, endpoints and HAProxy system defaults.

LoadBalancer

A LoadbalancerInstance (LBI) is a logical HAProxy load balancer that is managed in Polycrate as a managed object. It belongs to an organization and workspace, receives a public IP from IPAM and is deployed multi-site via Regions.

Deployment runs through the block rollout system — no longer via K8sApp as the critical path.

What an LBI can do

Feature Description
Dedicated public IP IPAM assignment; API field ip_address_value (flat, copyable)
Multiple ports Port mappings incl. API field wizard_ports (HAProxy config is generated)
Free-form config Additional HAProxy fragment
Endpoints Health probes; detail UI with Endpoints tab
Metrics Billing-relevant traffic instant values (30d); charts on demand
Multi-region One deployment per region with a block in the region workspace

Architecture

LoadbalancerInstance (Org + Workspace)
│
├── ip_address → IPAM
├── ports / wizard_ports / config
│
└── Deployments (1..n)
      └── LoadbalancerInstanceDeployment
            ├── region → Region (or legacy LoadbalancerRegion bridge)
            ├── block  → Block in region.workspace (HAProxy)
            └── rollout_item → BlockRolloutItem

Desired state vs. rollout

  1. LBI reconciliation sets the desired state (block config, labels, checksums) and on drift enqueues block.enqueue_action('install').
  2. The BlockRollout scheduler (approx. 5s tick) dispatches the ActionRuns and writes the deployed checksum back after completion.
  3. Soft-delete: DELETE starts cleanup/uninstall via the same rollout path.

Conditions

Condition Severity Meaning
LOADBALANCER_NO_HEALTHY_DEPLOYMENTS CRITICAL No region deployment installed/serving
LOADBALANCER_DEPLOYMENTS_PENDING WARNING Checksum drift or running installs

Checksum drift alone does not lead to CRITICAL as long as deployments are installed and serving traffic. Details: Conditions.

Creating & configuring

  1. LoadBalancer → New (organization + workspace)
  2. Select an IP from IPAM (or have one assigned)
  3. Set ports / wizard_ports — config is regenerated
  4. Select target regions — deployments and blocks are created via reconciliation
  5. Optionally attach Endpoints

New instances start with state=WARNING (Provisioning in progress) until reconciliation and rollout deliver state=OK and an IP.

Via the API: api/v1/loadbalancers/... (basename loadbalancerinstance).

Metrics

Billing and list metrics come from hourly metrics beats (not from the 60s reconcile):

Metric Meaning
30d traffic (in/out) Instant aggregate for billing and UI

Older 24h bandwidth/connection median fields have been removed. Charts can still be loaded on demand from VictoriaMetrics — see Metrics.

Endpoints for health

At least one endpoint (e.g. HTTPS to the public IP) controls reachability and contributes to the object state. State updates from agent check results can take effect immediately (hot path), not only on the next reconcile tick.

HAProxy system defaults (as of API 0.32.0)

The generated default config uses long client/server/tunnel timeouts so that long-lived TCP connections (SSH, DB, WebSockets) do not drop after one minute. Values come from SystemConfig and fall back to code defaults for invalid entries:

Key Default
LOADBALANCER_HAPROXY_MAXCONN 10000
LOADBALANCER_HAPROXY_TIMEOUT_CONNECT 5s
LOADBALANCER_HAPROXY_TIMEOUT_CLIENT 24h
LOADBALANCER_HAPROXY_TIMEOUT_SERVER 24h
LOADBALANCER_HAPROXY_TIMEOUT_TUNNEL 24h

Changes to these keys create config drift and trigger an LBI rollout. Region-specific workload settings (region_config.haproxy) remain separate.

Related topics