Overview
Open-source GoModel sends one provider through one proxy with
proxy_url. That is enough for a single
geo-restricted provider, but not for a fleet that must always leave through
an allowlisted egress IP: when that one proxy goes down, every request behind
it fails.
Egress proxy pools add the missing pieces:
- Pools of HTTP, HTTPS, SOCKS5, or SOCKS5h proxies, picked by
failover
(first healthy, in order) or round_robin.
- Health checks that probe every proxy on a schedule and skip members that
fail, then bring them back once they pass again.
- Rules that assign providers to pools by name pattern or provider type,
so a new provider is covered without touching its own configuration.
A provider’s own proxy_url still wins over any rule. Providers that no rule
matches keep the gateway-wide HTTP_PROXY, HTTPS_PROXY, and NO_PROXY
behaviour.
Like SSO, enabled egress fails closed: startup aborts when the egress
entitlement is missing or the configuration is invalid. Traffic that was
meant to leave through a proxy never silently leaves from the gateway’s own
address instead.
extensions.egress in the main GoModel YAML
configuration:
Rules are evaluated in order and the first match wins. A pattern matches the
provider name (openai-eu, openai*); with a type: prefix it matches the
provider type instead (type:gemini). With a single pool and no rules every
provider uses that pool.
The same settings are available as environment variables, which override the
YAML values. One pool per PRO_EGRESS_PROXY_<NAME>; the name becomes the pool
name in lowercase with underscores as hyphens (EU_STATIC becomes
eu-static):
Health checks and failover
Every member is probed before the gateway serves its first request, so a
proxy that is already down never receives traffic. Without check_url a probe
is a TCP connection to the proxy port. With check_url it is a HEAD request
through the proxy; any relayed response counts as healthy, including 401 or
404 from the target, while a 5xx counts as failure because forward proxies
answer 502, 503, and 504 themselves when they cannot reach the target.
After the first probe a member needs failure_threshold consecutive failures
to be skipped and one success to return. When every member of a pool is
unhealthy the pool is still used, starting with its first member, and a
warning is logged once per outage. A matched pool never falls back to a direct
connection.
Inspect
Health transitions are logged with the pool name, member position, and the
proxy URL with any password masked. Prometheus exposes:
gomodel_pro_egress_proxy_healthy{pool,member,proxy}: 1 while the member
is in rotation.gomodel_pro_egress_health_checks_total{pool,member,proxy,result}: probes
by outcome.gomodel_pro_egress_selections_total{pool,member,proxy}: requests each
member was chosen for.
Alert on gomodel_pro_egress_proxy_healthy == 0 to learn about a dead proxy
before the pool runs out of members.
