> ## Documentation Index
> Fetch the complete documentation index at: https://datum.net/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Envoy
> How Datum uses the Envoy proxy and Envoy Gateway as the data plane for the Application Load Balancer.
[Envoy](https://www.envoyproxy.io/) is the open source, high-performance proxy that handles Layer 7 traffic on Datum. You use it as Datum's [Application Load Balancer (ALB)](https://datum.net/docs/alb/overview.md). The ALB is built on Envoy and configured through [Envoy Gateway](https://gateway.envoyproxy.io/) and the Kubernetes [Gateway API](https://gateway-api.sigs.k8s.io/). The ALB started life as Datum's "AI Gateway", and it's still built for AI and agent traffic as much as for websites and APIs.
Clients reach Envoy in their nearest Datum location. Envoy serves each request from an Instance in the same location, or from the nearest location that has one.
```mermaid theme={null}
%%{init: {"flowchart": {"subGraphTitleMargin": {"top": 6, "bottom": 18}}}}%%
flowchart TB
B["① browser · West Coast
anycast HTTPS · app.example.com"]
A["① AI agent · Central US
anycast HTTPS · api.example.com"]
M["① mobile app · East Coast
anycast HTTPS · api.example.com"]
subgraph west["us-west-1 · SJC"]
EW["② Envoy · ALB
TLS · WAF · routes · auth
no Instance in this location"]
end
subgraph central["us-central-1 · DFW"]
EC["② Envoy · ALB
TLS · WAF · routes · auth"]
end
subgraph east["us-east-1 · IAD"]
EE["② Envoy · ALB
TLS · WAF · routes · auth"]
end
subgraph vpc["Your gVPC network"]
ID["③ Instance · Dallas
private address :8080"]
IA["③ Instance · Ashburn
private address :8080"]
end
B --> EW
A --> EC
M --> EE
EW -.->|"④ nearest healthy Instance"| ID
EC -->|HTTP · private| ID
EE -->|HTTP · private| IA
classDef box fill:#E6E6E6,stroke:#8A8E99,color:#222
class B,A,M,EW,EC,EE,ID,IA box
style west fill:#EDEDEC,stroke:#8A8E99,color:#B5605E
style central fill:#EDEDEC,stroke:#8A8E99,color:#B5605E
style east fill:#EDEDEC,stroke:#8A8E99,color:#B5605E
style vpc fill:#EDEDEC,stroke:#8A8E99,color:#B5605E
linkStyle 0,1,2,4,5 stroke:#5A5F6B,stroke-width:1.4px
linkStyle 3 stroke:#B5605E,stroke-width:1.6px,stroke-dasharray:6 5
```
## How Datum runs Envoy
Datum runs Envoy as a shared fleet, deployed in every Datum location:
* **One fleet, every customer.** Every location runs a pool of Envoy proxies that serves the ALBs of every customer at once. Datum doesn't run a separate proxy for each ALB, so creating an ALB doesn't wait for new infrastructure to start.
* **Close to your users.** ALB hostnames are anycast. A client's request arrives at the nearest Datum location, and Envoy in that location terminates TLS and handles it. To see which location you reach, visit [edge.datum.net](https://edge.datum.net/).
* **Scales with the network.** Each new Datum location adds Envoy capacity close to the users it serves, and Datum adds proxies within a location as traffic grows. You don't size, place or scale a load balancer yourself.
* **Configured centrally.** You declare an ALB once, in your project. Datum's network services operator turns your resources into Gateway API resources, and Envoy Gateway pushes the resulting configuration to Envoy in every location.
## Into your private network
Envoy is how public traffic reaches your [Compute](https://datum.net/docs/compute/overview.md) Instances, which have private addresses only on your [gVPC](https://datum.net/docs/galactic-vpc/overview.md) network.
For each request, Envoy opens a new connection to a healthy Instance, preferring one in the same location. If the location has no healthy Instance, Envoy sends the request to the nearest location that has one, over Datum's backbone. Datum terminates TLS at Envoy and connects to your Instances over plain HTTP on your private network. For how to publish a workload, see [Compute and ALB](https://datum.net/docs/compute/compute-and-alb.md).
Because the fleet is shared, Envoy must never confuse your network with another customer's, even when both use the same private addresses. Datum handles this below Envoy, in the [Galactic](https://datum.net/docs/platform/galactic.md) network:
* On each Envoy node, a sidecar keeps a Linux VRF, a separate routing table, for each customer network that Envoy connects to.
* When Envoy connects to one of your Instances, its connection is bound to your network's VRF. The packet leaves the node wrapped in an [SRv6](https://datum.net/docs/platform/segment-routing.md) header that identifies your network.
* On the Instance's node, Datum unwraps the packet into your network's routing table only, and delivers it.
Envoy itself only routes HTTP. Isolation between customers comes from the network, not from rules in each proxy.
An ALB can also send traffic to a public origin, such as an existing website, over HTTPS on the internet. The same Envoy fleet serves both kinds of origin.
## Where Envoy fits
When you create an ALB, you describe what you want with Datum resources, and Datum's [network services operator](https://github.com/datum-cloud/network-services-operator) turns them into Envoy configuration:
* **[HTTPProxy](https://datum.net/docs/alb/httpproxy/overview)** is the main resource you write: hostnames, routes, origins, redirects, rewrites, and header changes. Datum's operator turns it into a Gateway API `Gateway` and `HTTPRoute`, and Envoy Gateway programs Envoy from them.
* **[TrafficProtectionPolicy](https://datum.net/docs/alb/configuration/waf.md)** adds the [Coraza](https://www.coraza.io/) web application firewall with the [OWASP Core Rule Set](https://coreruleset.org/), which runs inside Envoy. It inspects requests before they reach your origin and responses before they leave Datum for the client (outbound traffic).
* **Certificates and DNS** for the ALB's hostnames are managed by Datum alongside the Envoy configuration.
For the full picture of the resources behind a load balancer, see [What an ALB is made of](https://datum.net/docs/alb/overview.md#what-an-alb-is-made-of).
## What Envoy gives you
Envoy handles the protocols and traffic features of the ALB, including:
* HTTP/1.1, HTTP/2, gRPC, and WebSockets.
* TLS termination, with certificates that Datum issues and renews.
* Path, header, and query matching, with weighted traffic across several origins.
* Redirects, URL rewrites, and request and response header changes.
* Access logs for every request, including the ones the firewall blocks. See [ALB observability](https://datum.net/docs/alb/observability.md).
## Using Envoy Gateway resources directly
Some advanced features use Envoy Gateway resources (`gateway.envoyproxy.io/v1alpha1`) that you apply to your project with `datumctl`, alongside your `HTTPProxy`:
| Resource | Used for | Guide |
| - | - | - |
| `SecurityPolicy` | Basic authentication and OIDC sign-in | [Basic auth](https://datum.net/docs/alb/authentication/basic-auth.md), [OIDC with Google](https://datum.net/docs/alb/authentication/oidc-google.md), [Auth0](https://datum.net/docs/alb/authentication/oidc-auth0.md) |
| `Backend` and `BackendTrafficPolicy` | Failover between a primary and a fallback origin | [Load balancer failover](https://datum.net/docs/alb/configuration/failover.md) |
Because these are standard Envoy Gateway and Gateway API resources, the upstream [Envoy Gateway documentation](https://gateway.envoyproxy.io/docs/) is a useful reference. Not every upstream feature is available on Datum, so start from the Datum guides.
## Related
* [ALB overview](https://datum.net/docs/alb/overview.md)
* [HTTPProxy](https://datum.net/docs/alb/httpproxy/overview)
* [Platform API](https://datum.net/docs/platform/kubernetes.md) — why Datum's platform and APIs are built on Kubernetes.
* [Galactic](https://datum.net/docs/platform/galactic.md) — the network underneath gVPC.
* [Iroh Relays](https://datum.net/docs/platform/iroh-relays.md) — how tunnels reach Datum's edge.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.