DOCSEARCHbyAlgolia
Submit Docs

Emissary-ingress Documentation

repository·main·Indexed 26 days ago

https://github.com/emissary-ingress/emissary

A Kubernetes-native API Gateway and Layer 7 load balancer built on Envoy Proxy. It provides traffic management, security, and observability for microservices, supporting gRPC, HTTP/2, TCP, and WebSockets. The project includes tools like Ambex (an experimental Aggregated Discovery Service), kubestatus for managing Kubernetes resource statuses, and kat for Kubernetes acceptance testing.

Tokens
20.3K
Snippets
29
Records
127
Agent score
86%

What's inside Emissary-ingress

  1. Overview of kat Kubernetes Acceptance Testing tool

    main

    kat is a Kubernetes acceptance testing tool designed to streamline the process of testing applications built on Kubernetes. It is optimized for speed by batching resource applications and executing API queries asynchronously.

    The tool automates the following workflow:

    1. Applying multiple YAML manifests in a single batch.
    2. Waiting for services to become available.
    3. Running multiple queries against the spun-up APIs.
    4. Performing assertions on the query results.

  2. Overview of Emissary-ingress

    main

    Emissary-ingress is an open-source, Kubernetes-native API Gateway, Layer 7 load balancer, and Kubernetes Ingress built on Envoy Proxy. It is a CNCF incubation project.

    Key capabilities include:

    • Traffic Management: Load balancing with support for gRPC, HTTP/2, TCP, and WebSockets.
    • Declarative Configuration: Manage routing via Kubernetes Custom Resource Definitions (CRDs) or annotations on Kubernetes Services.
    • Security: Authentication, rate limiting, and TLS termination.
    • Resiliency: Sticky sessions, rate limiting, and circuit breaking.
    • Observability: Integrations with Grafana, Prometheus, and Datadog.
    • Advanced Deployment: Canary releases and progressive delivery.
    • Integrations: Connects with service meshes like Consul, Linkerd, and Istio, and supports Knative serverless integration.

  3. Overview of Emissary-ingress Architecture

    main

    Emissary-ingress is a Kubernetes-native API Gateway built on top of Envoy Proxy. It uses Kubernetes Custom Resource Definitions (CRDs) to provide a declarative, cloud-native way to configure Envoy Proxy for routing cluster traffic.

    Core components include:

    • CRDs: Extend the Kubernetes API with Emissary-specific abstractions.
    • Apiext: A dedicated container implementing the Webhook Conversion interface for CRDs.
    • Diagd: An in-process component providing a diagnostic UI and translating snapshots/IR into Envoy configuration.
    • Ambex: An in-process gRPC server implementing Envoy xDS for dynamic configuration.
    • Envoy Proxy: The in-process proxy that handles all user traffic routing.

  4. Understand the Emissary-ingress Container Architecture

    main

    Emissary-ingress is packaged as a single container image containing all necessary components to simplify Envoy Proxy deployment in a cloud-native environment. The container uses a single entrypoint to manage multiple binaries (Golang, Python, and C++).

    Core Components

    • busyambassador: A Golang binary that acts as a dispatcher (similar to busybox). It allows the container to support multiple binaries by dispatching commands provided in the Kubernetes deployment command field.
    • entrypoint: The default Golang binary run by busyambassador. It serves as the parent process, managing various goroutines and child OS processes.
    • diagd: A Python program that provides a Diagnostic Admin UI and processes cluster changes into Envoy-ready configurations.
    • ambex: The Envoy ADS (Aggregated Discovery Service) Server, implemented as a gRPC server that implements Envoy xDS v2 and v3 APIs.
    • envoy: A specialized fork of Envoy Proxy that handles routing, filtering, TLS termination, metrics, and tracing.
    • Watt (Watch All The Things): A component within the entrypoint that watches for changes in the Kubernetes Cluster, Consul, and the local FileSystem to trigger configuration updates.

  5. Security priority and resource exhaustion concerns

    main

    Emissary-ingress prioritizes vulnerabilities that compromise data confidentiality or integrity.

    Availability (DoS and resource exhaustion) is also a high priority, especially since Emissary is often deployed at the edge. While standard resource consumption issues (e.g., high CPU/memory usage) are handled via the normal bugfix process, the formal security process is activated for high-risk profiles such as:

    • "Query of death": A single client query that can crash the entire Emissary instance.
    • Highly asymmetric resource exhaustion: Attacks where minimal traffic from a single client can cause significant resource exhaustion.

  6. Understand the Ambassador Configuration Pipeline

    main

    Ambassador transforms user-provided configuration into Envoy configuration through an intermediate stage. The pipeline follows this flow:

    Ambassador config $\rightarrow$ IR (Intermediate Representation) $\rightarrow$ Envoy config.

    This architecture allows Ambassador to manage complex internal logic and transformations before generating the final Envoy V1 configuration.

  7. Quickstart: Running Ambex with Envoy

    main

    To test the Ambex ADS service, follow these steps to run Ambex and an Envoy instance configured with a bootstrap ADS configuration.

    1. Start Ambex (using the --watch flag for instantaneous reloads):

      go run github.com/datawire/ambassador/cmd/busyambassador ambex --watch ./example/ambex/

    2. Start Envoy in a separate shell using a bootstrap configuration that points to Ambex:

      envoy -l debug -c ./example/envoy/bootstrap-ads.yaml

    3. Verify by sending a request via curl:

      $ curl localhost:8080/hello
