Git Interface

Varnish Cache

Learn how to use the Varnish Cache module.

Deploy

Follow the steps below to deploy the Varnish Cache module to your environment:

Go to the Git config of the environment you want to deploy the Varnish Cache module in.
In the top of the page, copy the URL next to Clone with HTTPS.
Open a terminal and change the current working directory to the location where you want the cloned environment repository.
Clone the environment repository to your local computer. Type git clone followed by the copied URL and then press Enter:
```
git clone <copied_url>
```
In the root directory of the environment repository, create a new directory for the module to reside in, such as varnish.
note
More than one of the same module can be added to an environment by using unique directory names.
In the new module directory, create a new file named proxy-features.json with the required parameters:
varnish/proxy-features.json
```
{
    "parameter/pipe_timeout": 125,
    "parameter/http_max_hdr": 128,
    "statics-enable-caching": "6h"
}
```

In the new directory, create a new file named default.vcl with at least the following:

varnish/default.vcl
vcl 4.0;

backend default {
    .host = "next-hop";
    .port = "80";
}

# Add your default VCL.

Alternatively, get started with the following template:

varnish/default.vcl
# This is an extension on the default VCL that CloudFlow has created to get
# you up and running with Varnish.
#
# Please note: There is an underlying default Varnish behavior that occurs after the VCL logic
# you see below. You can see the builtin code here
# https://github.com/varnishcache/varnish-cache/blob/5.2/bin/varnishd/builtin.vcl
#
# See the VCL chapters in the Users Guide at https://www.varnish-cache.org/docs/
# and http://varnish-cache.org/trac/wiki/VCLExamples for more examples.

# Marker to tell the VCL compiler that this VCL has been adapted to the
# new 4.0 format.
vcl 4.0;

# Tells Varnish the location of the upstream. Do not change .host and .port.
backend default {
    .host = "next-hop";
    .port = "80";
    .first_byte_timeout = 125s;
    .between_bytes_timeout = 125s;
}

# The following VMODs are available for use if required:
#import std; # see https://www.varnish-cache.org/docs/5.2/reference/vmod_std.generated.html
#import header; # see https://github.com/varnish/varnish-modules

# Method: vcl_recv
# Documentation: https://varnish-cache.org/docs/5.2/users-guide/vcl-built-in-subs.html#vcl-recv
# Description: Happens before we check if we have this in cache already.
#
# Purpose: Typically you clean up the request here, removing cookies you don't need,
# rewriting the request, etc.
sub vcl_recv {

    # CloudFlow default code
    #
    # Purpose: If the request method is not GET, HEAD or PURGE, return pass.
    # Documentation: Reference documentation for vcl_recv.
    if (req.method != "GET" && req.method != "HEAD" && req.method != "PURGE") {
        return (pass);
    }

    # CloudFlow default code
    #
    # Purpose: If the request contains auth header return pass.
    # Documentation: Reference documentation for vcl_recv.
    if (req.http.Authorization) {
        /* Not cacheable by default */
        return (pass);
    }
}

# Method: vcl_backend_fetch
# Documentation: https://varnish-cache.org/docs/5.2/users-guide/vcl-built-in-subs.html#vcl-backend-fetch
# Description: Called before sending the backend request.
#
# Purpose: Typically you alter the request for the backend here. Overriding to the
# required hostname, upstream Proto matching, etc
sub vcl_backend_fetch {
    # No default CloudFlow code for vcl_backend_fetch
}

# Method: vcl_backend_response
# Documentation: https://varnish-cache.org/docs/5.2/users-guide/vcl-built-in-subs.html#vcl-backend-response
# Description: Happens after reading the response headers from the backend.
#
# Purpose: Here you clean the response headers, removing Set-Cookie headers
# and other mistakes your backend may produce. This is also where you can manually
# set cache TTL periods.
sub vcl_backend_response {

}

# Method: vcl_deliver
# Documentation: https://varnish-cache.org/docs/5.2/users-guide/vcl-built-in-subs.html#vcl-deliver
# Description: Happens when we have all the pieces we need, and are about to send the
# response to the client.
#
# Purpose: You can do accounting logic or modify the final object here.
sub vcl_deliver {
    # CloudFlow default code
    #
    # Purpose: We are setting 'HIT' or 'MISS' as a custom header for easy debugging.
    if (obj.hits > 0) {
        set resp.http.section-io-cache = "Hit";
    } else {
        set resp.http.section-io-cache = "Miss";
    }
}

# Method: vcl_hash
# Documentation: https://varnish-cache.org/docs/5.2/users-guide/vcl-built-in-subs.html#vcl-hash
# Description: This method is used to build up a key to look up the object in Varnish.
#
# Purpose: You can specify which headers you want to cache by.
sub vcl_hash {
    # CloudFlow default code
    #
    # Purpose: Split cache by HTTP and HTTPS protocol.
    hash_data(req.http.X-Forwarded-Proto);
}

