SYS.DOCS // DOCS

Gateway API

The Gateway page shows how traffic reaches your cluster: each gateway class, the addresses it answers on, and every service exposed through it with its request rate, p95 latency, error rate, and backend health. Envoy Gateway is the controller behind public exposure and custom domain routing. MetalLB adds private VIP-backed gateway classes on the cluster private subnet, the Cloudflare connector advertises that subnet through Cloudflare Zero Trust, and the Tailscale operator publishes gateway classes into your tailnet. The deprecated ingress-nginx controller still runs for existing installs.

The page has three tabs: Overview, Metrics, and Logs. Overview works on every cluster. Metrics and Logs read from the Observability add-on.

Overview

Gateway classes

Each gateway class is a tile with:

Its addresses, labelled by the DNS record type they belong in: A, AAAA, or CNAME.
Requests per second, p95 latency, and the 5xx error rate, from the Envoy proxy behind the class.
A sparkline of the request rate over the last 30 minutes.
The number of services and domains routed through the class, and any setting that differs from the defaults, such as a 60 second timeout or two replicas.

The class name opens the class page. Settings on the tile opens the class settings directly.

Create gateway class adds a new entry point. A class is backed by a public cloud load balancer, a private cloud load balancer, a MetalLB private VIP, or your tailnet through Tailscale. Each class receives its own addresses once the load balancer is ready.

Services

The services table lists every deployment and app exposed through a gateway class, and any that are not exposed yet.

Column	Value
Host	The hostname, linked
Gateway class	The class the route is attached to
req/s	Requests per second reaching this service’s `HTTPRoute`
p95	95th percentile latency for those requests
errors	Share of requests answered with a 5xx status. Hover for the 4xx share
Backends	Healthy backends out of the total behind the route
TLS	Certificate state and days until it expires

Rows with errors or unhealthy backends sort to the top. Errors filters to those rows, Not exposed to services reachable only inside the cluster, and the search box matches service names and hostnames.

Edit opens the service’s own settings: the deployment’s Access tab, the app’s Settings › Access section, or the agent’s settings page. Expose on an internal service opens the same place.

Gateway class pages

Each gateway class has its own page with four tabs.

Overview shows the live numbers for the class: requests per second, p95 latency with p50 and p99, the 5xx and 4xx shares, open client connections, and throughput. Below them are the request rate chart, the services table for this class only, and the domains that use the class.
Metrics and Logs are the page-level tabs, scoped to this class.
Settings holds the class policies and proxy scheduling. Save settings applies every changed value in one step, and Reset discards the edits.

The header shows the class addresses with a copy button next to each, and one line with the settings the class runs with.

To delete a class other than the primary one, use Delete gateway class at the bottom of its Settings tab. The button stays disabled while domains, deployments, or apps still use the class, and the card names them.

Components

The last table on the Overview tab lists Envoy Gateway and the add-ons that back private and tailnet classes, with version, status, what each is in use by, and Install, Upgrade, or Uninstall. Upgrading rolls the Envoy proxies out again; existing classes and routes are kept.

MetalLB allocates private VIPs from the cluster private subnet for gateway classes and service-level private LoadBalancers.
Cloudflare connector advertises that same private subnet through Cloudflare Zero Trust.
Tailscale operator publishes selected gateway classes into your tailnet or exposes workloads directly with the tailscale ingress class.

Metrics

The Metrics tab charts gateway traffic over a window from 5 minutes to 7 days, for all gateway classes or one of them.

Requests by status class (2xx, 3xx, 4xx, 5xx)
Latency at p50, p95, and p99
Bandwidth in and out
Upstream failures: timeouts, retries, resets, and pending overflow
Proxy CPU and memory, with Envoy’s own heap size alongside the working set
New connections by HTTP version, and connections the client closed while a request was still in flight
TLS handshakes, session reuse, and handshake failures

