First we need to create some tags, with tags we specify where we want our VCL to be deployed. We
will create a production tag named prod
.
In the CLI we can create tags with the tags add
command. You will see the created tag as an
output. Remember the tag ID, we will use that in the next step.
$ vcli tags add prod
+----+------+--------+----------------+---------+
| ID | Name | Static | Organization | Creator |
+----+------+--------+----------------+---------+
| 1 | prod | false | [System Admin] | test(1) |
+----+------+--------+----------------+---------+
We create a tag at the Tags
page. You can also create tags when tagging an
agent.
After we created our tags, we can now tag our agents.
We can see our running agents with the command agents ls
, we need to list the agents to see the
agent IDs.
$ vcli agents ls
+----+---------+----------+---------------+--------------+-----------------+------+
| ID | Name | State | Varnish Host | Varnish Port | Varnish Version | Tags |
+----+---------+----------+---------------+--------------+-----------------+------+
| 1 | server3 | Running | 172.25.255.53 | 8083 | plus-6.0.7r1 | |
| 2 | server1 | Running | 172.25.255.50 | 8081 | plus-6.0.7r1 | |
| 3 | server4 | ReadOnly | 172.25.255.55 | 8084 | plus-6.0.7r1 | |
| 4 | server2 | Running | 172.25.255.51 | 8082 | plus-6.0.7r1 | |
+----+---------+----------+---------------+--------------+-----------------+------+
Now we can tag the agent that we want by using the agent tag
command. The first parameter is the
agent ID, the second parameter after --tags
are the tag IDs separated by commas if you want to use
multiple tags for an agent. There will be a question if you are sure you want to tag this agent, as
it might effect existing VCLGroup configurations.
$ vcli agents tag 1 --tags 1
Changing tags for an agent could result in VCLGroups being undeployed, are you sure? (y/N): y
+----+---------+----------+---------------+--------------+-----------------+---------+
| ID | Name | State | Varnish Host | Varnish Port | Varnish Version | Tags |
+----+---------+----------+---------------+--------------+-----------------+---------+
| 1 | server3 | Running | 172.25.255.53 | 8083 | plus-6.0.7r1 | (1)prod |
| 2 | server1 | Running | 172.25.255.50 | 8081 | plus-6.0.7r1 | |
| 3 | server4 | ReadOnly | 172.25.255.55 | 8084 | plus-6.0.7r1 | |
| 4 | server2 | Running | 172.25.255.51 | 8082 | plus-6.0.7r1 | |
+----+---------+----------+---------------+--------------+-----------------+---------+
We go to the Servers
page, there we click on the server we want to tag.
Click on Select tag(s)
. A modal will appear with the tag you just created, click on it and click
Apply
. In this modal you can create tags as well.
When the changes are applied you will see a green notification and the tag will be visible before
the Add more tags
button.
We need to add the domains that our site will be available at.
In the CLI we use the domains add
command. Remember the domain ID, we need that later on.
$ vcli domains add example.org
+----+-------------+----------------+---------+
| ID | FQDN | Organization | Creator |
+----+-------------+----------------+---------+
| 1 | example.org | [System Admin] | test(1) |
+----+-------------+----------------+---------+
We go to the Domains
page to create a domain. Click Create Domain
, add the FQDN in the field (you can add multiple at once by separating them with space, comma or enter) and click the Create button. The domain is now created.
Next we need to add a VCL file, we will use a very simple VCL file. This VCL file needs to be configured to your specific needs, for some VCL information please refer to our developer portal.
vcl 4.1;
backend default {
.host = "127.0.0.1";
.port = "80";
}
sub vcl_recv {
if (req.url == "/varnish-ping") {
return(synth(200));
}
if (req.url == "/varnish-ready") {
return(synth(200));
}
}
Adding a VCL with the CLI is pretty easy. The first parameter is the name of the VCL that you wish
to use in the Varnish Controller, in this case test.vcl
. The second parameter is the path to a
file on your system or the VCL source. Remember the ID of the file as we need it later.
$ vcli file add test.vcl ./example.vcl
+---------+---------+-----------+-------+-----+----------+-------------+---------------------+----------------+---------+
| File ID | Version | Name | Label | Dir | Git Hash | Description | Created | Organization | Creator |
+---------+---------+-----------+-------+-----+----------+-------------+---------------------+----------------+---------+
| 1 | 1 | test.vcl | | | | New version | 2025-03-19 10:35:55 | [System Admin] | test(1) |
+---------+---------+-----------+-------+-----+----------+-------------+---------------------+----------------+---------+
We go to the Editor
. click the hamburger
icon next to the search
icon, and press Add new file
Enter the name of the file you want to create and press enter.
Now you can add the contents of your VCL, at the top right there is a save button. You can also save
by right-clicking the file, and press save from the popup-menu, or use one of the pre-defined
shortcuts found under the hamburger
menu.
Now you can add the contents of your VCL, at the top right there is a save button. You can also save
by right-clicking the file, and press save from the popup-menu, or use one of the pre-defined
shortcuts found under the hamburger
menu. Every time you save a file, a new version is created,
you can give these version description in the input field or leave it blank.
We are almost ready to have our VCL running on Varnish. Creating a VCLGroup is an important step as it defines where your VCL runs, on how many agents and for what domains.
We need to create the VCLGroup, we will call it test
. The first parameter is the name test
. The
third parameter is the domain we created previously, you can specify multiple domains separated by a
comma.
$ vcli vg add test --tags name=prod --domains 1
+----+------+-------+----------+----------------+-----------+--------------+-------+---------------+---------+----------+----------------+-------------+----------------+---------+
| ID | Name | Root | Deployed | Total Deployed | Tags | Track Latest | Git | Last Deployed | MainVCL | Includes | Domains | RoutingRule | Organization | Creator |
+----+------+-------+----------+----------------+-----------+--------------+-------+---------------+---------+----------+----------------+-------------+----------------+---------+
| 1 | test | false | false | | [prod(1)] | false | false | N/A | [empty] | [empty] | (1)example.org | | [System Admin] | test(1) |
+----+------+-------+----------+----------------+-----------+--------------+-------+---------------+---------+----------+----------------+-------------+----------------+---------+
We will use the following command to start the deployment of your VCLGroup.
# Deploy will first compile and if that succeeds, the VCLGroup will start to deploy on agents.
$ vcli vg deploy 1 --vcl 1
Compiled on the following agents:
+-------------+----------+-----------------+----------+--------------+---------+-------+-----------+
| VCLGroup ID | Agent ID | MainVCL | Includes | Compile Time | Status | Error | Timestamp |
+-------------+----------+-----------------+----------+--------------+---------+-------+-----------+
| 1 | 1 | (1)test1.vcl[1] | | 832.752273ms | success | | |
+-------------+----------+-----------------+----------+--------------+---------+-------+-----------+
# Show the deployment status
$ vcli vg ls
+----+------+-------+----------+----------------+-----------+--------------+-------+---------------------+-----------------+----------+----------------+-------------+----------------+---------+
| ID | Name | Root | Deployed | Total Deployed | Tags | Track Latest | Git | Last Deployed | MainVCL | Includes | Domains | RoutingRule | Organization | Creator |
+----+------+-------+----------+----------------+-----------+--------------+-------+---------------------+-----------------+----------+----------------+-------------+----------------+---------+
| 1 | test | false | true | 1/1 (100%) | [prod(1)] | false | false | 2025-03-19 10:46:33 | (1)test1.vcl[1] | [empty] | (1)example.org | | [System Admin] | test(1) |
+----+------+-------+----------+----------------+-----------+--------------+-------+---------------------+-----------------+----------+----------------+-------------+----------------+---------+
# It's also possible to see the actual state per agent.
$ vcli vg state 1
+----------+-----------+----------+-------+-------------+------------+---------+---------------------+----------------+---------+
| VCLGroup | Agent | Deployed | Error | Last Failed | Last Retry | Retries | DeployedAt | Organization | Creator |
+----------+-----------+----------+-------+-------------+------------+---------+---------------------+----------------+---------+
| (1)test | (1)agent2 | true | | N/A | N/A | 0 | 2025-03-19 10:46:33 | [System Admin] | test(1) |
+----------+-----------+----------+-------+-------------+------------+---------+---------------------+----------------+---------+
You have now successfully deployed your VCL file with the Varnish Controller.
Go to the Configurations
page and click the create button. You will be presented with the
configuration screen of a VCLGroup. Here we are using the newly created domain and tag to define our
configuration. Add a taggroup with the newly created tag prod
, if the server is correctly tagged
you should see a 1
right above the server icon. You can view the matching servers of this tag/tags
by clicking that icon.
Add the domain you created by clicking the button Add domains
, here you will get three options.
When tags and domains are specified, save the VCLGroup.
The next step is to deploy files. Proceed by clicking the tab at the top the page Deploy & Compile
. Here you can select to either deploy via files managed by the controller (like the one we
just created), or use a git repository as source. For this example we will use the option Manual
.
Select your vcl by clicking the file tree with the chevron icon, and use the option
Select VCL File
, in the modal that will appear select your newly created file.
After a file has been selected, we will try to detect all your includes that might exist in the VCL file and automatically include them for the deployment. In this example our VCL don’t use any includes. By clicking the file you will get an option to specify what version you want to deploy, in this case we use the latest (2).
At the end your configuration you can click on the Deploy
button. This will deploy your files to
the agent that we tagged before.
You have now successfully deployed your VCL file with the Varnish Controller.