The 2 minute guide to running Ambassador on Minikube

Ambassador is three things:

1. Microservices API gateway
2. Kubernetes ingress controller
3. Load balancer

It builds on top of strong shoulders of Envoy proxy.

In this 2 minute guide, we will look at how to quickly setup Ambassador as Kubernetes ingress controller. We will use Kubernetes running locally on our machine using Minikube.

Let’s start by starting a single-node Kubernetes using Minikube CLI. I recommend reading Minikube documentation for installation instructions. We start single-node Kubernetes by executing the following command.

minikube start

Once single-node Kubernetes is started, we will create Ambassador deployment object along with Ambassador admin service. The ambassador-admin is a NodePort service that provides web UI.

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

You will see three running Ambassador pods.

kubectl get pod

NAME                         READY     STATUS    RESTARTS   AGE
ambassador-7ddf64cdb-hlg4x   1/1       Running   0          25m
ambassador-7ddf64cdb-qmxtg   1/1       Running   0          25m
ambassador-7ddf64cdb-z8zvf   1/1       Running   0          25m

Next, we will create Ambassador service for the deployment object we create in previous step.

Create a ambdassador-service.yaml and put following contents to it.

---
apiVersion: v1
kind: Service
metadata:
  name: ambassador
spec:
  type: LoadBalancer
  externalTrafficPolicy: Local
  ports:
   - port: 80
  selector:
    service: ambassador

The externalTrafficPolicy with value Local means that requests should only be proxied to local endpoints. It will never forward traffic to other nodes preserving the original source IP address.

You can deploy the service by executing following command.

kubectl apply -f ambassador-service.yaml

Now, we will create a new service. We will define Ambassador annotations on the service, and use the Mapping contained in to configure the route. The service configuration is shown below. Create a new file hello_world.yaml and put following contents to it.

---
apiVersion: v1
kind: Service
metadata:
  name: hello-world
  annotations:
    getambassador.io/config: |
      ---
      apiVersion: ambassador/v0
      kind:  Mapping
      name:  hello_world_mapping
      prefix: /hello-world/
      service: hello-world
spec:
  selector:
    app: hello-world
  ports:
  - port: 80
    targetPort: 8080
---
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  name: hello-world
spec:
  replicas: 1
  strategy:
    type: RollingUpdate
  template:
    metadata:
      labels:
        app: hello-world
    spec:
      containers:
      - name: hello-world
        image: infrastructureascode/hello-world

The service is a simple Go web server that prints Hello, World!. We have defined a mapping that will route traffic from the /hello-world/ to hello-world service.

Create the service by running following command.

kubectl create -f hello_world.yaml

Now, we can test our service. We will use the URL of Ambassador ingress. We can get that by running following command.

minikube service list

|-------------|------------------|-----------------------------|
|  NAMESPACE  |       NAME       |             URL             |
|-------------|------------------|-----------------------------|
| default     | ambassador       | http://192.168.99.107:31336 |

You can make cURL request to test the endpoint.

curl http://192.168.99.107:31336 

You should receive

Hello, World!

That’s it for today. I will keep exploring Ambassador more and post my learnings here.