Add support for gRPC-Web using Envoy's grpc_web filter

For more information, please refer to
https://www.envoyproxy.io/docs/envoy/v1.9.0/configuration/http_filters/grpc_web_filter#config-http-filters-grpc-web

Thanks to @rotemtam for the original implementation with the gRPC HTTP/1.1
bridge in #1201 for making this so trivial for me to contribute!

Implements feature request #456.

.bookignore

@@ -0,0 +1,3 @@
+README.md
+package*.json
+build-website.sh

.markdownlintrc

@@ -0,0 +1,6 @@
+{
+  "no-trailing-spaces": { "br_spaces": 2 },
+  "no-multiple-blanks": false,
+  "line-length": false,
+  "ol-prefix": { "style": "ordered" }
+}

INDEX.md

@@ -0,0 +1,3 @@
+# GitBook Index Page
+
+This page is overwritten by the documentation build process.

README.md

@@ -0,0 +1,12 @@
+# Ambassador documentation
+
+We've switched to GatsbyJS for generating the documentation, which gives us more control and flexibility over the layout.
+
+## Authoring documentation
+
+If you're authoring the documentation, just edit the Markdown files. You can use GitHub to preview the Markdown.
+
+## Documentation infrastructure notes
+
+* The rendered YAML and markdown files are copied by Travis CI to a separate Gatsby-based toolchain. Still TODO is to provide a local version of this toolchain.
+* The `doc-links.yml` file is the new TOC.

_layouts/footer.html

@@ -0,0 +1,5 @@
+
+
+<hr>
+
+join our Slack chat

_layouts/website/page.html

@@ -0,0 +1,21 @@
+{% extends template.self %}
+
+{% block book_sidebar %}
+<a href="/" class="logo__link">
+    <img class="logo" src="/images/ambassador-logo.svg" alt="logo">
+</a>
+
+{{ super() }}
+{% endblock %}
+
+{% block page %}
+<a id="datawire-breadcrumb" href="https://datawire.io/learn/open-source-docs">
+    ← Back to Datawire Open Source Documentation
+</a>
+{{ super() }}
+{% endblock %}
+
+{% block javascript %}
+    {{ super() }}
+    <script src="/js/datawire-breadcrumb.js" type="text/javascript"></script>
+{% endblock %}

_redirects

