Installing Waypoint for Kubernetes

Warning

This content is part of the legacy version of Waypoint that is no longer actively maintained. For additional information on the new vision of Waypoint, check out this blog post and the HCP Waypoint documentation.

The first step in using Waypoint with Kubernetes is installing Waypoint both on your local machine and within the Kubernetes cluster. Waypoint provides a Helm chart to setup a fully production ready Waypoint server cluster on Kubernetes.

Why a server? Waypoint requires a serverside component to enable features such as GitOps, history tracking, resource health checking, collaboration with teammates, etc. You can also run Waypoint in a purely local mode for quick tasks where the previously mentioned features aren't important.

Installing the Waypoint CLI

If you're setting up a Waypoint server cluster for the first time or you're a person who prefers to work with a command-line interface (CLI), you'll need the waypoint CLI installed on your local machine. The waypoint CLI is used to run Waypoint operations such as builds and deploys as well as to configure the server.

Note on permissions: The Waypoint installer requires permissions for managing the Kubernetes cluster. This covers basic permission needs, such as statefulset management, as well as the management of RBAC objects, such as cluster role bindings. Platforms typically have these permissions in a set role. For example, GCP's Kubernetes Engine Admin role provides the necessary permissions to install a Waypoint server via the base installer or with Helm.

If you have an existing Waypoint server cluster already created and you're just trying to use Waypoint, you may be able to just use the web interface instead. Ask another team member with Waypoint setup for the URL to your interface and credentials to log in.

To install the Waypoint client, go to the Downloads page and follow the instructions. We provide raw binaries as well as full system packages depending on your operating system.

To verify Waypoint is setup, run waypoint in your terminal. The output should start with something that looks like:

$ waypoint
Welcome to Waypoint
Docs: https://waypointproject.io
Version: vX.Y.Z

Not working? Ensure the waypoint binary is on your PATH. This may require restarting your terminal program.

Installing the Waypoint Server with Helm

The recommended process for installing Waypoint on Kubernetes is with Helm using the official Waypoint Helm chart. This documentation assumes you have helm installed and that your kubectl is already configured to talk to a Kubernetes cluster.

You can install Waypoint using the following commands:

$ helm repo add hashicorp https://helm.releases.hashicorp.com
"hashicorp" has been added to your repositories

$ helm install waypoint hashicorp/waypoint

The Helm chart has many configurable values but is designed to work out of the box with reasonable defaults.

Once you run helm install, it may take Waypoint up to 10 minutes to bootstrap itself. During this time, you may retry running the command below to log in to your Waypoint cluster. Once the command succeeds, Waypoint is ready for usage! If the command below fails, wait a few moments and try again; the Waypoint cluster is probably still bootstrapping.

$ waypoint login -from-kubernetes

At this point, Waypoint is configured and ready for use!

What Just Happened?

If you're just starting to get a feel with Waypoint, you can skip this section. As you plan to move Waypoint into real production usage, it is probably worth understanding what the above actually does beneath the covers. The following is an overview of what happened between the helm install and waypoint login commands:

A Waypoint server was started on Kubernetes. The Waypoint server must store data, so a persistent volume claim is used to store this state.
A Waypoint runner profile was configured so that operations such as builds, deploys, etc. launch within Kubernetes pods.
The Waypoint server was bootstrapped which creates the first user. The authentication token for this first user was stored in a Kubernetes Secret.
A LoadBalancer service was created to access the Waypoint service.
The waypoint login command used your local Kubernetes configuration to look up the Waypoint service and connect to it using the bootstrapped authentication token present in the Kubernetes secret.

All of these steps could be run manually if you wanted, but the official recommendation on Kubernetes is to use the Helm chart. Still, it is important to know that there isn't any magic happening behind the scenes.