# Aralez: a Pingora-based reverse proxy that discovers pods and reloads itself

> Aralez is a Rust reverse proxy built on Cloudflare's Pingora that resolves upstreams from a file, Consul or the Kubernetes API, reloads configuration over an HTTP API, and handles TLS, authentication, caching and rate limiting in one process.

**sadoyan/aralez** — Aralez (Արալեզ), Reverse proxy built on top of Cloudflare's Pingora

- Repository: https://github.com/sadoyan/aralez
- Website: https://aralez.rs
- Stars: 803 · Forks: 34
- Language: Rust
- License: Apache-2.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/sadoyan-aralez

## A reverse proxy shaped like a small ingress controller

Aralez is described as a reverse proxy built on top of Cloudflare's Pingora, and it is written in Rust. The positioning is what makes it interesting: it is not a general purpose nginx replacement but something the project calls a lightweight ingress-style proxy. The stated features cover zero-configuration automatic protocol handling, TLS, upstream management, and Consul and Kubernetes integration for dynamic pod discovery and health-checked routing. In practice the target user is an operator running a handful of services in a container environment who wants pod endpoints to appear in the proxy without editing a file by hand on every deploy. It is also attractive to teams that already know the Pingora ecosystem, since Aralez layers operational concerns on top of that engine rather than replacing it.

## Upstreams come from a file, Consul or the Kubernetes API

The upstream layer is the core mechanism. Three providers are listed. The file provider declares upstreams in the configuration file, which is the simple case. The consul provider updates upstreams dynamically from HashiCorp Consul, and the kubernetes provider updates them dynamically from the Kubernetes API server. That dynamic path is what turns the proxy into something pod-aware: endpoints can appear and disappear, and the project describes the integration as covering dynamic pod discovery and health-checked routing. Configuration is not confined to upstreams either. The upstream list itself lives in a separate file whose location is set by the upstreams_conf key, and load balancing offers round-robin, health checks and optional sticky sessions. A second nuance that catches people out: Aralez detects automatically whether an upstream expects a secure connection, so an upstream without TLS does not need a separate declaration.

## Config reloads arrive over an HTTP API on port 3000

The configuration surface is a single main.yaml, and several of its keys define the operational contract. The config_address key sets the HTTP API address for pushing upstreams.yaml from a remote location, with the example value 0.0.0.0:3000, and the feature list calls this remote config push, aimed at CI/CD systems that update configuration without a restart. The proxy itself listens on proxy_address_http, shown as 0.0.0.0:6193, and optionally on proxy_address_tls at 0.0.0.0:6194. Other keys worth knowing before a first deployment: threads sets the number of running daemon threads and defaults to 1, runuser and rungroup drop root privileges after launch when started as root, daemon runs the process in the background, pid_file gives the PID path, upstream_keepalive_pool_size sizes the upstream connection pool, and proxy_configs points at the directory holding configuration files, which must be writable by the aralez user. Logging is controlled by log_level, with values from info up to trace or off, and access_log accepts access and error.

## Certificates arrive by HTTP-01 challenge or from a watched folder

TLS handling is bundled rather than delegated. Aralez orders and renews certificates through Let's Encrypt using the HTTP-01 challenge, and it also autoloads new or changed certificates from a folder without a restart. The dependency list explains the mechanism: instant-acme and rcgen handle the certificate side, rustls-pemfile reads PEM files, and x509-parser inspects certificates, while the notify crate is what makes folder watching possible. The TLS cipher policy is a configuration decision rather than a fixed one, with proxy_tls_grade accepting high, medium or unsafe and defaulting to medium, where high is described as matching a Qualys SSL Labs A+ grade. That default and the A+ option are the project's own claim, so treat it as a starting point rather than an audited result, and set the grade explicitly if you have a compliance requirement.

## Authentication, caching and rate limits in the same binary

The feature list covers the pieces an ingress controller usually delegates to separate services. Authentication comes in four shapes: Basic Auth, an API key passed through the x-api-key header, JWT verification where the tokens are issued by Aralez itself through a /jwt API, and forward auth, which sends the request on to an external authentication server. Caching is an in-memory cache with a configurable TTL and no external dependency, and the rate limiter can apply global or per-route limits to upstream requests. WebSocket connection upgrades and gRPC are detected and handled automatically, header injection is available globally and per route for both server and client headers, and a built-in minimalistic file server is included for static files that should be added as upstreams for public access. The Rust dependency set backs this up with moka for the cache, pingora-limits for the limiter, jsonwebtoken for tokens, prometheus for metrics, and privdrop for privilege dropping.

