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.
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: cidr
cidr-to-tag-csv
has been removed and replaced by: cidr-csv
asn-to-tag
has been removed and replaced by: asn
asn-to-tag-csv
has been removed and replaced by: asn-csv
geolocation-to-tag
has been removed and replaced by: geolocation
geolocation-to-tag-csv
has been removed and replaced by: geolocation-csv
If 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}/stats
Before 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.com
example.com:8080
:8080
If 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.