Upgrading Waypoint

Note: As of Waypoint 0.2.1, waypoint install and waypoint server install do support an upgrade. If you choose not to use the automated upgrade command, another way to upgrade to the latest server is to remove the existing server and then reinstall with waypoint install. Consider backing up data.db with docker cp waypoint-server:/data/data.db ./data.db, kubectl cp waypoint-server-0:/data/data.db ./data.db or similar.

Note: Upgrading on a k8s cluster requires using the flag -k8s-pull-policy=Always when rerunning waypoint install. There is a known issue that will be resolved in 0.2.1.

Note: If you are currently running Waypoint before 0.2.0, you will not be able to take snapshots prior to upgrading your server.

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 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 for details on how to determine compatibility. This page will focus on how to upgrade components in both compatible and incompatible scenarios.

URL Service

If you are upgrading from Waypoint server version 0.2.0 and older, Waypoint will register a new URL for your deployments after upgrading. Going forward, as of 0.2.1, this should no longer be an issue when upgrading Waypoint server.

Server Upgrade Command

As of 0.2.1, 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.
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 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

Check any upgrade notes for the version you're upgrading to and verify there are no issues that will affect your upgrade.
Shut down the previous server version A.
Start the new server version B.

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

Check any upgrade notes for the version you're upgrading to and verify there are no issues that will affect your upgrade.
Check the help text from running waypoint server upgrade -help.
Ensure you are in the right server context before upgrading. This can be verified through waypoint context.
When ready, run the upgrade command for your given platform. For example:

waypoint server upgrade -platform=kubernetes -auto-approve

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

Client Upgrade

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

Entrypoint Upgrade

Check any upgrade notes for the version you're upgrading to and verify there are no issues that will affect your upgrade.
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.
Rebuild and redeploy your application with the new entrypoint.

Backwards Incompatible Upgrade

A backwards incompatible upgrade is one where the protocol version becomes incompatible from one version to another.

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.
Upgrade incompatible clients next by following the standard client upgrade process but ensure the version being upgraded to is compatible with the server version.
Upgrade incompatible entrypoints by following the standard entrypoint upgrade process and ensuring the entrypoints being used are compatible with the server version.
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.