SearchA VCLGroup is a container of configuration that defines what and how to deploy VCL files and how to route requests via the request router. Each VCLGroup is deployed independently with its own file versions. This allows precise control, efficient deployments, and rollbacks that affect only the targeted VCLGroup.
The VCLGroup can no longer be assigned files directly via creation or modification. The files used by a VCLGroup are only applied once they have been validated and successfully compiled via deployment of the VCLGroup. Hence, the VCLGroup only contains configuration for how to deploy it. Routingrules, domains and deployment type remains the same.
A VCLGroup configuration consists of:
Note that RoutingRules is optional and are only used if the VCLGroup should be used with the
Request Router. Same goes with the GitConfig that is only used if the VCLGroup should be managed
by Git.
The domains specified in the VCLGroup will be the ones handled by Varnish if the VCLGroup is deployed as a shared deployment (default). The VCL files deployed for this VCLGroup will then get all requests for these domains. These domains are also used for request routing when the Request Router is in use. Similarly, during invalidation via the Controller, these domains are targeted for invalidation.
Tag-Sets define where a VCLGroup should be deployed (previously called deployments). A tag-set is an array of tags, and multiple tag-sets can be specified. For deployment, all tags in a tag-set must match the tags on an agent. If agents have different tag combinations, multiple tag-sets are needed to match and deploy the VCLGroup to all desired agents.
Example:
VCLGroup.TagSets: [x,y], [x,z]
Agent1: [x,z]
Agent2: [x,y,q]
Agent3: [x,y]
The TagSet consists of 2 set of tags, [x,y] and [x,z]. The first set [x,y] will match agents
Agent2 and Agent3. The second set [x,z] will match Agent1. So both sets will therefore match all
agents in the example and the VCLGroup will be deployed to all of them.
A root deployment is a deployment of only one VCLGroup toward an agent, that is, one VCL loaded into Varnish. The deployed VCLGroup will be responsible for domain routing. This is basically deploying one single VCL into Varnish.
When deploying a VCLGroup as a root deployment, the agent will not accept any other deployments to that agent. This means that any other VCLGroups that potentially could be deployed to the same agent will not validate successfully.
The default way of deploying a VCLGroup is a none-root deployment, also known as shared/cloud deployment. This type of deployment shares a Varnish between multiple VCLGroups with different domains. The domain routing is handled automatically and for each request, the host is matched to the corresponding domain and routed to the correct VCLGroups VCL.
The track latest feature makes the VCLGroup automatically compile/validate and deploy the latest version of any given file. This also applies to Git managed VCLGroups. The Controller will automatically check for a new version or a new git commit and then validate on one random matching server, to make sure that the files compile correctly. Then deploy the latest versions. If it fails, the status can be seen in the Deploy Status for a VCLGroup. If it fails, the old deployed files will still be deployed.
Note that if this is enabled for a VCLGroup, as soon as a new commit or a new file version is created, it will directly try to deploy it.
Routingrules is used to define how to route to the domains of the VCLGroup. See Routing Rules. Also take a look at the examples for request routing found here.
A VCLGroup is deployed with one or more files. These are deployed onto the Varnish servers via the Controller agent. The files are then loaded into varnish for the given VCLGroup.
This file must be valid VCL. The MainVCL handles all requests for the VCLGroup and is compiled and loaded into the Varnish server.
Includes can be empty. But if the MainVCL is using include statements, these included files need
to be added to the Includes field of the VCLGroup. Any other files used by the VCL can also be
added to the Includes field.
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.
A VCLGroup can be deployed using a deploy-configuration that consists of:
All, Random or Agents (on which servers to validate the deployment)agents. These agents will be used to
verify the deployment, they must have matching tags.A deployment is applied to a VCLGroup only if it validates and compiles successfully. If the
Random method is used (default), a random matching agent is selected to compile the VCL files. If
All is used, all matching agents will compile the VCL files. This runs in parallel but may take
longer depending on agent server load. If Agents is specified with a list of agents, compilation
occurs only on those agents, provided the VCLGroup matches their tags.
Example of a deploying with detached:
# Deploy an existing VG with ID 1 (will return immediately)
vcli vg deploy 1 --vcl 1 -d
# Check compile status
vcli vg status 1
# Check deployment state on agents (available when the compile succeeded)
vcli vg state 1
# Verify/Compile on a given set of agents (specified with IDs)
# This will NOT deploy, only compile given files.
# --vcl: MainVCL with ID 1 and version 2
# --includes: File with ID 2 (latest versions) and file with ID 3 and version 1
# --validate: on agents with ID 1,2,3 (only matching agents will be used of the given ones)
vcli vg compile 1 --vcl 1:2 --includes 2,3:1 --validate agents=1,2,3
# Same as above but only compile on a random matching agent (default)
vcli vg compile 1 --vcl 1:2 --includes 2,3:1 --validate random
# Same as above but compile on ALL matching agents
vcli vg compile 1 --vcl 1:2 --includes 2,3:1 --validate all
# Compile can be exchanged with deploy, where an actual deploy will be made
# if the validation/compilation succeeds.
vcli vg deploy 1 --vcl 1:2 --includes 2,3:1 --validate agents=1,2,3
vcli vg deploy 1 --vcl 1:2 --includes 2,3:1 --validate random
vcli vg deploy 1 --vcl 1:2 --includes 2,3:1 --validate all
A successful deployment of a VCLGroup sets the deployed files as the MainVCL and Includes for
that VCLGroup. These are updated only through a deploy or rollback and cannot be manually modified.
If a VCLGroups is undeployed and deployed again, it will use the same files as previously deployed.
# Undeploy a deployed VCLGroup
vcli vg undeploy 1
# Redeploy the VCLGroup with last deployed files.
# A compilation/validation will be made beforehand on a random matching agent.
vcli vg deploy 1
Reloading a VCLGroup triggers re-compilation of its VCL files on all agents where it is deployed. This can be used to refresh things like DNS lookups defined in the VCL files.
Agent states of a VCLGroup show the current status for each agent it can be deployed to. To view deployment details for a specific Varnish server, check the agent states of the VCLGroup.This displays the deployment status for that server and any errors that may have occurred.
Rollback of a VCLGroup only applies to the files that has been deployed for the VCLGroup. Every time a VCLGroup is successfully deployed a deploy log entry will be created for the VCLGroup that specifies which files and versions that are currently deployed. The rollback will basically take the previous deploy log entry and apply these files back to the VCLGroup. The Controller will before re-applying the previous deployment verify that it can still be deployed and will compile/validate the files on a random matching server before deploying to all matching servers. A rollback will also create a deploy log entry with the deployed files.
A deploy log contains the MainVCL and includes that where used when the VCLGroup was successfully deployed. It also contains a created timestamp to show when the deploy log was created (hence, when the deployment were successfully performed). Deploy logs are tied to a certain VCLGroup.
A rollback can be performed on any deploy log entry for the VCLGroup. When performing a rollback the ID of the deploy log entry can be specified to rollback to that specific deploy log entry.
# List deploy log entries for a VCLGroup with ID 1
vcli vg deploylogs 1
# Rollback a deployed VCLGroup with ID 1 to the previous deployed files.
vcli vg rollback 1
# Rollback a deployed VCLGroup with ID 1 to the deploy log entry with ID 2
vcli vg rollback 1 -l 2
# Remove a old deploy log entry with ID's 1, 2 and 3 for VCLGroup 1
vcli vg deploylogs 1 -d 1,2,3