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:

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

  2. Export the default k0s configuration file:

    1. docker exec k0s k0s config create > k0s.yaml

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

    1. docker exec k0s cat /var/lib/k0s/pki/admin.conf > k0s-cluster.conf
    2. 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:

    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

    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:

    1. docker stop k0s
    2. docker rm k0s

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

    1. 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.30.5-k0s.0

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

    1. kubectl get services -n ambassador

    Output:

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

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

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

    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

  2. Apply the YAML file:

    1. kubectl apply -f petstore.yaml

    Output:

    1. service/petstore created
    2. deployment.apps/petstore created
    3. mapping.getambassador.io/petstore created

  3. Validate that the service is running.

    In the terminal using curl:

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

    Output:

    1. [{"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.