The Varnish Controller packages use semantic versioning to help install the correct packages that are compatible with each other. The versions consist of major (X), minor (Y) and patch (Z) numbers with a possible addition. This is an example version:
1.2.3 referred to as
X.Y.Z. The advice is to always have all packages run the same major (X), minor (Y) and patch (Z) version. When a package is upgraded to a new major (X) or minor (Y) release, the other packages need to be updated as well for compatibility. Patch (Z) releases are backwards compatible within the same major (X) and minor (Y) release and may differ between the packages. We do recommend also running the same patch versions.
X value increases when there are changes in the release that could impact your setup or your custom implementation of the API. For example when there is a change in the CLI / API output that could break your implementation of the API, there will be a new major (X) release as your implementation might need to be changed. Check the changelog carefully to see what has been changed in the release.
Y value is increased when there are breaking changes internally between the packages. For example when Brainz needs extra data from the Agent to operate there will be a new minor version. All packages will need to be updated to the same minor version for compatibility.
Z value increases when we have fixed a bug that is backward compatible with previous releases or when we add new functionality that is backwards compatible. For example we added a configuration parameter to disable some UI features. This is a non-breaking change and you can update a single package in this case. It is recommended to have all packages at the same patch version.
There are some minor exceptions for the interface towards the user:
The Varnish Controller has build in protection for incompatible versions.
Scenario 1: API-GW, CLI or Agent packages are upgraded to a new major (X) or minor (Y) version and Brainz is running an older version. API-GW upgraded from
1.1.0 and Brainz is running
Behavior 1: The API-GW, CLI and Agent will terminate but it does not affect Varnish and the deployed VCL files. There are log entries in the API-GW, CLI and Agent that the version is incompatible with Brainz. This will protect your deployed VCL and will not impact the Varnish instance.
Scenario 2: Only Brainz is upgraded to a new major (X) or minor (Y) version, the API-GW, CLI or Agent are not yet upgraded. Brainz upgrade from
1.1.0. API-GW, CLI or Agent keep running on
Behavior 2: Same as Behavior 1, API-GW, CLI or Agent will terminate but it does not affect Varnish and the deployed VCL files. There are log entries in the API-GW, CLI and Agent that the version is incompatible with Brainz. This will protect your deployed VCL and will not impact the Varnish instance.
Scenario 3: There are multiple API-GW or Agents running. One is upgraded to a new major (X) or minor (Y) version. The others keep running and are not yet upgraded.
Behavior 3: The API-GW or Agents that are updated will not handle & execute requests until Brainz is updated. Once Brainz is updated the other packages that run older versions will not handle & execute requests.
Brainz is a bit special as in it can modify the database and cause other problems when running multiple Brainz instances. Brainz will quit when it detects another Brainz running on an older version. The older version will keep running making sure the system keeps operating as usual. The upgraded Brainz instance will try to restart automatically when setup with systemd or in your container environment and check the version again. Until the upgraded Brainz is the only one running or all Brainz instances are upgraded to the same version they will start and handling requests again. This makes sure that non upgraded components keep working when upgrading until all Brainz instances are upgraded.
The NATS messaging server (varnish-controller-nats) follows upstream versioning and is not part of the Varnish Controller Semantic Versioning scheme. We recommend to use the latest version of varnish-controller-nats.
Container images follows the same versioning scheme as our packages, with varnish-controller-nats as an exception.
Pinning to a version
:5.1 will update to all future patch
versions within version 5, and pinning to
automatically update all future minor versions within version 5.