Emissary-Ingress is an open-source API gateway and Kubernetes ingress controller built on the Envoy proxy. Developers describe how external traffic should reach their services (paths, hosts, TLS, retries, authentication, rate limits) as Kubernetes custom resources, and Emissary turns that into Envoy configuration at the edge of the cluster. It addresses the gap between a basic ingress controller, which only routes HTTP paths, and a full API gateway, which teams otherwise run as a separate product with its own database and admin console. The project began in 2014 at Datawire (later Ambassador Labs) as Ambassador, and was renamed Emissary-Ingress when it joined the CNCF as an incubating project in April 2021. Ambassador Labs continues to sell a commercial edition, Ambassador Edge Stack, on top of it.
CNCF daily · Sprint 1, day 3 · API Gateway
At a glance
| Category | API Gateway |
| CNCF status | Incubating. Accepted April 2021 |
| Written in | Go (control plane), with Envoy (C++) as the data plane |
| License | Apache 2.0 |
| Configuration | Kubernetes CRDs: Listener, Host, Mapping, Module, plus auth and rate-limit services |
| State | Stored entirely in Kubernetes, with no separate database |
| Current major version | 4.x (first released March 2026) |
Architecture
flowchart TB
CLIENT[Clients<br/>browsers, mobile apps, partners] --> LB[Cloud or MetalLB<br/>load balancer]
LB --> ENVOY
subgraph EMI[Emissary-Ingress pods]
CTRL[Emissary control plane<br/>watches CRDs, builds config]
ENVOY[Envoy<br/>TLS, routing, retries]
CTRL -->|xDS config| ENVOY
end
API[Kubernetes API<br/>Listener, Host, Mapping] --> CTRL
ENVOY -->|ext_authz| AUTH[Auth service<br/>OIDC, JWT, API keys]
ENVOY -->|rate limit check| RL[Rate limit service]
ENVOY --> S1[orders-api]
ENVOY --> S2[payments-api]
ENVOY --> S3[web frontend]
ENVOY --> MESH[Service mesh<br/>Istio or Linkerd]
ENVOY --> TEL[Metrics and traces<br/>Prometheus, OpenTelemetry]
| Component | Responsibility |
|---|---|
| Control plane | Watches Emissary’s custom resources and Kubernetes Services, validates them and generates Envoy configuration. |
| Envoy | Terminates TLS and performs all L7 routing, retries, timeouts, load balancing, CORS and header manipulation. |
| Listener / Host | Define which ports Emissary listens on and which hostnames and TLS certificates it serves. |
| Mapping | The core routing resource: maps a host and path prefix to a backend service, with per-route timeouts, retries and rewrites. |
| Module | Global settings such as default timeouts, diagnostics and Envoy tuning. |
| External services | Optional authentication (Envoy ext_authz) and rate-limit services that Emissary calls for each request. |
Design principle. Emissary is decentralised and declarative: each team owns the Mapping resources for its own services, in its own namespace, alongside its Deployment, instead of a central gateway team editing one shared configuration. Because all state lives in Kubernetes, the gateway scales horizontally with no database to manage, and Envoy’s performance applies to every route.
Production reference design
An edge gateway for a microservice platform on EKS, GKE, AKS or on-premises Kubernetes:
- Install the CRDs, then Emissary with Helm, following the quick start for the release you choose. Emissary’s CRDs must be applied before the chart, and on upgrades as well. Run at least three replicas behind a cloud load balancer, or behind MetalLB on-premises.
- Declare a Listener and a Host, with TLS certificates issued by cert-manager.
- Let each team add Mappings for its services, for example:
Check the API version against your release’s documentation, as Emissary has moved through several CRD versions.apiVersion: getambassador.io/v3alpha1 kind: Mapping metadata: name: orders-api namespace: orders spec: hostname: api.example.com prefix: /orders/ service: orders-api.orders:8080 timeout_ms: 5000 retry_policy: retry_on: "5xx" num_retries: 2 - Centralise security at the edge: connect an external auth service for OIDC or JWT validation, add per-client rate limits, and set CORS and security headers globally with a Module.
- Observe and deliver safely: scrape Envoy’s Prometheus metrics, send traces to an OpenTelemetry collector, and use weighted Mappings or Argo Rollouts for canary releases behind the gateway.
Typical production uses include a single public API endpoint in front of many microservices, edge authentication and rate limiting for partner APIs, and developer self-service routing in internal platforms.
Operational considerations
- Upgrade CRDs deliberately. Major versions change CRD versions and defaults; read the migration notes and upgrade CRDs before the Helm release.
- Know which edition you run. Some features (such as advanced rate limiting, a developer portal and single sign-on filters) live in the commercial Ambassador Edge Stack, not in Emissary.
- Run it highly available. Use multiple replicas, PodDisruptionBudgets and topology spread, and size Envoy for peak connections and TLS handshakes.
- Guard shared hostnames. Because any team can create Mappings, use RBAC, namespaces and admission policy to stop one team from claiming another team’s host or path.
- Watch the Gateway API shift. The Kubernetes Gateway API is becoming the standard way to configure ingress; evaluate how your Emissary version supports it, and whether Envoy Gateway is the better long-term fit.
Adoption
- When Emissary joined the CNCF in 2021, the announcement named users including Ticketmaster, Chick-fil-A, AppDirect, Lifion by ADP and OneFootball, with one deployment handling up to 500,000 requests per second.
- Ambassador Labs builds its commercial Ambassador Edge Stack on Emissary.
- The project remains actively released: version 4.0 shipped in March 2026, with 4.1 following in May 2026.
Alternatives
| Solution | Model | Best suited to |
|---|---|---|
| Envoy Gateway (part of the Envoy project) | Gateway API–native control plane for Envoy | New platforms standardising on the Gateway API |
| Contour (CNCF Incubating) | Envoy-based ingress controller | Simple, well-supported ingress with HTTPProxy and Gateway API |
| Kong Gateway | Plugin-rich API gateway, open-source and enterprise | Teams needing a large plugin ecosystem and API management |
| NGINX Gateway Fabric / ingress-nginx | NGINX-based ingress | Teams already invested in NGINX |
| Istio ingress gateway | Envoy gateway integrated with the mesh | Clusters already running Istio |
| Cloud gateways (AWS API Gateway, Apigee) | Managed API management | Teams wanting usage plans, portals and billing out of the box |
Strengths and limitations
| Strengths | Limitations |
|---|---|
| Envoy performance with a Kubernetes-native, self-service config model | Smaller community than NGINX or Kong-based gateways |
| No external database: all state in Kubernetes CRDs | Some enterprise features only in the commercial edition |
| Built-in hooks for external auth and rate limiting | CRD version migrations make major upgrades careful work |
| Integrates cleanly with Istio, Linkerd, Prometheus and tracing | Gateway API–native projects are drawing new adoption |
| Mature, with large production deployments | Incubating, not yet Graduated |
Recommendation
Trial Emissary-Ingress if you want a self-service, Envoy-based API gateway with edge authentication and rate limiting configured through Kubernetes resources, and especially if you may later move to Ambassador Edge Stack. For new platforms built around the Kubernetes Gateway API, assess Envoy Gateway and Contour alongside it, and choose based on Gateway API maturity and the features you need at the edge.
References: CNCF project page · CNCF blog: Emissary-Ingress is now a CNCF incubating project · Emissary-Ingress on GitHub · Emissary-Ingress documentation