Varnish Controller

Using Labels

Custom VCL Labels

This tutorial shows how to use custom labels for loaded VCL’s in Varnish using Varnish Controller. Note that a shared deployment cannot be used together with custom VCL labels, it must be a root deployed VCLGroup.

A root deployed VCLGroup means that the Varnish Controller will not generate any VCL, rather it will only load the user provided VCL’s from the VCLGroup. Hence, only one VCLGroup can be deployed to the servers that have a root deployed VCLGroup.

Prepare Environment

First we need to login, create a label and then label the agent (Varnish server) that we want to deploy the VCLGroup to.

# Login using your user
vcli login -u test

# Create a tag
vcli tag add prod

# Agent with ID 1 and tag with ID 1
vcli agents tag 1 -t 1

Create VCLs

This example uses one MainVCL that forwards all requests to the included VCL file. The included VCL is labeled with the label test.


vcl 4.1;
backend default none;

sub vcl_recv {
    return (vcl(test));

Included VCL:

vcl 4.1;

backend default none;

sub vcl_recv {
    return (synth(200, "In label VCL"));

Upload the VCL’s to Varnish Controller.

# Create the main VCL
vcli file add main.vcl /tmp/m.vcl

# Create the included VCL that will have a label (named "test")
# The label name is used in our main VCL: "return (vcl(test));"
vcli file add --label=test main2.vcl /tmp/m2.vcl

In the editor we can assign a label by clicking on the label button in the right corner.

image alt >

Deployment Configuration and VCLGroup

Create a deployment configuration and a VCLGroup. We don’t have to create a domain as we will deploy the VCLGroup as a root deployment.

# Add deployment configuration with tag ID 1
vcli dep add mydep -t 1

# Create the VCLGroup and mark it as root deployment (--root)
# Select our main vcl with ID 1 and our included (labeled) VCL with ID 2.
vcli vg add myvg --root=true --dep 1 --vcl 1 --inc 2

# Deploy the VCLGroup with ID 1
vcli vg deploy 1

That’s it! If we inspect our varnishadm vcl.list we can see that the agent has deployed our two VCL’s using labels:

available   auto/cold          0 temp_root_847376b41a3d5560846090ab4a6130a4f0ca2a4fb5dca8f10efe63b12b6efff2
available   auto/warm          0 vg1_488c5d74522cac6e62c784b9daae0eb4d9615287e3fe123829d5ed7e891e3040_1 (1 label)
available  label/warm          0 test -> vg1_488c5d74522cac6e62c784b9daae0eb4d9615287e3fe123829d5ed7e891e3040_1 (1 return(vcl))
active      auto/warm          0 vg1_eb2f9fe217b38622973dcf9f442fb171d16f3df0854545d349f446bb87b395bd_1

That’s it! If we navigate to Varnish Servers/Commands, then selecting the servers and inspect varnishadm vcl.list we can see that the agent has deployed our two VCL’s using labels:

image alt >