← Back to Frameworks

Ambassador

Kubernetes-native API Gateway. Based on Envoy proxy, provides GitOps workflows, canary deployments, and rate limiting capabilities.

API GatewayKubernetesEnvoy ProxyGitOpsCloud Native

Server

Ambassador

Overview

Ambassador is a Kubernetes-native API Gateway built on Envoy Proxy, designed specifically for cloud-native applications and microservices architectures. As an open-source solution that emphasizes developer productivity and self-service configuration, Ambassador provides declarative configuration through Custom Resource Definitions (CRDs) and integrates seamlessly with GitOps workflows. Known for its developer-friendly approach and Kubernetes-first design philosophy, Ambassador enables teams to manage ingress traffic with advanced features like canary deployments, rate limiting, and progressive delivery while maintaining the simplicity that modern development teams require.

Details

Ambassador 2025 edition continues to evolve as a leading Kubernetes-native API Gateway, leveraging the power of Envoy Proxy for high-performance traffic management. The platform is now available as Emissary-Ingress (CNCF incubating project) and Ambassador Edge Stack (commercial offering), providing options for different organizational needs. Built around the principle of developer self-service, Ambassador eliminates the traditional bottlenecks of centralized gateway management by allowing application teams to configure routing and policies independently. The solution excels in Kubernetes environments with its CRD-based configuration model, native integration with service mesh technologies, and strong support for modern deployment patterns like canary releases and blue-green deployments.

Key Features

  • Kubernetes-Native Architecture: CRD-based configuration with seamless K8s integration
  • Envoy Proxy Foundation: High-performance L7 proxy with advanced load balancing
  • GitOps Workflow Support: Declarative configuration management with version control
  • Developer Self-Service: Independent team configuration without central bottlenecks
  • Advanced Traffic Management: Canary deployments, circuit breaking, and retry policies
  • Observability Integration: Built-in metrics, tracing, and monitoring capabilities

Advantages and Disadvantages

Advantages

  • Native Kubernetes integration with CRD-based configuration providing seamless developer experience
  • Envoy Proxy foundation delivering enterprise-grade performance and reliability with proven scaling capabilities
  • GitOps-friendly declarative configuration enabling version-controlled infrastructure management
  • Developer-centric workflow reducing operational overhead and enabling team autonomy
  • Strong CNCF ecosystem integration with service mesh and cloud-native tooling compatibility
  • Comprehensive documentation and active community support with regular feature updates

Disadvantages

  • Kubernetes dependency limiting deployment options to container orchestration environments
  • Learning curve for teams unfamiliar with Kubernetes concepts and CRD management
  • Resource overhead compared to simpler proxy solutions for basic use cases
  • Limited enterprise features in open-source version requiring commercial upgrade
  • Envoy Proxy complexity can make troubleshooting challenging for teams without L7 proxy experience
  • Rapid project evolution with potential breaking changes between major versions

Reference Links

Code Examples

Installation and Basic Setup

# Install Ambassador using kubectl
kubectl apply -f https://app.getambassador.io/yaml/emissary/3.9.1/emissary-crds.yaml
kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system
kubectl apply -f https://app.getambassador.io/yaml/emissary/3.9.1/emissary-emissaryns.yaml

# Install using Helm
helm repo add datawire https://app.getambassador.io
helm repo update
helm install emissary-ingress datawire/emissary-ingress \
  --namespace emissary \
  --create-namespace

# Verify installation
kubectl get pods -n emissary-system
kubectl get service -n emissary-system

# Get external IP
kubectl get service ambassador -n emissary-system

Basic Service Configuration

# Service definition
apiVersion: v1
kind: Service
metadata:
  name: example-service
  namespace: default
spec:
  selector:
    app: example-app
  ports:
  - port: 80
    targetPort: 8080
    name: http

---
# Basic Mapping (Route configuration)
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
  name: example-mapping
  namespace: default
spec:
  hostname: api.example.com
  prefix: /api/
  service: example-service:80
  timeout_ms: 3000
  retry_policy:
    retry_on: "5xx"
    num_retries: 3

---
# Alternative HTTP route using Kubernetes Gateway API
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: example-route
spec:
  parentRefs:
  - name: ambassador
    namespace: emissary-system
  hostnames:
  - api.example.com
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api/
    backendRefs:
    - name: example-service
      port: 80

Advanced Routing and Traffic Management

# Host-based routing
apiVersion: getambassador.io/v3alpha1
kind: Host
metadata:
  name: example-host
spec:
  hostname: api.example.com
  acmeProvider:
    authority: https://acme-v02.api.letsencrypt.org/directory
    email: [email protected]
  tlsSecret:
    name: example-tls-secret

---
# Weighted routing for canary deployments
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
  name: example-canary
spec:
  hostname: api.example.com
  prefix: /api/v2/
  service: example-service-v2:80
  weight: 20  # 20% traffic to v2

---
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
  name: example-stable