## Building the binary and the container image

The repository carries a Makefile with a conventional set of targets, so a contributor works through cargo rather than a bespoke script:
```bash
build: ## Build project
	cargo build --workspace $(TARGET) $(FEATURES)

deps: ## Check project dependencies for advisories
	cargo deny check advisories
```
The default TARGET is --all-targets and FEATURES is --all-features, and the all target chains build, test, fmt and checkup, with checkup running clippy and cargo check. The Dockerfile builds on rust:1.98-trixie and cross compiles for musl targets using zig, with separate handling for amd64 and arm64 and an explicit failure for any other architecture. The final image is a distroless base and the entry point is the binary itself:
```dockerfile
FROM --platform=${TARGETARCH} gcr.io/distroless/cc-debian13:nonroot AS release
COPY ${TARGETPLATFORM}/aralez /usr/local/bin/aralez
ENTRYPOINT ["/usr/local/bin/aralez"]
```
Users who are not building from source can take binaries from the GitHub releases page, the crate from crates.io, images from Docker Hub and GitHub Packages, and there is a charts directory for Helm style deployment. The documentation site at aralez.rs is the manual to read before running this in production.

## Pre-release crates, Apache-2.0 and a quick release cadence

Two things deserve attention before you pin a version. The dependency list includes release candidates rather than stable releases in two places: dashmap is at 7.0.0-rc2 and notify is at 9.0.0-rc.4, so a rebuild can pick up a different patch of a pre-release dependency than the one your binary was tested with. Cargo.lock is committed, which contains that risk, but any rebuild on a fresh dependency resolution deserves a regression test. The licence is Apache-2.0, a permissive licence with no copyleft obligation on the projects that embed the binary, though the Apache patent and notice terms still apply to redistribution. On maintenance, the repository is not archived and the last push was on 2026-10-19, with releases v.0.95.1 on 2026-10-16, v.0.94.4 on 2026-10-05 and v.0.94.1 on 2026-09-27, so the project is moving fast, and version numbers carry a leading v. prefix in the tag names.

## Conclusion

Aralez fits teams that want an ingress-style proxy for Consul or Kubernetes environments without running a full ingress controller, and that value hot reloads, built-in TLS and authentication over a single static configuration file. It is the wrong choice for a static single-upstream site, where its machinery buys nothing, and for operators who need long-term support on the pre-release crates in its dependency set. Before adopting it, check the main.yaml keys against your own ports and paths, read the docs site at aralez.rs for the parts this page does not cover, and confirm that the release you pin matches the Pingora 0.9.0 API your integration expects.

## FAQ

### How do I install Aralez and run it for the first time?

Binaries are published on the GitHub releases page, the crate is on crates.io as aralez, and container images are available on Docker Hub and GitHub Packages. Once the binary is in place, the main.yaml file in proxy_configs holds the settings, with the upstream list in the file named by upstreams_conf.

### Which ports does Aralez listen on and what is config_address for?

The HTTP bind address is set with proxy_address_http, shown as 0.0.0.0:6193, and the optional HTTPS bind address with proxy_address_tls at 0.0.0.0:6194. The config_address key, shown as 0.0.0.0:3000, is the HTTP API address used for pushing upstreams.yaml from a remote location.

### Can Aralez discover Kubernetes pods without a restart?

Yes. Upstreams can be declared statically in a file, or updated dynamically from HashiCorp Consul or from the Kubernetes API server, and the project lists dynamic config reloads over an API as a feature. The upstream list itself is a separate file so it can be replaced independently of main.yaml.

### Does Aralez handle TLS certificates automatically?

It orders and renews certificates through Let's Encrypt using the HTTP-01 challenge, and it autoloads new or changed certificates from a folder without a restart. The cipher policy is chosen with proxy_tls_grade, which accepts high, medium or unsafe and defaults to medium.

## Sources

- [License: Apache-2.0](https://github.com/sadoyan/aralez/blob/main/LICENSE)
- [Project website](https://aralez.rs)
- [README](https://github.com/sadoyan/aralez/blob/main/README.md)
- [Releases](https://github.com/sadoyan/aralez/releases)
- [sadoyan/aralez on GitHub](https://github.com/sadoyan/aralez)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sadoyan-aralez