Hello ADS!!!

  10. Follow the Ambassador configuration lifecycle

    main

    To generate an Envoy configuration from scratch, follow these steps:

    1. Construct ACResource objects: Use ACResource.from_dict or ACResource.from_yaml to create resources from your source (disk, K8s, etc.).
    2. Instantiate ambassador.Config: Call aconf.load_all(resources) with your collection.
    3. Instantiate ambassador.IR: Create the Intermediate Representation from the config: ir = IR(aconf).
    4. Instantiate ambassador.envoy.V1Config: Build the final Envoy configuration from the IR.

  11. Understand the configuration data flow (Watt to Envoy)

    main

    The configuration flow starts with Watt watching for changes in the Kubernetes API, Consul, or the FileSystem. When a change is detected, the following sequence occurs:

    1. Watt triggers Snapshot Generation.
    2. An in-memory snapshot is updated.
    3. diagd is notified.
    4. diagd processes the snapshot, generates an Intermediate Representation (IR), and creates Envoy configurations.
    5. diagd persists configuration files to the /ambassador/snapshots/ directory and the base directory (e.g., /ambassador/bootstrap-ads.json, /ambassador/envoy/envoy.json).
    6. diagd sends a SIGHUP signal to notify envoy and ambex of the new configuration.
    7. ambex (the ADS server) picks up the new configuration to serve it to Envoy via gRPC.

  12. Extend common.mk targets

    main

    The common.mk snippet provides a uniform interface by declaring high-level targets like make build, make clean, and make check. Most of these are provided as empty definitions, allowing you to extend them in your Makefile by adding dependencies.

    Extending standard targets

    To add a task to a target like build or lint, add the task as a dependency:

    # Build the 'foo' file when running 'make build'
build: foo

# Run flake8 when running 'make lint'
lint: flake8
flake8:
	flake8 mypackage/
.PHONY: flake8

    The special make check target

    Unlike other targets, make check uses a specific pattern involving test-suite.tap. To add a test to the check suite, do not use check: my-test. Instead, define a dependency on a .tap file:

    # CORRECT way to add a test to the check suite
test-suite.tap: my-test.tap

    common.mk also ensures that make clean automatically removes test-suite.tap.

    build: foo

lint: flake8
flake8:
	flake8 mypackage/
.PHONY: flake8

test-suite.tap: my-test.tap