Components validate that they run the same major and minor version as Brainz. All components (Brainz, API-GW, Agents, Routers, VCLI and UI server) must be upgraded to 7.6.0.
The database schema is migrated automatically when the first upgraded Brainz instance starts. Deployed VCLGroups stay deployed during the upgrade and Varnish keeps serving traffic while the controller components restart.
Starting with 7.6.0, files created by the agent, brainz and router are created with secure
permissions by default: files as 0640 and directories as 0770 with setgid, instead of
0644/0755.
Existing installations keep the legacy permissions. During the upgrade, components that already
exist are pinned to the legacy behavior through a per-component configuration override of the
secure-create-fs-perms flag, so an upgrade does not change any permissions. Only components
registered after the upgrade get the secure default.
To enable secure permissions on an existing component, remove the configuration override (or set
secure-create-fs-perms=true). For agents, make sure varnishd can read the agent-managed files:
the agent applies the group configured with secure-create-fs-group (default varnish) and must
itself be a member of that group. If the group cannot be resolved or the agent is not a member, the
agent falls back to legacy permissions and reports the reason on the flag. See
Secure File System Permissions.
The Controller UI is now served by a UI server that is a Varnish Controller component like any
other. The package and the binary keep their names (varnish-controller-ui), and an existing
installation keeps working: arguments that were renamed are translated automatically and logged, and
arguments whose feature is gone are accepted and ignored. The compatibility layer will be removed in
a future release, so update your configuration.
With -enable-nats, the UI server now receives TLS certificates and configuration from the
controller. See Graphical User Interface for
the full list of options and the new capabilities.
Renamed arguments. The old name still works and logs
WARNING: The flag "-<old>" has been renamed to "-<new>" ... at startup. If both the old and the
new name are given, the old one is ignored.
| Old argument | New argument | Notes |
|---|---|---|
-app-log-level |
-log |
The disabled level is now called quiet and the old name is not accepted, so a UI server configured with disabled fails to start. The default is warning instead of info. |
-app-static-path |
-static-path |
|
-app-index-file |
-index-file |
|
-app-compress |
-compress |
|
-app-cache |
-cache |
|
-app-request-log |
-request-log |
|
-http-read-timeout |
-read-timeout |
|
-http-write-timeout |
-write-timeout |
Raised automatically if it would expire before the API-GW can answer. |
-csp-rules |
-csp |
-csp now takes the policy itself, see below. |
-cors-allowed-origins |
-trusted-origins |
Merged with -csrf-trusted-origins into one allowlist. |
-csrf-trusted-origins |
-trusted-origins |
Merged with -cors-allowed-origins into one allowlist. |
-api-timeout |
-compile-timeout |
Shares the name and value used by brainz and the API-GW. |
-no-tls |
-secure-cookies |
Inverted: -no-tls becomes -secure-cookies=false. |
Removed arguments. They are accepted and ignored, with
WARNING: The flag "-<name>" has been DEPRECATED and is no longer used.
| Removed argument | Replacement |
|---|---|
-csrf |
None. Cross-site protection is always on and is now based on the Sec-Fetch-Site and Origin request headers instead of a token. It needs no configuration for same-origin requests. Allow other origins with -trusted-origins. |
-csrf-secret |
None, there is no CSRF token to sign. |
-csrf-cookie-ttl |
None, there is no CSRF cookie. |
-cookie-path |
None. The cookie path is fixed at /. |
-cookie-logged-in-name |
None. The cookie names (vc-logged-in, vc-at, vc-rt) are a fixed contract with the frontend. |
-cookie-access-name |
None, see above. |
-cookie-refresh-name |
None, see above. |
-hsts-max-age |
None. -hsts now sends a fixed max-age of one year. |
-idp-https-redirect |
None. HTTPS callback URLs have been the default since 7.0.1. |
Changed arguments. The name is the same but the meaning is not.
| Argument | Change |
|---|---|
-csp |
Was a boolean that switched the policy in -csp-rules on and off. It now takes the policy itself, and an empty value disables the header. -csp=true and -csp=false still work and log a warning: true means the default policy, false means no header. |
-x-frame-options |
Was a boolean. It now takes the header value, deny (the new default) or sameorigin. An empty value disables the header and leaves framing to the CSP frame-ancestors directive. true and false still work and log a warning. |
-tls, -cert, -key |
-tls now only asks for the local certificate files to be loaded. HTTPS is served on its own port, -https-port (default 8443), while the plain listener keeps running on -http-port. An installation that used -tls -http-port 443 must move the port: -tls -https-port 443. A missing or unusable certificate file is no longer fatal. |
-http-port |
Unchanged default (8080), but it is now always the plain HTTP port. |
Environment variables now use the Controller’s VARNISH_CONTROLLER_ prefix, e.g.
VARNISH_UI_SERVER_API_HOSTS becomes VARNISH_CONTROLLER_API_HOSTS. The VARNISH_UI_SERVER_
variables, including the old flag names, are still read as a fallback and log a warning naming the
variable to use instead.
-no-tls with -secure-cookies=false. The
Forbidden - origin invalid message is gone, a rejected request now answers
403 cross-origin request forbidden./var/lib/varnish-controller/varnish-controller-ui-server/ by default) must
be writable by the varnish-controller user, since the UI server persists the configuration it
receives there.vcli now refuses to talk to a UI server endpoint. If vcli was previously pointed at a UI
server that proxied the API, point it directly at an API-GW instead (default port 8002). It also
refuses an API-GW whose major or minor version differs from its own.This release updates the internal NATS serialization layer and agent/router subject format. All components (Brainz, API-GW, Agents, Routers, VCLI and UI) must be upgraded to 7.5.0 at the same time. Mixed versions will not be able to communicate.
VCLs are now loaded differently. Setting VMOD path is no longer supported. If you have custom VMOD path configurations, replace them with absolute paths before upgrading.
Starting with 7.5.0, the agent generates a traffic_router_health.vcl file that allows the Traffic
Router to probe agent health through Varnish using a JSON-based health check. This enables the
router to query health, utilization, and maintenance status in a single request per Varnish instance
instead of one request per domain.
Shared deployments include this file automatically, no action is required.
Root deployments require a manual change. Add the following include statement to your custom
VCL, before any subroutine definitions:
vcl 4.1;
include "traffic_router_health.vcl";
# Your existing VCL logic
include must appear before your vcl_recv definition. The health check handler uses return (pass) to exit early for probe requests. If your vcl_recv returns first, router health probes will not be handled correctly.
Without this include, the Traffic Router falls back to per-domain health probing (one HTTP request per domain per agent), which is less efficient and does not report utilization or maintenance status.
For full details, see Traffic Router Health VCL.
Before starting the upgraded router, make sure it has a upgraded Brainz instance available.
When the Router is started immediately after upgrade, it requires a running Brainz instance of the same version to fetch a new configuration from it.
From 7.3.0 onwards, the brainz base directory (usually
/var/lib/varnish-controller/varnish-controller-brainz/) needs to have write permission for brainz,
which usually runs under username varnish-controller.
If no permission changes to the directory have been made in the past, no further actions are necessary.
No write access for the brainz results in the log message failed to write component ID file ....
-no-tls is replaced by -secure-cookies=false and the Forbidden - origin invalid message no longer exists, see UI server arguments.
This 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-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.