Custom VCL to bypass Fastly cache

You can create a custom VCL snippet to bypass the Fastly cache so you can troubleshoot request traffic to the origin server, for example to determine whether site issues are caused by caching, or to troubleshoot headers.

You can configure the snippet to bypass Fastly caching for requests from a specific IP address or URL.

We recommend testing custom VCL configurations in a Staging environment before merging them into a Production environment.

Prerequisites:

Your environment must be configured to use the Fastly CDN. See Set up Fastly

  • 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 Magento Cloud Staging and Production environments.

To bypass Fastly cache based on IP address or URL:

  1. Log in to the Magento Admin UI.

  2. Click Stores > Settings > Configuration > Advanced > System.

  3. Expand Full Page Cache > Fastly Configuration > Custom VCL Snippets.

  4. Click Create Custom Snippet.

  5. Add the VCL snippet values:

    • Namebypass_fastly

    • Typerecv

    • Priority5

    • VCL snippet content —

      The following example bypasses Fastly for a specific IP address:

      1
      2
      3
      
      if (client.ip == "<Your IPv4 IP address>" || client.ip == "<Your IPv6 IP address>") {
        return(pass);
      }
      

      The following example bypasses Fastly for a specific URL pattern:

      1
      
      if (req.url ~ "/media/feeds/GoogleShoppingHiVisNew.xml") {  return (pass);}
      

      For an exact URL match, use the == operator instead of the ~ operator. See the Fastly VCL reference for details.

  6. Click Create.

    Create Fastly Bypass VCL snippet

  7. After the page reloads, click Upload VCL to Fastly in the Fastly Configuration section.

  8. After the upload completes, refresh the cache according to the notification at the top of the page.

    Fastly validates the updated VCL version during the upload process. If the validation fails, edit your custom VCL snippet to fix any issues. Then, upload the VCL again.

After you add the VCL snippet, you can use cURL commands to submit requests to the origin server from the specified IP address or URL as shown in the following example:

1
curl -svo /dev/null www.example.com/index.html

Then, inspect the response to troubleshoot issues with the uncached content.

Modify the custom VCL snippet

  1. Log in to the Magento Admin UI.

  2. Click Stores > Settings > Configuration > Advanced > System.

  3. Expand Full Page Cache > Fastly Configuration > Custom VCL Snippets.

    Manage custom VCL snippets

  4. In the Action column, click the settings icon next to the snippet to edit.

  5. After the page reloads, click Upload VCL to Fastly in the Fastly Configuration section.

  6. After the upload completes, refresh the cache according to the notification at the top of the page.

The Custom VCL snippets UI option shows only the snippets added through the Admin UI. You must use the Fastly API to manage custom snippets added through the API.

Delete the custom VCL snippet

You can delete custom VCL snippet code from your Fastly configuration by uploading an empty version of the snippet from the Magento Admin UI, or delete it completely using the Fastly API.

  • Upload an empty version of the snippet file to Fastly to remove the VCL logic from the active VCL version:

    • Edit the snippet and delete the VCL snippet content.
    • Save the configuration.
    • Upload the VCL to Fastly to apply your changes.
  • Use the Fastly API Delete custom VCL snippet operation to delete the snippet completely, or submit a Magento support ticket to request deletion.

Instead of manually uploading custom VCL snippets, you can add snippets to the $MAGENTO_CLOUD_APP_DIR/var/vcl_snippets_custom directory in your environment. Snippets in this directory upload automatically any time you click upload VCL to Fastly in the Admin UI. See Automated custom VCL snippets deployment in the Fastly CDN module for Magento 2 documentation.