The strip above the charts shows the current request rate, 5xx rate, p50, p95, p99, bandwidth, connections, CPU, memory, and the number of days until the soonest certificate served by the class expires.

Below the charts, a table lists every HTTPRoute with traffic in the window: host, route, requests per second, 5xx rate, and p95. Click a route to open its own charts under the row: backend responses by status class, backend latency at p50, p95, and p99, upstream failures, and backends (total, healthy, and requests in flight). These come from the route’s upstream side, so they show what the backend answered. Responses Envoy sends itself, such as a 429 from the class rate limit, stay in the class charts and in Logs.

Logs

The Logs tab searches Envoy access logs. Filter by gateway class, host, status class, and path, over a window from 5 minutes to 24 hours. The strip at the top ranks paths by 5xx count, then by volume. The table shows the newest 300 matching requests with status, method and path, host, duration, bytes sent, the client address, and Envoy’s response flags. Narrow the filters to see requests beyond the newest 300.

Response flags

The Flags column is empty when the backend answered normally. Otherwise it carries Envoy’s short code for what ended the request. Hover a flag for its meaning. The ones you are most likely to see:

Flag	Meaning
RL	Rate limited by the class rate limit, answered with 429
UAEX	Denied by the class allowlist, answered with 403
UT	The backend did not answer within the class request timeout
UH	No healthy backend behind the route
UF	Envoy could not connect to the backend
UO	The backend circuit breaker is open
URX	The backend retry limit was exceeded
NR	No route matched the request
DC	The client closed the connection before the response finished
DPE	The request from the client was malformed
LR	Envoy reset the connection

The full list is in the Envoy access log reference.

Cluster Overview integration

When a cluster has Gateway API controllers available, the Overview tab’s Infrastructure Topology panel surfaces each gateway class with:

The primary endpoints for the primary gateway class.
A compact aggregate traffic readout with requests/s, 5xx, latency, and connections.

Gateway classes and traffic classes

Edka uses traffic classes to select how workloads are exposed.

The primary Envoy Gateway class is eg.
Additional gateway classes can be created for:
- dedicated public cloud load balancers
- dedicated private cloud load balancers
- MetalLB private VIP endpoints on the cluster private subnet
- private tailnet traffic exposure with Tailscale tailnet (BYOD)
Each class receives its own public IPs or private VIP once provisioning finishes.

Deployments and managed domains then target the appropriate traffic class. Wildcard domains and DNS-validated hostname domains work with public or private Gateway API classes. HTTP-validated hostname domains require a public class.

Class policies

Each gateway class carries three policies that apply to every service routed through it: the request timeout, a rate limit, and an allowlist. All three are on the class’s Settings tab, under Requests and Access.

Rate limit

The limit counts requests per client IP, per second or per minute. Requests over the limit get a 429 response. Leave the field empty for no limit.

Edka writes the limit as a local rate limit on the class’s BackendTrafficPolicy. Local means each Envoy replica keeps its own counters, so a class running two replicas admits up to twice the configured rate for one client. Public classes see the real client address through the proxy protocol on the Hetzner load balancer. On tailnet classes the counter is keyed by the tailnet address of the client. On self-hosted clusters, and on private VIP classes, it is keyed by the address the connection arrives from, so clients behind one proxy or NAT share a counter.

Allowlist

The allowlist is a set of IPv4 or IPv6 CIDRs. When it has at least one entry, only clients inside those ranges reach the class; everyone else gets a 403 on both the HTTP and HTTPS listeners. Use my IP adds the range of the browser’s current address. Leave the list empty to allow every client.

Edka writes the allowlist as a SecurityPolicy on the class’s Gateway with a default deny action and one allow rule. Clearing the list deletes the policy.

The allowlist also answers Let’s Encrypt when it validates a hostname domain over HTTP, so the validation cannot pass. Saving an allowlist is refused while the class has domains using HTTP validation; the message names them. Switch those domains to DNS validation first. Wildcard domains always use DNS validation and are not affected.