include "section-features.vcl";

note

The default.vcl file only overrides built-in subroutines (in the builtin.vcl file) when a terminating statement is provided, such as return (pass), or else it will prepend subroutines to the matching built-in subroutine.

caution

The built-in VCL provides safe defaults that should only be overridden with careful consideration.

tip

Check out the related Varnish Cache documentation to get started with customizing your Varnish Cache module.

In the environment's section.config.json file, add the following module object to the proxychain array, replacing <module_directory_name> with the value used in step five and <module_image> with the module image you want to deploy:
section.config.json
```
...
"proxychain": [
    ...
    {
        "name": "<module_directory_name>",
        "image": "<module_image>"
    },
    ...
],
...
```
section.config.json
```
...
"proxychain": [
    ...
    {
        "name": "varnish",
        "image": "varnish:7.0.2"
    },
    ...
],
...
```
note
The proxychain array order determines how the modules are layered in the environment's proxy stack. The first array item is closest to the client and the last is closest to the origin.
Stage, commit, and push the changes to the environment's remote repository:
```
git add .
git commit -m "Add the Varnish Cache module"
git push
```

Manage

Manage the Varnish Cache module through the Git config.

tip

Check out the related Varnish Cache documentation to get started with customizing your Varnish Cache module.

note

Submit a support request by clicking the Support link in the left sidebar if you need help managing this module.

Quick config

Follow the steps below to quickly configure the Varnish Cache module for an environment in your project:

Go to the quick config of the environment you want to quickly configure the Varnish Cache module for.
Configure your caching for static assets and HTML documents and then click Update:
Caching static assets
Static asset caching is enabled by default and will cache the following content types in Varnish Cache for six hours while retaining the Cache-Control value received from the origin: css, js, jpeg, png, gif, ico, swf, and woff.
- Cache Statics TTL: The amount of time Varnish Cache should cache your static assets for.
- Remove Querystring: Whether query strings should be stripped. This means assets will be cached as the same object even if the query string differs, which can increase your cache hit rate.
- Browser Cache TTL: The amount of time the browser should cache your static assets for.
caution
Defining the browser cache should be done with careful consideration because that specific cache layer is difficult to invalidate without a versioning system.
Caching HTML documents
HTML documents caching is disabled by default.
- HTML Document TTL: The amount of time Varnish Cache should cache your HTML documents for.
- HTML Document Grace TTL: The amount of time Varnish Cache should deliver a stale cached HTML document when an error is received from the origin.
- URLs regex: Regular expression for URLs that should not be cached.
- Cookies regex: Regular expression for HTTP cookies that should not be cached.

Clear cache

Follow the steps below to clear the Varnish Cache module for an environment in your project:

Console

Go to the clear cache of the environment you want to clear the Varnish Cache module for.
Clear individual cached objects either through a particular URL or a custom Varnish ban expression, or all cached objects.

API

Go to the API documentation.
In the API list, click on Proxy.

In the Proxy list, click on the following API endpoint:

POST /account/{accountId}/application/{applicationId}/environment/{environmentName}/proxy/{proxyName}/state

Build your API call by filling out the required parameters.
tip
The accountId, applicationId, and environmentName parameters can be obtained from the browser address bar when logged in to your CloudFlow organization. The proxyName is the directory name of the module that is in the associated Git config (typically varnish).

tip

Check out the related Varnish Cache documentation on clearing cached objects.

note

A ban will not prevent an object from being cached in the future, it only clears objects that have already been cached.

Whitelist origin requests

Follow the steps below to whitelist requests made to the origin for an environment in your project:

Go to the Git config of the environment you want to whitelist requests made to the origin for.
In the environment's varnish/default.vcl file, set the CloudFlow-Shared-Secret request header in the vcl_recv subroutine before any terminating statements, such as return (pass), while replacing <your_shared_secret> with a secret that will be checked on the origin (e.g. RTio4vNHfxiWabqKxj8PZ99k):
varnish/default.vcl
```
sub vcl_recv {
    set req.http.CloudFlow-Shared-Secret = "<your_shared_secret>";
}
```
Whitelist the CloudFlow-Shared-Secret request header on the origin server, for example:
nginx.conf
```
location / {
    if ($http_cloudflow_shared_secret != <your_shared_secret>) {
        return 403;
    }
}
```
.htaccess
```
RewriteEngine On
RewriteCond %{HTTP:CloudFlow-Shared-Secret} !<your_shared_secret>
RewriteRule ^ - [F]
```
note
The examples above demonstrate blocking all requests that do not contain the following request header: CloudFlow-Shared-Secret: <your_shared_secret>

Custom logging

Follow the steps below to enable custom logging for an environment in your project:

