Deploying VCL files

Creating tags

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.

“Screenshot of the ‘Tags’ page, showing a section for creating a new tag and a list of existing tags.”

Tagging agents

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.

The tags will be reset with the tag command. So if you are using multiple tags you always need to specify all tags for the agent.

$ 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.

Screenshot of the ‘Servers’ page. The mentioned ‘Select tag(s)’ is below ‘Server Tags’ in the first white box.

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.

Screenshot of the ‘Servers’ page again. It now shows a dialogue with available and selected tags.

When the changes are applied you will see a green notification and the tag will be visible before the Add more tags button.

Screenshot of the ‘Servers’ page, showing that the previously selected tag is now in the list of assigned tags.

Adding domains

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.

Screenshot of the ‘Domains’ page. It has a section to enter a new domain name. To illustrate its purpose, ’example.com’ is entered in the input box for the new domain name.

Adding VCL files

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.

Screenshot of the Editor page. The ‘hamburger’ menu is opened, and the ‘Add new file’ entry is highlighted

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.

Creating & deploying a VCLGroup

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) |
+----+------+-------+----------+----------------+-----------+--------------+-------+---------------+---------+----------+----------------+-------------+----------------+---------+

Deploying a VCLGroup

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 tag group 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.

Select from certificates
- This let’s you pick only matching domains from a certificate of your choosing
Select domains
- Select by all available domains created in the controller
Create domains
- Create a new domain (or multiple)

When tags and domains are specified, save the VCLGroup.

image alt >

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.

image alt >

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.

image alt >

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).

image alt >

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.