spec:
  hostname: api.example.com
  prefix: /api/v2/
  service: example-service-v1:80
  weight: 80  # 80% traffic to v1

---
# Header-based routing
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
  name: example-header-routing
spec:
  hostname: api.example.com
  prefix: /api/
  service: example-service-beta:80
  headers:
    x-canary-user: "true"

Authentication and Authorization

# JWT Authentication Filter
apiVersion: getambassador.io/v3alpha1
kind: Filter
metadata:
  name: jwt-filter
spec:
  JWT:
    jwksURI: "https://auth.example.com/.well-known/jwks.json"
    audience: "api.example.com"
    issuer: "https://auth.example.com"

---
# OAuth2 Filter
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: "oauth2-client-secret"
    scopes:
    - "read"
    - "write"

---
# Apply authentication to mapping
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
  name: protected-api
spec:
  hostname: api.example.com
  prefix: /protected/
  service: protected-service:80
  filters:
  - name: jwt-filter
    namespace: default

Rate Limiting and Circuit Breaking

# Rate Limit Filter
apiVersion: getambassador.io/v3alpha1
kind: RateLimitService
metadata:
  name: ratelimit-service
spec:
  service: "ratelimit:5000"

---
apiVersion: getambassador.io/v3alpha1
kind: RateLimit
metadata:
  name: api-rate-limit
spec:
  domain: ambassador
  limits:
  - pattern:
    - generic_key:
        descriptor_value: "api-requests"
    rate: 100
    unit: minute

---
# Circuit Breaker configuration
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
  name: circuit-breaker-example
spec:
  hostname: api.example.com
  prefix: /api/
  service: example-service:80
  circuit_breakers:
  - max_connections: 100
    max_pending_requests: 50
    max_requests: 200
    max_retries: 3
    consecutive_5xx: 5
    interval: 30s
    base_ejection_time: 30s
    max_ejection_percent: 50

gRPC and WebSocket Support

# gRPC service mapping
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
  name: grpc-service
spec:
  hostname: grpc.example.com
  prefix: /
  service: grpc-service:9090
  grpc: true
  timeout_ms: 10000

---
# WebSocket service mapping
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
  name: websocket-service
spec:
  hostname: ws.example.com
  prefix: /ws
  service: websocket-service:8080
  use_websocket: true
  idle_timeout_ms: 60000

Observability and Monitoring

# Distributed tracing configuration
apiVersion: getambassador.io/v3alpha1
kind: TracingService
metadata:
  name: tracing-service
spec:
  service: "jaeger:14268"
  driver: jaeger
  config:
    service_name: ambassador
    sampler:
      type: probabilistic
      param: 0.1

---
# Metrics and monitoring
apiVersion: getambassador.io/v3alpha1
kind: Module
metadata:
  name: ambassador
spec:
  config:
    diagnostics:
      enabled: true
    statsd:
      enabled: true
      host: "statsd-service"
    enable_grpc_http11_bridge: true
    enable_grpc_web: true
    proper_case: true

TLS and Security Configuration

# TLS Context for custom certificates
apiVersion: getambassador.io/v3alpha1
kind: TLSContext
metadata:
  name: example-tls-context
spec:
  hosts:
  - api.example.com
  secret: example-tls-secret
  min_tls_version: v1.2
  max_tls_version: v1.3
  cipher_suites:
  - "ECDHE-RSA-AES128-GCM-SHA256"
  - "ECDHE-RSA-AES256-GCM-SHA384"
  ecdh_curves:
  - "X25519"
  - "P-256"

---
# CORS configuration
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
  name: cors-example
spec:
  hostname: api.example.com
  prefix: /api/
  service: example-service:80
  cors:
    origins: 
    - "https://app.example.com"
    - "https://admin.example.com"
    methods:
    - GET
    - POST
    - PUT
    - DELETE
    headers:
    - Content-Type
    - Authorization
    exposed_headers:
    - X-Request-ID
    credentials: true
    max_age: "86400"

Development and Testing

# Development mapping with debug headers
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
  name: dev-mapping
spec:
  hostname: dev.example.com
  prefix: /api/
  service: example-service:80
  add_request_headers:
    x-environment: "development"
    x-debug-mode: "true"
  add_response_headers:
    x-served-by: "ambassador-dev"
  remove_request_headers:
  - x-internal-header

Edge Stack Features (Commercial)

# Service Preview for development
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
  name: preview-mapping
  annotations:
    getambassador.io/service-preview.enabled: "true"
spec:
  hostname: preview.example.com
  prefix: /api/
  service: preview-service:80
  load_balancer:
    policy: round_robin

---
# Advanced load balancing
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
  name: advanced-lb
spec:
  hostname: api.example.com
  prefix: /api/
  service: example-service:80
  load_balancer:
    policy: ring_hash
    hash_policy:
    - header:
        name: "x-user-id"
  outlier_detection:
    consecutive_5xx: 3
    interval: 30s
    base_ejection_time: 30s