Versioning

Strategy

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.

Major versions

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

Minor versions

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

Patch versions

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

Exceptions

There are some minor exceptions for the interface towards the user:

• System Debug API call can change at any time between any release. This is a debug call that requires potential changes between any type of release to improve the debug information from a running Varnish Controller system. This is to help the support of Varnish Controller.
• Log messages can change at any time between any type of release.

Varnish Controller version protection

The Varnish Controller has build in protection for incompatible versions.

API-GW, CLI & Agents

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.0.1 to 1.1.0 and Brainz is running 1.0.1.

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.0.1 to 1.1.0. API-GW, CLI or Agent keep running on 1.0.1.

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

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.

Nats

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.

Varnish

The controller supports at least the two latest versions of the Varnish Cache Enterprise.

Varnish Controller container images versioning

Container images follows the same versioning scheme as our packages, with varnish-controller-nats as an exception.

Example varnish-controller-brainz:

• Varnish Controller brainz version 5.1.1

Pinning to a version :5.1 will update to all future patch versions within version 5, and pinning to :5 will automatically update all future minor versions within version 5.

Example varnish-controller-agent:

• Varnish Controller agent version 5.1.1
• varnish-plus 6.0.10r5 (latest)
• varnish-plus 6.0.10r4 (previous)

varnish-controller-nats version table