Upgrading Waypoint

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.

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.

Helm Chart

If you're using the Waypoint Helm chart to install Waypoint, you can upgrade using the helm upgrade command. Please take note of any version-specific upgrade notes prior to upgrading, which may include minimum Helm chart versions for the upgrade or steps you should take prior or following the upgrade.

$ 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 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.
Take a snapshot of the server
Shut down the previous server version A.
Start the new server version B.
Restore the server snapshot
Verify the connection

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. 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.
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.

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

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.