Both policies stay on the primary class across Envoy Gateway upgrades.

Request timeout

Envoy Proxy defaults HTTP request timeouts to 15 seconds. Uploads, exports, report generation, or slow upstream work may need longer.

Enter the number of seconds in Request timeout on the class’s Settings tab and save. 0 turns the timeout off. Envoy answers 504 when a backend takes longer than the timeout. Edka stores the value on the managed Envoy Gateway resources and applies it through a BackendTrafficPolicy targeted at that gateway class, so it is the default for every Edka-managed route on the class.

Use this setting instead of patching Edka-managed HTTPRoute resources by hand. Reconciliation can recreate managed routes, while the gateway class timeout stays part of the managed configuration. A custom HTTPRoute you own keeps its own timeout in the manifest you manage.

Proxy scheduling

Each gateway class runs its own Envoy proxy Deployment. The Proxies section of the class’s Settings tab sets how many replicas run, their worker threads, and the node pool they are pinned to.

Replicas

A class runs one Envoy replica by default. Set two or more for high availability: the replicas are kept on separate nodes, roll out one at a time, and carry a disruption budget that keeps at least one proxy running during node drains and upgrades. Traffic keeps flowing while a node fails or is replaced.

Each replica needs its own ready node in the selected placement. Saving is refused when the cluster, or the selected node pool, has fewer schedulable nodes than replicas; the message reports how many it found.

Worker threads

Each proxy runs 2 Envoy worker threads by default. Worker threads accepts 1 to 64. Every worker thread keeps its own connections to the backends, so more threads than the traffic needs means more connections and more reconnects. Two threads carry thousands of requests per second. For more capacity or availability, add replicas. Saving a new value restarts the proxies.

Node pool

Choose a node pool to pin the proxies to dedicated nodes, for example an ingress pool sized for network throughput, or to keep them off a pool reserved for other work. Default placement lets Kubernetes schedule them anywhere. When the pool carries taints, Apply taint tolerations adds matching tolerations; switch it off to keep the proxies off tainted nodes in that pool.

A node pool that still hosts a gateway class cannot be deleted. Move the class to another placement first.

Replicas, worker threads, and placement stay on the primary class across Envoy Gateway upgrades. The Envoy Gateway control plane itself keeps default placement.

DNS and traffic flow

Public gateway classes

Point your domain’s A and AAAA records at the addresses shown on the class tile and the class page.
Wildcard domains and single hostname domains are both supported.
Hostname domains can use HTTP-01 or DNS-01 validation on this path.

MetalLB private VIP gateway classes

Create a gateway class with exposure mode MetalLB private VIP for a private Envoy entry point on the cluster private subnet.
Attach a wildcard domain or DNS-validated hostname domain from Domains for private DNS names and managed TLS on top of that VIP.
Route the cluster private subnet through the Cloudflare connector or your own private network if remote users need access.
HTTP-01 validation is not available on this path because it requires public reachability.

Tailscale tailnet (BYOD)

Create a gateway class with exposure mode Tailscale tailnet (BYOD) for Envoy Gateway routing with private exposure through your tailnet.
Envoy stays in-cluster, and the Gateway service is published to your tailnet through the Tailscale operator. The class shows the tailnet hostname as a CNAME and the tailnet IP as an A record.
Because that traffic class stays private, public Let’s Encrypt HTTP-01 validation is not available on that path. Use DNS-01 for wildcard or hostname domains. If the operator is not installed yet, the Components table shows an install action.

Alerts

The Gateway alert pack watches proxy availability, 5xx rate, p95 latency, rate limiting, backend health per route, upstream timeouts, TLS handshake failures, and certificate expiry. Install it from Observability › Alerts › Packs. The rules are listed in Alerts.

Legacy ingress support

NGINX Ingress is deprecated in Edka. Existing Ingress-based workloads continue to run. Gateway API with Envoy Gateway is the traffic path for all clusters and deployments, and NGINX Ingress will be removed in a future release.