@@ -0,0 +1,10 @@
+# Redirects; parsed by Netlify
+/how-to/grpc               /user-guide/grpc
+/how-to/tls-termination    /user-guide/tls-termination
+/how-to/statistics         /reference/statistics
+/how-to/auth-external      /reference/services/auth-service
+/user-guide/running        /reference/running
+/reference/auth-external   /reference/services/auth-service
+/reference/auth-tls-certs  /reference/core/tls
+/helm/*                    https://s3.amazonaws.com/datawire-static-files/ambassador/:splat
+/index.yaml                https://s3.amazonaws.com/datawire-static-files/ambassador/index.yaml

about/alternatives.md

@@ -0,0 +1,19 @@
+# Alternatives to Ambassador
+
+Alternatives to Ambassador fall in 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://getkong.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](/about/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 a L7 proxy. Ambassador 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, while an API gateway manages north/south traffic. Documentation on how to deploy Ambassador with Istio is [here](/user-guide/with-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).

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. Ambassador was especially designed for these organizations where developers have operational responsibility for their service(s).
+
+As such, Ambassador is designed to be used by both developers and operators.
+
+## Self-Service via Kubernetes Annotations
+
+Ambassador 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. Ambassador 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 Ambassador.
+
+## Kubernetes-Native Architecture
+
+Ambassador relies entirely on Kubernetes for reliability, availability, and scalability. For example, Ambassador persists all state in Kubernetes, instead of requiring a separate database. Scaling Ambassador 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/).
+
+Ambassador 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
+
+Ambassador fully supports gRPC and HTTP/2 routing, thanks to Envoy's extensive capabilities in this area. See [gRPC and Ambassador](/user-guide/grpc) for more information.
+
+## Istio Integration
+
+Ambassador integrates with the [Istio](https://istio.io) service mesh as the edge proxy. In this configuration, Ambassador routes external traffic to the internal Istio service mesh. See [Istio and Ambassador](/user-guide/with-istio) for details.
+
+## Authentication
+
+Ambassador supports authenticating incoming requests. When configured, Ambassador will check with a third party authentication service prior to routing an incoming request. For more information, see the [authentication tutorial](/user-guide/auth-tutorial).
+
+## Rate Limiting
+
+Ambassador supports rate limiting incoming requests. When configured, Ambassador will check with a third party rate limit service prior to routing an incoming request. For more information, see the [rate limiting tutorial](/user-guide/rate-limiting-tutorial).
+
+## Integrated Diagnostics
+
+Ambassador includes a diagnostics service so that you can quickly debug issues associated with configuring Ambassador. For more information, see [running Ambassador](https://www.getambassador.io/reference/running).

about/microservices-api-gateways.md

@@ -0,0 +1,60 @@
+# Microservices API Gateways vs. Traditional Enterprise API Gateways
+
+A microservices API gateway is an API gateway designed to accelerate the development workflow of independent services teams. A microservices API gateway provides all the functionality for a team to independently publish, monitor, and update a microservice.
+
+This focus on accelerating the development workflow is distinct from the purpose of traditional API gateways, which focus on the challenges of managing APIs. Over the past decade, organizations have worked to expose internal systems through well-defined APIs. The challenge of safely exposing hundreds or thousands of APIs to end users (both internal and external) led to the emergence of API gateways. Over time, API gateways have become centralized, mission critical pieces of infrastructure that control access to these APIs.
+
+In this article, we'll discuss how the difference in business objective (productivity vs management) results in a very different API gateway.
+
+## Microservices Organization
+
+In a microservices organization, small teams of developers work independently from each other to rapidly deliver functionality to the customer. In order for each service team to work independently, with a productive workflow, a services team needs to be able to:
+
+1. Publish their service, so that others can use the service
+2. Monitor their service, to see how well it's working
+3. Test and update their service, so they can keep on improving the service
+
+The team needs to all of this *without* requiring assistance from another operations or platform team--as soon as a services team requires another team, they're no longer working independently, and this can lead to bottlenecks.
+
+For service publication, a microservices API gateway provides a static address for consumers, and dynamically route requests to the appropriate service address. In addition, providing authentication and TLS termination for security are typical considerations in exposing a service to other consumers.
+
+Understanding the end user experience of a service is crucial to improving the service. For example, a software update could inadvertently impact the latency of certain requests. A microservices API gateway is well situated to collect key observability metrics on end user traffic as it routes traffic to the end service.
+
+A microservices API gateway also supports dynamically routing user requests to different service versions for canary testing. By routing a small fraction of end user requests to a new version of a service, service teams can safely test the impact of new updates to a small subset of users.
+
+## Microservices API Gateways vs. Enterprise API Gateways
+
+At first glance, the use case described above may be fulfilled with a enterprise-focused API gateway. While this may be true, the actual emphasis of enterprise API gateways and microservices API gateways are somewhat different:
+
+| Use case      | API gateway       | Microservices API gateway                |
+|---------------|-------------------|------------------------------|
+| Primary Purpose  | Expose, compose, and manage internal business APIs | Expose and observe internal business services |
+| Publishing Functionality | API management team or service team registers / updates gateway via admin API | Service team registers / updates gateway via declarative code as part of the deployment process |
+| Monitoring | Admin and operations focused e.g. meter API calls per consumer, report errors (e.g. internal 5XX). | Developer focused e.g. latency, traffic, errors, saturation |
+| Handling and Debugging Issues | L7 error-handling (e.g. custom error page or payload). Run gateway/API with additional logging. Troubleshoot issue in staging environment | Configure more detailed monitoring. Enable traffic shadowing and / or canarying |
+| Testing | Operate multiple environments for QA, Staging and Production. Automated integration testing, and gated API deployment. Use client-driven API versioning for compatibility and stability (e.g. semver) | Facilitate canary routing for dynamic testing (taking care with data mutation side effects). Use developer-driven service versioning for upgrade management |
+| Local Development | Deploy gateway locally (via installation script, Vagrant or Docker), and attempt to mitigate infrastructure differences with production. Use language-specific gateway mocking and stubbing frameworks | Deploy gateway locally via service orchestration platform (e.g. Kubernetes) |
+
+## Self-Service Publishing
+
+A team needs to be able to publish a new service to customers without requiring an operations or API management team. This ability to self-service for deployment and publication enables the team to keep the feature release velocity high. While a traditional enterprise API gateway may provide a simple mechanism (e.g., REST API) for publishing a new service, in practice, the usage is often limited to the use of a dedicated team that is responsible for the gateway. The primary reason for limiting publication to a single team is to provide an additional (human) safety mechanism: an errant API call could have potentially disastrous effects on production.
+
+Microservices API gateways utilize mechanisms that enable service teams to easily *and* safely publish new services, with the inherent understanding that the producing team are responsible for their service, and will fix an issue if one occurs. A microservices gateway provides configurable monitoring for issue detection, and provides hooks for debugging, such as inspecting traffic or traffic shifting/duplication.
+
+## Monitoring & Rate Limiting
+
+A common business model for APIs is metering, where a consumer is charged different fees depending on API usage. Traditional enterprise API gateways excel in this use case: they provide functionality for monitoring per-client usage of an API, and the ability to limit usage when the client exceeds their quota.
+
+A microservice gateway also requires monitoring and rate limiting, but for different reasons. Monitoring user-visible metrics such as throughput, latency, and availability are important to ensure that new updates don't impact the end user. Robust end user metrics are critical to allowing rapid, incremental updates. Rate limiting is used to improve the overall resilience of a service. When a service is not responding as expected, an API gateway can throttle incoming requests to allow a service to recover and prevent a cascade failure.
+
+## Testing and Updates
+
+A microservices application has multiple services, each of which is being independently updated. Automated pre-production testing of a moving target is necessary but not sufficient for microservices. Canary testing, where a small percentage of production traffic is routed to a new service version, is an important tool to help test an update. By limiting a new service version to a small percentage of users, the impact of a service failure is limited.
+
+In a traditional enterprise API gateway, routing is used to isolate or compose/aggregate changing API versions. Automated pre-production testing and manual post-production verification and exploration is required.
+
+# Summary
+
+Traditional enterprise API gateways are designed to solve the challenges of API management. While they may appear to solve some of the challenges of adopting microservices, the reality is that a microservices workflow creates a different set of requirements. Integrating a microservices API gateway into your development workflow empowers service teams to self-publish, monitor, and update their service, quickly and safely. This will enable your organization to ship software more rapidly, and with more reliability than ever before.
+
+For further reading on how an API Gateway can accelerate continuous delivery, read [this blog post](https://blog.getambassador.io/continuous-delivery-how-can-an-api-gateway-help-or-hinder-1ff15224ec4d).

about/quickstart.md

@@ -0,0 +1,59 @@
+# Five minute quickstart
+
+In this section, we'll get Ambassador running locally with a demo configuration. In the next section, we'll then walk through how to deploy Ambassador in Kubernetes with a custom configuration.
+
+## 1. Running the Demo Configuration
+
+By default, Ambassador uses a demo configuration to show some of its basic features. Get it running with Docker, and expose Ambassador on port 8080:
+
+```shell
+docker run -it -p 8080:80 --name=ambassador --rm quay.io/datawire/ambassador:{VERSION} --demo
+```
+
+## 2. Ambassador's Diagnostics
+
+Ambassador provides live diagnostics viewable with a web browser. While this would normally not be exposed to the public network, the Docker demo publishes the diagnostics service at the following URL:
+
+`http://localhost:8080/ambassador/v0/diag/`
+
+Some of the most important information - your Ambassador version, how recently Ambassador's configuration was updated, and how recently Envoy last reported status to Ambassador - is right at the top. The diagnostics overview can show you what it sees in your configuration map, and which Envoy objects were created based on your configuration.
+
+## 3. The Quote of the Moment Service
+
+Since Ambassador is an API gateway, its primary purpose is to provide access to microservices. The demo is preconfigured with a mapping that connects the `/qotm/` resource to the "Quote of the Moment" service -- a demo service that supplies quotations. You can try it out here:
+
+```shell
+curl http://localhost:8080/qotm/
+```
+
+This request will route to the `qotm` service at `demo.getambassador.io`, and return a quote in a JSON object.
+
+You can also see the mapping by clicking the `mapping-qotm.yaml` link from the diagnostic overview, or by opening
+
+`http://localhost:8080/ambassador/v0/diag/mapping-qotm.yaml`
+
+## 4. Authentication
+
+On the diagnostic overview, you can also see that Ambassador is configured to do authentication -- click the `auth.yaml` link, or open
+
+`http://localhost:8080/ambassador/v0/diag/auth.yaml`
+
+for more here. Ambassador uses a demo authentication service at `demo.getambassador.io` to mediate access to the Quote of the Moment: simply getting a random quote is allowed without authentication, but to get a specific quote, you'll have to authenticate:
+
+```shell
+curl -v http://localhost:8080/qotm/quote/5
+```
+
+will return a 401, but
+
+```shell
+curl -v -u username:password http://localhost:8080/qotm/quote/5
+```
+
+will succeed. (Note that that's literally "username" and "password" -- the demo auth service is deliberately not very secure!)
+
+Note that it's up to the auth service to decide what needs authentication -- teaming Ambassador with an authentication service can be as flexible or strict as you need it to be.
+
+## Next steps
+
+We've just walked through some of the core features of Ambassador in a local configuration. Next, we'll walk through how to configure these features in Kubernetes.

about/roadmap.md

@@ -0,0 +1,10 @@
+# Roadmap
+
+Ambassador is an API gateway for microservices built on [Envoy](https://www.envoyproxy.io). Planned features for future releases include the following:
+
+* Enhanced diagnostics service
+* Advanced integration with Istio
+* Pushing the authentication filter into upstream Envoy
+* Expanded tutorials on monitoring
+
+Ambassador is under continuous development. If you have any requests or suggestions for the roadmap, please join the [Slack chat](https://d6e.co/slack) or [file an issue](https://github.com/datawire/ambassador/issues).

about/support.md

@@ -0,0 +1,17 @@
+# Need help deploying Ambassador at your organization?
+Our support team is here to help!
+
+## Community Support
+[Join our Slack channel](http://d6e.co/slack) to talk with other users in the community and get your questions answered. If you can’t find an answer there, [contact us about a support contract](https://www.getambassador.io/contact).
+
+## Deployment Support
+Ambassador can accelerate your migration to Kubernetes. Deployment support helps you with Ambassador and Kubernetes migration, before you move to production.
+
+## Production Support
+We offer two types of production support contracts for users deploying Ambassador in production.
+
+We offer both business hour (8am - 5pm EST, M-F) and 24x7 Sev 1 support for Ambassador. 24x7 Sev 1 support includes custom hotfix support for production outages if necessary.
+
+## Pricing
+
+[Contact us](https://www.getambassador.io/contact) to learn how we can help, and for detailed pricing information.