SearchVarnish Controller
VCLGroups can be seen as a way of grouping VCL files, other files, deployments and domains. It’s the VCLGroup that is being deployed to one
or more agents. The VCLGroup consists of a MainVCL, Includes, Domains and Deployments.
The VCLGroup is created after VCL, Domain and a Deployment have been created. When all these parts are stitched together into a VCLGroup, the VCLGroup can be deployed. Deploying a VCLGroup tells the system that we want it to be deployed to agents.
Includes can be empty. But if the MainVCL is using include statements, these included files need to be added to the Includes of the
VCLGroup. Any other files used by the VCL can also be added to the Includes.
From version 6.0.12r2 of Varnish Enterprise,vmod_utils supports a function called lookup_file()
that can be used to find files in the vcl_path. The controller agent will load the VCL with a VCLGroup unique path set in the parameter vcl_path. Hence, using the lookup_file(), this path can be
found and used to find files that has been included via the “includes” of the VCLGroup. This can be useful for reading some ACL files or other none-VCL files.
Even if a VCLGroup is marked as deployed, it doesn’t mean that it’s actually deployed to agents. It only tells the system that the VCLGroup should be deployed, if possible. The deployments for the VCLGroup specify the current state of the deployment to servers. If multiple deployments are assigned to a VCLGroup, these deployments can have different states depending on their configuration and matching agents. This means that a deployed VCLGroup might not be deployed to any agents, if there are no agents matching any of the deployments tags.
Reloading a VCLGroup triggers a re-compilation of the VCL files for that VCLGroup in all agents. This could be used to reload DNS lookups that are used in the VCL files.
Note: Deprecated in 6.0.0
A VCLGroup can be staged. Staging an existing VCLGroup means that we want to test a new set of VCL files before deploying to the real VCLGroup. When staging a VCLGroup, the system will automatically create a new VCLGroup and a deployment that uses the new set of VCL files, and then deploy with either the same or a new domain to the agents matching the staging tags. Once the staged VCLGroup has been tested it can be promoted to production. Promoting a VCLGroup replaces the currently used VCL files to the staged VCL files and becomes deployed. The staged VCLGroup and deployment that were automatically created by the system will be removed by the system on successful deployment.
The staging functionality can be achieved manually using the API. It’s a helper functionality to make it easier for the user.
When replacing your MainVCL or Includes or editing a VCL / file your changes are put in a draft state. A manual deployment needs to be run to apply your changes to the agents. There are features in the CLI and UI to view the difference between your draft state and the deployed version. The API returns the draft state when querying for a single VCL or file. The VCL’s and files have a changed state if there are pending changes or a state new if it has never been deployed. We keep track of 1 draft version.
Before a deployment takes place a snapshot is created of the currently deployed VCL’s and files in the VCLGroup. This gives the option to do a quick rollback in case of a mistake. On a rollback the VCL’s and files to rollback are put in a draft state and the previously deployed source is deployed. The VCL’s and files will get a rolled back state indicating that they are rolled back, if a file no longer exists the rollback will re-create the file with a state created at rollback. We keep track of 1 snapshot per VCLGroup.
A VCLGroup contains so-called error states. These are errors that occurred during deployment to agents. It could include error(s) to one or more agents if something went wrong with either all or just a few agents (compilation errors, missing vmods, etc). The errors are cleared once the VCLGroup is reloaded, redeployed or updated.
VGState, or VCLGroup States, keeps the current states of the deployments. This can vary depending on failover between agents.