Installing the Ambassador Gateway on k0s

In this tutorial, you’ll learn how to run k0s under Docker and configure it with the Ambassador API Gateway and a MetalLB service loadbalancer. We’ll also deploy a sample service and expose it with an Ambassador mapping resource.

Utilizing the extensible bootstrapping functionality with Helm, it’s as simple as adding the right extensions to the k0s.yaml file when configuring your cluster.

Running k0s under docker

If you’re not on a platform natively supported by k0s, running under docker is a viable option (see k0s in Docker). Since we’re going to create a custom configuration file we’ll need to map that into the k0s container - and of course we’ll need to expose the ports required by Ambassador for outside access.

Start by running k0s under docker :

  1. docker run -d --name k0s --hostname k0s --privileged -v /var/lib/k0s -p 6443:6443 docker.io/k0sproject/k0s:latest

Once running, export the default k0s configuration file using

  1. docker exec k0s k0s default-config > k0s.yaml

and export the cluster config so you can access it with kubectl:

  1. docker exec k0s cat /var/lib/k0s/pki/admin.conf > k0s-cluster.conf
  2. export KUBECONFIG=$KUBECONFIG:<absolute path to k0s-cluster.conf>

(somewhat brute-force but gets the job done)

Configuring k0s.yaml

Open the file in your favorite code editor and add the following extensions at the bottom:

  1. extensions:
  2.   helm:
  3.     repositories:
  4.       - name: datawire
  5.         url: https://www.getambassador.io
  6.       - name: bitnami
  7.         url: https://charts.bitnami.com/bitnami
  8.     charts:
  9.       - name: ambassador
  10.         chartname: datawire/ambassador
  11.         version: "6.5.13"
  12.         namespace: ambassador
  13.         values: |2
  14.           service:
  15.             externalIPs:
  16.             - 172.17.0.2
  17.       - name: metallb
  18.         chartname: bitnami/metallb
  19.         version: "1.0.1"
  20.         namespace: default
  21.         values: |2
  22.           configInline:
  23.             address-pools:
  24.             - name: generic-cluster-pool
  25.               protocol: layer2
  26.               addresses:
  27.               - 172.17.0.2

(you might need to replace the 172.17.0.2 IP with your local IP which you can find higher up in the generated file under spec.api.address)

As you can see it adds both Ambassador and Metallb (required for LoadBalancers) with corresponding repositories and (minimal) configurations. This example only uses your local network - providing a range of IPs for MetalLB that are addressable on your LAN is suggested if you want to access these services from anywhere on your network.

Now stop/remove your k0s container with docker stop k0s and docker rm k0s, then start it again with additional ports and the above config file mapped into it:

  1. docker run --name k0s --hostname k0s --privileged -v /var/lib/k0s -v <path to k0s.yaml file>:/k0s.yaml -p 6443:6443 -p 80:80 -p 443:443 -p 8080:8080 docker.io/k0sproject/k0s:latest

Let it start, and eventually (this can take some time) you’ll be able to list the Ambassador Services:

  1. kubectl get services -n ambassador
  2. NAME                          TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)                      AGE
  3. ambassador-1611224811         LoadBalancer   10.99.84.151    172.17.0.2    80:30327/TCP,443:30355/TCP   2m11s
  4. ambassador-1611224811-admin   ClusterIP      10.96.79.130    <none>        8877/TCP                     2m11s
  5. ambassador-1611224811-redis   ClusterIP      10.110.33.229   <none>        6379/TCP                     2m11s

Install the Ambassador edgectl tool and run the login command:

  1. edgectl login --namespace=ambassador localhost

This will open your browser and take you to the Ambassador Console - all ready to go.

Deploy / map a service

Let’s deploy and map the Swagger Petstore service; create a petstore.yaml file with the following content.

  1. ---
  2. apiVersion: v1
  3. kind: Service
  4. metadata:
  5.   name: petstore
  6.   namespace: ambassador
  7. spec:
  8.   ports:
  9.     - name: http
  10.       port: 80
  11.       targetPort: 8080
  12.   selector:
  13.     app: petstore
  14. ---
  15. apiVersion: apps/v1
  16. kind: Deployment
  17. metadata:
  18.   name: petstore
  19.   namespace: ambassador
  20. spec:
  21.   replicas: 1
  22.   selector:
  23.     matchLabels:
  24.       app: petstore
  25.   strategy:
  26.     type: RollingUpdate
  27.   template:
  28.     metadata:
  29.       labels:
  30.         app: petstore
  31.     spec:
  32.       containers:
  33.         - name: petstore-backend
  34.           image: docker.io/swaggerapi/petstore3:unstable
  35.           ports:
  36.             - name: http
  37.               containerPort: 8080
  38. ---
  39. apiVersion: getambassador.io/v2
  40. kind:  Mapping
  41. metadata:
  42.   name: petstore
  43.   namespace: ambassador
  44. spec:
  45.   prefix: /petstore/
  46.   service: petstore

Once you’ve created this, apply it:

  1. kubectl apply -f petstore.yaml
  2. service/petstore created
  3. deployment.apps/petstore created
  4. mapping.getambassador.io/petstore created

and you should be able to curl the service:

  1. curl -k 'https://localhost/petstore/api/v3/pet/findByStatus?status=available'
  2. [{"id":1,"category":{"id":2,"name":"Cats"},"name":"Cat 1","photoUrls":["url1","url2"],"tags":[{"id":1,"name":"tag1"},{"id":2,"name":"tag2"}],"status":"available"},{"id":2,"category":{"id":2,"name":"Cats"},"name":"Cat 2","photoUrls":["url1","url2"],"tags":[{"id":1,"name":"tag2"},{"id":2,"name":"tag3"}],"status":"available"},{"id":4,"category":{"id":1,"name":"Dogs"},"name":"Dog 1","photoUrls":["url1","url2"],"tags":[{"id":1,"name":"tag1"},{"id":2,"name":"tag2"}],"status":"available"},{"id":7,"category":{"id":4,"name":"Lions"},"name":"Lion 1","photoUrls":["url1","url2"],"tags":[{"id":1,"name":"tag1"},{"id":2,"name":"tag2"}],"status":"available"},{"id":8,"category":{"id":4,"name":"Lions"},"name":"Lion 2","photoUrls":["url1","url2"],"tags":[{"id":1,"name":"tag2"},{"id":2,"name":"tag3"}],"status":"available"},{"id":9,"category":{"id":4,"name":"Lions"},"name":"Lion 3","photoUrls":["url1","url2"],"tags":[{"id":1,"name":"tag3"},{"id":2,"name":"tag4"}],"status":"available"},{"id":10,"category":{"id":3,"name":"Rabbits"},"name":"Rabbit 1","photoUrls":["url1","url2"],"tags":[{"id":1,"name":"tag3"},{"id":2,"name":"tag4"}],"status":"available"}]

or you can open https://localhost/petstore/ in your browser and change the URL of the specification to https://localhost/petstore/api/v3/openapi.json (since we mapped it to the /petstore prefix).

If you navigate to the Mappings part of the Ambassador Console (opened above) you will see the corresponding PetStore mapping as configured.

Summary

This should get you all set with running Ambassador under k0s. If you’re not running under Docker just skip the docker-related steps above - but make sure that you have updated the k0s configuration in the same way as above.

If you’re stuck with or have any questions about Ambassador please try the Ambassador Slack to get help.