Skip to content

Commit 69f1cc4

Browse files
kflynnkflynn
committed
Merge docs/emissary from ambassador-docs
Signed-off-by: Flynn <[email protected]>
2 parents 8b0c814 + 5ec02a4 commit 69f1cc4

File tree

4,872 files changed

+362279
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

4,872 files changed

+362279
-0
lines changed

Diff for: ‎docs/1.13/about/alternatives.md

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# $productName$ vs. other software
2+
3+
Alternatives to the $productName$ fall into three basic categories:
4+
5+
* Hosted API gateways, such as the [Amazon API gateway](https://aws.amazon.com/api-gateway/).
6+
* Traditional API gateways, such as [Kong](https://konghq.org/).
7+
* L7 proxies, such as [Traefik](https://traefik.io/), [NGINX](http://nginx.org/), [HAProxy](http://www.haproxy.org/), or [Envoy](https://www.envoyproxy.io), or Ingress controllers built on these proxies.
8+
9+
Both hosted API gateways and traditional API gateways are:
10+
11+
* Not self-service. The management interfaces on traditional API gateways are not designed for developer self-service, and provide limited safety and usability for developers.
12+
* Not Kubernetes-native. They're typically configured using REST APIs, making it challenging to adopt cloud-native patterns such as GitOps and declarative configuration.
13+
* [Designed for API management, versus microservices](../../topics/concepts/microservices-api-gateways).
14+
15+
A Layer 7 proxy can be used as an API gateway, but typically requires additional bespoke development to support microservices use cases. In fact, many API gateways package the additional features needed for an API gateway on top of an L7 proxy. The $productName$ uses Envoy, while Kong uses NGINX. If you're interested in deploying Envoy directly, we've written an [introductory tutorial](https://www.datawire.io/guide/traffic/getting-started-lyft-envoy-microservices-resilience/).
16+
17+
## Istio
18+
19+
[Istio](https://istio.io) is an open-source service mesh, built on Envoy. A service mesh is designed to manage East/West traffic (traffic between servers and your data center), while an API gateway manages North/South traffic (in and out of your data center). Documentation on how to deploy the $productName$ with Istio is [here](../../howtos/istio). In general, we've found that North/South traffic is quite different from East/West traffic (i.e., you don't control the client in the North/South use case).

Diff for: ‎docs/1.13/about/faq.md

+131
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# Frequently Asked Questions
2+
3+
## General
4+
5+
### Why $productName$?
6+
7+
Kubernetes shifts application architecture for microservices, as well as the
8+
development workflow for a full-cycle development. $productName$ is designed for
9+
the Kubernetes world with:
10+
11+
* Sophisticated traffic management capabilities (thanks to its use of [Envoy Proxy](https://www.envoyproxy.io)), such as load balancing, circuit breakers, rate limits, and automatic retries.
12+
* API management capabilities such as a developer portal and OpenID Connect integration for Single Sign-On.
13+
* A declarative, self-service management model built on Kubernetes Custom Resource Definitions, enabling GitOps-style continuous delivery workflows.
14+
15+
We've written about [the history of $productName$](https://blog.getambassador.io/building-ambassador-an-open-source-api-gateway-on-kubernetes-and-envoy-ed01ed520844), [Why $productName$ In Depth](../why-ambassador), [Features and Benefits](../features-and-benefits) and about the [evolution of API Gateways](../../topics/concepts/microservices-api-gateways/).
16+
17+
### What's the difference between the $OSSproductName$ and the $AESproductName$?
18+
19+
The $OSSproductName$ was the name of the original open-source project. As the project evolved, we realized that the functionality we were building had extended far beyond an API Gateway. In particular, the $AESproductName$ is intended to provide all the functionality you need at the edge -- hence, an "edge stack." This includes an API Gateway, ingress controller, load balancer, developer portal, and more.
20+
21+
### How is $AESproductName$ licensed?
22+
23+
The core $OSSproductName$ is open source under the Apache Software License 2.0. The GitHub repository for the core is [https://github.com/datawire/ambassador](https://github.com/datawire/ambassador). Some additional features of the $AESproductName$ (e.g., Single Sign-On) are not open source and available under a proprietary license.
24+
25+
### Can I use the add-on features for $AESproductName$ for free?
26+
27+
Yes! The core functionality of the $AESproductName$ is free and has no limits whatsoever. If you wish to use one of our additional, proprietary features such as Single Sign-On, you can get a free community license for up to 5 requests per second. Please contact [sales](/contact-us/) if you need more than 5 RPS.
28+
29+
For more details on core unlimited features and premium features, see the [editions page](/editions).
30+
31+
### How does $productName$ use Envoy Proxy?
32+
33+
$productName$ uses [Envoy Proxy](https://www.envoyproxy.io) as its core proxy. Envoy is an open-source, high-performance proxy originally written by Lyft. Envoy is now part of the Cloud Native Computing Foundation.
34+
35+
### Is $productName$ production ready?
36+
37+
Yes. Thousands of organizations, large and small, run $productName$ in production.
38+
Public users include Chick-Fil-A, ADP, Microsoft, NVidia, and AppDirect, among others.
39+
40+
### What is the performance of $productName$?
41+
42+
There are many dimensions to performance. We published a benchmark of [$productName$ performance on Kubernetes](/resources/envoyproxy-performance-on-k8s/). Our internal performance regressions cover many other scenarios; we expect to publish more data in the future.
43+
44+
### What's the difference between a service mesh (such as Istio) and $productName$?
45+
46+
Service meshes focus on routing internal traffic from service to service
47+
("east-west"). $productName$ focuses on traffic into your cluster ("north-south").
48+
While both a service mesh and $productName$ can route L7 traffic, the reality is that
49+
these use cases are quite different. Many users will integrate $productName$ with a
50+
service mesh. Production customers of $productName$ have integrated with Consul,
51+
Istio, and Linkerd2.
52+
53+
## Common Configurations
54+
55+
### How do I disable the 404 landing page?
56+
57+
Established users will want to better control 404 behavior both for usability and
58+
security. You can leverage the Mapping resource to implement this functionality to
59+
your cluster. $productName$ users can use a 'catch-all' mapping using the '/'
60+
prefix in a mapping configuration. The simplest mapping, described below, returns only 404 text.
61+
To use a custom 404 landing page, simply insert your service and remove the rewrite value.
62+
63+
```yaml
64+
apiVersion: getambassador.io/v2
65+
kind: Mapping
66+
metadata:
67+
name: "404-fallback"
68+
spec:
69+
prefix: "/"
70+
rewrite: "/404/" # This must not map to any existing prefix!
71+
service: localhost:8500
72+
```
73+
74+
For more information on the Mapping resource, see [Advanced Mapping Configuration](../../topics/using/mappings).
75+
76+
### How do I disable the default Admin mappings?
77+
78+
In a production environment, public access to the console and admin endpoints is not an
79+
ideal situation. To solve this, we will be using an Ambassador Module to remove the default
80+
mappings and create a new, host-based mapping to expose the Admin endpoint more securely. The
81+
Ambassador module applies system-wide configuration settings for $productName$ to follow.
82+
83+
```yaml
84+
apiVersion: getambassador.io/v2
85+
kind: Module
86+
metadata:
87+
name: ambassador
88+
spec:
89+
config:
90+
diagnostics:
91+
enabled: false
92+
```
93+
94+
After applying this module, the admin endpoint is no longer accessible from the outside world.
95+
We cannot, however, exclude actual administrators from this endpoint, so to create a more managed
96+
endpoint for them to use, create a mapping to expose the endpoint.
97+
98+
```yaml
99+
apiVersion: getambassador.io/v2
100+
kind: Mapping
101+
metadata:
102+
name: admin-mapping
103+
spec:
104+
host: admin.example.com
105+
prefix: /edge_stack/
106+
rewrite: /edge_stack_ui/edge_stack/
107+
service: localhost:8500
108+
```
109+
110+
Now, administrators can connect to the admin console via hostname. Additional [Mapping](../../topics/using/intro-mappings) and
111+
[Filter](/docs/edge-stack/latest/topics/using/filters/) settings can be appropriately configured to better control access to admin services. To
112+
learn more about Ambassador Module configurations, see [Ambassador Module](../../topics/running/ambassador)
113+
114+
## Troubleshooting
115+
116+
### How do I get help for $productName$?
117+
118+
We have an online [Slack community](http://a8r.io/slack) with thousands of
119+
users. We try to help out as often as possible, although we can't promise a
120+
particular response time. If you need a guaranteed SLA, we also have commercial
121+
contracts. [Contact sales](/contact-us/) for more information.
122+
123+
### What do I do when I get the error `no healthy upstream`?
124+
125+
This error means that $productName$ could not connect to your backend service.
126+
Start by verifying that your backend service is actually available and
127+
responding by sending an HTTP response directly to the pod. Then, verify that
128+
$productName$ is routing by deploying a test service and seeing if the mapping
129+
works. Then, verify that your load balancer is properly routing requests to
130+
$productName$. In general, verifying each network hop between your client and
131+
backend service is critical to finding the source of the problem.

Diff for: ‎docs/1.13/about/features-and-benefits.md

+39
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Features and benefits
2+
3+
In cloud-native organizations, developers frequently take on responsibility for the full development lifecycle of a service, from development to QA to operations. $productName$ was specifically designed for these organizations where developers have operational responsibility for their service(s).
4+
5+
As such, the $productName$ is designed to be used by both developers and operators.
6+
7+
## Self-Service via Kubernetes Annotations
8+
9+
$productName$ is built from the start to support _self-service_ deployments -- a developer working on a new service doesn't have to go to Operations to get their service added to the mesh, they can do it themselves in a matter of seconds. Likewise, a developer can remove their service from the mesh, or merge services, or separate services, as needed, at their convenience. All of these operations are performed via Kubernetes annotations, so it can easily integrate with your existing development workflow.
10+
11+
## Flexible canary deployments
12+
13+
Canary deployments are an essential component of cloud-native development workflows. In a canary deployment, a small percentage of production traffic is routed to a new version of a service to test it under real-world conditions. $productName$ allows developers to easily control and manage the amount of traffic routed to a given service through annotations. [This tutorial](https://www.datawire.io/faster/canary-workflow/) covers a complete canary workflow using the $productName$.
14+
15+
## Kubernetes-native architecture
16+
17+
$productName$ relies entirely on Kubernetes for reliability, availability, and scalability. For example, $productName$ persists all state in Kubernetes, instead of requiring a separate database. Scaling the $productName$ is as simple as changing the replicas in your deployment, or using a [horizontal pod autoscaler](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/).
18+
19+
$productName$ uses [Envoy](https://www.envoyproxy.io) for all traffic routing and proxying. Envoy is a modern L7 proxy that is used in production at companies including Lyft, Apple, Google, and Stripe.
20+
21+
## gRPC and HTTP/2 support
22+
23+
$productName$ fully supports gRPC and HTTP/2 routing, thanks to Envoy's extensive capabilities in this area. See [gRPC and the $productName$](../../howtos/grpc) for more information.
24+
25+
## Istio Integration
26+
27+
$productName$ integrates with the [Istio](https://istio.io) service mesh as the edge proxy. In this configuration, $productName$ routes external traffic to the internal Istio service mesh. See [Istio and the $productName$](../../howtos/istio) for details.
28+
29+
## Authentication
30+
31+
$productName$ supports authenticating incoming requests with a [custom authentication service](../../howtos/basic-auth/), and $AESproductName$ natively supports OAuth/OpenID Connect, or JWT. When configured, the $AESproductName$ will check with a third party authentication service prior to routing an incoming request. For more information, see the [authentication guide](/docs/edge-stack/latest/topics/using/filters/).
32+
33+
## Rate limiting
34+
35+
$productName$ supports rate limiting incoming requests. When configured, the $productName$ will check with a third party rate limit service prior to routing an incoming request. For more information, see the [rate limiting guide](../../topics/using/rate-limits/).
36+
37+
## Integrated UI
38+
39+
$productName$ includes a diagnostics service so that you can quickly debug issues associated with configuring the $productName$. For more information, see [running $productName$ in Production](../../topics/running).

Diff for: ‎docs/1.13/about/support.md

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Need help?
2+
3+
If you need help deploying $productName$ at your organization, there are several different options available to you.
4+
5+
## Support tiers
6+
7+
### $productName$ community support
8+
9+
If you are running the $OSSproductName$ or the $AESproductName$ with free, community licenses, [join our Slack channel](http://a8r.io/slack) to talk with other users in the community and get your questions answered.
10+
11+
If you can’t find an answer there, [contact us](/contact-us) to learn more about the support options available with $AESproductName$ Enterprise.
12+
13+
### $AESproductName$ Enterprise
14+
15+
With $AESproductName$ Enterprise, you have access to deployment and production support. To learn more, [contact sales](/contact-us).
16+
17+
**Deployment and Update Support**: $AESproductName$ can accelerate your migration to Kubernetes, or your upgrade between versions of $AESproductName$. Deployment support helps you with the $AESproductName$ and Kubernetes migration, before you move to production.
18+
19+
**Production Support**: We offer two types of production support contracts for users deploying the $AESproductName$ in production. We offer both business hour (8am - 5pm EST, M-F) and 24x7 Sev 1 support for the $AESproductName$. 24x7 Sev 1 support includes custom hotfix support for production outages if necessary.
20+
21+
## File a Github Issue
22+
23+
If you see a bug you want to fix, see room for documentation improvements, or have something else you want to change, you can [file an issue on github](https://github.com/datawire/ambassador/issues/new).
24+
25+
## Pricing
26+
27+
[Contact us](/contact-us) to learn how we can help, and for detailed pricing information.

Diff for: ‎docs/1.13/about/why-ambassador.md

+54
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Why $productName$?
2+
3+
$productName$ gives platform engineers a comprehensive, self-service edge stack for managing the boundary between end-users and Kubernetes. Built on the [Envoy Proxy](https://www.envoyproxy.io) and fully Kubernetes-native, $productName$ is made to support multiple, independent teams that need to rapidly publish, monitor, and update services for end-users. A true edge stack, $productName$ can also be used to handle the functions of an API Gateway, a Kubernetes ingress controller and a layer 7 load balancer (for more, see [this blog post](https://blog.getambassador.io/kubernetes-ingress-nodeport-load-balancers-and-ingress-controllers-6e29f1c44f2d)).
4+
5+
## How Does $productName$ work?
6+
7+
$productName$ is an open-source, Kubernetes-native [microservices API gateway](../../topics/concepts/microservices-api-gateways) built on the [Envoy Proxy](https://www.envoyproxy.io). $productName$ is built from the ground up to support multiple, independent teams that need to rapidly publish, monitor, and update services for end-users. $productName$ can also be used to handle the functions of a Kubernetes ingress controller and load balancer (for more, see [this blog post](https://blog.getambassador.io/kubernetes-ingress-nodeport-load-balancers-and-ingress-controllers-6e29f1c44f2d)).
8+
9+
## Cloud-native applications today
10+
11+
Traditional cloud applications were built using a monolithic approach. These applications were designed, coded, and deployed as a single unit. Today's cloud-native applications, by contrast, consist of many individual (micro)services. This results in an architecture that is:
12+
13+
* __Heterogeneous__: Services are implemented using multiple (polyglot) languages, they are designed using multiple architecture styles, and they communicate with each other over multiple protocols.
14+
* __Dynamic__: Services are frequently updated and released (often without coordination), which results in a constantly-changing application.
15+
* __Decentralized__: Services are managed by independent product-focused teams, with different development workflows and release cadences.
16+
17+
### Heterogeneous services
18+
19+
$productName$ is commonly used to route traffic to a wide variety of services. It supports:
20+
21+
* configuration on a *per-service* basis, enabling fine-grained control of timeouts, rate limiting, authentication policies, and more.
22+
* a wide range of L7 protocols natively, including HTTP, HTTP/2, gRPC, gRPC-Web, and WebSockets.
23+
* Can route raw TCP for services that use protocols not directly supported by $productName$.
24+
25+
### Dynamic services
26+
27+
Service updates result in a constantly changing application. The dynamic nature of cloud-native applications introduces new challenges around configuration updates, release, and testing. $productName$:
28+
29+
* Enables [progressive delivery](../../topics/concepts/progressive-delivery), with support for canary routing and traffic shadowing.
30+
* Exposes high-resolution observability metrics, providing insight into service behavior.
31+
* Uses a zero downtime configuration architecture, so configuration changes have no end-user impact.
32+
33+
### Decentralized workflows
34+
35+
Independent teams can create their own workflows for developing and releasing functionality that are optimized for their specific service(s). With $productName$, teams can:
36+
37+
* Leverage a [declarative configuration model](../../topics/concepts/gitops-continuous-delivery), making it easy to understand the canonical configuration and implement GitOps-style best practices.
38+
* Independently configure different aspects of $productName$, eliminating the need to request configuration changes through a centralized operations team.
39+
40+
## $productName$ is engineered for Kubernetes
41+
42+
$productName$ takes full advantage of Kubernetes and Envoy Proxy.
43+
44+
* All of the state required for $productName$ is stored directly in Kubernetes, eliminating the need for an additional database.
45+
* The $productName$ team has added extensive engineering efforts and integration testing to ensure optimal performance and scale of Envoy and Kubernetes.
46+
47+
## For more information
48+
49+
[Deploy $productName$ today](../../tutorials/getting-started) and join the community [Slack Channel](http://a8r.io/slack).
50+
51+
Interested in learning more?
52+
53+
* [Why did we start building $productName$?](https://blog.getambassador.io/building-ambassador-an-open-source-api-gateway-on-kubernetes-and-envoy-ed01ed520844)
54+
* [$productName$ Architecture overview](../../topics/concepts/architecture)

Diff for: ‎docs/1.13/community.md

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Community
2+
3+
## Contributor's guide
4+
Please review our [contributor's guide](https://github.com/emissary-ingress/emissary/blob/master/DEVELOPING.md)
5+
on GitHub to learn how you can help make Emissary-ingress better.
6+
7+
## Changelog
8+
Our [changelog](https://github.com/emissary-ingress/emissary/blob/$branch$/CHANGELOG.md)
9+
describes new features, bug fixes, and updates to each version of Emissary-ingress.
10+
11+
## Meetings
12+
Check out our community [meeting schedule](https://github.com/emissary-ingress/emissary/blob/master/MEETING_SCHEDULE.md) for opportunities to interact with Emissary-ingress developers.

0 commit comments

Comments
 (0)