API Gateway Solutions - Learning Module

Loading content...

0/273

Ambassador (Emissary-Ingress): Kubernetes-Native

The Kubernetes-Native API Gateway

As Kubernetes became the dominant container orchestration platform, a gap emerged: traditional API gateways weren't designed for Kubernetes' declarative, eventually-consistent operational model. They required separate management planes, didn't understand Kubernetes services, and couldn't leverage Kubernetes' native abstractions.

Ambassador (now Emissary-Ingress as a CNCF project) was purpose-built to fill this gap. It operates as a Kubernetes-native ingress controller powered by Envoy Proxy, configured entirely through Kubernetes Custom Resource Definitions (CRDs).

This page explores Ambassador's architecture, how it integrates with Kubernetes primitives, its Envoy foundation, and when it's the optimal choice for Kubernetes-based deployments.

What You Will Learn

By the end of this page, you will understand Ambassador's Kubernetes-native architecture, how CRD-based configuration works, the relationship with Envoy, deployment patterns in Kubernetes, and decision criteria for choosing Ambassador.

The Kubernetes-Native Philosophy

What "Kubernetes-Native" Means

Being Kubernetes-native isn't about deploying on Kubernetes—any gateway can run in containers. True Kubernetes-native architecture means:

Configuration via CRDs — No separate config files, APIs, or databases; configuration lives in Kubernetes
Kubernetes service discovery — Automatically routes to Kubernetes Services
GitOps compatible — Declarative YAML, version-controlled, applied via kubectl
Namespace-aware — Respects Kubernetes RBAC and multi-tenancy
Controller pattern — Watches for changes, reconciles desired vs. actual state

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
# Ambassador Mapping resource - defines a route
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
  name: user-service-mapping
  namespace: production
spec:
  hostname: api.example.com
  prefix: /users/
  service: user-service.production:8080
  timeout_ms: 10000
  retry_policy:
    retry_on: "5xx"
    num_retries: 3
  labels:
    ambassador:
      - request_label_group:
          - user-api
---
# Rate limiting configuration
apiVersion: getambassador.io/v3alpha1
kind: RateLimitService
metadata:
  name: rate-limiter
  namespace: ambassador
spec:
  service: rate-limit-service.ambassador:8081
  protocol_version: v3
---
# TLS configuration  
apiVersion: getambassador.io/v3alpha1
kind: Host
metadata:
  name: api-host
  namespace: ambassador
spec:
  hostname: api.example.com
  tlsSecret:
    name: api-tls-cert
  requestPolicy:
    insecure:
      action: Redirect

The Controller Pattern

Ambassador operates as a Kubernetes controller:

┌─────────────────────────────────────────────────────────────────┐
│                    Kubernetes Cluster                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   API Server (etcd)                                             │
│        │                                                        │
│        │  Watch CRDs (Mappings, Hosts, etc.)                    │
│        ▼                                                        │
│   ┌─────────────────────┐                                       │
│   │   Ambassador Edge   │                                       │
│   │      Controller     │◄── Reconciliation Loop                │
│   └─────────┬───────────┘                                       │
│             │                                                   │
│             │ Generate Envoy Configuration                      │
│             ▼                                                   │
│   ┌─────────────────────┐                                       │
│   │   Envoy Proxy       │◄── xDS Configuration                  │
│   │   (Data Plane)      │                                       │
│   └─────────────────────┘                                       │
│             │                                                   │
│             │ Route Traffic                                     │
│             ▼                                                   │
│   ┌─────────────────────┐                                       │
│   │   Backend Services  │                                       │
│   └─────────────────────┘                                       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

This pattern means:

Configuration changes apply without restarts
Kubectl is your only management interface
Standard Kubernetes RBAC controls who can modify routes
Configuration is automatically version-controlled in etcd

GitOps with Ambassador

Ambassador's CRD-based configuration integrates perfectly with GitOps tools like ArgoCD or Flux. Your entire gateway configuration—routes, TLS, rate limits—lives in Git and is applied declaratively. Changes trigger automatic reconciliation.

The Envoy Foundation

Ambassador is fundamentally an Envoy management plane. Envoy handles all traffic; Ambassador translates Kubernetes CRDs into Envoy configuration.

Why Envoy?

Envoy was purpose-built for modern service mesh and edge proxy use cases:

High performance — C++, event-driven, minimal latency overhead
Dynamic configuration — xDS APIs for runtime updates without restart
Observability built-in — Detailed metrics, distributed tracing, access logs
Extensibility — Filter chains, Lua, WASM
Cloud-native pedigree — Created at Lyft, now CNCF graduated project

