Upgrading to Waypoint 0.11.0 from 0.10.x

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 0.10.x can be upgraded to Waypoint 0.11.0 using a standard upgrade. There are some considerations depending on what platform your server is installed on. There are no breaking changes in the protocol or waypoint.hcl configuration file. However, there was a bug related to the usage of dynamic configuration which will require attention during the upgrade. Those details are below.

Server Snapshot

Waypoint servers at versions 0.10.4 and 0.10.5 have a bug that prevents snapshots from being taken if a dynamic configuration source was set using the waypoint config source-set command. If your server is running at either of these versions and a waypoint config source-set command was run, then you will not be able to take snapshots using the command waypoint server snapshot.

To check if you are affected by the bug in question, run waypoint server snapshot. If this succeeds, disregard the rest of the below remediation steps. You are unaffected by this bug and can use waypoint server upgrade with no extra steps beyond your normal upgrade procedure.

If this fails, proceed with the below remediation steps. There are three options to upgrade to v0.11.0 if you are unable to create snapshots.

The first is, if you do not need a snapshot of the database before upgrading, then run the server upgrade with the flag -snapshot=false to proceed with upgrading:

$ waypoint server upgrade -snapshot=false

The second alternative is to delete all config sources from Waypoint using waypoint config source-set with the -delete flag, and then run waypoint server upgrade. After the server is upgraded, you can re-create the config sources using waypoint config source-set.

# Repeat the command below for each config source that is set; this example
# deletes the globally-scoped Vault config source
waypoint config source-set -delete -type=vault -scope=global

The third approach is to use platform-native persistence solutions to back up the file system where the Waypoint database is stored. This includes Docker, AWS ECS, Kubernetes, and HashiCorp Nomad. The steps to do this with each of these platforms are detailed below.

Docker

The Waypoint server stores data in a single data.db file, and in Docker its default location is /data/data.db. In the server data directory, copy the snapshot data and name the file waypoint-restore.db.

Now run:

waypoint server upgrade -snapshot=false

AWS ECS

The database of a Waypoint server installed to AWS ECS is persisted in a file system, provided by the Elastic File System (EFS) service of AWS. To preserve the database during the upgrade, a new EFS volume will need to be created. An access point will need to be added to this volume as well. This access point's path must be set to /waypointserverdata. The POSIX user and root directory creation permissions should both have their user and group ID set to 100 and 1000, respectively. The access point permissions should be set to 755.

The data in the old file system must be synchronized to the new one. This may be done using AWS DataSync. The source location should be configured as your old file system for the Waypoint server and the destination should be configured as the file system you just created.

Now run:

waypoint server upgrade -snapshot=false

Kubernetes

Given that volume snapshots are not part of the core API, as a pre-requisite to taking a volume snapshot, ensure CRDs are installed first. Once complete, proceed.

Confirm your storage class and add that to the following command to create a volume snapshot. Then verify your snapshot was created.

$ kubectl get storageclass

$ cat <<EOF | kubectl apply -f -
apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshot
metadata:
  name: waypoint-snapshot
spec:
  volumeSnapshotClassName: <storage-class>
  source:
    persistentVolumeClaimName: data-default-waypoint-server-0
EOF

$ kubectl get volumesnapshot
NAME                READYTOUSE   SOURCEPVC                        SOURCESNAPSHOTCONTENT   RESTORESIZE   SNAPSHOTCLASS   SNAPSHOTCONTENT   CREATIONTIME   AGE
waypoint-snapshot                data-default-waypoint-server-0                                         <storage-class>                                              13s

Now run:

waypoint server upgrade -snapshot=false

HashiCorp Nomad

Taking a snapshot of the Waypoint server's database before an upgrade will depend on what storage Waypoint was initially setup with. For host mounted volumes you will need to make a manual backup of the host volume itself and attempt the upgrade with snapshots disabled.

If you previously installed Waypoint using a CSI driver, it is possible to use the snapshot feature of the CSI driver to ensure a snapshot of your server is taken before upgrading. Run the following steps to take a snapshot.

Stop Waypoint server
Take a snapshot of the volume Waypoint used for server installation in Nomad
Verify the snapshot is ready in Nomad before continuing
Upgrade Waypoint to 0.11.0
Verify Waypoint server version

$ nomad job stop waypoint-server
[...]
  ✓ Deployment "7a885db5" successful

    2023-02-14T15:44:44-08:00
    ID          = 7a885db5
    Job ID      = waypoint-server
    Job Version = 37
    Status      = successful
    Description = Deployment completed successfully

$ nomad volume snapshot create <volume-id> waypoint-0-11-upgrade
Snapshot ID                        Volume ID    Size    Create Time             Ready?
<volume-id>@waypoint-0-11-upgrade  <volume-id>  211MiB  2023-02-14-15:45-08:00  true

$ nomad job inspect waypoint-server > waypoint-server-0.10.json
$ # Make a copy of `waypoint-server.json` and set {"Job": "Stop": false} and the waypoint server image version to "0.11.0" in the "waypoint-server" task group.
$ # Submit the job to nomad to start again.

$ nomad job run -json waypoint-server-0.11.0.json
[...]
  ✓ Deployment "b82dc4a1" successful

    2023-02-14T15:49:12-08:00
    ID          = b82dc4a1
    Job ID      = waypoint-server
    Job Version = 38
    Status      = successful
    Description = Deployment completed successfully

Now run:

waypoint server upgrade -snapshot=false

Verifying the Server Version with the UI

You can verify the server version by loading the UI and looking at the footer. You should see a version starting with v0.11.0. If you see an earlier version, your platform may be using an old cached image.

Verifying the Server Version with the CLI

You can verify both the CLI version and server version by running:

$ waypoint version
CLI: v0.11.0 (-------)
Server: v0.11.0