Blue background with pattern

Magento 2 × Varnish: Architecting the Future of Caching Together

Improving Varnish Integration
Peter Jaap Blaakmeer Orange dot 26-05-2025

On May 22nd and 23rd 2025, the Varnish Taskforce gathered for two full-day, in-person deep dives into the Varnish Cache and Magento 2 integration. Organized by elgentos and hosted at the Phpro (Xplore Group) offices, the event brought together a small group of Magento developers, Varnish experts, devops engineers and hosting experts with a shared mission: improve the Varnish integration and the VCL for Magento 2.

On Thursday morning we started with an overview by Thijs Feryn to do a quick catch-up on what the Varnish built-in VCL does and an overview of Varnish's Finite State Machine.

Thijs Feryn Varnish doing a presentation about the builtin VCL

After this, we went line-by-line through an optimized VCL that has been put together from various Github PR's and brainstormed improvements. These improvements were transformed into tasks.

After a great lunch provided by Phpro (a big thank you!), these tasks were picked up in the afternoon by the individual developers. No high-level fluff—just real-world coding, config tweaks, and high-throughput performance testing.

The second day, we re-convened and spent time on adding the Magento 2 logic. We first did this by creating the elgentos/magento2-varnish-extended extension, in which we put all the logic to dynamically build a VCL file using several new configuration fields in the backend. We aim to port this code to a Magento 2 and a Mage-OS pull request so these features can be implemented in the mainline.

A small overview:

  • Our goal is to reduce the VCL in size to make it easier to understand and to fall back on the built-in VCL as much as possible
  • Parts of the VCL that deal with old vulnerabilities (like Httpoxy), old technology (like X-Pool for Capistrano) or old headers (like Pragma) are removed
  • Parts of the VCL that take responsibility for configurations that shouldn't be the VCL's responsibility (but the host's or the developer's responsibility) are removed (like configuring passes using URL's)
  • The health probe stays enabled since we use it to set the lower grace period on a healthy backend
  • We lowered the default grace period on backend responses from 3 days to 1 day
  • We assume the Xkey vmod is installed so we can enable soft-purging
  • We discourage debugging Varnish through the frontend by removing publicly visible headers, except for the X-Magento-Cache-Debug header (in order to historically track hit ratios through RUM data)
  • We created a new VCL generator with extended template features (if/else and foreach syntax)
  • We updated the varnish:vcl:generate command to be able to use configured values from the database, and added more parameters
  • We added more comments to the VCL to make developers understand the choices that have been made better
  • We created a bunch of tests in Varnish Testing Language (VTL) to test the VCL
  • We allow cache purge via Ctrl-Shift-R or Cmd-Shift-R for IP's in purge ACL list
  • Added admin notification in Magento after clearing cache to show number of purged objects
  • We add more configuration options in the backend to give more control over the generated VCLMade marketing parameters configurable (and added warnings for possible misconfiguration)Enable/disable back/forward-cache (default enabled)Enable/disable static file caching in Varnish (default enabled)Enable/disable media file caching in Varnish (default enabled)Enable/disable Xkey support in Varnish (default enabled)Choose between softpurging and hardpuging using Xkey (default softpurging)Allow passing of request based on found cookies (to support Xdebug or headless CMS previews)

What made these days stand out wasn’t just the technical depth, but the collaborative energy: everyone came with hard questions, sharp answers and we ended up with a far better VCL than before, and lots of work in motion for further improving the Varnish implementation in Magento.

Thank you to all the attendees for coming;