add open source distro section w envoy on kube (#501)

This PR adds a new section to the Getting Started guide entitled "Other Use Cases" which show how Envoy can be used in specific situations. The thought is that users may want to use an Envoy distribution instead of Envoy itself for specific scenarios.

I also added a tutorial on how to use the open source Ambassador project to deploy Envoy as an API Gateway in Kubernetes, with an example that mirrors the google smoketest that is also used in the getting started.

Signed-off-by: Richard Li <richard@datawire.io>

docs/root/install/distro/ambassador.rst

@@ -0,0 +1,125 @@
+.. _install_ambassador:
+
+Envoy as an API Gateway in Kubernetes
+=====================================
+
+A common scenario for using Envoy is deploying it as an edge service (API
+Gateway) in Kubernetes. `Ambassador <https://www.getambassador.io>`_ is an open
+source distribution of Envoy designed for Kubernetes. Ambassador uses Envoy for
+all L4/L7 management and Kubernetes for reliability, availability, and
+scalability. Ambassador operates as a specialized control plane to expose
+Envoy's functionality as Kubernetes annotations.
+
+This example will walk through how you can deploy Envoy on Kubernetes via
+Ambassador.
+
+Deploying Ambassador
+--------------------
+
+Ambassador is configured via Kubernetes deployments. To install Ambassador/Envoy
+on Kubernetes, run the following if you're using a cluster with RBAC enabled:
+
+.. code-block:: console
+
+   kubectl apply -f https://www.getambassador.io/yaml/ambassador/ambassador-rbac.yaml
+
+or this if you are not using RBAC:
+
+.. code-block:: console
+
+   kubectl apply -f https://www.getambassador.io/yaml/ambassador/ambassador-no-rbac.yaml
+
+The above YAML will create a Kubernetes deployment for Ambassador that includes
+readiness and liveness checks. By default, it will also create 3 instances of
+Ambassador. Each Ambassador instance consists of an Envoy proxy along with the
+Ambassador control plane.
+
+We'll now need to create a Kubernetes service to point to the Ambassador
+deployment. In this example, we'll use a ``LoadBalancer`` service. If your
+cluster doesn't support ``LoadBalancer`` services, you'll need to change to a
+``NodePort`` or ``ClusterIP``.
+
+.. code-block:: yaml
+
+  ---
+  apiVersion: v1
+  kind: Service
+  metadata:
+    labels:
+      service: ambassador
+    name: ambassador
+  spec:
+    type: LoadBalancer
+    ports:
+    - port: 80
+      targetPort: 80
+    selector:
+      service: ambassador
+
+Save this YAML to a file ``ambassador-svc.yaml``. Then, deploy this service to
+Kubernetes:
+
+.. code-block:: console
+
+   kubectl apply -f ambassador-svc.yaml
+
+At this point, Envoy is now running on your cluster, along with the Ambassador
+control plane.
+
+Configuring Ambassador
+----------------------
+
+Ambassador uses Kubernetes annotations to add or remove configuration. This
+sample YAML will add a route to Google, similar to the basic configuration
+example in the :ref:`Getting Started guide <install_getting_started>`.
+
+.. code-block:: yaml
+
+  ---
+  apiVersion: v1
+  kind: Service
+  metadata:
+    name: google
+    annotations:
+      getambassador.io/config: |
+        ---
+        apiVersion: ambassador/v0
+        kind:  Mapping
+        name:  google_mapping
+        prefix: /google/
+        service: https://google.com:443
+        host_rewrite: www.google.com
+  spec:
+    type: ClusterIP
+    clusterIP: None
+
+Save the above into a file called ``google.yaml``. Then run:
+
+.. code-block:: console
+
+   kubectl apply -f google.yaml
+
+Ambassador will detect the change to your Kubernetes annotation and add the
+route to Envoy. Note that we used a dummy service in this example; typically,
+you would associate the annotation with your real Kubernetes service.
+
+Testing the mapping
+-------------------
+
+You can test this mapping by getting the external IP address for the Ambassador
+service, and then sending a request via ``curl``.
+
+.. code-block:: console
+
+   $ kubectl get svc ambassador
+   NAME         CLUSTER-IP     EXTERNAL-IP     PORT(S)        AGE
+   ambassador   10.19.241.98   35.225.154.81   80:32491/TCP   15m
+   $ curl -v 35.225.154.81/google/
+
+More
+----
+
+Ambassador exposes multiple Envoy features on mappings, such as CORS, weighted
+round robin, gRPC, TLS, and timeouts. For more information, read the
+`configuration documentation
+<https://www.getambassador.io/reference/configuration>`_.

docs/root/install/getting_started.rst

@@ -52,3 +52,14 @@ Envoy binary, and putting the binary in an Ubuntu container.
   :maxdepth: 1
 
   sandboxes/local_docker_build
+
+Other use cases
+---------------
+
+In addition to the proxy itself, Envoy is also bundled as part of several open
+source distributions that target specific use cases.
+
+.. toctree::
+  :maxdepth: 1
+
+  distro/ambassador