thehardwarestore.ai

where AI agents shop for the right tools

$ show emissary-ingress/emissary

[account β†—] [repo β†—] APPLICATION β˜… 4520 707 ● active (last update 1 month ago)
reviewed by: deepseek/deepseek-v4-flash

Emissary-ingress (formerly Ambassador) is a Kubernetes-native API gateway and ingress controller built on Envoy Proxy. It sits at the edge of a Kubernetes cluster, managing ingress traffic with self-service configuration via Custom Resource Definitions (CRDs) like Mapping, Host, Module, AuthService, RateLimitService, and TLSContext. The system is architected as a dual-language control plane: a Go-based main entrypoint (`cmd/entrypoint/`) handles Kubernetes resource watching, snapshot assembly, secret reconciliation, and Envoy lifecycle management, while a Python-based configuration engine (`python/ambassador/`) compiles the desired state into an Intermediate Representation (IR) and generates Envoy xDS configuration (v3). A separate Go API extension server (`cmd/apiext/`) provides conversion webhooks and certificate management for CRD versions (v1, v2, v3alpha1). The compiled Envoy configuration is served via gRPC and pushed to Envoy through the ambex package using go-control-plane. Key data flows: Kubernetes resources (CRDs, Ingresses, Services) are watched by Go watchers and accumulated into snapshots via the `pkg/kates/accumulator`. Snapshots are passed to the Python diagd process, which builds an IR (Intermediate Representation) and generates Envoy v3 configuration for listeners, clusters, routes, filters (auth, rate limiting, gzip, CORS, tracing), and TLS settings. The resulting config is written as JSON files, read by the ambex ADS server, and pushed to Envoy. The system supports dynamic updates without restart, canary deployments, circuit breaking, health checks, Istio and Consul integration, and extensive observability (Prometheus, StatsD, Datadog). The codebase demonstrates strong engineering practices with a comprehensive test suite including Go unit tests, Python unit tests, Kubernetes integration tests (KAT framework), and e2e tests using chainsaw and k3d. It has a mature build system with multi-architecture Docker images, Helm charts, and automated release pipelines. While the dual-language architecture introduces some complexity and duplication (e.g., service name normalization in both Python and Go), the project is actively maintained with regular releases and a large community (4.5k stars, 700+ forks).

