Cache tags + Varnish

Varnish Cache is a web application accelerator, also known as a caching HTTP reverse proxy. Varnish is used on thousands of Drupal sites to increase page load performance by 10-1000x, and it can be used with cache tags to simplify cache invalidation.

For basic cache tag integration, you need to do three things to ensure Varnish works well with the cache tags generated by Drupal:

• Update Varnish VCL to properly handle BAN requests.
• Send a cache tags header (e.g., X-Cache-Tags) with each request, containing a space-separated list of all cache tags for the page.
• Send a BAN request with the appropriate cache tags whenever content or configuration changes and cached pages with related tags must expire.

Updating Varnish VCL

The Symfony FOSHttpCache package has great documentation on the VCL changes needed to support cache tags, but here are the minimal required VCL changes to get started (for Varnish 4.x):

Inside vcl_recv:

sub vcl_recv {
    ...
    # Only allow BAN requests from IP addresses in the 'purge' ACL.
    if (req.method == "BAN") {
        # Same ACL check as above:
        if (!client.ip ~ purge) {
            return (synth(403, "Not allowed."));
        }

        # Logic for the ban, using the X-Cache-Tags header.
        if (req.http.X-Cache-Tags) {
            ban("obj.http.X-Cache-Tags ~ " + req.http.X-Cache-Tags);
        }
        else {
            return (synth(403, "X-Cache-Tags header missing."));
        }

        # Throw a synthetic page so the request won't go to the backend.
        return (synth(200, "Ban added."));
    }
}

Inside vcl_backend_response:

sub vcl_backend_response {
    # Set ban-lurker friendly custom headers.
    set beresp.http.X-Url = bereq.url;
    set beresp.http.X-Host = bereq.http.host;
    ...
}

Inside vcl_deliver:

sub vcl_deliver {
    # Remove ban-lurker friendly custom headers when delivering to client.
    unset resp.http.X-Url;
    unset resp.http.X-Host;
    # Comment these for easier Drupal cache tag debugging in development.
    unset resp.http.X-Cache-Tags;
    unset resp.http.X-Cache-Contexts;
    ...
}

Be sure to restart Varnish after making the necessary VCL changes!

Sending the Cache Tag Header

You can enable one of the following modules to make Drupal output an HTTP header containing cache tags:

Note that in versions prior to 8.x-3.0-beta5, the Purge module automatically configured the Purge-Cache-Tags header, but it was removed as this responsibility was moved to submodules instead.

Sending BAN Requests on Content or Configuration Changes

Using the Generic HTTP Purger module, go to the Purge configuration page (admin/config/development/performance/purge) and add an HTTP Purger.

Enter your Varnish server details (hostname, port, path, etc.) and under the "Headers" configuration, enter the following:

• Header: X-Cache-Tags
• Value: [invalidation:expression]

Once saved and with a cron job set to process the purge queue (drush p-queue-work), Varnish should begin banning pages as soon as the queue triggers the BANs!

Some notes in this documentation were adapted from the following sources:

• Using Drupal 8 Cache Tags with Varnish and Purge
• Add cache tag support to default Drupal VM Varnish config