Go to the Git config of the environment you want to enable custom logging for.
In the environment's varnish/default.vcl file, set the section-io-tag response header in the vcl_deliver subroutine before any terminating statements (if any exist), such as return (deliver), while replacing <your_custom_log> with the value that you want to log (e.g. req.http.X-Forwarded-For or req.http.X-Amz-Cf-Id):
varnish/default.vcl
```
sub vcl_deliver {
    set req.http.section-io-tag = <your_custom_log>;
}
```
varnish/default.vcl
```
sub vcl_deliver {
    set req.http.section-io-tag = req.http.X-Forwarded-For;
}
```

Pass mode

Follow the steps below to enable pass mode for an environment in your project:

Go to the Git config of the environment you want to enable pass mode for.

In the environment's varnish/default.vcl file, replace it with the following:

varnish/default.vcl
vcl 4.0;

backend default {
    .host = "next-hop";
    .port = "80";
    .first_byte_timeout = 125s;
    .between_bytes_timeout = 125s;
}

sub vcl_recv {
    return (pass);
}

sub vcl_backend_response {
    set beresp.uncacheable = true;
    set beresp.ttl = 120s;
    return (deliver);
}

Redirects

Follow the steps below to add redirects for an environment in your project:

Go to the Git config of the environment you want to add redirects for.

In the environment's varnish/default.vcl file, add the following to the vcl_recv and vcl_synth subroutines:

varnish/default.vcl
sub vcl_recv {
    if (req.url ~ "^/first/old/path") {
        return (synth(301, "/new/permanent/path"));
    }

    if (req.url ~ "(?i)^/second/case-insensitive/old/path") {
        # Some origins use case-insensitive URLs and it is important to match this behavior in Varnish
        # regular expressions with the `(?i)` modifier, or use the `std.tolower` or `std.toupper` functions.
        return (synth(302, "/new/temporary/path"));
    }
}

sub vcl_synth {
    if (resp.status == 301 || resp.status == 302) {
        set resp.http.location = resp.reason;
        set resp.reason = "Moved";
        return (deliver);
    }
}

Rewrites

Follow the steps below to add rewrites for an environment in your project:

Go to the Git config of the environment you want to add rewrites for.

In the environment's varnish/default.vcl file, add the following to the vcl_recv subroutine:

varnish/default.vcl
sub vcl_recv {
    if (req.url == "/styles.css") {
        set req.url = "/assets/css/styles.css";
    }
}

Geolocation blocking

Follow the steps below to enable geolocation blocking for an environment in your project:

Go to the Git config of the environment you want to enable geolocation blocking for.
In the environment's varnish/default.vcl file, add the following to the vcl_recv subroutine:
varnish/default.vcl
```
sub vcl_recv {
    if (req.http.section-io-geo-country-code != "AU") {
        return (synth(403, "Forbidden"));
    }
}
```
tip
section-io-geo-country-code can be replaced with any geolocation HTTP request header added by the ingress controller.

IP blocking

Follow the steps below to enable IP blocking for an environment in your project:

Go to the Git config of the environment you want to enable IP blocking for.
In the environment's varnish/default.vcl file, add the following to the vcl_recv subroutine, replacing 123.456.789.10 with the IP address you want to block:
varnish/default.vcl
```
sub vcl_recv {
    if (req.http.True-Client-IP == "123.456.789.10") {
        return (synth(403, "Forbidden"));
    }
}
```

Delete

Follow the steps below to delete the Varnish Cache module from your environment:

Go to the Git config of the environment you want to delete the Varnish Cache module from.
In the top of the page, copy the URL next to Clone with HTTPS.
Open a terminal and change the current working directory to the location where you want the cloned environment repository.
Clone the environment repository to your local computer. Type git clone followed by the copied URL and then press Enter:
```
git clone <copied_url>
```
In the root directory of the environment repository, delete the Varnish Cache module directory (typically named varnish).
note
Skip this step to disable the module instead of deleting it.

In the environment's section.config.json file, delete the module object from the proxychain array, which will look like the following:

section.config.json
...
"proxychain": [
    ...
    {
        "name": "<module_directory_name>",
        "image": "<module_image>"
    },
    ...
],
...

section.config.json
...
"proxychain": [
    ...
    {
        "name": "varnish",
        "image": "varnish:7.0.2"
    },
    ...
],
...

Stage, commit, and push the changes to the environment's remote repository:
```
git add .
git commit -m "Delete the Varnish Cache module"
git push
```

Deploy​

note

note

caution

tip

note

Manage​

tip

note

Quick config​

Caching static assets​

caution

Caching HTML documents​

Clear cache​

Console​

API​

tip

tip

note

Whitelist origin requests​

note

Custom logging​

Pass mode​

Redirects​

Rewrites​

Geolocation blocking​

tip

IP blocking​

Delete​

note

Deploy

Manage

Quick config

Caching static assets

Caching HTML documents

Clear cache

Console

API

Whitelist origin requests

Custom logging

Pass mode

Redirects

Rewrites

Geolocation blocking

IP blocking

Delete