Envoy as an API Gateway in Kubernetes with Ambassador

A common scenario for using Envoy is deploying it as an edge service (API Gateway) in Kubernetes. Ambassador 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:

  1. kubectl apply -f https://www.getambassador.io/yaml/ambassador/ambassador-rbac.yaml

or this if you are not using RBAC:

  1. 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.

  1. ---
  2. apiVersion: v1
  3. kind: Service
  4. metadata:
  5.   labels:
  6.     service: ambassador
  7.   name: ambassador
  8. spec:
  9.   type: LoadBalancer
  10.   ports:
  11.   - port: 80
  12.     targetPort: 80
  13.   selector:
  14.     service: ambassador

Save this YAML to a file ambassador-svc.yaml. Then, deploy this service to Kubernetes:

  1. 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 Getting Started guide.

  1. ---
  2. apiVersion: v1
  3. kind: Service
  4. metadata:
  5.   name: google
  6.   annotations:
  7.     getambassador.io/config: |
  8.       ---
  9.       apiVersion: ambassador/v0
  10.       kind:  Mapping
  11.       name:  google_mapping
  12.       prefix: /google/
  13.       service: https://google.com:443
  14.       host_rewrite: www.google.com
  15. spec:
  16.   type: ClusterIP
  17.   clusterIP: None

Save the above into a file called google.yaml. Then run:

  1. 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.

  1. $ kubectl get svc ambassador
  2. NAME         CLUSTER-IP     EXTERNAL-IP     PORT(S)        AGE
  3. ambassador   10.19.241.98   35.225.154.81   80:32491/TCP   15m
  4. $ 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.