Merge docs/emissary from ambassador-docs

Signed-off-by: Flynn <[email protected]>

docs/1.13/about/alternatives.md

@@ -0,0 +1,19 @@
+# $productName$ vs. other software
+
+Alternatives to the $productName$ fall into three basic categories:
+
+* Hosted API gateways, such as the [Amazon API gateway](https://aws.amazon.com/api-gateway/).
+* Traditional API gateways, such as [Kong](https://konghq.org/).
+* 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.
+
+Both hosted API gateways and traditional API gateways are:
+
+* 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.
+* Not Kubernetes-native. They're typically configured using REST APIs, making it challenging to adopt cloud-native patterns such as GitOps and declarative configuration.
+* [Designed for API management, versus microservices](../../topics/concepts/microservices-api-gateways).
+
+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/).
+
+## Istio
+
+[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).

docs/1.13/about/faq.md

@@ -0,0 +1,131 @@
+# Frequently Asked Questions
+
+## General
+
+### Why $productName$?
+
+Kubernetes shifts application architecture for microservices, as well as the
+development workflow for a full-cycle development. $productName$ is designed for
+the Kubernetes world with:
+
+* 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.
+* API management capabilities such as a developer portal and OpenID Connect integration for Single Sign-On.
+* A declarative, self-service management model built on Kubernetes Custom Resource Definitions, enabling GitOps-style continuous delivery workflows.
+
+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/).
+
+### What's the difference between the $OSSproductName$ and the $AESproductName$?
+
+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.
+
+### How is $AESproductName$ licensed?
+
+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.
+
+### Can I use the add-on features for $AESproductName$ for free?
+
+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.
+
+For more details on core unlimited features and premium features, see the [editions page](/editions).
+
+### How does $productName$ use Envoy Proxy?
+
+$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.
+
+### Is $productName$ production ready?
+
+Yes. Thousands of organizations, large and small, run $productName$ in production.
+Public users include Chick-Fil-A, ADP, Microsoft, NVidia, and AppDirect, among others.
+
+### What is the performance of $productName$?
+
+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.
+
+### What's the difference between a service mesh (such as Istio) and $productName$?
+
+Service meshes focus on routing internal traffic from service to service
+("east-west"). $productName$ focuses on traffic into your cluster ("north-south").
+While both a service mesh and $productName$ can route L7 traffic, the reality is that
+these use cases are quite different. Many users will integrate $productName$ with a
+service mesh. Production customers of $productName$ have integrated with Consul,
+Istio, and Linkerd2.
+
+## Common Configurations
+
+### How do I disable the 404 landing page?
+
+Established users will want to better control 404 behavior both for usability and
+security.  You can leverage the Mapping resource to implement this functionality to
+your cluster.  $productName$ users can use a 'catch-all' mapping using the '/'
+prefix in a mapping configuration.  The simplest mapping, described below, returns only 404 text.
+To use a custom 404 landing page, simply insert your service and remove the rewrite value.
+
+```yaml
+apiVersion: getambassador.io/v2
+kind: Mapping
+metadata:
+  name: "404-fallback"
+spec:
+  prefix: "/"
+  rewrite: "/404/" # This must not map to any existing prefix!
+  service: localhost:8500
+```
+
+For more information on the Mapping resource, see [Advanced Mapping Configuration](../../topics/using/mappings).
+
+### How do I disable the default Admin mappings?
+
+In a production environment, public access to the console and admin endpoints is not an
+ideal situation.  To solve this, we will be using an Ambassador Module to remove the default
+mappings and create a new, host-based mapping to expose the Admin endpoint more securely.  The
+Ambassador module applies system-wide configuration settings for $productName$ to follow.
+
+```yaml
+apiVersion: getambassador.io/v2
+kind: Module
+metadata:
+  name: ambassador
+spec:
+  config:
+    diagnostics:
+      enabled: false
+```
+
+After applying this module, the admin endpoint is no longer accessible from the outside world.
+We cannot, however, exclude actual administrators from this endpoint, so to create a more managed
+endpoint for them to use, create a mapping to expose the endpoint.
+
+```yaml
+apiVersion: getambassador.io/v2
+kind: Mapping
+metadata:
+  name: admin-mapping
+spec:
+  host: admin.example.com
+  prefix: /edge_stack/
+  rewrite: /edge_stack_ui/edge_stack/
+  service: localhost:8500
+```
+
+Now, administrators can connect to the admin console via hostname.  Additional [Mapping](../../topics/using/intro-mappings) and
+[Filter](/docs/edge-stack/latest/topics/using/filters/) settings can be appropriately configured to better control access to admin services.  To
+learn more about Ambassador Module configurations, see [Ambassador Module](../../topics/running/ambassador)
+
+## Troubleshooting
+
+### How do I get help for $productName$?
+
+We have an online [Slack community](http://a8r.io/slack) with thousands of
+users. We try to help out as often as possible, although we can't promise a
+particular response time. If you need a guaranteed SLA, we also have commercial
+contracts. [Contact sales](/contact-us/) for more information.
+
+### What do I do when I get the error `no healthy upstream`?
+
+This error means that $productName$ could not connect to your backend service.
+Start by verifying that your backend service is actually available and
+responding by sending an HTTP response directly to the pod. Then, verify that
+$productName$ is routing by deploying a test service and seeing if the mapping
+works. Then, verify that your load balancer is properly routing requests to
+$productName$. In general, verifying each network hop between your client and
+backend service is critical to finding the source of the problem.

docs/1.13/about/features-and-benefits.md

@@ -0,0 +1,39 @@
+# Features and benefits
+
+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).
+
+As such, the $productName$ is designed to be used by both developers and operators.
+
+## Self-Service via Kubernetes Annotations
+
+$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.
+
+## Flexible canary deployments
+
+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$.
+
+## Kubernetes-native architecture
+
+$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/).
+
+$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.
+
+## gRPC and HTTP/2 support
+
+$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.
+
+## Istio Integration
+
+$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.
+
+## Authentication
+
+$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/).
+
+## Rate limiting
+
+$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/).
+
+## Integrated UI
+
+$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).

