DocumentationCommerceCommerce on Cloud Infrastructure Guide

Custom VCL to bypass Fastly cache

Last update: Thu Apr 27 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Admin
  • Developer

You can create a custom VCL snippet to bypass the Fastly cache so you can troubleshoot request traffic to the origin server. For example, you can create a snippet 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.

NOTE
Before merging custom VCL configuration into a production environment, make sure to test the code in the Staging environment.

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.

To bypass Fastly cache based on IP address or URL:

  1. Log in to the Admin.

  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:

    • Name — bypass_fastly

    • Type — recv

    • Priority — 5

    • VCL snippet content —

      The following example bypasses Fastly for a specific IP address:

      code language-conf 
      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:

      code language-conf 
      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:

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

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

NOTE
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 when you click upload VCL to Fastly in the Commerce Admin. See Automated custom VCL snippets deployment in the Fastly CDN module for Magento 2 documentation.

Modify the custom VCL snippet

  1. Log in to the Admin.

  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.

WARNING
The Custom VCL snippets UI option shows only the snippets added through the Adobe Commerce Admin. If you add snippets using the Fastly API, use the API to manage them.

Delete the custom VCL snippet

  1. Log in to the Admin.

  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 trash icon next to the snippet to delete.

  5. On the next modal window, click DELETE and activate a new version.

WARNING
The Custom VCL snippets UI option shows only the snippets added through the Adobe Commerce Admin. If you add snippets using the Fastly API, use the API to manage them.
05f2f56e-ac5d-4931-8cdb-764e60e16f26