SearchVarnish Controller
NOTE: For minor version changes you should follow the Upgrade Path, including a database backup.
Before upgrading please take a backup of your database, this will make it possible to rollback to the previously installed version.
The below topics are subject to changes that might affect an existing setup, especially if the REST API is used.
We recomend to upgrade in the following order, to avoid downtime:
To avoid traffic down time when upgrading the Traffic Router, it might be a good idea to set Start Healthy: true for the Routing Rule. This will make
sure that the router keeps routing directly after restart, instead of waiting for the health check threshold that has been configured. This will however
make the router redirect traffic to potentially unhealthy nodes, until the threshold has been reached after restart.
tags MigrationNote: No action is required from the user for this change. This is just upgrade information.
Version 6.0.0 adds support for a new type called TagRoute, which is an improved tags routing decision, that supports subdecisions.
If the existing controller have RoutingRules with tags in the lookup-order, these will be automatically converted into TagRoutes. The lookup-order
will change from tags to tags:<id>, where the ID points out a TagRoute that will be created automatically during the upgrade process.
To change the behavior of the tags routing decision, changes is done to the TagRoute object. The subdecision can then be changed from the default
leastutilized to healthy, random or leastutilized.
Example:
# Pior to upgrade
lookup-order: tags,external,random
# After upgrade
lookup-order: tags:1,external,random
New vcli commands:
# List tagroutes
vcli tagroutes ls
# Change subdecision of a tag route
vcli u 1 --subdecision=random
The permission system has been reworked a bit and has a more fine grained verification of nested permissions. A lot of these changes are automatically migrated during upgrade. But some permissions for users might require some tweaking. If you encounter any issues related to permissions in version 6.0, please check: Missing permissions.
Instead of two fixed CORS headers that could be configured for HTTP routing, now an open list of headers can be specified. The old configuration is automatically migrated to the new headers field.
ErrorKey has been removed from the error responses.varnishstat endpoints are renamed to stats as they no longer hold just Varnish Statistics. As of version 5 there was support for both endpoints, the following API endpoints need to be changed:
/api/v1/agents/varnishstats to /api/v1/agents/stats/api/v1/agents/{id}/varnishstats to /api/v1/agents/{id}/stats/api/v1/domains/varnishstats to /api/v1/domains/stats/api/v1/domains/{id}/varnishstats to /api/v1/domains/{id}/stats/api/v1/routers/varnishstats to /api/v1/routers/stats/api/v1/routers/{id}/varnishstats to /api/v1/routers/{id}/stats/api/v1/tags/varnishstats to /api/v1/tags/stats/api/v1/tags/{id}/varnishstats to /api/v1/tags/{id}/stats/api/v1/vclgroups/varnishstats to /api/v1/vclgroups/stats/api/v1/vclgroups/{id}/varnishstats to /api/v1/vclgroups/{id}/statsBefore upgrading please take a backup of your database, this will make it possible to rollback to the previously installed version.
Brainz should be the first component that is upgraded, after brainz has been upgraded upgrade the API-GW, VCLI, agents and routers.
In the database the Varnish Controller now forces the timezone to UTC. This might impact your own implementations if you are doing comparisons with time yourself.
Agents and routers may appear in Down state during upgrade. The deployed VCLs and routing configuration will still be active.
There is a change for invalidations and TLS, the varnish-invalidation-tls now indicates if Varnish is running with TLS and the invalidation request should be with TLS. A new flag varnish-invalidation-tls-verify indicates if the TLS cert should be verified or not.
Brainz now have a base-dir for storing files. This is by default /var/lib/varnish-controller/varnish-controller-brainz/. In a container
environment, this needs to be configured using the VARNISH_CONTROLLER_BASE_DIR environment variable or the -base-dir flag.
No changes required after upgrading
vcli vcl * commands have been removed, you can use the same command but instead of vcli vcls use vcli files.vcli inspect <command> now always outputs an array, even for results with one object where as previously it just returned the object.vcli <command> update now only return the changed element.perm, account, idp and org lists all entries after delete.org update, tag update and perm add to avoid mistakes.vcli org update now supports -y to avoid interactive confirmation.-idp flag from org add as the org needs to be created before adding an IDP to an org.-v from session (was showing same output)./api/v1/vcls/* endpoints have been removed,you can use the same endpoint and bodies but instead of /api/v1/vcls use /api/v1/files endpoints instead./api/v1/agents/1/vclgroups endpoint has been removed, use /api/v1/vclgroups?agents.id=1&vg_states.deployed=true instead./api/v1/tags/1/agents endpoint has been removed, use /api/v1/agents?tags.id=1 instead./api/v1/vclgroups/1/agents endpoint has been removed, use /api/v1/agents?vcl_groups.id=1&vg_states.deployed=true instead.operator=and has been removed from the filters, instead of ?tags.id=1,2&operator=and use ?tags.id[all]=1,2.deployed: true/false has been changed to a deployment state deployState: 1/2/3.
The router flag http-tls has been replaced by the flag https-routing. This needs to be updated if TLS routing is used.
The https-port and https-host has been added for HTTPS routing in the router. These flags specify host and port for the TLS enabled endpoint of the router.
There are some important changes for the agent configuration. The options for varnish-port and varnish-invalidation-port are removed. These should be entered in the varnish-host and varnish-invalidation-host fields. For the varnish-host the following formats should be used example.com:8080. The varnish-invalidation-host by default the varnish-host is used. The following formats can be used for the invalidation configuration:
example.comexample.com:8080:8080If you are using the varnish-ext-ip in the agent configuration you will need to change this. This flag has been removed and will need to be replaced by the ipv4 and/or ipv6 flag.
If a custom root VCL is used for the agent, the template has slightly changed. The following template code:
{{range $index, $element := .}}
Should be replaced with:
{{range $index, $element := .Routes}}
Note the .Routes instead of just the ..
There are 2 important changes to be aware of:
[controller] is changed to [brainz] for brainz.[api] is changed to [api-gw] for api-gw.First upgrade brainz. If multiple brainz instances are running, they will back off until all have been upgraded and then the database will be migrated by one of the instances. brainz will make sure that no brainz instance has been running for the last 10 seconds before performing migrations and start.
After brainz has been upgraded, the agents and api-gw will stop since they are no longer compatible with the new version of brainz. Deployed VCLs will still be deployed to Varnish.
Upgrade agents and api-gw components. Then the VCLI and UI.
Components can be upgraded in any order, but it’s recommended to upgrade brainz first.
First upgrade brainz. If multiple brainz instances are running, they will back off until all have been upgraded and then the database will be migrated by one of the instances. brainz will make sure that no brainz instance has been running for the last 10 seconds before performing migrations and start.
After brainz has been upgraded, the agents and api-gw will stop since they are no longer compatible with the new version of brainz. Deployed VCLs will still be deployed to Varnish.
Upgrade agents and api-gw components. Then the VCLI and UI.
Components can be upgraded in any order, but it’s recommended to upgrade brainz first.
In most cases, no configuration changes is required after upgrade. It will be enough to upgrade packages
and make sure that the component services gets restarted. Please read through changelog to make sure
your setup isn’t using anything that has been changed (such as the -keep-deleted flag for brainz).
For more information regarding version compatibility, see Versioning.