Emissary-ingress: a Kubernetes-native API gateway on Envoy, and what it costs to run

The problem Emissary-ingress removes: Envoy config you do not have to hand-write

Envoy Proxy is a capable Layer 7 proxy and a poor thing to configure by hand. Its routing configuration is a large structured document, and every route change means regenerating and reloading that document. Emissary-ingress exists to sit between Kubernetes and Envoy: the README describes it as an "open-source Kubernetes-native API Gateway + Layer 7 load balancer + Kubernetes Ingress built on Envoy Proxy". The audience is platform and infrastructure engineers who already run Kubernetes and want ingress routing, TLS termination, and traffic policy expressed as Kubernetes objects rather than as Envoy YAML.

The project was formerly known as Ambassador API Gateway, and it is a CNCF incubation project. That history matters when you search for documentation, because older material uses the Ambassador name and the repository still ships Python packages named ambassador and ambassador-diag as dependencies. If you find a tutorial referring to Ambassador Edge Stack or to the Ambassador API Gateway, check which release line it targets before following it.

How the control plane and data plane split works

The architecture section of the README is short but unambiguous. Emissary is configured through Kubernetes CRDs, or through annotations on Kubernetes Services. Internally it uses Envoy Proxy to handle routing data. Externally it relies on Kubernetes for scaling and resiliency. In practice that means Emissary watches the Kubernetes API for the objects that describe your routing intent, translates them into Envoy configuration, and hands that configuration to the Envoy processes that actually accept and forward traffic.

The split has consequences worth naming. Because scaling and resiliency come from Kubernetes, Emissary does not carry its own clustering or leader-election machinery for the data plane; you scale it the way you scale any Deployment, and you get availability the way you get it anywhere else in the cluster. Because configuration comes from CRDs and Service annotations, a route change is a Kubernetes API write, which means your existing RBAC, audit logging and GitOps tooling apply to gateway configuration without a separate control channel.

The repository layout reflects a multi-language build. The primary language is Python, with a pyproject.toml that pins Python 3.13.5 and depends on ambassador and ambassador-diag 4.x, while go.mod declares the module github.com/emissary-ingress/emissary/v3 and requires Go 1.25.0. The Makefile carries the Envoy version as a variable, ENVOY_IMAGE, defaulting to envoyproxy/envoy:distroless-v1.39.0. If you build from source rather than installing a release, that variable is where the Envoy version is pinned.

Getting Emissary-ingress running and routing your first request

The README does not reproduce install commands. It says the fastest way to get started is to follow the Quickstart, and it points at the Emissary documentation and the Emissary FAQ for other common questions. It also states that Emissary is configured via Kubernetes CRDs, or via annotations on Kubernetes Services. The repository contains charts/, which is where the Helm chart lives, and the README's commented badge links reference a Helm repository named datawire with a package named emissary-ingress. Those two facts are all the install guidance the README and repository files support, so treat the chart directory as the source of truth for the chart name and version rather than any example you find elsewhere.

The first real use is a route. The README links a Mappings topic under self-service configuration, which is the CRD that binds a host and prefix to a Kubernetes Service. The exact apiVersion and field names depend on the release line you installed, so read the Mapping schema from the CRDs in your cluster rather than copying an example written for a different major version. A Mapping that kubectl accepts against a CRD group your release did not install will not produce a route, and Emissary has no reason to warn you about an object it never sees.

For the same reason, the README does not document rollback, and it does not document how a CRD upgrade interacts with existing Mapping objects. If your plan depends on reverting a gateway upgrade quickly, that plan has to rest on your own cluster backup and restore procedure.

Where Emissary-ingress is the wrong tool

The configuration model is Kubernetes. If your workloads do not run in Kubernetes, or if you need a gateway that fronts both cluster and non-cluster backends with one uniform control plane, Emissary-ingress adds a Kubernetes dependency without removing the other one. The README is explicit that it relies on Kubernetes for scaling and resiliency, so there is no standalone mode to fall back on.

