Compatibility Promise
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 has multiple components that need to interact with each other: the clients, the server, entrypoints, etc. Due to the diverse nature of these components, Waypoint has a protocol versioning system designed to minimize breaking changes and allow users to predictably run differing versions of each component.
Waypoint version compatibility is determined based on the protocol version and not the release version such as "1.2.3". Two different Waypoint release versions are compatible so long as their protocol versions are compatible. This allows for multiple simultaneous Waypoint versions to be in use, which is expected.
Our promises:
We promise that two Waypoint versions can interoperate with each other if their protocol versions overlap.
We promise that there will always be a release with overlapping protocol versions to allow all Waypoint components to safely upgrade.
For Waypoint servers, we promise that each subsequent release will be compatible with the prior release for upgrades. Concretely: 0.4 can upgrade to 0.5 but may not be able to safely upgrade to 0.6 directly. You often will be able to upgrade multiple versions at once but you must verify with the upgrade guides first.
Note that point #3 is only applicable to servers since they are the only component that stores state. For all other components (CLI, UI, entrypoints, etc.), compatibility promise #1 is most important.
Scope of Compatibility
The usage of the term "compatibility" describes the ability for two separate Waypoint processes to interoperate by API. Compatibility does not cover CLI commands or flags, the Waypoint configuration file, or UI layout.
We will make our best effort to keep these compatible across versions but they are not covered by the protocol version or the compatibility promise outlined on this page.
You may learn of any backwards incompatibilities in these sections in the upgrade guide for a specific version.
Protocol Versions
Waypoint advertises protocol versions which can be used to determine if differing release versions are compatible with each other. Protocol versions are integers that are greater than or equal to 1.
For each advertised protocol version, Waypoint advertises a minimum compatible version along with the current compatible version. A client may communicate with a Waypoint server so long as the current protocol versions are within the range advertised.
Finally, Waypoint advertises two types of protocol versions: one for the API, and one exclusively for the entrypoint protocol. This allows Waypoint to iterate on the API in potentially backwards incompatible ways without breaking entrypoints, and vice versa.
Current Protocol Version Table
The current protocol version table can be viewed here.
Example
The following is a concrete example of using the protocol versions to determine compatibility. The Waypoint versions and their advertised protocol versions are examples and not real, current Waypoint versions.
The scenario of the currently deployed Waypoint components is:
| Component | Version | Protocol Min | Protocol Current |
|---|---|---|---|
| Server | 5.1.0 | 3 | 5 |
| CLI | 5.3.2 | 4 | 5 |
| Entrypoint | 4.1.0 | 1 | 3 |
| Entrypoint | 3.3.0 | 1 | 2 |
In this scenario, there is a diverse set of Waypoint components currently deployed. Each has differing versions and its own set of protocol compatibilities. This is expected and normal. For example, developers will often use newer CLIs than what the server may be running and deployments will often run older (sometimes much older) entrypoint versions if they haven't been rebuilt and redeployed recently.
In this scenario, a new version of Waypoint comes out with the following compatibility:
| Component | Version | Protocol Min | Protocol Current |
|---|---|---|---|
| Server | 6.0.0 | API: 5 | API: 6 |
| Entrypoint: 3 | Entrypoint: 4 |
Going through the list of components, we can see:
The CLI is compatible. It speaks protocols 4 to 5, inclusive, and the API protocol for the new server would be 5 to 6. We should consider upgrading the CLI eventually but we don't need to immediately.
Entrypoint v4.1.0 is compatible, but v3.3.0 is not. The slightly newer (but still very outdated) entrypoint is still compatible so there are no problems there. But the deployments running entrypoint v3.3.0 need to be upgraded before the server is since they're incompatible. The entrypoint protocol for v3.3.0 was 1 to 2, and the new server only speaks 3 to 4.
To safely perform the upgrades required, please read the upgrade guide.
Frequency of Protocol Version Change
Protocol versions exist so that we can introduce breaking changes safely, but that doesn't mean that we will do so frequently. We recognize that protocol version changes can be very disruptive, and therefore aim to minimize the frequency of these changes.
At the time of writing, Waypoint is a relatively new project. Based on prior experience with other projects, we expect some protocol version changes during early releases (0.x) but for the frequency to quickly dissipate as the project matures.
We can look to Consul as an example, since they use a similar protocol versioning feature. By looking at their protocol version history, we can see that we introduced a new protocol version in the first 6 months of the project but retained compatibility for 2 years (until version 0.7). And while we introduced more protocol versions we continue to be compatible with versions over 4 years old.
With Waypoint, we hope to achieve something similar: we may iterate on the protocol quickly as a new project, but will aim to maintain compatibility for as long as possible.