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:
-
Regular snippets—Custom regular VCL snippets are coded for specific VCL versions. You can create, modify, and deploy regular VCL snippets from the Admin or the Fastly API.
-
Dynamic snippets—VCL snippets created using the Fastly API. You can modify and deploy dynamic snippets without having to update the Fastly VCL version for your service.
We recommend using custom VCL snippets with Edge Dictionaries and Access Control Lists (ACL) to store data used in your custom code.
-
Edge dictionary—Stores data as key-value pairs in a dictionary container that can be referenced from custom VCL snippets
-
Edge ACL—Stores the client IP address data that defines the access control list for block or allow rules implemented using custom VCL snippets
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:
- Guide to Fastly VCL—Information about the Fastly Varnish implementation, Fastly VCL extensions, and resources for learning more about Varnish and VCL.
- Fastly VCL reference—Detailed programming reference to develop and troubleshoot Fastly custom VCL and custom VCL snippets.
You can create and manage custom VCL snippets from the Adobe Commerce Admin or by using the Fastly API:
-
Adobe Commerce Admin—We recommend using the Adobe Commerce Admin to manage custom VCL snippets because it automates the process to validate, upload, and apply the VCL changes to the Fastly service configuration. Also, you can view and edit the custom VCL snippets added to the Fastly service configuration from the Admin.
-
Fastly API—If you cannot access the Admin, use the Fastly API to manage custom VCL snippets. For example, use the API to troubleshoot the Fastly service configuration when the site is down, or to add a custom VCL snippet. Also, some operations can be completed only using the API. For example, you must use the API to reactivate an older VCL version or to view all the VCL snippets included in a specified VCL version. See API quick reference for VCL snippets.
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:
-
Checks the incoming IP address,
client.ip
on each request -
Blocks any request with an IP address included in the ACLNAME edge ACL, returning a
403 Forbidden
error
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.
API_KEY
active
true
or false
. If true, the snippet or version is in use. Clone an active snippet using its version number.content
dynamic
false
for regular snippets included in the versioned VCL for the Fastly service configuration. Returns true
for a dynamic snippet which can be modified and deployed without requiring a new VCL version.number
priority
Numeric value from 1
to 100
that specifies when the custom VCL snippet code runs. Snippets with lower priority values run first. If not specified, the priority
value defaults to 100
.
Any custom VCL snippet with a priority value of 5
runs immediately, which is best for VCL code that implements request routing (block and allowlists and redirects). Priority 100
is best for overriding default VCL snippet code.
All default VCL snippets included in the Magento-Fastly module have priority=50
.
- Assign a high priority like
100
to run custom VCL code after all other VCL functions and override the default VCL code.
service_id
type
init
(above subroutines) and recv
(within subroutines). For details, see the Fastly VCL snippets reference.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:
-
Configure your Adobe Commerce on cloud infrastructure environment for Fastly services. See Set up Fastly.
-
Get Fastly API credentials to authenticate requests to the Fastly API. Make sure that you get the credentials for the correct environment: Staging or Production.
-
Save Fastly service credentials as bash environment variables that you can use in cURL commands:
code language-bash export FASTLY_SERVICE_ID=<Service-ID>
code language-bash export FASTLY_API_TOKEN=<API-Token>
The exported environment variables are available only in the current bash session and are lost when you close the terminal. You can redefine variables by exporting a new value. To view the list of exported variables related to Fastly:
code language-bash export | grep FASTLY
Add VCL snippets
This tutorial provides the basic steps to add custom snippets using the Fastly API.
Prerequisites
-
Your environment must be configured to use the Fastly CDN. See Configure Fastly services.
-
Ensure that you are running the latest version of the Fastly CDN module for Magento 2. See Upgrade the Fastly Module.
-
Verify the environment configuration for the Fastly service. See Check Fastly caching.
-
You must have Admin credentials to access the Staging and Production environments.
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:
-
name
—Name for the VCL snippet. -
dynamic
—Indicates if this is a regular snippet or a dynamic snippet. -
type
—Specifies the location for inserting the generated snippet, such asinit
(above subroutines) andrecv
(within subroutines). See Fastly VCL snippet object values for information on these values. -
priority
—A value from1
to100
that determines when the custom VCL snippet code runs. Custom VCL snippets with lower values run first.All default VCL code from the Fastly VCL module has a
priority
of50
. If you want an action to occur last or to override the default VCL code, use a higher number, such as100
. To run custom VCL snippet code immediately, set the priority to a lower value, such as5
. -
content
—The snippet of VCL code to run in one line, without line breaks. See Example custom VCL snippet.
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.
-
Use the Fastly API validate VCL version operation to verify the updated VCL code.
code language-bash curl -H "Fastly-Key: $FASTLY_API_TOKEN" https://api.fastly.com/service/$FASTLY_SERVICE_ID/version/$FASTLY_EDIT_VERSION/validate
If the Fastly API returns an error, fix the issue and validate the updated VCL version again.
-
Use the Fastly API activate operation to activate the new VCL version.
code language-bash curl -H "Fastly-Key: $FASTLY_API_TOKEN" https://api.fastly.com/service/$FASTLY_SERVICE_ID/version/$FASTLY_EDIT_VERSION/activate -X PUT
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.
-
Get active VCL version number
code language-bash curl -H "Fastly-Key: $FASTLY_API_TOKEN" https://api.fastly.com/service/$FASTLY_SERVICE_ID/version/active
-
List all regular VCL snippets attached to a service
code language-bash curl -H "Fastly-Key: $FASTLY_API_TOKEN" https://api.fastly.com/service/$FASTLY_SERVICE_ID/version/$FASTLY_VERSION/snippet
-
Review an individual snippet
code language-bash curl -H "Fastly-Key: $FASTLY_API_TOKEN" https://api.fastly.com/service/$FASTLY_SERVICE_ID/version/$FASTLY_VERSION/snippet/<snippet_name>
The
<snippet_name>
is the name of a snippet, such asmy_regular_snippet
. -
Update a snippet
Modify the prepared JSON file and send the following request:
code language-bash curl -H "Fastly-Key: $FASTLY_API_TOKEN" https://api.fastly.com/service/$FASTLY_SERVICE_ID/version/$FASTLY_VERSION/snippet/<snippet_name> -H 'Content-Type: application/json' -X PUT --data @<filename.json>
-
Delete an individual VCL snippet
Get a list of snippets and use the following
curl
command with the specific snippet name to delete:code language-bash curl -H "Fastly-Key: $FASTLY_API_TOKEN" https://api.fastly.com/service/$FASTLY_SERVICE_ID/version/$FASTLY_VERSION/snippet/<snippet_name> -X DELETE
-
Override values in the default Fastly VCL code
Create a snippet with updated values and assign a priority of
100
.