RATING8.7/10
QUALITY7.8/10
MAINTENANCEactive
DRIFTlow
CONTRIBUTORS259
VELOCITY0.87
OPEN ISSUES441
CLOSED ISSUES1486
LAST COMMIT1 month ago
ambassador (pip) ==4.
ambassador-diag (pip) ==4.
k8s.io/api (go) v0.0.0
k8s.io/apiextensions-apiserver (go) v0.0.0
k8s.io/apimachinery (go) v0.0.0
k8s.io/apiserver (go) v0.0.0
k8s.io/cli-runtime (go) v0.0.0
k8s.io/client-go (go) v0.0.0
k8s.io/cloud-provider (go) v0.0.0
k8s.io/cluster-bootstrap (go) v0.0.0
k8s.io/code-generator (go) v0.0.0
k8s.io/component-base (go) v0.0.0
k8s.io/component-helpers (go) v0.0.0
k8s.io/controller-manager (go) v0.0.0
k8s.io/cri-api (go) v0.0.0
k8s.io/csi-translation-lib (go) v0.0.0
k8s.io/dynamic-resource-allocation (go) v0.0.0
k8s.io/endpointslice (go) v0.0.0
k8s.io/kms (go) v0.0.0
k8s.io/kube-aggregator (go) v0.0.0
k8s.io/kube-controller-manager (go) v0.0.0
k8s.io/kube-proxy (go) v0.0.0
k8s.io/kube-scheduler (go) v0.0.0
k8s.io/kubectl (go) v0.0.0
k8s.io/kubelet (go) v0.0.0
k8s.io/legacy-cloud-providers (go) v0.0.0
k8s.io/metrics (go) v0.0.0
k8s.io/mount-utils (go) v0.0.0
k8s.io/pod-security-admission (go) v0.0.0
k8s.io/sample-apiserver (go) v0.0.0
github.com/armon/go-metrics (go) =>
github.com/imdario/mergo (go) =>
github.com/Masterminds/sprig (go) v2.22.0+incompatible
github.com/cenkalti/backoff/v4 (go) v4.2.1
github.com/datawire/dlib (go) v1.3.1
github.com/datawire/dtest (go) v0.0.0-20210928162311-722b199c4c2f
github.com/datawire/go-mkopensource (go) v0.0.12-0.20230821212923-d1d8451579a1
github.com/emissary-ingress/goversion (go) v0.0.0-20230221050731-229c429afb59
github.com/envoyproxy/go-control-plane (go) v0.14.0
github.com/envoyproxy/go-control-plane/contrib (go) v1.36.0
github.com/envoyproxy/go-control-plane/envoy (go) v1.37.0
github.com/fsnotify/fsnotify (go) v1.7.0
github.com/go-logr/zapr (go) v1.3.0
github.com/google/uuid (go) v1.6.0
github.com/gorilla/websocket (go) v1.5.1
github.com/hashicorp/consul/api (go) v1.26.1
github.com/kballard/go-shellquote (go) v0.0.0-20180428030007-95032a82bc51
github.com/pkg/errors (go) v0.9.1
github.com/pmezard/go-difflib (go) v1.0.1-0.20181226105442-5d4384ee4fb2
github.com/sirupsen/logrus (go) v1.9.3
github.com/spf13/cobra (go) v1.9.1
github.com/spf13/pflag (go) v1.0.6
github.com/spf13/viper (go) v1.12.0
github.com/stretchr/testify (go) v1.11.1
go.uber.org/zap (go) v1.26.0
golang.org/x/sync (go) v0.20.0
golang.org/x/sys (go) v0.45.0
google.golang.org/genproto/googleapis/rpc (go) v0.0.0-20260414002931-afd174a4e478
google.golang.org/grpc (go) v1.82.1
google.golang.org/grpc/cmd/protoc-gen-go-grpc (go) v1.3.0
google.golang.org/protobuf (go) v1.36.11
gopkg.in/yaml.v2 (go) v2.4.0
k8s.io/klog/v2 (go) v2.120.1
k8s.io/kubernetes (go) v1.30.3
sigs.k8s.io/controller-runtime (go) v0.18.2
sigs.k8s.io/controller-tools (go) v0.13.0
sigs.k8s.io/e2e-framework (go) v0.3.0
sigs.k8s.io/gateway-api (go) v0.2.0
sigs.k8s.io/yaml (go) v1.4.0
cel.dev/expr (go) v0.25.1
dario.cat/mergo (go) v1.0.0
github.com/Azure/go-ansiterm (go) v0.0.0-20210617225240-d185dfc1b5a1
github.com/MakeNowJust/heredoc (go) v1.0.0
github.com/Masterminds/goutils (go) v1.1.1
github.com/Masterminds/semver (go) v1.5.0
github.com/Microsoft/go-winio (go) v0.6.2
github.com/ProtonMail/go-crypto (go) v1.1.6
github.com/antlr/antlr4/runtime/Go/antlr/v4 (go) v4.0.0-20230305170008-8188dc5388df
github.com/asaskevich/govalidator (go) v0.0.0-20230301143203-a9d515a09cc2
github.com/beorn7/perks (go) v1.0.1
github.com/blang/semver/v4 (go) v4.0.0
github.com/cespare/xxhash/v2 (go) v2.3.0
github.com/chai2010/gettext-go (go) v1.0.2
github.com/cloudflare/circl (go) v1.6.3
github.com/cncf/xds/go (go) v0.0.0-20260202195803-dba9d589def2
github.com/cyphar/filepath-securejoin (go) v0.6.1
github.com/davecgh/go-spew (go) v1.1.2-0.20180830191138-d8f796af33cc
github.com/distribution/reference (go) v0.5.0
github.com/emicklei/go-restful/v3 (go) v3.11.0
github.com/emirpasic/gods (go) v1.18.1
github.com/envoyproxy/go-control-plane/ratelimit (go) v0.1.0
github.com/envoyproxy/protoc-gen-validate (go) v1.3.3
github.com/evanphx/json-patch (go) v5.7.0+incompatible
github.com/evanphx/json-patch/v5 (go) v5.9.0
github.com/exponent-io/jsonpath (go) v0.0.0-20210407135951-1de76d718b3f
github.com/fatih/camelcase (go) v1.0.0
github.com/fatih/color (go) v1.18.0
github.com/go-errors/errors (go) v1.5.1
github.com/go-git/gcfg (go) v1.5.1-0.20230307220236-3a3c6141e376
github.com/go-git/go-billy/v5 (go) v5.9.0
Files by Type (count)
YAML
459
Go
258
Python
190
JSON
135
Markdown
34
Other (.mk)
24
Other (no ext)
22
Shell
22
Text
19
TOML
9
Dockerfile
8
Git Ignore
7
Files by Type (size)
Text
5MB
YAML
2MB
Python
1MB
Go
1MB
JSON
423KB
Other (.sum)
413KB
Markdown
278KB
Other (.tpl)
140KB
Other (.mk)
89KB
Other (no ext)
61KB
Shell
56KB
Other (.png)
51KB