Ambassador CRDs to Envoy Mapping
Ambassador CRD	Envoy Concept	Purpose
Mapping	Route	URL path → upstream service
Host	FilterChainMatch + TLS	TLS termination, hostname
TLSContext	DownstreamTlsContext	TLS settings, protocols
RateLimitService	RateLimitFilter	External rate limit service
AuthService	ExtAuthz Filter	External authentication
TracingService	HttpTracer	Distributed tracing config
Module	Various	Global Ambassador settings

xDS Dynamic Configuration

Envoy's xDS APIs (discovery services) enable dynamic configuration:

LDS (Listener Discovery) — What ports/protocols to listen on
RDS (Route Discovery) — URL routing rules
CDS (Cluster Discovery) — Upstream service definitions
EDS (Endpoint Discovery) — Service instance addresses
SDS (Secret Discovery) — TLS certificates

Ambassador implements an xDS server that Envoy connects to, pushing configuration updates in real-time. This is why configuration changes apply instantly—Ambassador updates xDS, Envoy receives new config via streaming gRPC.

Envoy Expertise Advantage

Understanding Envoy internals helps debug Ambassador issues. Ambassador diagnostics expose raw Envoy config at /ambassador/v0/diag/. Complex issues may require reading Envoy documentation. If your team already knows Envoy, Ambassador has a lower learning curve.

Core Features and Capabilities

Routing and Traffic Management

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
# Header-based routing
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
  name: canary-users
spec:
  prefix: /api/v1/users
  service: users-v2.production:8080
  headers:
    x-canary-user: "true"
  weight: 100
---
# Default route for non-canary
apiVersion: getambassador.io/v3alpha1  
kind: Mapping
metadata:
  name: stable-users
spec:
  prefix: /api/v1/users
  service: users-v1.production:8080
  weight: 100
---
# Weighted traffic splitting (10% canary)
apiVersion: getambassador.io/v3alpha1
kind: Mapping  
metadata:
  name: users-canary-split
spec:
  prefix: /api/v1/users
  service: users-v1.production:8080
  weight: 90
---
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
  name: users-canary-new
spec:
  prefix: /api/v1/users
  service: users-v2.production:8080
  weight: 10

Authentication

Ambassador integrates with external authentication services via the AuthService CRD:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
apiVersion: getambassador.io/v3alpha1
kind: AuthService
metadata:
  name: jwt-auth
  namespace: ambassador
spec:
  auth_service: auth-service.auth:3000
  proto: http
  path_prefix: /auth
  allowed_request_headers:
    - Authorization
    - X-API-Key
  allowed_authorization_headers:
    - X-User-ID
    - X-User-Roles
  timeout_ms: 5000
  failure_mode_allow: false
---
# Apply auth to specific routes
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
  name: protected-api
spec:
  prefix: /api/
  service: api-service:8080
  # Auth is applied globally by default
  # Use bypass_auth: true to exclude specific routes

Rate Limiting

Ambassador supports external rate limit services (envoy-ratelimit) and provides descriptors for granular control:

apiVersion: getambassador.io/v3alpha1
kind: RateLimitService
metadata:
  name: ratelimit
spec:
  service: ratelimit.ratelimit:8081
  protocol_version: v3
---
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
  name: rate-limited-api
spec:
  prefix: /api/
  service: api-service:8080
  labels:
    ambassador:
      - request_label_group:
          - source_cluster:
              key: x-api-key
              header: X-API-Key
          - destination_cluster:
              key: service_name
              generic_key:
                value: api-service

Ambassador Feature Summary
Category	Features
Routing	Path, header, query param matching; regex; prefix/exact; weighted splitting
Load Balancing	Round-robin, ring-hash, maglev, least-request; health checking
Resilience	Timeouts, retries, circuit breaking, outlier detection
Security	External auth, TLS termination, mTLS, CORS
Observability	Prometheus metrics, distributed tracing (Zipkin, Jaeger, Datadog)
Protocols	HTTP/1.1, HTTP/2, gRPC, WebSocket, TCP

Deployment Patterns in Kubernetes

Basic Deployment

# Install via Helm
helm repo add datawire https://app.getambassador.io
helm install ambassador datawire/emissary-ingress \
  --namespace ambassador \
  --create-namespace \
  --set replicaCount=3

High Availability Configuration

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
replicaCount: 3
 
resources:
  limits:
    cpu: 2000m
    memory: 1Gi
  requests:
    cpu: 500m
    memory: 512Mi
 
autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70
 
affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 100
        podAffinityTerm:
          labelSelector:
            matchExpressions:
              - key: service
                operator: In
                values:
                  - ambassador
          topologyKey: topology.kubernetes.io/zone
 
service:
  type: LoadBalancer
  annotations:
    service.beta.kubernetes.io/aws-load-balancer-type: "nlb"
    service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled: "true"

Multi-Cluster / Multi-Ingress

