Search

Upgrading

Upgrading

From 6.* to 7.0.0

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:

  1. Upgrade Brainz, API-GW, VCLI, UI and NATS
  2. Agents will terminate. Upgrade them and make sure they restart.
  3. Upgrade Traffic Routers (make sure they restart)

General

  • Varnish Enterprise Version ≥6.0.8r2 is required for version 7 of the Controller.
  • VCLGroups no longer depends on each other via files. Each VCLGroup must be deployed individually.

Agents

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.

  • Argument: -agent-stats-filter is replaced by: stats-filter
  • Argument: -vclgroup-stats-filter is replaced by: -stats-filter, defined filters need to be prefixed: with VBE.*..
  • Argument: -accounting-stats-filter is replaced by: -stats-filter, defined filters need to be prefixed: with ACCG.*.total..
  • Argument: -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

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.

VCLI Changes

Files

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.

Deployments

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

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>

VCLI Removals (Deprecations)

  • Flag: cidr-to-tag has been removed and replaced by: cidr
  • Flag: cidr-to-tag-csv has been removed and replaced by: cidr-csv
  • Flag: asn-to-tag has been removed and replaced by: asn
  • Flag: asn-to-tag-csv has been removed and replaced by: asn-csv
  • Flag: geolocation-to-tag has been removed and replaced by: geolocation
  • Flag: geolocation-to-tag-csv has been removed and replaced by: geolocation-csv

API Endpoint Changes

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": []
 }
]

From 5.* to 6.0.0

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.

Upgrade Path

We recommend to upgrade in the following order, to avoid downtime:

  1. Upgrade brainz, api-gw, vcli, UI and NATS
  2. Agents will terminate. Upgrade them and make sure they restart.
  3. Upgrade Traffic Routers (make sure they restart)

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.

Routing Rules tags Migration

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:

# 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

Permissions

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.

HTTP Routing Headers

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.

General

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.

API Changes

  • Statistics JSON data has been lower cased to match other JSON data via the REST API.
  • ErrorKey has been removed from the error responses.
  • All 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

From 4.* to 5.0.0

Before upgrading please take a backup of your database, this will make it possible to rollback to the previously installed version.

General

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.

Components

Agent

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

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.

Router

No changes required after upgrading

VCLI

  • All vcli vcl * commands have been removed, you can use the same command but instead of vcli vcls use vcli files.
  • The JSON output has been improved but might be different from the previous output.
  • The vcli inspect <command> now always outputs an array, even for results with one object where as previously it just returned the object.
  • The vcli <command> update now only return the changed element.
  • Commands perm, account, idp and org lists all entries after delete.
  • Delete no longer fails if there are no elements left to list.
  • Confirmation added for org update, tag update and perm add to avoid mistakes.
  • vcli org update now supports -y to avoid interactive confirmation.
  • Removed -idp flag from org add as the org needs to be created before adding an IDP to an org.
  • Removed -v from session (was showing same output).
  • Improved error handling when requesting json output, all errors are now shown in JSON format.

API-GW

  • All /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.
  • The /api/v1/agents/1/vclgroups endpoint has been removed, use /api/v1/vclgroups?agents.id=1&vg_states.deployed=true instead.
  • The /api/v1/tags/1/agents endpoint has been removed, use /api/v1/agents?tags.id=1 instead.
  • The /api/v1/vclgroups/1/agents endpoint has been removed, use /api/v1/agents?vcl_groups.id=1&vg_states.deployed=true instead.
  • The operator=and has been removed from the filters, instead of ?tags.id=1,2&operator=and use ?tags.id[all]=1,2.
  • In the VCLGroup response deployed: true/false has been changed to a deployment state deployState: 1/2/3.
    • 1 - Deployed (Deployed)
    • 2 - Deploying (Currently deploying)
    • 3 - Undeployed (Not deployed)

From 4.0 to 4.1

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.

From 3.0.* to 4.0.0

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:

  • To override the host example.com
  • To override the host and port example.com:8080
  • To only override the port :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 ..

From 2.0.* to 3.0.0

There are 2 important changes to be aware of:

  1. Persistent statistics could grow your database significantly depending on the amount of agents, VCLGroups and counters to keep track of.
  2. When using a configuration file, the scopes are renamed:
    • [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.

From 1.0.4 to 2.0.0

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.


®Varnish Software, Wallingatan 12, 111 60 Stockholm, Organization nr. 556805-6203