---
title: "Load balancers"
description: "Expose Services through EZGH load balancers with LoadBalancer Services, Ingress and the Gateway API."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Load balancers

A cluster creates [EZGH load balancers](/load-balancers) for you, in your project and the cluster's
VPC, as its cluster bot. You install no controller. Load balancers are billed as load balancers.

| Kubernetes object | Load balancer |
| --- | --- |
| A `LoadBalancer` Service | One TCP load balancer; each Service port is a listener |
| An Ingress with `ingressClassName: ezgh` | One HTTP load balancer; Ingresses can share one |
| A Gateway with `gatewayClassName: ezgh` | One HTTP load balancer per Gateway |

Every load balancer a cluster creates is public. Each holds a public IPv4 address, which counts against
your [IPv4 address quota](/quotas/default-quotas).

## Targets are pods

Load balancers send traffic straight to pod addresses, never through NodePorts. Targets follow the
Service's endpoints as pods come and go, and each is an IPv4 address. Targets are registered one at a
time, so a large rollout reaches the load balancer gradually.

Each pod created behind a load-balanced Service gets a readiness gate,
`target-health.lb.ezghcloud.com/<Service name>`. The pod isn't Ready until the load balancer's health
checks pass on it, so a rolling deploy waits for each new pod and drops no requests. Pods that existed
before the Service don't have the gate.

## LoadBalancer Services

```yaml
apiVersion: v1
kind: Service
metadata:
  name: shop
spec:
  type: LoadBalancer
  selector:
    app: shop
  ports:
    - port: 443
      targetPort: 8443
```

The Service's `status.loadBalancer` gets the load balancer's address once it's `active`, which takes a
few minutes. Deleting the Service deletes the load balancer.

These annotations on the Service set up its load balancer. An annotation that can't be used is
reported as an event on the Service, and the Service's load balancer isn't changed.

| Annotation | |
| --- | --- |
| `lb.ezghcloud.com/tls-ports` | Ports, comma-separated, whose listeners terminate TLS. Needs `certificates` |
| `lb.ezghcloud.com/certificates` | [Certificates](/load-balancers/tls) (`crt_…`), comma-separated |
| `lb.ezghcloud.com/proxy-protocol` | `v2` sends proxy protocol v2 to the pods. Default `none` |
| `lb.ezghcloud.com/allowed-source-cidrs` | The CIDRs allowed in, comma-separated. `spec.loadBalancerSourceRanges` works too |
| `lb.ezghcloud.com/subnet` | The subnet (`sbn_…`) for the load balancer. Default the cluster's |
| `lb.ezghcloud.com/ipv4-address` | A public IPv4 address (`pip_…`) of yours to use. It can't change once the load balancer exists |
| `lb.ezghcloud.com/idle-timeout-seconds` | The listeners' idle timeout |
| `lb.ezghcloud.com/deregistration-delay-seconds` | How long a removed pod's connections drain |
| `lb.ezghcloud.com/healthcheck-protocol` | `tcp`, `http` or `https` |
| `lb.ezghcloud.com/healthcheck-port`, `healthcheck-path`, `healthcheck-matcher` | The health check's port, path and the status codes that pass |
| `lb.ezghcloud.com/healthcheck-interval-seconds`, `healthcheck-timeout-seconds` | How often, and how long each check waits |
| `lb.ezghcloud.com/healthcheck-healthy-threshold`, `healthcheck-unhealthy-threshold` | Checks in a row that make a target healthy or unhealthy |

An annotation left out takes the [listener and target group defaults](/load-balancers/target-groups).

A load balancer has at most 10 listeners, and a target group at most 500 targets. Only TCP ports are
served: a UDP or SCTP port gets no listener, and an event on the Service names it.

## Ingress

An Ingress with `ingressClassName: ezgh` becomes an HTTP load balancer with a rule for each path:

- An http listener on port 80, always. An https listener on port 443 once the Ingress names a
  certificate: a `kubernetes.io/tls` Secret in `spec.tls`, which is imported into Web Certificates, or
  certificates (`crt_…`) in `lb.ezghcloud.com/certificates`.
- `lb.ezghcloud.com/ssl-redirect: "true"` makes port 80 redirect to https (`301`).
- `Exact` paths match exactly; `Prefix` and `ImplementationSpecific` paths are prefixes. A request no
  rule matches goes to the `defaultBackend`, or gets a `404`.
- Ingresses in one namespace with the same `lb.ezghcloud.com/group` share one load balancer. An Ingress
  without it has a load balancer of its own.

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: shop
  annotations:
    lb.ezghcloud.com/ssl-redirect: "true"
spec:
  ingressClassName: ezgh
  tls:
    - hosts: [shop.example.com]
      secretName: shop-tls
  rules:
    - host: shop.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: storefront
                port:
                  number: 80
```

The load balancer sends HTTP to the pods, so the backend is an HTTP port of a ClusterIP Service.

## Gateway API

The `ezgh` GatewayClass passes the Gateway API core conformance tests. Each Gateway is one load
balancer, and HTTPRoutes become its rules.

- Listeners are `HTTP` or `HTTPS`; `TLS`, `TCP` and `UDP` listeners aren't accepted, and nor is
  `spec.addresses`.
- An `HTTPS` listener's certificate comes from a `kubernetes.io/tls` Secret in `certificateRefs`,
  imported into Web Certificates as a certificate the Gateway owns, or from certificates (`crt_…`) in
  its `tls.options` under `lb.ezghcloud.com/certificates`. A Secret in another namespace needs a
  ReferenceGrant.
- Besides the core features, the GatewayClass supports method and query parameter matches, response
  header modification, and path, port, scheme, `307` and `308` redirects.
- A rule with a match or filter that isn't supported is dropped, and the route says so in its status
  (`PartiallyInvalid`, or not `Accepted` when nothing is left).

## Not supported

- URL rewrites and regular-expression path matches
- GRPCRoute
- HTTP/2 to targets
- UDP

Source: https://docs.ezghcloud.com/kubernetes/load-balancers/index.mdx
