README
¶
Emissary-ingress
Emissary-Ingress is an open-source Kubernetes-native API Gateway + Layer 7 load balancer + Kubernetes Ingress built on Envoy Proxy. Emissary-ingress is a CNCF incubation project (and was formerly known as Ambassador API Gateway).
Emissary-ingress enables its users to:
- Manage ingress traffic with load balancing, support for multiple protocols (gRPC and HTTP/2, TCP, and web sockets), and Kubernetes integration
- Manage changes to routing with an easy to use declarative policy engine and self-service configuration, via Kubernetes CRDs or annotations
- Secure microservices with authentication, rate limiting, and TLS
- Ensure high availability with sticky sessions, rate limiting, and circuit breaking
- Leverage observability with integrations with Grafana, Prometheus, and Datadog, and comprehensive metrics support
- Enable progressive delivery with canary releases
- Connect service meshes including Consul, Linkerd, and Istio
- Knative serverless integration
See the full list of features here.
Branches
(If you are looking at this list on a branch other than master, it
may be out of date.)
master- branch for Emissary-ingress 3.7.z work (✔ upcoming release)release/v3.6- branch for Emissary-ingress 3.6.z workrelease/v2.5- branch for Emissary-ingress 2.5.z work (✔ upcoming release)release/v1.14- branch for Emissary-ingress 1.14.z work (✔ maintenance, supported through September 2022)
Architecture
Emissary is configured via Kubernetes CRDs, or via annotations on Kubernetes Services. Internally,
it uses the [Envoy Proxy] to actually handle routing data; externally, it relies on Kubernetes for
scaling and resiliency. For more on Emissary's architecture and motivation, read this blog post.
Getting Started
You can get Emissary up and running in just three steps. Follow the instructions here: https://www.getambassador.io/docs/emissary/latest/tutorials/getting-started/
If you are looking for a Kubernetes ingress controller, Emissary provides a superset of the functionality of a typical ingress controller. (It does the traditional routing, and layers on a raft of configuration options.) This blog post covers Kubernetes ingress.
For other common questions, view this FAQ page.
You can also use Helm to install Emissary. For more information, see the instructions in the Helm installation documentation
Check out full the Emissary documentation at www.getambassador.io.
Community
Emissary-ingress is a CNCF Incubating project and welcomes any and all contributors.
Check out the Community/ directory for information on
the way the community is run, including:
- the
CODE_OF_CONDUCT.md - the
GOVERNANCE.mdstructure - the list of
MAINTAINERS.md - the
MEETING_SCHEDULE.mdof regular trouble-shooting meetings and contributor meetings - how to get
SUPPORT.md.
The best way to join the community is to join our Slack channel.
Check out the DevDocumentation/ directory for
information on the technicals of Emissary, most notably the
DEVELOPING.md contributor's guide.
If you're interested in contributing, here are some ways:
- Write a blog post for our blog
- Investigate an open issue
- Add more tests
The Ambassador Edge Stack is a superset of Emissary-ingress that provides additional functionality including OAuth/OpenID Connect, advanced rate limiting, Swagger/OpenAPI support, integrated ACME support for automatic TLS certificate management, and a cloud-based UI. For more information, visit https://www.getambassador.io/editions/.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
busyambassador
Ambassador combines the various Golang binaries used in the Ambassador container, dispatching on os.Args[0] like BusyBox.
|
Ambassador combines the various Golang binaries used in the Ambassador container, dispatching on os.Args[0] like BusyBox. |
|
docker
|
|
|
pkg
|
|
|
api/getambassador.io/v1
Package v1 contains API Schema definitions for the getambassador.io v1 API group
|
Package v1 contains API Schema definitions for the getambassador.io v1 API group |
|
api/getambassador.io/v2
Package v2 contains API Schema definitions for the getambassador.io v2 API group
|
Package v2 contains API Schema definitions for the getambassador.io v2 API group |
|
api/getambassador.io/v3alpha1
Package v3alpha1 contains API Schema definitions for the getambassador.io v3alpha1 API group
|
Package v3alpha1 contains API Schema definitions for the getambassador.io v3alpha1 API group |
|
busy
Package busy implements a dispatcher for BusyBox-style multi-call binaries.
|
Package busy implements a dispatcher for BusyBox-style multi-call binaries. |
|
debug
The debug package is intended to aid in live debugging of misbehaving Ambassadors in production.
|
The debug package is intended to aid in live debugging of misbehaving Ambassadors in production. |
|
envoy-control-plane/cache/v3
Package cache defines a configuration cache for the server.
|
Package cache defines a configuration cache for the server. |
|
envoy-control-plane/client/sotw/v3
Package sotw provides an implementation of GRPC SoTW (State of The World) part of XDS client
|
Package sotw provides an implementation of GRPC SoTW (State of The World) part of XDS client |
|
envoy-control-plane/conversion
Package conversion contains shared utility functions for converting xDS resources.
|
Package conversion contains shared utility functions for converting xDS resources. |
|
envoy-control-plane/log
Package log provides a logging interface for use in this library.
|
Package log provides a logging interface for use in this library. |
|
envoy-control-plane/server/rest/v3
Package rest provides an implementation of REST-JSON part of XDS server
|
Package rest provides an implementation of REST-JSON part of XDS server |
|
envoy-control-plane/server/sotw/v3
Package sotw provides an implementation of GRPC SoTW (State of The World) part of XDS server
|
Package sotw provides an implementation of GRPC SoTW (State of The World) part of XDS server |
|
envoy-control-plane/server/v3
Package server provides an implementation of a streaming xDS server.
|
Package server provides an implementation of a streaming xDS server. |
|
envoy-control-plane/test
Package test contains test utilities
|
Package test contains test utilities |
|
envoy-control-plane/test/main
Package main contains the test driver for testing xDS manually.
|
Package main contains the test driver for testing xDS manually. |
|
envoy-control-plane/test/resource/v3
Package resource creates test xDS resources
|
Package resource creates test xDS resources |
|
envoy-control-plane/test/v3
Package test contains test utilities
|
Package test contains test utilities |
|
envoy-control-plane/wellknown
Package wellknown contains common names for filters, listeners, etc.
|
Package wellknown contains common names for filters, listeners, etc. |
|
k8s
Package k8s is a facade over (super-terrible, very difficult to understand) client-go to provide a higher-level interface to Kubernetes, with support for simple, high-level APIs for watching resources (including from stable, long-running processes) and implementing basic controllers.
|
Package k8s is a facade over (super-terrible, very difficult to understand) client-go to provide a higher-level interface to Kubernetes, with support for simple, high-level APIs for watching resources (including from stable, long-running processes) and implementing basic controllers. |
|
kates
The kates package is a library for writing kubernetes extensions.
|
The kates package is a library for writing kubernetes extensions. |
|
metriton
Package metriton implements submitting telemetry data to the Metriton database.
|
Package metriton implements submitting telemetry data to the Metriton database. |
|
tools
|
|
|
src/dsum
Command dsum (short for d-summarize) helps keep good developer UX while running a command with potentially noisy output.
|
Command dsum (short for d-summarize) helps keep good developer UX while running a command with potentially noisy output. |
|
src/filter-yaml
This script is to help generate any flat yaml files from the emissary helm chart.
|
This script is to help generate any flat yaml files from the emissary helm chart. |
|
src/flock
flock.go is a minimal implementation of flock(1) (from util-linux) for systems that don't have flock(1) but do have flock(2).
|
flock.go is a minimal implementation of flock(1) (from util-linux) for systems that don't have flock(1) but do have flock(2). |
|
src/gotest2tap
gotest2tap.go translates `go test -json` on stdin to TAP v13 on stdout.
|
gotest2tap.go translates `go test -json` on stdin to TAP v13 on stdout. |
|
src/testcert-gen
Command testcert-gen generates TLS certificates and keys for use in the Emissary test suite.
|
Command testcert-gen generates TLS certificates and keys for use in the Emissary test suite. |