Using dynamic VCL Snippets

Dynamic VCL Snippets are one of two types of snippets that allow you to insert small sections of VCL logic into your service configuration without requiring custom VCL (though you can still include snippets in custom VCL when necessary).

You can only create dynamic snippets via the API. Because they are versionless objects (much like dictionaries or ACLs at the edge), dynamic snippets can be modified independently from changes to your Fastly service. This means you can modify snippet code rapidly without deploying a service version that may not be ready for production.

Creating and using a dynamic VCL Snippet

Using the curl command line tool, make the following API call in a terminal application:

$ curl -X POST -s https://api.fastly.com/service/<Service ID>/version/<Editable Version>/snippet -H "Fastly-Key:FASTLY_API_TOKEN" -H 'Content-Type: application/x-www-form-urlencoded' --data $'name=my_dynamic_snippet_name&type=recv&dynamic=1&content=if ( req.url ) {\n set req.http.my-snippet-test-header = "true";\n}';

Fastly returns a JSON response that looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
13

{
 "service_id": "<Service Id>",
 "version": "<Editable Version>",
 "name": "my_dynamic_snippet_name",
 "type": "recv",
 "priority": 100,
 "dynamic": 1,
 "content": null,
 "id": "decafbad12345",
 "created_at": "2016-09-09T20:34:51+00:00",
 "updated_at": "2016-09-09T20:34:51+00:00",
 "deleted_at": null
}

Viewing dynamic VCL Snippets in the web interface

You can view a list of dynamic VCL snippets. You can also view just the source of a specific snippet or a specific snippet's location in generated VCL.

Viewing a list of dynamic VCL Snippets

To view the entire list of a service's dynamic VCL Snippets directly in the web interface:

1. Log in to the Fastly web interface.

2. From the Home page, select the appropriate VCL service. You can use the search box to search by ID, name, or domain.

3. Click Edit configuration and then select the option to clone the active version.

4. Click VCL Snippets. The VCL Snippets page appears listing all dynamic VCL Snippets for your service in the Dynamic snippets area.

   

Viewing the source of a specific snippet

You can view just the source of a specific snippet:

1. Log in to the Fastly web interface.
2. From the Home page, select the appropriate VCL service. You can use the search box to search by ID, name, or domain.
3. Click Edit configuration and then select the option to clone the active version.
4. Click VCL Snippets.
5. Click View Source to the right of the name of the snippet.

Viewing the location of a specific snippet in generated VCL

You can view a specific snippet's location in generated VCL:

1. Log in to the Fastly web interface.
2. From the Home page, select the appropriate VCL service. You can use the search box to search by ID, name, or domain.
3. Click Edit configuration and then select the option to clone the active version.
4. Click VCL Snippets.
5. Click Show in Generated VCL to the right of the name of the snippet. The Generated VCL window appears.

Fetching a list of all dynamic VCL Snippets

To list all dynamic VCL Snippets attached to a service, make the following API call in a terminal application:

$ curl -X GET -s https://api.fastly.com/service/<Service ID>/version/<Version ID>/snippet -H "Fastly-Key:FASTLY_API_TOKEN"

Fetching an individual dynamic VCL Snippet

To fetch an individual snippet, make the following API call in a terminal application:

$ curl -X GET -s https://api.fastly.com/service/<Service ID>/snippet/<Snippet ID> -H "Fastly-Key:FASTLY_API_TOKEN"

Unlike fetching regular VCL Snippets, you do not include the version in the URL and you must use the ID returned when the snippet was created, not the name.

Updating an existing dynamic VCL Snippet

To update an individual snippet, make the following API call in a terminal application:

$ curl -X PUT -s https://api.fastly.com/service/<Service ID>/snippet/<Snippet ID> -H "Fastly-Key:FASTLY_API_TOKEN" -H 'Content-Type: application/x-www-form-urlencoded' --data $'content=if ( req.url ) {\n set req.http.my-snippet-test-header = \"affirmative\";\n}';

Deleting an existing dynamic VCL Snippet

To delete an individual snippet, make the following API call in a terminal application:

$ curl -X DELETE -s https://api.fastly.com/service/<Service ID>/version/<Version ID>/snippet/<my_dynamic_snippet_name> -H "Fastly-Key:FASTLY_API_TOKEN"

Including dynamic snippets in custom VCL

By specifying a location of none for the type parameter, snippets will not be rendered in VCL. This allows you to include snippets in custom VCL using the following syntax:

include "snippet::<snippet name>"

The same VCL Snippet can be included in custom VCL in as many places as needed.

Example use: blocking site scrapers

Say you wanted to implement some pattern matching against incoming requests to block someone trying to scrape your site. Say also that you've developed a system that looks at all incoming requests and generates a set of rules that can identify scrapers using a combination of the incoming IP address, the browser, and the URL they're trying to fetch. Finally, say that the system updates the rules every 20 minutes.

If, during system updates, your colleagues are also making changes to the rest of your Fastly configuration, you probably don't want the system to automatically deploy the latest version of the service since it might be untested. Instead you could generate the rules as a Dynamic VCL Snippet. Whenever the snippet is updated, all other logic remains the same as the currently deployed version and only your rules are modified.