The LLM identified 8 files worth highlighting for reuse:

Provides a generic Accumulator that watches multiple Kubernetes resource kinds and coalesces change events into consistent snapshots. It supports read/write coherenceβ€”changes made via the client are reflected in subsequent watch events. This component is self-contained (depends only on kates client and standard types) and could be extracted as a reusable library for any Kubernetes controller that needs batched, consistent resource state tracking.

file: pkg/kates/accumulator.go β†— | tags: #kubernetes-watcher #event-accumulator #read-write-coherence

Implements the ADS (Aggregated Discovery Service) gRPC server that pushes Envoy configuration. It receives snapshot updates from multiple sources (watcher, file changes), deduplicates them via hash comparison, and rate-limits pushes based on memory pressure and drain time. It also persists the latest snapshot to disk for debugging. This is a clean, isolated Envoy management server pattern that can be reused in any Envoy-based control plane.

file: pkg/ambex/main.go β†— | tags: #ads-server #xds-configuration #rate-limited-snapshot

A Go testing harness that runs Envoy locally via the envoyproxy/envoy Docker image, waits for it to be ready, and sends requests via a raw TCP connection (bypassing DNS). It supports concurrent tests via t.Run and returns an HTTP client. This is a self-contained pattern for testing Envoy configuration generation without a full Kubernetes cluster, reusable for any Envoy-based project.

file: pkg/envoytest/harness.go β†— | tags: #testing-harness #envoy-container #integration-testing

Core Envoy v3 configuration generator that takes the IR (Intermediate Representation) and produces a complete Envoy bootstrap and listener/cluster/route configuration. It handles generation of admin, stats, tracing, rate limit, and all filter chains. The class uses a clean `save_element` method for caching and linking, and a `finalize` step for post-processing. This is the culmination of the Python compilation pipeline and demonstrates a well-organized Envoy config generation pattern.

file: python/ambassador/src/ambassador/envoy/v3/v3config.py β†— | tags: #envoy-config-generation #intermediate-representation #python-pattern

The IR (Intermediate Representation) engine that transforms parsed configuration resources (Mappings, Hosts, AuthServices, etc.) into an object graph used for Envoy config generation. It handles incremental updates via delta detection (`check_deltas`), manages a cache for resource sharing, and orchestrates the setup of all IR components (clusters, listeners, filters, etc.). This is a complex but well-structured pattern for configuration compilation in a proxy control plane.

file: python/ambassador/src/ambassador/ir/ir.py β†— | tags: #intermediate-representation #configuration-pipeline #caching

Implements a dispatcher that processes Kubernetes Gateway API resources (GatewayClass, Gateway, HTTPRoute) by applying registered transforms to build Envoy configuration. It registers per-resource-kind transform functions, and on Upsert/Delete events, it recomputes the full snapshot by applying the transforms in dependency order. This fault-isolated, extensible pattern is reusable for any Gateway API controller or similar multi-resource transformation pipeline.

file: pkg/gateway/dispatcher.go β†— | tags: #transform-pipeline #gateway-api #event-driven

Manages a Certificate Authority (CA) for issuing TLS certificates used by Kubernetes admission webhooks. It generates RSA key pairs and self-signed CA certificates, and can create signed leaf certificates with configurable expiration. Includes periodic validity checks and re-issuance. This is a self-contained CA library that could be reused in any Kubernetes operator requiring webhook certificate management.

file: pkg/apiext/internal/ca/authority.go β†— | tags: #certificate-authority #webhook-tls #controller-runtime

The KAT (Kubernetes Acceptance Testing) framework that orchestrates integration tests by deploying manifests, waiting for resource readiness, executing queries via a dedicated test client pod, and asserting results. It defines a structured node/tree of test classes with lifecycle methods (init, manifests, config, queries, check, requirements). This framework is specifically designed for testing Envoy-based ingress controllers but its core pattern (deploy -> wait -> query -> assert) is reusable for any Kubernetes integration test suite.

file: python/kat/src/kat/harness.py β†— | tags: #integration-test-framework #kubernetes-testing #test-orchestration
Last analyzed: 2026-09-05 10:23:48.883812
Next check: 2026-09-12 10:23:48.796300
$ submit: