---
layout: docs
page_title: Upgrading
description: |-
  Waypoint is designed to be flexible and resilient when upgrading from one version to the next. We've carefully thought out an upgrade process so you can predict what will be involved when upgrading Waypoint.
---

# Upgrading Waypoint

Waypoint is designed to be flexible and resilient when upgrading from
one version to the next. We've carefully thought out an upgrade process
so you can predict what will be involved when upgrading Waypoint.

Waypoint is composed of many components which each have their own upgrade
considerations:

- **Client** (such as the CLI or UI) - Users of Waypoint are not expected
  to exactly match the Waypoint server version. The Waypoint upgrade process
  and compatibility promise allows for clients with differing versions from
  a Waypoint server.

- **Entrypoint** - The [entrypoint](/docs/entrypoint) is built and run
  directly on the deployment artifact. Users of Waypoint cannot be expected
  to rebuild and redeploy all applications. The Waypoint upgrade process
  and compatibility promise is designed so that entrypoints retain compatibility
  as long as possible.

- **Server** - The server component of Waypoint must remain compatible
  with all actively used clients and entrypoints. The Waypoint upgrade process
  is designed for you to know when and how to safely upgrade the server.

Please see our [compatibility promise](/docs/upgrading/compatibility)
for details on how to determine compatibility. This page will focus on
how to upgrade components in both compatible and incompatible scenarios.

### Helm Chart

If you're using the [Waypoint Helm chart](https://github.com/hashicorp/waypoint-helm)
to install Waypoint, you can upgrade using the `helm upgrade` command.
Please take note of any
[version-specific upgrade notes](/docs/upgrading/version-guides) prior
to upgrading, which may include minimum Helm chart versions for the upgrade
or steps you should take prior or following the upgrade.

```shell-session
$ helm repo update
$ helm upgrade waypoint hashicorp/waypoint
```

-> Note that the "waypoint" value in `helm upgrade` refers to the
release name you chose during `helm install`. This may be different for you.

### Server Upgrade Command

Waypoint provides a command for users to upgrade the
Waypoint server in place. For each platform, Waypoint attempts to
update the server image in place to latest by default, or to the server image
specified via a flag passed in to the upgrade command.

When the upgrade command is executed, Waypoint does the following:

- Takes a snapshot of the current server database and saves snapshot locally. The
  snapshot file can be saved elsewhere if a new name is passed in using the flag
  `-snapshot-name`, or optionally skipped all together.
- Runs the upgrade for the requested platform:
  - `docker` - This platform will force pull the image requested to update the
    container in docker.
  - `kubernetes` - This platform will submit a patch request to kubernetes to
    set the image requested on the waypoint-server pod. By default, Waypoint's
    StatefulSet is configured to `RollingUpdate`, so the pod will pull the
    requested version shortly after running the Waypoint upgrade command.
  - `nomad` - This platform will update the waypoint server job with the server
    image requested.
  - `ecs` - This platform will locate the existing cluster, update task definitions, and upgrade the image to the latest.
- Verifies that waypoint CLI can still connected and speak to Waypoint server

If you wish to use the automated upgrade command line approach, follow the
Standard Upgrade guide using the _Automated Upgrade_ Server Upgrade subsection.

## Standard Upgrade

A standard upgrade is one where the [protocol version](/docs/upgrading/compatibility)
remains compatible for all components from one upgrade to another. In other
words, this is an upgrade with no backwards incompatibilities.

Unless otherwise noted by the release notes, you can upgrade the server,
client, and entrypoints in any order for a standard, backwards compatible upgrade.

### Server Upgrade

#### Manual Upgrade

1. Check any upgrade notes for the version you're upgrading to and verify
   there are no issues that will affect your upgrade.

2. [Take a snapshot of the server](https://www.waypointproject.io/commands/server-snapshot)

3. Shut down the previous server version A.

4. Start the new server version B.

5. [Restore the server snapshot](https://www.waypointproject.io/commands/server-restore)

6. [Verify the connection](https://www.waypointproject.io/commands/context-verify)

-> **Note:** There is no way today to avoid a small amount of downtime
when upgrading from version A to version B. In practice this should be
okay since all components continue to gracefully work while the server
is down, and the downtime should be short. We plan on improving this
in the future.

#### Automated Upgrade

1. Check any upgrade notes for the version you're upgrading to and verify
   there are no issues that will affect your upgrade.

2. Check the help text from running `waypoint server upgrade -help`.

3. Ensure you are in the right server context before upgrading.
   Check current context with `waypoint context inspect`. If this is not the intended context to upgrade,
   run `waypoint context list` and choose the right one with `waypoint context use <name>`.
   The upgrade automatically runs `waypoint context verify`.

4. When ready, run the upgrade command for your given platform. For example:

```shell-session
waypoint server upgrade -platform=kubernetes -auto-approve
```

This will automatically save a snapshot of the server in your current directory
prior to upgrading.

If the server was installed with a remote runner, Waypoint will uninstall the existing runner and install a new one with the new version.

### Client Upgrade

1. Check any upgrade notes for the version you're upgrading to and verify
   there are no issues that will affect your upgrade.

2. Replace the client with the new version.

### Entrypoint Upgrade

1. Check any upgrade notes for the version you're upgrading to and verify
   there are no issues that will affect your upgrade.

2. Upgrade the client first. The client generally embeds the new entrypoint.
   If you're installing the entrypoint from an external source this step can
   be skipped.

3. Rebuild and redeploy your application with the new entrypoint.

## Backwards Incompatible Upgrade

A backwards incompatible upgrade is one where the
[protocol version](/docs/upgrading/compatibility)
becomes incompatible from one version to another.

1. For backwards incompatible upgrades, you must first upgrade the
   server to the version that will remain compatible with both the old
   and new protocol version you're attempting to upgrade to.

2. Upgrade incompatible clients next by following the standard
   [client upgrade process](#client-upgrade) but ensure the version being
   upgraded to is compatible with the server version.

3. Upgrade incompatible entrypoints by following the standard
   [entrypoint upgrade process](#entrypoint-upgrade) and ensuring the
   entrypoints being used are compatible with the server version.

4. _Optional:_ Upgrade to the next version of the server which was
   incompatible with your prior set of components. This often better prepares
   you for future changes. This step was impossible at step (1) since either
   clients or entrypoints were incompatible prior to steps (2) and (3).

## Future Upgrade Improvements

We have plans in the future to introduce tooling to make it much easier to
confidently upgrade your Waypoint installations. Some of our roadmap plans
include:

- Built-in tooling to list all protocol versions currently in use.

- Built-in tooling to propose a step-by-step upgrade guide for a version
  that takes into account target and current protocol versions. This will let
  you know what needs upgrading and what doesn't.
