Installing Ambassador API Gateway

You can configure k0s with the Ambassador API Gateway and a MetalLB service loadbalancer. To do this you leverage Helm's extensible bootstrapping functionality to add the correct extensions to the k0s.yaml file during cluster configuration.

Note: Currently Ambassador API Gateway does not support Kubernetes v1.22 or above. See here for details.

Use Docker for non-native k0s platforms

With Docker you can run k0s on platforms that the distribution does not natively support (refer to Run k0s in Docker). Skip this section if you are on a platform that k0s natively supports.

As you need to create a custom configuration file to install Ambassador Gateway, you will first need to map that file into the k0s container and to expose the ports Ambassador needs for outside access.

1. Run k0s under Docker:

   docker run -d --name k0s --hostname k0s --privileged -v /var/lib/k0s -p 6443:6443 docker.io/k0sproject/k0s:v1.31.1-k0s.0
   

2. Export the default k0s configuration file:

   docker exec k0s k0s config create > k0s.yaml
   

3. Export the cluster config, so you can access it using kubectl:

   docker exec k0s cat /var/lib/k0s/pki/admin.conf > k0s-cluster.conf
   export KUBECONFIG="$KUBECONFIG:$PWD/k0s-cluster.conf"
   

Configure k0s.yaml for Ambassador Gateway

1. Open the k0s.yml file and append the following extensions at the end:

   extensions:
     helm:
       repositories:
         - name: datawire
           url: https://www.getambassador.io
         - name: bitnami
           url: https://charts.bitnami.com/bitnami
       charts:
         - name: ambassador
           chartname: datawire/ambassador
           version: "6.5.13"
           namespace: ambassador
           values: |2
             service:
               externalIPs:
               - 172.17.0.2
         - name: metallb
           chartname: bitnami/metallb
           version: "1.0.1"
           namespace: default
           values: |2
             configInline:
               address-pools:
               - name: generic-cluster-pool
                 protocol: layer2
                 addresses:
                 - 172.17.0.2
   

   Note: It may be necessary to replace the 172.17.0.2 IP with your local IP address.

   This action adds both Ambassador and MetalLB (required for LoadBalancers) with the corresponding repositories and (minimal) configurations. Be aware that the provided example illustrates the use of your local network and that you will want to provide a range of IPs for MetalLB that are addressable on your LAN to access these services from anywhere on your network.

2. Stop/remove your k0s container:

   docker stop k0s
   docker rm k0s
   

3. Retart your k0s container, this time with additional ports and the above config file mapped into it:

   docker run --name k0s --hostname k0s --privileged -v /var/lib/k0s -v "$PWD"/k0s.yaml:/k0s.yaml -p 6443:6443 -p 80:80 -p 443:443 -p 8080:8080 docker.io/k0sproject/k0s:v1.31.1-k0s.0
   

   After some time, you will be able to list the Ambassador Services:

   kubectl get services -n ambassador
   

   Output:

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

4. Install the Ambassador edgectl tool and run the login command:

   edgectl login --namespace=ambassador localhost
   

   Your browser will open and deeliver you to the Ambassador Console.

Deploy / Map a Service

1. Create a YAML file for the service (for example purposes, create a Swagger Petstore service using a petstore.YAML file):

   ---
   apiVersion: v1
   kind: Service
   metadata:
     name: petstore
     namespace: ambassador
   spec:
     ports:
       - name: http
         port: 80
         targetPort: 8080
     selector:
       app: petstore
   ---
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: petstore
     namespace: ambassador
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: petstore
     strategy:
       type: RollingUpdate
     template:
       metadata:
         labels:
           app: petstore
       spec:
         containers:
           - name: petstore-backend
             image: docker.io/swaggerapi/petstore3:unstable
             ports:
               - name: http
                 containerPort: 8080
   ---
   apiVersion: getambassador.io/v2
   kind:  Mapping
   metadata:
     name: petstore
     namespace: ambassador
   spec:
     prefix: /petstore/
     service: petstore
   

2. Apply the YAML file:

   kubectl apply -f petstore.yaml
   

   Output:

   service/petstore created
   deployment.apps/petstore created
   mapping.getambassador.io/petstore created
   

3. Validate that the service is running.

   In the terminal using curl:

   curl -k 'https://localhost/petstore/api/v3/pet/findByStatus?status=available'
   

   Output:

   [{"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 by way of your browser:

   Open https://localhost/petstore/ in your browser and change the URL in the field at the top of the page to https://localhost/petstore/api/v3/openapi.json (as it is mapped to the /petstore prefix) and click Explore.

4. Navigate to the Mappings area in the Ambassador Console to view the corresponding PetStore mapping as configured.