Getting started with custom VCL

Fastly supports a customized version of the Varnish Configuration Language (VCL) to tailor the Fastly service configuration to your requirements.

Custom VCL snippets are blocks of VCL logic added to the active VCL version uploaded to your Adobe Commerce site. A custom VCL snippet modifies how Fastly caching services respond to request traffic. For example, you can add a custom VCL snippet to allow request traffic only from specified client IP addresses. Or, create a snippet to block traffic from websites known for sending referral spam to your Adobe Commerce sites.

Custom VCL snippets—generated, compiled, and transmitted to all Fastly caches—load and activate without server downtime.

Fastly supports two types of custom VCL snippets:

We recommend using custom VCL snippets with Edge Dictionaries and Access Control Lists (ACL) to store data used in your custom code.

The dictionary and ACL data is deployed to the Fastly Edge nodes accessible across network regions. Also, the data can be updated dynamically across the network without requiring you to redeploy the VCL code for your staging or production environment.

Tutorial

This tutorial and examples demonstrate the use of regular custom VCL snippets with Edge Dictionaries and Edge ACLs to customize the Fastly service configuration for Adobe Commerce. For more detailed information, see the Fastly documentation:

You can create and manage custom VCL snippets from the Adobe Commerce Admin or by using the Fastly API:

Example VCL snippet code

The following example shows the custom VCL snippet (JSON format) that filters traffic by client IP address:

{
  "service_id": "FASTLY_SERVICE_ID",
  "version": "{Editable Version #}",
  "name": "apply_acl",
  "priority": "100",
  "dynamic": "1",
  "type": "hit",
  "content": "if ((client.ip ~ {ACLNAME}) && !req.http.Fastly-FF){ error 403; }"
}

The VCL logic in the content field performs the following actions:

The following table provides details about key data for custom VCL snippets. For a more detailed reference, see the VCL snippets reference in the Fastly documentation.

Manage custom VCL from Admin

You can add custom VCL snippets from the Fastly Configuration > Custom VCL Snippets section in the Admin.

The Custom VCL snippets view shows only snippets that have been added through the Admin. If snippets are added using the Fastly API, use the API to manage them.

The following examples show how to create and manage custom VCL snippets from the Admin, and to use Fastly Edge modules and Edge dictionaries:

Manage VCL using the API

The following walk-through shows you how to create regular VCL snippet files and add them to your Fastly service configuration using the Fastly API. You can create and manage the snippets from the terminal application. You do not need an SSH connection into a specific environment.

Prerequisites:

Add VCL snippets

This tutorial provides the basic steps to add custom snippets using the Fastly API.

Prerequisites

Step 1: Locate the active VCL version

Use the Fastly API get version operation to get the active VCL version number:

curl -H "Fastly-Key: $FASTLY_API_TOKEN" https://api.fastly.com/service/$FASTLY_SERVICE_ID/version/active

In the JSON response, note the active VCL version number returned in the number key, for example "number": 99. You need the version number when you clone the VCL for editing.

{
  "testing": false,
  "locked": true,
  "number": 99,
  "active": true,
  "service_id": "872zhjyxhto5SIRb3GAE0",
  "staging": false,
  "created_at": "2019-01-29T22:38:53Z",
  "deleted_at": null,
  "comment": "Magento Module uploaded VCL",
  "updated_at": "2019-01-29T22:39:06Z",
  "deployed": false
}

Save the active version number in a bash environment variable for use in subsequent API requests:

export FASTLY_VERSION_ACTIVE=<Version>

Step 2: Clone the active VCL version and all snippets

Before you can add or modify custom VCL snippets, you must create a copy of the active VCL version for editing. Use the Fastly API clone operation:

curl -H "Fastly-Key: $FASTLY_API_TOKEN" https://api.fastly.com/service/$FASTLY_SERVICE_ID/version/$FASTLY_VERSION_ACTIVE/clone -X PUT

In the JSON response, the version number is incremented, and the active key value is false. You can modify the new, inactive VCL version locally.

{
  "testing": false,
  "locked": false,
  "number": 100,
  "active": false,
  "service_id": "vW2bLFWhhto5SIRb3GAE0",
  "staging": false,
  "created_at": "2019-01-29T22:38:53Z",
  "deleted_at": null,
  "comment": "Magento Module uploaded VCL",
  "updated_at": "2019-01-29T22:39:06Z",
  "deployed": false
}

Save the new version number in a bash environment variable for use in subsequent commands:

export FASTLY_EDIT_VERSION=<Version>

Step 3: Create a custom VCL snippet

Create and save your custom VCL code in a JSON file with the following content and format:

{
  "name": "<name>",
  "dynamic": "0",
  "type": "<type>",
  "priority": "100",
  "content": "<code all in one line>"
}

The values include:

Step 4: Add VCL snippet to Fastly configuration

Use the Fastly API create snippet operation to add the custom VCL snippet to the VCL version.

curl -H "Fastly-Key: $FASTLY_API_TOKEN" https://api.fastly.com/service/$FASTLY_SERVICE_ID/version/$FASTLY_EDIT_VERSION/snippet -H 'Content-Type: application/json' -X POST --data @<filename.json>

The <filename.json> is the name of the file that you prepared in the previous step. Repeat this command for each VCL snippet.

If you receive a 500 Internal Server Error response from the Fastly service, check the JSON file syntax to make sure you are uploading a valid file.

Step 5: Validate and activate custom VCL snippets

After you add a custom VCL snippet, Fastly inserts the snippet in the VCL version that you are editing. To apply changes, complete the following steps to validate the VCL snippet code and activate the VCL version.

API quick reference for VCL snippets

These API request examples use exported environment variables to provide the credentials to authenticate with Fastly. For details on these commands, see the Fastly API reference.