In this tutorial, we'll learn how to install and configure Envoy Proxy on Ubuntu 24.04.
What Is Envoy Proxy and Why Use It?
Envoy is a high-performance, open-source Layer 7 proxy designed for modern cloud-native applications. Originally developed by Lyft, it has grown into one of the most widely adopted proxies for microservices and service mesh architectures.
Key benefits:
- Advanced load balancing: Outlier detection, retries, circuit breaking.
- Service discovery support: Works with Consul, Kubernetes, DNS, and custom SDS.
- First-class observability: Metrics, logging, and distributed tracing.
- HTTP/2 and gRPC support: Ideal for modern APIs.
- Security: mTLS, rate limiting, and RBAC with extensions.
- Service mesh-ready: Core component of Istio and other meshes.
You’ll likely use Envoy when building a large-scale API platform, managing microservice traffic, deploying an edge proxy, or integrating a service mesh.
Prerequisites
Before we begin, ensure we have the following:
- An Ubuntu 24.04 on dedicated server or KVM VPS.
- Basic Linux Command Line Knowledge.
Dependencies:
sudo apt update
sudo apt install -y curl apt-transport-https ca-certificates lsb-release
Install Envoy Proxy on Ubuntu 24.04
The official Envoy packages are distributed through the Tetrate APT repository. This is the recommended and most stable installation method.
Step 1: Install Envoy
Add the Envoy APT repository
wget -O- https://apt.envoyproxy.io/signing.key | sudo gpg --dearmor -o /etc/apt/keyrings/envoy-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/envoy-keyring.gpg] https://apt.envoyproxy.io jammy main" | sudo tee /etc/apt/sources.list.d/envoy.list
Update system packages
sudo apt update
Install Envoy Proxy
sudo apt install -y envoy
Verify installation
envoy --version
Example output:
envoy version: a0504e87c5a246cb097b37049b1e4dc7706c2a90/1.32.2/Clean/RELEASE/BoringSSL
Configure Envoy Proxy (Beginner-Friendly)
Envoy uses YAML-based configuration. The config defines:
- Listeners (incoming traffic)
- Routes (HTTP rules)
- Clusters (upstreams)
- Admin interface
- Load balancing parameters
Create Envoy’s main configuration directory:
sudo mkdir -p /etc/envoy
Example Envoy Configuration (YAML)
Below is a clean and production-friendly starter configuration. This matches the Envoy Proxy configuration Ubuntu requirements and includes load balancing, routes, and admin access.
Create the file:
sudo nano /etc/envoy/envoy.yaml
Paste the following:
static_resources:
listeners:
- name: listener_http
address:
socket_address:
address: 0.0.0.0
port_value: 10000
filter_chains:
- filters:
- name: envoy.filters.network.http_connection_manager
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
stat_prefix: ingress_http
route_config:
name: local_route
virtual_hosts:
- name: backend_service
domains: ["*"]
routes:
- match:
prefix: "/"
route:
cluster: backend_cluster
http_filters:
- name: envoy.filters.http.router
clusters:
- name: backend_cluster
connect_timeout: 1s
type: logical_dns
lb_policy: round_robin
load_assignment:
cluster_name: backend_cluster
endpoints:
- lb_endpoints:
- endpoint:
address:
socket_address:
address: 127.0.0.1
port_value: 8080
admin:
address:
socket_address:
address: 127.0.0.1
port_value: 9901
What this configuration does:
- Listens on 10000 for incoming requests
- Forwards traffic to a local app running on 127.0.0.1:8080
- Enables the Envoy admin panel on port 9901
- Uses round-robin load balancing
- Works out-of-the-box for most dev or testing environments
Step 2: Create systemd unit
Run Envoy as a Systemd Service
To manage Envoy like any other system service, create a systemd file.
sudo nano /etc/systemd/system/envoy.service
Paste:
[Unit]
Description=Envoy Proxy
After=network.target
[Service]
Type=simple
User=root
ExecStart=/usr/bin/envoy -c /etc/envoy/envoy.yaml --log-level info
Restart=on-failure
[Install]
WantedBy=multi-user.target
Step 3: Reload systemd and enable service
sudo systemctl daemon-reload
sudo systemctl enable envoy
sudo systemctl start envoy
Check service status
sudo systemctl status envoy
Step 4: Test Envoy Proxy
Test Listener (Port 10000)
Send a request:
curl -I http://localhost:10000
You should see a response from your backend application.
Test Admin Dashboard (Port 9901)
Visit:
http://127.0.0.1:9901/
The admin UI shows:
- Stats
- Logs
- Listener/cluster info
- Config dump
Common Troubleshooting Issues
1. Envoy fails to start (config errors)
Check syntax:
envoy --mode validate -c /etc/envoy/envoy.yaml
2. Port already in use
Find the conflicting service:
sudo lsof -i :10000
3. DNS resolution issues in clusters
Switch to strict_dns:
type: strict_dns
4. Upstreams returning 503
Check:
- Backend health
- Firewall rules
- Application logs
5. Admin dashboard not loading
Ensure you are accessing from localhost only:
address: 127.0.0.1
Real-world Example
Load Balance /api/orders Across 3 Backend Servers
1. Make sure your backend services are running
Each server must run the same service on the same port.
Example:
All /api/orders services run on port 8080
http://10.0.0.11:8080/api/orders
http://10.0.0.12:8080/api/orders
http://10.0.0.13:8080/api/orders
2. Edit your Envoy configuration
sudo nano /etc/envoy/envoy.yaml
FULL Envoy YAML Example
(Load balancing across 3 servers with round-robin + health checks)
static_resources:
listeners:
- name: listener_http
address:
socket_address:
address: 0.0.0.0
port_value: 10000
filter_chains:
- filters:
- name: envoy.filters.network.http_connection_manager
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
stat_prefix: ingress_http
route_config:
name: local_route
virtual_hosts:
- name: backend_services
domains: ["*"]
routes:
- match:
prefix: "/api/orders"
route:
cluster: orders_cluster
http_filters:
- name: envoy.filters.http.router
clusters:
- name: orders_cluster
type: strict_dns
connect_timeout: 1s
lb_policy: round_robin
load_assignment:
cluster_name: orders_cluster
endpoints:
- lb_endpoints:
- endpoint:
address:
socket_address:
address: 10.0.0.11
port_value: 8080
- endpoint:
address:
socket_address:
address: 10.0.0.12
port_value: 8080
- endpoint:
address:
socket_address:
address: 10.0.0.13
port_value: 8080
health_checks:
- timeout: 1s
interval: 5s
unhealthy_threshold: 2
healthy_threshold: 2
http_health_check:
path: "/health"
expected_statuses:
- start: 200
end: 299
admin:
address:
socket_address:
address: 127.0.0.1
port_value: 9901
Save and exit the file.
3. Create a health endpoint on your backend
Each backend service should have:
GET http://10.0.0.11:8080/health
GET http://10.0.0.12:8080/health
GET http://10.0.0.13:8080/health
Returning:
{"status":"ok"}
Now validate envoy.yaml file:
envoy --mode validate -c /etc/envoy/envoy.yaml
If valid, restart Envoy:
sudo systemctl restart envoy
5. Test load balancing
curl http://localhost:10000/api/orders
Final Thoughts
Envoy Proxy is one of the most powerful tools available for modern distributed systems, whether you’re building an API gateway, reverse proxy, or service mesh environment. With Ubuntu 24.04, installing and managing Envoy is straightforward and stable thanks to official packages and well-documented configuration structures.
This guide provided practical examples, real deployment recommendations, and a ready-to-use configuration to help you get started the right way.
For deeper technical details, always refer to the official documentation:
FAQs
1. Is Envoy better than Nginx?
Envoy offers advanced load balancing, HTTP/2, gRPC, and service mesh capabilities, making it a better choice for modern microservices environments.
2. What port does Envoy use for the admin interface?
By default, 9901. You can change this in the YAML file.
3. Can Envoy be used as an API Gateway?
Yes. Envoy is frequently used as a programmable, high-performance API Gateway.
4. Does Envoy support HTTPS?
Yes. Envoy supports TLS, mTLS, SDS, certificate rotation, and advanced crypto features.
5. Can I run Envoy inside Docker or Kubernetes?
Absolutely. Envoy is widely used in containerized and orchestrated environments.
