1Emissary-ingress
2================
3
4<!-- [![Alt Text][image-url]][link-url] -->
5[![Version][badge-version-img]][badge-version-link]
6[![Docker Repository][badge-docker-img]][badge-docker-link]
7[![Join Slack][badge-slack-img]][badge-slack-link]
8[![Core Infrastructure Initiative: Best Practices][badge-cii-img]][badge-cii-link]
9
10[badge-version-img]: https://img.shields.io/docker/v/emissaryingress/emissary?sort=semver
11[badge-version-link]: https://github.com/emissary-ingress/emissary/releases
12[badge-docker-img]: https://img.shields.io/docker/pulls/emissaryingress/emissary
13[badge-docker-link]: https://hub.docker.com/r/emissaryingress/emissary
14[badge-slack-img]: https://img.shields.io/badge/slack-join-orange.svg
15[badge-slack-link]: https://a8r.io/slack
16[badge-cii-img]: https://bestpractices.coreinfrastructure.org/projects/1852/badge
17[badge-cii-link]: https://bestpractices.coreinfrastructure.org/projects/1852
18
19<!-- Links are (mostly) at the end of this document, for legibility. -->
20
21[Emissary-Ingress](https://www.getambassador.io) is an open-source Kubernetes-native API Gateway +
22Layer 7 load balancer + Kubernetes Ingress built on [Envoy Proxy](https://www.envoyproxy.io).
23Emissary-ingress is a CNCF incubation project (and was formerly known as Ambassador API Gateway).
24
25Emissary-ingress enables its users to:
26* Manage ingress traffic with [load balancing], support for multiple protocols ([gRPC and HTTP/2], [TCP], and [web sockets]), and Kubernetes integration
27* Manage changes to routing with an easy to use declarative policy engine and [self-service configuration], via Kubernetes [CRDs] or annotations
28* Secure microservices with [authentication], [rate limiting], and [TLS]
29* Ensure high availability with [sticky sessions], [rate limiting], and [circuit breaking]
30* Leverage observability with integrations with [Grafana], [Prometheus], and [Datadog], and comprehensive [metrics] support
31* Enable progressive delivery with [canary releases]
32* Connect service meshes including [Consul], [Linkerd], and [Istio]
33* [Knative serverless integration]
34
35See the full list of [features](https://www.getambassador.io/features/) here.
36
37Branches
38========
39
40(If you are looking at this list on a branch other than `master`, it
41may be out of date.)
42
43- [`master`](https://github.com/emissary-ingress/emissary/tree/master) - branch for Emissary-ingress 3.1.z work (:heavy_check_mark: current latest)
44- [`release/v3.0`](https://github.com/emissary-ingress/emissary/tree/release/v3.0) - branch for Emissary-ingress 3.0.z work (:x: EOL; upgrade to 3.1.z)
45- [`release/v2.4`](https://github.com/emissary-ingress/emissary/tree/release/v2.4) - branch for Emissary-ingress 2.4.z work (:heavy_check_mark: upcoming release)
46- [`release/v2.3`](https://github.com/emissary-ingress/emissary/tree/release/v2.3) - branch for Emissary-ingress 2.3.z work (:heavy_check_mark: maintenance, supported through December 2022)
47- [`release/v2.2`](https://github.com/emissary-ingress/emissary/tree/release/v2.2) - branch for Emissary-ingress 2.2.z work (:x: EOL; upgrade to 2.3.z)
48- [`release/v2.1`](https://github.com/emissary-ingress/emissary/tree/release/v2.1) - branch for Emissary-ingress 2.1.z work (:x: EOL; upgrade to 2.3.z)
49- [`release/v2.0`](https://github.com/emissary-ingress/emissary/tree/release/v2.0) - branch for Emissary-ingress 2.0.z work (:x: EOL; upgrade to 2.3.z)
50- [`release/v1.14`](https://github.com/emissary-ingress/emissary/tree/release/v1.14) - branch for Emissary-ingress 1.14.z work (:heavy_check_mark: maintenance, supported through September 2022)
51- [`release/v1.13`](https://github.com/emissary-ingress/emissary/tree/release/v1.13) - branch for Emissary-ingress 1.13.z work (:x: EOL; upgrade to 1.14.z)
52- [`release/v1.12`](https://github.com/emissary-ingress/emissary/tree/release/v1.12) - branch for Ambassador API Gateway 1.12.z work (:x: EOL; upgrade to 1.14.z)
53- [`release/v1.11`](https://github.com/emissary-ingress/emissary/tree/release/v1.11) - branch for Ambassador API Gateway 1.11.z work (:x: EOL; upgrade to 1.14.z)
54- [`release/v1.10`](https://github.com/emissary-ingress/emissary/tree/release/v1.10) - branch for Ambassador API Gateway 1.10.z work (:x: EOL; upgrade to 1.14.z)
55- [`release/v1.9`](https://github.com/emissary-ingress/emissary/tree/release/v1.9) - branch for Ambassador API Gateway 1.9.z work (:x: EOL; upgrade to 1.14.z)
56- [`release/v1.8`](https://github.com/emissary-ingress/emissary/tree/release/v1.8) - branch for Ambassador API Gateway 1.8.z work (:x: EOL; upgrade to 1.14.z)
57- [`release/v1.7`](https://github.com/emissary-ingress/emissary/tree/release/v1.7) - branch for Ambassador API Gateway 1.7.z work (:x: EOL; upgrade to 1.14.z)
58- [`release/v1.6`](https://github.com/emissary-ingress/emissary/tree/release/v1.6) - branch for Ambassador API Gateway 1.6.z work (:x: EOL; upgrade to 1.14.z)
59- [`release/v1.5`](https://github.com/emissary-ingress/emissary/tree/release/v1.5) - branch for Ambassador API Gateway 1.5.z work (:x: EOL; upgrade to 1.14.z)
60- [`release/v1.4`](https://github.com/emissary-ingress/emissary/tree/release/v1.4) - branch for Ambassador API Gateway 1.4.z work (:x: EOL; upgrade to 1.14.z)
61- [`release/v1.3`](https://github.com/emissary-ingress/emissary/tree/release/v1.3) - branch for Ambassador API Gateway 1.3.z work (:x: EOL; upgrade to 1.14.z)
62- [`release/v1.2`](https://github.com/emissary-ingress/emissary/tree/release/v1.2) - branch for Ambassador API Gateway 1.2.z work (:x: EOL; upgrade to 1.14.z)
63- [`release/v1.1`](https://github.com/emissary-ingress/emissary/tree/release/v1.1) - branch for Ambassador API Gateway 1.1.z work (:x: EOL; upgrade to 1.14.z)
64
65Architecture
66============
67
68Emissary is configured via Kubernetes CRDs, or via annotations on Kubernetes `Service`s. Internally,
69it uses the [Envoy Proxy] to actually handle routing data; externally, it relies on Kubernetes for
70scaling and resiliency. For more on Emissary's architecture and motivation, read [this blog post](https://blog.getambassador.io/building-ambassador-an-open-source-api-gateway-on-kubernetes-and-envoy-ed01ed520844).
71
72Getting Started
73===============
74
75You can get Emissary up and running in just three steps. Follow the instructions here: https://www.getambassador.io/docs/emissary/latest/tutorials/getting-started/
76
77If 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](https://blog.getambassador.io/kubernetes-ingress-nodeport-load-balancers-and-ingress-controllers-6e29f1c44f2d).
78
79For other common questions, view this [FAQ page](https://www.getambassador.io/docs/emissary/latest/about/faq/).
80
81You can also use Helm to install Emissary. For more information, see the instructions in the [Helm installation documentation](https://www.getambassador.io/docs/emissary/latest/topics/install/helm/)
82
83Community
84=========
85
86Emissary-ingress is a CNCF Incubating project and welcomes any and all contributors. To get started:
87
88* Join our [Slack channel](https://a8r.io/slack)
89* Check out the [Emissary documentation](https://www.getambassador.io/docs/emissary/)
90* Read the [Contributor's Guide](https://github.com/emissary-ingress/emissary/blob/master/DEVELOPING.md).
91
92If you're interested in contributing, here are some ways:
93
94* Write a blog post for [our blog](https://blog.getambassador.io)
95* Investigate an [open issue](https://github.com/emissary-ingress/emissary/issues)
96* Add [more tests](https://github.com/emissary-ingress/emissary/tree/master/ambassador/tests)
97
98The 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/.
99
100<!-- Please keep this list sorted. -->
101[authentication]: https://www.getambassador.io/docs/emissary/latest/topics/running/services/auth-service/
102[canary releases]: https://www.getambassador.io/docs/emissary/latest/topics/using/canary/
103[circuit breaking]: https://www.getambassador.io/docs/emissary/latest/topics/using/circuit-breakers/
104[Consul]: https://www.getambassador.io/docs/emissary/latest/howtos/consul/
105[CRDs]: https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/
106[Datadog]: https://www.getambassador.io/docs/emissary/latest/topics/running/statistics/#datadog
107[Grafana]: https://www.getambassador.io/docs/emissary/latest/topics/running/statistics/#grafana
108[gRPC and HTTP/2]: https://www.getambassador.io/docs/emissary/latest/howtos/grpc/
109[Istio]: https://www.getambassador.io/docs/emissary/latest/howtos/istio/
110[Knative serverless integration]: https://www.getambassador.io/docs/emissary/latest/howtos/knative/
111[Linkerd]: https://www.getambassador.io/docs/emissary/latest/howtos/linkerd2/
112[load balancing]: https://www.getambassador.io/docs/emissary/latest/topics/running/load-balancer/
113[metrics]: https://www.getambassador.io/docs/emissary/latest/topics/running/statistics/
114[Prometheus]: https://www.getambassador.io/docs/emissary/latest/topics/running/statistics/#prometheus
115[rate limiting]: https://www.getambassador.io/docs/emissary/latest/topics/running/services/rate-limit-service/
116[self-service configuration]: https://www.getambassador.io/docs/emissary/latest/topics/using/mappings/
117[sticky sessions]: https://www.getambassador.io/docs/emissary/latest/topics/running/load-balancer/#sticky-sessions--session-affinity
118[TCP]: https://www.getambassador.io/docs/emissary/latest/topics/using/tcpmappings/
119[TLS]: https://www.getambassador.io/docs/emissary/latest/howtos/tls-termination/
120[web sockets]: https://www.getambassador.io/docs/emissary/latest/topics/using/tcpmappings/
View as plain text