# Emissary Ingress — Kubernetes-Native API Gateway on Envoy

> Emissary Ingress is an open-source Kubernetes API gateway built on Envoy Proxy, providing rate limiting, authentication, and traffic management for microservices.

## Install

Save in your project root:

# Emissary Ingress — Kubernetes-Native API Gateway on Envoy

## Quick Use
```bash
# Install Emissary Ingress via Helm
helm repo add datawire https://app.getambassador.io
helm install emissary datawire/emissary-ingress -n emissary --create-namespace

# Apply a Mapping to route traffic
kubectl apply -f - <<EOF
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
  name: my-service
spec:
  hostname: "api.example.com"
  prefix: /api/
  service: my-service:8080
EOF
```

## Introduction
Emissary Ingress (formerly Ambassador API Gateway) is a Kubernetes-native API gateway built on top of Envoy Proxy. It uses Custom Resource Definitions to configure routing, rate limiting, TLS termination, and authentication — all without restarting the proxy. Emissary is designed for teams running microservices on Kubernetes who need a developer-friendly, GitOps-compatible ingress layer.

## What Emissary Does
- Routes HTTP and gRPC traffic to Kubernetes services using declarative Mapping CRDs
- Provides rate limiting, circuit breaking, and automatic retries at the edge
- Terminates TLS with automatic certificate management via cert-manager or ACME
- Integrates with external authentication services for OAuth2, JWT, and API key validation
- Supports canary releases and traffic shifting for progressive delivery

## Architecture Overview
Emissary runs as a Kubernetes Deployment that wraps Envoy Proxy. The control plane watches for CRD changes (Mappings, Hosts, RateLimits) and translates them into Envoy xDS configuration updates delivered over gRPC. Envoy handles all data-plane traffic with zero-downtime configuration reloads. The architecture separates the control plane (CRD reconciliation) from the data plane (Envoy) for scalability and reliability.

## Self-Hosting & Configuration
- Install via Helm chart or YAML manifests into any Kubernetes cluster
- Define routing rules with Mapping CRDs specifying prefix, hostname, and target service
- Configure Host CRDs for TLS termination with automatic ACME certificate provisioning
- Set up RateLimitService CRDs for global or per-route rate limiting
- Enable tracing with Zipkin, Jaeger, or Datadog via Envoy tracing configuration

## Key Features
- Envoy-powered data plane with L7 routing, load balancing, and observability
- CRD-based configuration that integrates with GitOps workflows
- Built-in support for gRPC, WebSockets, and HTTP/2
- Developer self-service: teams manage their own Mapping CRDs without cluster-admin access
- Gateway API support alongside traditional Ingress resources

## Comparison with Similar Tools
- **Ingress-NGINX** — widely used but lacks advanced L7 features like rate limiting and auth
- **Istio Gateway** — more powerful service mesh but significantly more complex to operate
- **Traefik** — auto-discovers services but Emissary offers deeper Envoy customization
- **Kong Ingress** — plugin-based API gateway but heavier runtime with Lua/OpenResty

## FAQ
**Q: Is Emissary the same as Ambassador?**
A: Yes, Emissary Ingress was previously called Ambassador API Gateway. The project was renamed in 2021.

**Q: Does Emissary support the Kubernetes Gateway API?**
A: Yes, Emissary supports Gateway API resources alongside its own CRDs.

**Q: Can Emissary work alongside a service mesh like Istio?**
A: Yes, Emissary can serve as the edge gateway while Istio manages east-west traffic within the mesh.

**Q: How does Emissary handle configuration changes?**
A: Configuration changes are applied via Envoy xDS hot-reload with zero downtime — no proxy restart required.

## Sources
- https://github.com/emissary-ingress/emissary
- https://emissary-ingress.dev

---
Source: https://tokrepo.com/en/workflows/0a68950e-3998-11f1-9bc6-00163e2b0d79
Author: AI Open Source