Resources / LoadBalancer

LoadBalancer

A load balancer: spreads traffic over backends at L3 (IP packets per flow), L4 (TCP connections and UDP datagrams) or L7 (HTTP requests), with health checks, on nodes that run as Compute processes on a VPC. It serves once its engine is available on the platform; until then it stays Pending with reason EngineNotAvailable. Works over IPv6 alone.

Overview

APIedge.etorm.com/v1alpha1
Resourceloadbalancers (cluster-scoped inside its cluster)
Short nameslb
Available inproject clusters only
Statuswritten by a controller through /status

Minimal example

apiVersion: edge.etorm.com/v1alpha1
kind: LoadBalancer
metadata:
  name: example
spec:
  vpcRef:
    name: "<name>"

Spec

FieldTypeRequiredDefaultAllowedDescription
monitoringRefreference to MonitoringWorkspaceOptional MonitoringWorkspace to send L3/L4/L7 flow and latency telemetry to.
vpcRefreference to VPCyesThe VPC the nodes and the backends are on. Cannot be changed.
levelstring (one of)"l4"l3, l4, l7l3 forwards IP packets per flow; l4 balances TCP connections and UDP datagrams on listeners; l7 balances HTTP requests. Cannot be changed.
algorithmstring (one of)roundRobin, leastConnections, hashroundRobin (weighted), leastConnections (active connections per weight) or hash (consistent hashing on hashKey). Defaults to roundRobin; l3 always hash.
hashKeystringup to 80 charactersFor hash: source, flow (default for l3 and l4), header:<Name> or cookie:<name> (l7 only).
protocolslist of stringup to 4 itemsl3: which IP protocols are forwarded. Defaults to all.
listenerslist of objectup to 8 itemsl4 and l7: the ports the balancer accepts on.
listeners[].namestringup to 63 charactersName of the listener, unique; defaults to <protocol>-<port>.
listeners[].protocolstring (one of)yestcp, udp, httpProtocol the listener accepts.
listeners[].portintegeryes1 to 65535Port the listener accepts on.
listeners[].targetPortinteger1 to 65535Port to connect to on the backend; defaults to port.
backendslist of objectup to 64 itemsWhere traffic goes: processes, VPC members or addresses.
backends[].namestringup to 63 charactersName of the backend, unique in the balancer; defaults to b<index>.
backends[].processRefobjectA Compute process: traffic goes to its first interface on the VPC.
backends[].processRef.namestringyeslength 1 to 63Name of the process.
backends[].accountRefobjectA VPC member (Account).
backends[].accountRef.namestringyeslength 1 to 63Name of the account.
backends[].addressstringup to 45 charactersAn IPv6 or IPv4 address literal. IPv4 only when the VPC has an IPv4 network.
backends[].portinteger1 to 65535The backend's port. Defaults to the listener's targetPort.
backends[].weightinteger10 to 256Share of the traffic. 0 drains: no new flows, existing ones continue.
backends[].databaseRefobjectA Database of this project: traffic goes to the node that has the role now (so it follows a failover). The port defaults to the database port.
backends[].databaseRef.namestringyeslength 1 to 63Name of the database.
backends[].databaseRef.rolestring (one of)yesprimary, replicasprimary (the node that accepts writes) or replicas (the read-only nodes, else the primary).
backends[].brokerRefobjectA MessageBroker of this project: traffic goes to the node(s) that serve now. The port defaults to the first protocol port the node offers.
backends[].brokerRef.namestringyeslength 1 to 63Name of the message broker.
backends[].brokerRef.rolestring (one of)yesserving, endpointsserving (the node that serves now) or endpoints (every node).
healthCheckobject{}How backends are probed. A backend is Up after healthyThreshold successes in a row and Down after unhealthyThreshold failures in a row.
healthCheck.protocolstring (one of)tcp, http, icmp, nonetcp connects; http requests path and expects a 2xx or 3xx answer; icmp pings; none never probes. Defaults to icmp for l3 and tcp otherwise.
healthCheck.portinteger1 to 65535Port to probe; defaults to the backend's port.
healthCheck.pathstring"/"up to 512 charactersPath for http probes.
healthCheck.intervalSecondsinteger51 to 300Seconds between probes.
healthCheck.timeoutSecondsinteger21 to 60Seconds before a probe fails.
healthCheck.healthyThresholdinteger21 to 10Successes in a row to become Up.
healthCheck.unhealthyThresholdinteger31 to 10Failures in a row to become Down.
nodesinteger11 to 5How many nodes run the data plane. Each has its own address; any node accepts any traffic and they agree on every choice.
affinityGroupstringup to 63 charactersRun the nodes on the same host as every other process of the project with this affinity group (for example the backends the balancer reaches while no path joins two hosts). Without it the nodes are spread over different hosts.
maxNodesinteger1 to 5The most nodes the platform may run by itself. When the nodes refuse connections (condition Saturated) the platform raises spec.nodes by one, with a cooldown, up to this number. Unset, it never changes spec.nodes.
resourcesobject{}What each node may use.
resources.memoryPowerinteger60 to 10Memory per node: 64 KiB times two to this power (6 is 4 MiB).
resources.cpuMillicoresinteger2501 to 1000Processor time per node on average, in thousandths of a core.

Status

FieldTypeRequiredDefaultAllowedDescription
phasestringPending, Ready, Degraded (some nodes are not running, or no backend is up) or Failed.
addresseslist of stringWhere clients send traffic: every node's IPv6 address, then IPv4 addresses when present.
endpointslist of objectOne entry per node.
endpoints[].processstringThe node's process.
endpoints[].addressstringIts IPv6 address on the VPC.
endpoints[].portslist of integerPorts it accepts on.
loadobjectWhat the nodes report about refused connections (condition Saturated). Written when a node's report changes, not on every connection.
load.refusedRecentintegerConnections refused in the last minute, over all nodes.
load.refusedTotalintegerConnections refused since the nodes started.
load.backlogintegerThe most idle listening sockets per listener any node keeps (nodes raise it by themselves while they refuse).
load.atLimitbooleanA node is refusing at its own limit; only more nodes help.
planstringDigest of the plan the nodes run; changes whenever the configuration they get changes.
conditionslist of objectDetailed state, one entry per aspect; Ready says whether the traffic is being served.
conditions[].typestringAspect.
conditions[].statusstringTrue or False.
conditions[].reasonstringMachine-readable reason.
conditions[].messagestringHuman-readable detail.
backendslist of objectEach backend as the nodes see it.
backends[].namestringBackend name.
backends[].addressstringResolved address.
backends[].portintegerPort.
backends[].statestringUp, Down, Draining (weight 0) or Unknown (not probed yet).
backends[].reasonstringWhy it is Down or Unknown.
healthyBackendsintegerHow many backends are Up or Unknown and take new traffic.

Columns in listings

ColumnFrom
Level.spec.level
Algorithm.spec.algorithm
Address.status.addresses[0]
Healthy.status.healthyBackends
Phase.status.phase

Related guides

All resources