The second limitation is governance, and the README states it plainly: the project's original parent company has stepped back from direct involvement, and the README says the community is now more important than ever. That is a statement about who fixes things, not about whether the code works. It means you should read Community/MAINTAINERS.md and Community/GOVERNANCE.md before you commit, and decide whether the current maintainer set and release cadence match the risk profile of the traffic you are putting behind it. For an internal development cluster this may be irrelevant. For a production edge that terminates customer TLS, it is the first thing to settle.

The third is upgrade surface. Emissary-ingress ships CRDs, and Kubernetes CRD upgrades have their own operational rules that are independent of the Emissary release process. Since the README is silent on rollback, a fast revert depends on your own procedures rather than on project documentation.

Emissary-ingress compared with a plain Kubernetes Ingress controller

The nearest alternative is the Ingress resource handled by an ingress controller, including controllers that also use Envoy underneath. The difference is in what you can express. A Kubernetes Ingress object covers host and path routing and TLS, and that is roughly the ceiling of the resource. Emissary-ingress exposes a broader policy surface through its CRDs and Service annotations: the README lists load balancing, gRPC and HTTP/2, TCP and web sockets, authentication, rate limiting, TLS, sticky sessions, circuit breaking, canary releases, and integrations with Consul, Linkerd and Istio, plus Knative serverless integration.

That breadth is the trade. Every one of those capabilities is another custom resource with its own schema and its own upgrade path. If your requirement is host and path routing with TLS termination, an Ingress controller gets you there with resources that every Kubernetes practitioner already knows, and you avoid owning a set of CRDs. If your requirement includes canary weights, per-route circuit breaking, or an external authentication service, the Ingress resource cannot express it and you would be bolting on annotations that are controller-specific anyway.

Emissary-ingress also supports the Gateway API, which appears in the repository topics. That matters if you want to write routing in a portable API rather than in a project-specific one, though the README does not describe how much of the Gateway API surface is implemented, so treat that as something to verify against the documentation for your release line rather than as a given.

Licence, upgrade cost, and what the repository tells you about maintenance

Emissary-ingress is licensed under Apache-2.0, and pyproject.toml declares the Apache Software License classifier. Apache-2.0 is a permissive licence with an explicit patent grant, and it places no copyleft obligation on the services you route through the gateway. The repository also carries DEPENDENCIES.md and DEPENDENCY_LICENSES.md, which is where you would look if your organisation requires a full transitive dependency licence review before approving a component. That review is your process, not the project's, and nothing here should be read as legal advice.

On upgrade cost, two things in the repository are worth knowing before you plan a cadence. The README maintains frozen branches for older lines, with master frozen for Emissary-ingress 3.10 and release/v2.5 frozen for 2.5, while main is the active development branch. Frozen means no further changes on that line, so staying on a frozen branch is a decision with a known end state. Separately, the build bootstrapping in the Makefile refuses to run if your checkout sits inside GOPATH or if GOPATH and GOROOT point at the same directory, which is a hint that building from source is a supported but opinionated path. Most operators should install a released chart and leave the build alone.

The last push to the repository was on 2026-09-22, and the most recent release listed is v4.1.0 from 2026-05-19, preceded by v4.1.0-rc.0 on 2026-05-01 and v4.0.1 on 2026-03-26. That is a release cadence you can plan against, but the README's own note about the parent company stepping back is the context in which to read it.

Editorial conclusion

Adopt Emissary-ingress if you already run Kubernetes, want Envoy's data plane without hand-writing Envoy config, and are comfortable that the README states the original parent company has stepped back from direct involvement, so the community carries the project. Do not adopt it if you need a vendor-backed SLA or you are not on Kubernetes, because both the configuration model and the scaling model assume the Kubernetes API. Verify first which release line your cluster needs, whether the CRDs you intend to use are still documented for that line, and how you will upgrade the CRDs themselves, since the README does not document rollback.

Frequently asked questions

Official sources

1. emissary-ingress/emissary on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases