Issue #1254: Allow varnish vcl template to be overridden through template inheritance

Author: oxyc

docs/configurations/webservers-nginx.md

@@ -45,7 +45,7 @@ If you are using Ubuntu as your base OS and you want to get started quickly with
 If you can't customize via variables because an option isn't exposed, you can override the template used to generate the the virtualhost configuration file.
 
 ```yaml
-nginx_vhost_template: "{{ config_dir }}/nginx-vhost.conf.j2"
+nginx_vhost_template: "{{ config_dir }}/templates/nginx-vhost.conf.j2"
 ```
 
 You can either copy and modify the provided `nginx-vhost.conf.j2` template, or extend it and and override the specific template block you need to change.

docs/extras/varnish.md

@@ -31,4 +31,32 @@ $settings['reverse_proxy_addresses'] = array('127.0.0.1');
 
 If you don't set these values, Drupal will think all requests are coming from `127.0.0.1`. There are other settings you can change to make Drupal not store copies of cached pages in the Database (since Varnish is caching everything, this is redundant), but those other settings are not covered here.
 
+### Extending the base `drupalvm.vcl.j2` template
+
+If you can't customize via variables because an option isn't exposed, you can extend the base `drupalvm.vcl.j2` through Jinja2 template inheritance.
+
+```yaml
+varnish_default_vcl_template_path: "{{ config_dir }}/templates/drupalvm.vcl.j2"
+```
+
+_If you extend Drupal VM's provided base template, the path referenced should to be relative to the playbook.yml._
+
+```
+{% extends 'templates/drupalvm.vcl.j2' %}
+
+{% block backend -%}
+{{ super() }}
+.connect_timeout = 1s;
+{% endblock %}
+
+{% block vcl_deliver -%}
+unset resp.http.X-Url;
+unset resp.http.X-Host;
+unset resp.http.Purge-Cache-Tags;
+# Do not set X-Varnish-Cache headers.
+{% endblock %}
+```
+
+The `{{ super() }}` Jinja2 function returns the original block content from the base template.
+
 For a list of available role variables, see the [`geerlingguy.varnish` Ansible role's README](https://github.com/geerlingguy/ansible-role-varnish#readme).

provisioning/templates/drupalvm.vcl.j2

@@ -1,21 +1,28 @@
+{% block version -%}
 vcl 4.0;
+{% endblock %}
 
 # This Varnish VCL has been adapted from the Four Kitchens VCL for Varnish 3.
 
 # Default backend definition. Points to Apache, normally.
 backend default {
+    {% block backend -%}
     .host = "{{ varnish_default_backend_host }}";
     .port = "{{ varnish_default_backend_port }}";
     .first_byte_timeout = 300s;
+    {% endblock %}
 }
 
 # Access control list for PURGE requests.
 acl purge {
+    {% block acl_purge -%}
     "127.0.0.1";
+    {% endblock %}
 }
 
 # Respond to incoming requests.
 sub vcl_recv {
+    {% block http_header -%}
     # Add an X-Forwarded-For header with the client IP address.
     if (req.restarts == 0) {
         if (req.http.X-Forwarded-For) {
@@ -25,15 +32,19 @@ sub vcl_recv {
             set req.http.X-Forwarded-For = client.ip;
         }
     }
+    {% endblock %}
 
+    {% block method_purge -%}
     # Only allow PURGE requests from IP addresses in the 'purge' ACL.
     if (req.method == "PURGE") {
         if (!client.ip ~ purge) {
             return (synth(405, "Not allowed."));
         }
         return (purge);
     }
+    {% endblock %}
 
+    {% block method_ban -%}
     # Only allow BAN requests from IP addresses in the 'purge' ACL.
     if (req.method == "BAN") {
         # Same ACL check as above:
@@ -53,12 +64,16 @@ sub vcl_recv {
         # Throw a synthetic page so the request won't go to the backend.
         return (synth(200, "Ban added."));
     }
+    {% endblock %}
 
+    {% block pass_post -%}
     # Only cache GET and HEAD requests (pass through POST requests).
     if (req.method != "GET" && req.method != "HEAD") {
         return (pass);
     }
+    {% endblock %}
 
+    {% block pass_admin -%}
     # Pass through any administrative or AJAX-related paths.
     if (req.url ~ "^/status\.php$" ||
         req.url ~ "^/update\.php$" ||
@@ -69,7 +84,9 @@ sub vcl_recv {
         req.url ~ "^.*/ahah/.*$") {
            return (pass);
     }
+    {% endblock %}
 
+    {% block cookies -%}
     # Removing cookies for static content so Varnish caches these files.
     if (req.url ~ "(?i)\.(pdf|asc|dat|txt|doc|xls|ppt|tgz|csv|png|gif|jpeg|jpg|ico|swf|css|js)(\?.*)?$") {
         unset req.http.Cookie;
@@ -106,10 +123,12 @@ sub vcl_recv {
             return (pass);
         }
     }
+    {% endblock %}
 }
 
 # Set a header to track a cache HITs and MISSes.
 sub vcl_deliver {
+    {% block vcl_deliver -%}
     # Remove ban-lurker friendly custom headers when delivering to client.
     unset resp.http.X-Url;
     unset resp.http.X-Host;
@@ -121,10 +140,12 @@ sub vcl_deliver {
     else {
         set resp.http.X-Varnish-Cache = "MISS";
     }
+    {% endblock %}
 }
 
 # Instruct Varnish what to do in the case of certain backend responses (beresp).
 sub vcl_backend_response {
+    {% block vcl_backend_response -%}
     # Set ban-lurker friendly custom headers.
     set beresp.http.X-Url = bereq.url;
     set beresp.http.X-Host = bereq.http.host;
@@ -150,4 +171,5 @@ sub vcl_backend_response {
 
     # Allow items to remain in cache up to 6 hours past their cache expiration.
     set beresp.grace = 6h;
+    {% endblock %}
 }