First time writing a blog in a million years, kinda nervous. This post grew out of a recent collaboration with some remote colleagues where I was introduced to our new easy way of configuring clustering. I had to try it out for myself and now I just have to share it with you!
Before we dive in, a very brief review: clustering isn’t exactly "new" to Varnish, but it is essential. If you have more than one Varnish node, clustering allows them to act as a unified team. This means you can handle more requests with fewer trips to the origin, achieve higher hit ratios, and manage traffic spikes more smoothly.
Simply adding nodes isn't enough, though. If every node fetches the same data, you just end up putting massive pressure on your origin. To solve this, we introduced sharding which essentially routes requests for the same object to the same node every time:
My colleague Guillaume explains in his post about the Importance and Ease of Sharding Your Cache (that’s where I got the chart above); sharding ensures the origin only receives one request per object, and each cache only needs to store a fraction of the total data set.
Clustering is generally enabled by including cluster.vcl into your main.vcl. The cluster.vcl handles the self-routing logic for you, so you don't have to manually tweak your VCL for request hashing, which is great.
However, even with cluster.vcl handling all the internal routing logic, you still have to explain which nodes are in the cluster. If a node's IP changed or you wanted to scale out, you had to manually update your VCL. The code snippet below is an example of how to set up a dynamic cluster which is what cluster_auto_dns.vcl aims to replace:
So we finally come into the following solution:
Finally, the “new easy way” I mentioned. We’ve introduced cluster_auto_dns.vcl. This wraps cluster.vcl and allows easy configuration by reading VARNISH_CLUSTER_* environment variables. Now, your VCL stays clean and simple. With this, you can simply have the following in your VCL:
With that in place, you will only need to set two variables, for example using systemd and a drop-in file:
(Further details)
While we currently talk about cluster_auto_dns.vcl in Varnish Enterprise, I would like to just briefly introduce the topic of clustering with Varnish Helm, since we have also seen quite an improvement in its simplicity now.
For those using the Varnish Helm Chart within Kubernetes, enabling clustering can now be done by setting cluster.enabled: true in your values.yaml configuration:
The full values.yaml file can look like this below. Without going into the detailed code, note that you do not need to include additional VCL code, set a token, or specify a DNS name, since enabling cluster already handles these configurations.
Once applied, you can verify the cluster is active by checking services:
If cluster is indeed enabled, there would be varnish-enterprise-peers service:
You’re almost there! At this point, you are done with the heavy-lifting of setting up clustering, at least cluster_auto_dns.vcl or cluster.enabled: true did that for you. Whether you have clustering in the “regular” way or through Varnish Helm Chart, you can verify further by checking varnishstat to see if cluster-related metrics are present. You can run something like this command:
If everything is working correctly, you'll see counters related to your cluster.
Setting up a high-performance cluster traditionally involved some manual configuration. What we have seen now with cluster_auto_dns.vcl (or cluster.enabled: true for Varnish Helm) represents a significant improvement in managing clustering with Varnish. The overall goal remains consistent: to enable clustering to effectively coordinate when you have multiple Varnish nodes.
That is it! I sincerely hope this blog post helps you get started smoothly. If you have any questions or need a hand with your specific setup, don't hesitate to reach out to us at support@varnish-software.com.