Deploy Ambassador Edge Stack on Kubernetes

Ambassador Edge Stack is an open-source tool designed to function as a Swiss army knife of sorts for traffic between your Kubernetes clusters and the rest of the world. Ambassador offers Envoy-based ingres control, an API gateway, load-balancing and more through a single tool, allowing teams to reduce the number of individual components they need to install and support, in order to manage application traffic.

Ambassador also offers the advantage of being truly Kubernetes-native: It is configured using Kubernetes annotations and declarative configurations. It supports advanced API-management features like rate-limiting an circuit-breaking, as well.

Ambassador is quite simple to deploy. Below, we’ll walk through the steps to get Ambassador up and running on a Kubernetes cluster running on the Freedom plan of Platform9 Managed Kubernetes (PMK).

Set Up the PMK Free Tier Cluster

First, we need to set up a cluster in Platform9 that we’ll use to deploy Ambassador.

Follow these steps:

  1. Sign up for the Platform9 Freedom plan of PMK here and log in through your Web browser.
  2. Click the Create Cluster button and choose where you want to set up your cluster; BareOS for VMs or Physical, AWS or Azure. For this tutorial, we’ll use a BareOS installation, with nodes running on Ubuntu 16.04 virtual machines. (For details on how to set this up, see tutorials for Windows or macOS).
  3. To build a cluster using BareOS, log in to each virtual machine that you want to use as nodes, and run the command below to install the Platform9 CLI:

     $ bash <(curl -sL http://pf9.io/get_cli)
    

    Once the CLI is intalled run the prep-node command to configure the node and connect it to Platform9.

     $ pf9ctl cluster prep-node
    
  4. Go back to the Platform9 interface in your Web browser. You should now see a list of nodes that you can select to add to your cluster, as below:

    Nodes

  5. After you’ve selected your nodes, complete the steps on the screen to finish creating the cluster.
  6. You will need to select a node to serve as your master and then repeat the process to select worker nodes. Optionally, if you wish to use a multi-master cluster use the Virtual IP Address setup on the Networking step. Please ensure you have a reserved IP Address and that no network security will block traffic, otherwise the VIP configuration will fail.
  7. Once the cluster has been built and all nodes are in a converged and healthy state click the API Access tab (on the left of the Platform9 interface) and select an option to generate a Kubeconfig file and download the resulting file.
  8. To ensure your local environment is setup to connect to your new cluster apply the kubeconfig within your OS:

     $ export KUBECONFIG=/tmp/sample-kubeconfig.yaml
    
  9. Verify that the Kubeconfig was set up successfully:

     $ kubectl cluster-info
    

    You should see a message like this:

     Kubernetes master is running at https://192.168.1.12
     CoreDNS is running at https://192.168.1.12/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
     Metrics-server is running at https://192.168.1.12/api/v1/namespaces/kube-system/services/https:metrics-server:/proxy
    

Deploy Ambassador

Now, you’re ready to deploy Ambassador to your Platform9 Kubernetes cluster. There are two methods for doing this:

  1. Using the edgectl CLI tool, which automates most of the process.
  2. Manually downloading and applying the relevant YAML files.

    Whichever method you choose, remember that you’ll need to work within the same terminal where you ran the export Kubeconfig command from the previous section (or, you can run the export command again if you open a new terminal). Also remember that the Kubeconfig credentials you downloaded from the Platform9 Web console expire after twenty-four hours, so you’ll need to download a new Kubeconfig and export it to your environment if you exceed that window.

Install Ambassador with edgectl

Edgectl is a CLI tool that you can download from the website of Datawire, the main developer of Ambassador.

On Linux and macOS, you can download and run the installer with a curl command:

$ sudo curl -fL https://metriton.datawire.io/downloads/linux/edgectl \
        -o /usr/local/bin/edgectl \
        && sudo chmod a+x /usr/local/bin/edgectl

If you’re on Windows, download the installer from here.

Once edgectl is downloaded, run the installer with this command:

$ edgectl install

After installation completes, you can verify that the Ambassador pods are running under the Pods, Deployments, Services tab in Platform 9:

Services

As we can see, Ambassador has been deployed successfully on our Platform9 cluster.

Install Ambassador Manually

Deploying Ambassador manually is only slightly more complicated than using the Edgectl method as described above.

In the terminal where the Kubeconfig environment for your Platform9 cluster is active, run this command:

$ kubectl apply -f https://www.getambassador.io/yaml/aes-crds.yaml
$ kubectl wait --for condition=established --timeout=90s crd -lproduct=aes
$ kubectl apply -f https://www.getambassador.io/yaml/aes.yaml
$ kubectl -n ambassador wait --for condition=available --timeout=90s deploy -lproduct=aes

This will download and apply the YAML files to set up the Ambassador service.

You can then access the Ambassador Web console at your cluster’s IP address. If you don’t know that address, find it with the following command:

$ kubectl get -n ambassador service ambassador \
        -o "go-template={{range .status.loadBalancer.ingress}}{{or .ip .hostname}}{{end}}"

Now, there is one more step to perform: To log into the Ambassador Web console, you’ll first need to download and configure edgectl for your Ambassador instance. The Web console will display specific instructions to follow for this purpose. Complete those as directed, and you’ll be up and running.

Create an Ambassador Service

Ambassador uses Kubernetes Custom Resource Definitions to define how requests are mapped to services. The Resource Definitions are YAML files that are applied with kubectl.

Here’s a basic definition for a service that tells Ambassador to map requests for /httpbin/ to the service httpbin.org:

---
apiVersion: getambassador.io/v2
kind:  Mapping
metadata:
  name:  httpbin-mapping
spec:
  prefix: /httpbin/
  service: http://httpbin.org

To deploy this service, save the definition in a YAML file (we’ll use httpdbin.yaml for this example), then apply it with kubectl:

$ kubectl apply -f httpdbin.yaml

Additional Resources

For further guidance on how to configure Ambassador Edge Stack, examples of more complex service deployments and tips on best practices to follow, check out the official documentation. Ambassador also has an active Slack channel where you can get support.