Large organizations often deploy multiple Ambassador instances:

Per-environment — Separate ingresses for dev/staging/prod
Per-API type — Public API vs. internal API
Per-team — Namespace-scoped Ambassadors with RBAC

Ambassador supports namespaced configuration (v3.x) where CRDs only apply to the Ambassador in that namespace, enabling multi-tenant deployments.

Resource Sizing

Ambassador/Envoy memory usage scales with route count and connection count. Start with 512Mi and monitor. For 1000+ routes or 50K+ concurrent connections, increase to 2Gi+. CPU scales with request rate—1 CPU core handles ~10K RPS for simple routes.

Ambassador vs. Other Ingress Controllers

Kubernetes Ingress Controller Comparison
Aspect	Ambassador/Emissary	NGINX Ingress	Contour	Traefik
Underlying Proxy	Envoy	NGINX	Envoy	Go (native)
Config Model	CRDs	Annotations + CRDs	CRDs (HTTPProxy)	CRDs + annotations
Dynamic Config	Full xDS (hot)	Reload (brief drop)	Full xDS (hot)	Native (hot)
gRPC Support	Excellent	Good	Excellent	Good
Rate Limiting	External service	Annotations	External service	Built-in (basic)
Auth Integration	External AuthService	OAuth proxy sidecar	External	Forward Auth
Learning Curve	Moderate	Low	Low-Moderate	Low
Enterprise Version	Ambassador Edge Stack	NGINX Plus	N/A	Traefik Enterprise

Choose Ambassador When

•Envoy ecosystem — Using Istio, want consistency
•Advanced traffic management — Canary, shadow, weighted
•gRPC-heavy — First-class gRPC support
•Zero-downtime config — xDS eliminates reload drops
•Enterprise features — Ambassador Edge Stack

Consider Alternatives When

•Simple requirements — Basic routing, NGINX suffices
•NGINX expertise — Team knows NGINX deeply
•Resource constrained — Lower memory footprint needed
•Standard Ingress — Only need Ingress spec, not CRDs

Ambassador Edge Stack (Enterprise)

Ambassador Edge Stack (formerly Ambassador Pro) is the commercial offering with additional enterprise features:

Key Enterprise Features

Edge Stack vs. Emissary-Ingress (OSS)
Feature	Emissary-Ingress (OSS)	Ambassador Edge Stack
Core Routing	✅	✅
External Auth	✅	✅
Rate Limiting	External only	Built-in + External
OAuth2/OIDC Filter	❌	✅ Native
JWT Validation	External auth	✅ Built-in
Developer Portal	❌	✅
RBAC for Teams	K8s RBAC only	✅ Enhanced
Advanced Metrics	Prometheus only	✅ Enhanced dashboards
Commercial Support	❌	✅ 24/7 SLA

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
apiVersion: getambassador.io/v3alpha1
kind: FilterPolicy
metadata:
  name: oauth2-policy
spec:
  rules:
    - host: api.example.com
      path: /api/*
      filters:
        - name: oauth2-filter
          namespace: ambassador
          arguments:
            scopes:
              - api:read
              - api:write
---
apiVersion: getambassador.io/v3alpha1
kind: Filter
metadata:
  name: oauth2-filter
spec:
  OAuth2:
    authorizationURL: https://auth.example.com/oauth2/authorize
    tokenURL: https://auth.example.com/oauth2/token
    clientID: ambassador-client
    secret: ambassador-oauth-secret
    protectedOrigins:
      - origin: https://api.example.com

Licensing Consideration

Edge Stack pricing is typically per-cluster or per-node. Evaluate whether built-in OAuth and rate limiting justify the cost versus implementing external services with OSS Emissary-Ingress. Many organizations start with OSS and upgrade to Edge Stack when specific enterprise features are needed.

Summary: Ambassador / Emissary-Ingress

Key Takeaways

•Kubernetes-Native — CRD-based configuration, kubectl is the only interface, GitOps-ready.
•Envoy-Powered — Inherits Envoy's performance, xDS dynamic config, and extensive features.
•Zero-Downtime Config — xDS streaming eliminates configuration reload disruptions.
•Advanced Traffic Management — Canary, weighted routing, header-based routing built-in.
•External Services Pattern — Auth and rate limiting via external services, not embedded logic.
•OSS vs. Edge Stack — Evaluate whether enterprise OAuth, built-in rate limiting justify license cost.

What's Next:

Having explored Ambassador as a Kubernetes-native gateway built on Envoy, we'll next examine Envoy itself—the service proxy that powers not just Ambassador but also Istio, Contour, and numerous other cloud-native projects.

Page Complete

You now understand Ambassador's Kubernetes-native architecture, CRD-based configuration, Envoy foundation, and when it's the optimal choice for Kubernetes deployments.