Docker : Ambassador - Envoy API Gateway on Kubernetes

bogotobogo.com site search:

What is Ambassador?

Ambassador is an open source Kubernetes-Native API Gateway built on the Envoy Proxy.

API Gateway is an entry point for all client requests. The requests are proxied/routed to the appropriate services. Usually, traffic management, authentication, and monitoring are implemented in the API Gateway hiding the details from our services.

Ambassador operates as a specialized control plane to expose Envoy's functionality as Kubernetes annotations.

Here's what Ambassador does:

Makes it easy to change and add to your Envoy configuration via Kubernetes annotations
Adds the out-of-the-box configuration necessary for production Envoy, e.g., monitoring, health/liveness checks, and more
Extends Envoy with traditional API Gateway functionality such as authentication
Integrates with Istio, for organizations who need a full-blown service mesh

In this post, we will see how we can deploy Envoy on Kubernetes via Ambassador.

Ambassador only deploys in Kubernetes. This means that Ambassador delegates all the hard parts of scaling and availability to Kubernetes.

Fore more about API gateway, please check Microservices API Gateways vs. Traditional Enterprise API Gateways and Envoy vs NGINX vs HAProxy: Why the open source Ambassador API Gateway chose Envoy.

Deploy Ambassador

We'll use minikube:

$ minikube start
There is a newer version of minikube available (v0.32.0).  Download it here:
https://github.com/kubernetes/minikube/releases/tag/v0.32.0

To disable this notification, run the following:
minikube config set WantUpdateNotification false
Starting local Kubernetes v1.10.0 cluster...
Starting VM...
Getting VM IP address...
Moving files into cluster...
Setting up certs...
Connecting to cluster...
Setting up kubeconfig...
Starting cluster components...
Kubectl is now configured to use the cluster.
Loading cached images from config file.
$

To check if we're using a cluster with RBAC enabled. We should see the API version .rbac.authorization.k8s.io/v1 if RBAC is enabled:

$ kubectl api-versions
...
rbac.authorization.k8s.io/v1
...

Current status of the cluster looks like this:

$ kubectl get svc
NAME         TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)   AGE
kubernetes   ClusterIP   10.96.0.1    <none>        443/TCP   8h

$ kubectl get pods
No resources found.

To install Ambassador/Envoy on Kubernetes, run the following:

$ kubectl apply -f https://www.getambassador.io/yaml/ambassador/ambassador-rbac.yaml
service/ambassador-admin created
clusterrole.rbac.authorization.k8s.io/ambassador created
serviceaccount/ambassador created
clusterrolebinding.rbac.authorization.k8s.io/ambassador created
deployment.extensions/ambassador created

Now we have 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.

$ kubectl get pods
NAME                          READY   STATUS              RESTARTS   AGE
ambassador-67595bccdb-4nkn2   0/1     ContainerCreating   0          24s
ambassador-67595bccdb-6ddbj   0/1     ContainerCreating   0          24s
ambassador-67595bccdb-t4tzz   0/1     ContainerCreating   0          24s

$ kubectl get svc
NAME               TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)          AGE
ambassador-admin   NodePort    10.99.19.183   <none>        8877:30384/TCP   32s
kubernetes         ClusterIP   10.96.0.1      <none>        443/TCP          9h

Create a Kubernetes service to point to the Ambassador deployment

In order to deploy this service, we must create a Kubernetes manifest that specifies the desired end state of the service. For example, the my-service service could be defined as below:

kind: Service
apiVersion: v1
metadata:
  name: my-service
spec:
  selector:
    app: MyApp
  ports:
  - protocol: TCP
    port: 80
    targetPort: 9376

Because a Kubernetes service is the fundamental abstraction by which new services are exposed to other services and end users, Ambassador extends the service with custom annotations. For example:

kind: Service
apiVersion: v1
metadata:
  name: my-service
  annotations:
    getambassador.io/config: |
      ---
        apiVersion: ambassador/v0
        kind:  Mapping
        name:  my_service_mapping
        prefix: /my-service/
        service: my-service