docs/1.13/about/support.md

@@ -0,0 +1,27 @@
+# Need help?
+
+If you need help deploying $productName$ at your organization, there are several different options available to you.
+
+## Support tiers
+
+### $productName$ community support
+
+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.
+
+If you can’t find an answer there, [contact us](/contact-us) to learn more about the support options available with $AESproductName$ Enterprise.
+
+### $AESproductName$ Enterprise
+
+With $AESproductName$ Enterprise, you have access to deployment and production support. To learn more, [contact sales](/contact-us).
+
+**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.
+
+**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.
+
+## File a Github Issue
+
+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).
+
+## Pricing
+
+[Contact us](/contact-us) to learn how we can help, and for detailed pricing information.

docs/1.13/about/why-ambassador.md

@@ -0,0 +1,54 @@
+# Why $productName$?
+
+$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)).
+
+## How Does $productName$ work?
+
+$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)).
+
+## Cloud-native applications today
+
+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:
+
+* __Heterogeneous__: Services are implemented using multiple (polyglot) languages, they are designed using multiple architecture styles, and they communicate with each other over multiple protocols.
+* __Dynamic__: Services are frequently updated and released (often without coordination), which results in a constantly-changing application.
+* __Decentralized__: Services are managed by independent product-focused teams, with different development workflows and release cadences.
+
+### Heterogeneous services
+
+$productName$ is commonly used to route traffic to a wide variety of services. It supports:
+
+* configuration on a *per-service* basis, enabling fine-grained control of timeouts, rate limiting, authentication policies, and more.
+* a wide range of L7 protocols natively, including HTTP, HTTP/2, gRPC, gRPC-Web, and WebSockets.
+* Can route raw TCP for services that use protocols not directly supported by $productName$.
+
+### Dynamic services
+
+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$:
+
+* Enables [progressive delivery](../../topics/concepts/progressive-delivery), with support for canary routing and traffic shadowing.
+* Exposes high-resolution observability metrics, providing insight into service behavior.
+* Uses a zero downtime configuration architecture, so configuration changes have no end-user impact.
+
+### Decentralized workflows
+
+Independent teams can create their own workflows for developing and releasing functionality that are optimized for their specific service(s). With $productName$, teams can:
+
+* Leverage a [declarative configuration model](../../topics/concepts/gitops-continuous-delivery), making it easy to understand the canonical configuration and implement GitOps-style best practices.
+* Independently configure different aspects of $productName$, eliminating the need to request configuration changes through a centralized operations team.
+
+## $productName$ is engineered for Kubernetes
+
+$productName$ takes full advantage of Kubernetes and Envoy Proxy.
+
+* All of the state required for $productName$ is stored directly in Kubernetes, eliminating the need for an additional database.
+* The $productName$ team has added extensive engineering efforts and integration testing to ensure optimal performance and scale of Envoy and Kubernetes.
+
+## For more information
+
+[Deploy $productName$ today](../../tutorials/getting-started) and join the community [Slack Channel](http://a8r.io/slack).
+
+Interested in learning more?
+
+* [Why did we start building $productName$?](https://blog.getambassador.io/building-ambassador-an-open-source-api-gateway-on-kubernetes-and-envoy-ed01ed520844)
+* [$productName$ Architecture overview](../../topics/concepts/architecture)

docs/1.13/community.md

@@ -0,0 +1,12 @@
+# Community
+
+## Contributor's guide
+Please review our [contributor's guide](https://github.com/emissary-ingress/emissary/blob/master/DEVELOPING.md)
+on GitHub to learn how you can help make Emissary-ingress better.
+
+## Changelog
+Our [changelog](https://github.com/emissary-ingress/emissary/blob/$branch$/CHANGELOG.md)
+describes new features, bug fixes, and updates to each version of Emissary-ingress.
+
+## Meetings
+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.