A new platform for documentation and tutorials is launching soon.
We are migrating Waypoint documentation into HashiCorp Developer, our new developer experience.
»Installing Waypoint for Kubernetes
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
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
»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
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
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.
LoadBalancerservice was created to access the Waypoint service.
waypoint logincommand 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.