spec:
  selector:
    app: MyApp
  ports:
  - protocol: TCP
    port: 80
    targetPort: 9376

Now, we need to create a Kubernetes service to point to the Ambassador deployment. We'll use a LoadBalancer service. If our cluster doesn't support LoadBalancer services, we may want to change to a NodePort or ClusterIP.

As we can see, the routing configuration for Ambassador is associated with each individual service. In other words, with this approach, there is no centralized Ambassador configuration file.

An a practical example, we'll use http://httpbin.org as shown in following ambassador-svc.yaml configuration:

---
apiVersion: v1
kind: Service
metadata:
  labels:
    service: ambassador
  name: ambassador
  annotations:
    getambassador.io/config: |
      ---
      apiVersion: ambassador/v0
      kind:  Mapping
      name:  httpbin_mapping
      prefix: /httpbin/
      service: httpbin.org:80
      host_rewrite: httpbin.org
spec:
  type: LoadBalancer
  ports:
  - name: ambassador
    port: 80
    targetPort: 80
  selector:
    service: ambassador

Let's deploy this service to Kubernetes:

$ kubectl apply -f ambassador-svc.yaml
service/ambassador created

Envoy is now running on our cluster, along with the Ambassador control plane.

$ kubectl get svc
NAME               TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
ambassador         LoadBalancer   10.100.2.208   <pending>     80:32649/TCP     46s
ambassador-admin   NodePort       10.99.19.183   <none>        8877:30384/TCP   18h
kubernetes         ClusterIP      10.96.0.1      <none>        443/TCP          1d

By using Kubernetes annotations, Ambassador integrates transparently into our existing Kubernetes deployment workflow.

Ambassador will detect the change to our Kubernetes annotation and add the route to Envoy. Note that we used a dummy service in this example; typically, we would associate the annotation with our real Kubernetes service.

Testing the mapping

In order to get access to our microservices through Ambassador, we need an external URL to Ambassador's service interface. Let's start by getting the external IP address of Ambassador. You can get the IP address by running kubectl describe service ambassador and looking at the LoadBalancer Ingress line:

$ kubectl describe service ambassador
Name:                     ambassador
Namespace:                default
Labels:                   service=ambassador
Annotations:              getambassador.io/config:
                            ---
                            apiVersion: ambassador/v0
                            kind:  Mapping
                            name:  httpbin_mapping
                            prefix: /httpbin/
                            service: httpbin.org:80
                            host_rewrite: httpbin.org
                          kubectl.kubernetes.io/last-applied-configuration:
                            {"apiVersion":"v1","kind":"Service","metadata":{"annotations":{"getambassador.io/config":"---\napiVersion: ambassador/v0\nkind:  Mapping\n...
Selector:                 service=ambassador
Type:                     LoadBalancer
IP:                       10.100.2.208
Port:                     ambassador  80/TCP
TargetPort:               80/TCP
NodePort:                 ambassador  32649/TCP
Endpoints:                172.17.0.7:80,172.17.0.8:80,172.17.0.9:80
Session Affinity:         None
External Traffic Policy:  Cluster
Events:                   <none>

On Minikube, we'll need to use minikube service --url ambassador:

minikube service --url ambassador
http://192.168.99.100:32649

We can now speak to the httpbin service using Ambassador. Let's send a request via curl, then Ambassador routes the request to the httpbin service:

$ curl $(minikube service --url ambassador)/httpbin/ip
{
  "origin": "108.239.135.40"
}

$ curl $(minikube service --url ambassador)/httpbin/user-agent
{
  "user-agent": "curl/7.54.0"
}


$ curl $(minikube service --url ambassador)/httpbin/headers
{
  "headers": {
    "Accept": "*/*", 
    "Connection": "close", 
    "Host": "httpbin.org", 
    "User-Agent": "curl/7.54.0", 
    "X-Envoy-Expected-Rq-Timeout-Ms": "3000", 
    "X-Envoy-Original-Path": "/httpbin/headers"
  }
}

Here is the list of URIs of the http://httpbin.org: