---
layout: docs
page_title: Kubernetes - Install
description: |-
  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.
---

# 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](/docs/projects/git), 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](https://cloud.google.com/iam/docs/understanding-roles?hl=en#kubernetes-engine-roles)
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](/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:

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

~> **Not working?** Ensure the `waypoint` binary is on your
[`PATH`](https://superuser.com/questions/284342/what-are-path-and-other-environment-variables-and-how-can-i-set-or-use-them). This may require restarting your
terminal program.

## Installing the Waypoint Server with Helm

The recommended process for installing Waypoint on Kubernetes is with
[Helm](https://helm.sh/) using the
[official Waypoint Helm chart](https://github.com/hashicorp/waypoint-helm).
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:

```shell-session
$ 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](https://github.com/hashicorp/waypoint-helm/blob/main/values.yaml)
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.

```shell-session
$ 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](/docs/server/run#bootstrap-the-server)
  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.
