SearchThis release contains an updated version of the Gorilla CSRF protection library with a fix to
CVE-2025-24358. This fix makes it
necessary to explicitly turn off checks of the HTTPS-specific Origin header.
See the TLS for the Controller-UI examples for further details.
Installations, that do NOT use TLS need to add the -no-tls flag to their UI server startup
command.
Not adding the -no-tls flag will result in the error message Forbidden - origin invalid when
trying to log in.
Running the Controller-UI behind a reverse proxy such as Varnish or nginx might result in the
error message Forbidden - origin invalid if the HTTP Host header is changed by the proxy.
In Varnish, make sure to not change the req.http.host variable.
In nginx, add the following configuration directive behind the proxy_pass directive:
proxy_set_header Host $http_host;
Installations that use the -tls parameter or TLS termination through external software such as
Hitch or relayd do not need to change
anything.
This is a major release with breaking changes to the API and VCLI. Review the changes carefully, especially if you have automation, scripts, or integrations relying on them.
This release supports all currently maintained PostgreSQL versions: 13 to 17. We strongly recommend to upgrade PostgreSQL to at least version 15. PostgreSQL 15 has introduced optimized functionality that, if present, upcoming versions of the Controller will use. Thus, using PostgreSQL 15 or greater can significantly reduce the database load.
Before upgrading please take a backup of your database, this will make it possible to rollback to the previously installed version.
Upgrade in the following order to avoid downtime:
Agents no longer have the accounting flag, accounting is now by default activated and the old
root.vcl template without accounting support has been removed. This is one of the reasons the
Controller 7 requires at least version 6.0.8r2 of Varnish Enterprise.
The feature KeepOnFailure is now by default always used on the agents. Previously, the VCLGroup
could be configured with Keep On Failure that would keep the old VCL deployed if the new one failed
to be deployed. This is now always the case for agents.
-agent-stats-filter is replaced by: stats-filter-vclgroup-stats-filter is replaced by: -stats-filter, defined filters need to be
prefixed: with VBE.*..-accounting-stats-filter is replaced by: -stats-filter, defined filters need to
be prefixed: with ACCG.*.total..-accounting-stats-keys is replaced by -stats-filter, define the counters you
would like to track by your accounting key with the following prefix:
ACCG.*.<insert_your_key>.<your_counter_name>The -stats-filter matches on the whole accounting key and has support for wildcards, like the
previous statistics keys. Multiple wildcards in the same filter are supported.
Brainz now supports Git deployments. In order to use Git deployments the server brainz runs on
requires the git command and also network access to the outside world if the Git repo used is on a
remote host.
A lot of the file command has changed since it now handles files and file versions in a different
way than prior versions. We recommend to look at the examples given by vcli file -h. These
examples show how to test compile, create files and create new versions of files.
--dom has changed to --domains for vg add/update commands.--inc has changed to --includes for vg.Due to the change of how files and deployments are handled in version 7, the vg add/update command
no longer takes --vcl or --includes. These are instead part of the deploy, compile and
validate commands.
All existing configuration for files and the VCLGroup will be automatically migrated. No need for any manual action.
Previously, deployments (vcli deployments) were required to manage which servers a VCLGroup was
deployed to. This involved configuring tags along with min/max values and attaching them to the
VCLGroup to control to which agents that should apply the VCLGroup.
This mechanism has been completely removed and replaced by TagSets for more transparent and flexible control. Now, all agents that match the specified TagSets will automatically receive the VCLGroup deployment.
There is no longer a need to manage min/max agent counts. If you need more agents serving the VCLGroup, simply ensure they have the appropriate tags.
When upgrading to version 7.0.0, the Controller will automatically migrate all existing deployment configurations on VCLGroups to TagSets. No manual action or intervention is needed.
Certificates command has been changed in the VCLI. Previously the type was defined by a flag
--disk / --database, but is now a sub-command instead:
vcli cert database add --cert <path> --key <path>vcli cert disk add --cert <path> --key <path>cidr-to-tag has been removed and replaced by: cidrcidr-to-tag-csv has been removed and replaced by: cidr-csvasn-to-tag has been removed and replaced by: asnasn-to-tag-csv has been removed and replaced by: asn-csvgeolocation-to-tag has been removed and replaced by: geolocationgeolocation-to-tag-csv has been removed and replaced by: geolocation-csvIf you have automation or scripts interacting with the API, please verify that they are compatible with the latest changes.
## VCLGroups
POST /vclgroups
PUT /vclgroups/{id}
PUT /vclgroups/{id}/deploy
PUT /vclgroups/{id}/rollback
PUT /vclgroups/{id}/compile
## Files
POST /files/{id}/new
GET /files/{id}/versions
## License
GET /license/varnish-controller
## Deployments
POST /deployments
PUT /deployments
GET /deployments
For the invalidation object the key: monitoredAgents replaces the deprecated key:
agentsMonitoring:
[
{
"id": 1,
....
"monitoredAgents": []
}
]
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 recommend 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 MigrationVersion 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:
# Prior 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.
The staging functionality for VCLGroup’s has been removed. A staged VCLGroup will stay deployed but is converted to a regular VCLGroup, the Varnish Controller does not automatically delete the staged VCLGroup.
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-controller7/varnish-controller7-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.