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

LevelIt seesUse it for
l3IP packets: addresses, protocol, ports when presentAnything that is not plain TCP or UDP. A flow always goes to the same backend; ICMP errors follow their flow.
l4TCP connections and UDP datagrams, on the listeners you declareDatabases, queues, game servers, any TCP or UDP service.
l7HTTP requestsWeb 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

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

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

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.