Guides / Load balancing
Balance traffic and accept it at the edge
Use a LoadBalancer to spread traffic over backends, which can be your processes, members of a VPC or plain addresses. Use an Ingress as the entry point that accepts traffic and hands it to backends or to a load balancer. Both work at any of three levels and over IPv6 alone. They run as Compute processes on your VPC.
Access is by invitation. To ask for it, write to us. Until the engine is enabled for your project, a new load balancer or ingress stays Pending with reason EngineNotAvailable and carries no traffic.
This guide describes what the two resources accept and what the engine does with them. The engine relays TCP at L4, routes HTTP/1.1 at L7, and forwards L3 and UDP packets. It probes backends over TCP, HTTP and ICMP, and terminates TLS 1.2 and 1.3. It speaks HTTP/1.1 only, uses generated or stored certificates, and drops ICMPv6 errors at L3.
Pick a level
| Level | It sees | Use it for |
|---|---|---|
l3 | IP packets: addresses, protocol, ports when present | Anything that is not plain TCP or UDP. A flow always goes to the same backend; ICMP errors follow their flow. |
l4 | TCP connections and UDP datagrams, on the listeners you declare | Databases, queues, game servers, any TCP or UDP service. |
l7 | HTTP requests | Web services: every request is balanced, health checks can use HTTP, a header or cookie can pin a client to a backend. On an ingress: rules by host, path and header, and TLS. |
1. Create a load balancer
kubectl apply -f - <<EOF
apiVersion: edge.etorm.com/v1alpha1
kind: LoadBalancer
metadata: {name: web}
spec:
vpcRef: {name: lan}
level: l7
listeners: [{protocol: http, port: 80}]
algorithm: leastConnections
backends:
- {processRef: {name: web-0}, port: 8080}
- {processRef: {name: web-1}, port: 8080, weight: 2}
healthCheck: {protocol: http, path: /healthz}
EOF
kubectl get loadbalancer web
- A backend is exactly one of
processRef,accountReforaddress(IPv6, or IPv4 only when the VPC has an IPv4 network).weight: 0drains it. algorithmisroundRobin(weighted),leastConnections, orhashonsource,flow,header:<Name>orcookie:<name>. Removing a backend moves only the clients that were on it. Level l3 always useshash.- A backend is
UpafterhealthyThresholdgood probes in a row andDownafterunhealthyThresholdbad ones. Before the first probe it isUnknownand is used as if it were up. When every backend is down, new traffic is refused rather than sent to a dead backend. status.addresseslists each node's IPv6 address.status.backendsshows each backend's address, port and state, and why it is down.
2. Accept traffic with an ingress
kubectl apply -f - <<EOF
apiVersion: edge.etorm.com/v1alpha1
kind: Ingress
metadata: {name: site}
spec:
vpcRef: {name: lan}
level: l7
listeners:
- {protocol: http, port: 80}
- {protocol: https, port: 443, tls: {certificateRef: {name: site}}}
rules:
- {host: shop.example.com, pathPrefix: /api, target: {processRef: {name: web-0}, port: 8080}}
- {host: "*.example.com", target: {loadBalancerRef: {name: web}}}
defaultTarget: {address: "fd00::99", port: 9000}
EOF
- The first rule that matches decides.
hostis exact or*.name.pathPrefix: /apimatches/apiand/api/xbut not/apix.pathis exact. Everyheadersentry must be present with that value. A request that matches no rule goes todefaultTarget, or gets a 404 if there is none. - At
l4every listener names its owntarget. Atl3the onetargetreceives every packet that arrives at the ingress addresses. - A target is a load balancer, a process, a VPC member or an address. When it is a load balancer the traffic goes to that balancer's nodes and the port defaults to its first listener port.
3. Give an HTTPS listener a certificate
kubectl apply -f - <<EOF
apiVersion: edge.etorm.com/v1alpha1
kind: Certificate
metadata: {name: site}
spec:
domains: [shop.example.com, "*.shop.example.com"]
EOF
An https listener on an l7 ingress terminates TLS 1.3 and 1.2 in the ingress node, with rustls (written in Rust), and offers HTTP/1.1 only. The private key never appears in any object, log or response. Only the fingerprint and expiry are shown.
With source: generated, the default, each ingress node makes its own key and a self-signed certificate for the domains, valid 90 days. The key stays inside the node, and you have to tell clients to trust the certificate.
With source: stored, you supply the certificate chain and the private key, both PEM, as two objects in a bucket of your project:
spec:
source: stored
domains: [shop.example.com]
stored: {bucketRef: {name: certs}, certificateKey: shop/chain.pem, privateKeyKey: shop/key.pem}
We encrypt both objects in the bucket, and the ingress nodes read them with their own access. The key is never copied anywhere else.
A Certificate is Pending (NotInUse or Waiting), Ready (fingerprint and expiry shown) or Failed (with the reason, never key text). An ingress whose https certificate is Pending or Failed is Degraded with reason CertificateNotReady, and its http listeners keep serving. A listener holds one certificate, generated or stored. There are no client certificates and no HTTP/2.
How nodes, billing and roles work
nodes(1 to 5) runs that many processes, namedlb-<name>-<n>oring-<name>-<n>, each with its own address. They share no state.- Load balancers and ingresses are billed per hour. Their node processes are metered by Compute as well.
- The role
edge-adminmanages load balancers and ingresses, andedge-viewerreads them. The built-ineditorrole can also manage them. - Deleting a load balancer or ingress deletes its nodes. An ingress whose target has gone shows that target as
Downwith reasonNotFound.
Backends that follow a service
A backend or target can name a Database (its primary) or a MessageBroker (its serving node) with databaseRef or brokerRef instead of a fixed address. The address is read from the service on every pass, so you do not have to edit the backend when it changes.
Clean up
kubectl delete ingress site kubectl delete loadbalancer web kubectl delete certificate site
Next
Run a program as a process to give the balancer backends, or find out why something stays Pending.