Using regular VCL Snippets

Regular 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).

Unlike dynamic snippets, regular snippets can be created via the web interface or via the API. They are considered versioned objects. They belong to a specific service and any modifications you make to the snippet are locked and deployed when you deploy a new version of that service. We continue to clone them and deploy them with a service until you specifically delete them.

Creating a regular VCL Snippet

You can create regular VCL Snippets via the web interface or via the API.

Via the web interface

To create a regular VCL Snippet via the web interface:

1. Log in to the Fastly web interface.
2. From the Home page, select the appropriate 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 Create Snippet.

   

6. In the Name field, enter an appropriate name (for example, Example Snippet).

7. Using the Type controls, select the location in which the snippet should be placed as follows:

   • Select init to insert it above all subroutines in your VCL.
   • Select within subroutine to insert it within a specific subroutine and then select the specific subroutine from the Select subroutine menu.
   • Select none (advanced) to insert it manually. See Including regular snippets in custom VCL for the additional manual insertion requirements if you select this option.

8. In the VCL field, enter the snippet of VCL logic to be inserted for your service version.

9. Click Advanced options at the bottom of the page.

10. (Optional) In the Priority field, enter the order in which you want the snippet to execute. Lower numbers execute first.

11. Click Create to create the snippet.

Via the API

To create a regular VCL Snippet via the API, make the following API call using the curl command line tool 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 `fastly-cookie` -H 'Content-Type: application/x-www-form-urlencoded' --data $'name=my_regular_snippet&type=recv&dynamic=0&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_regular_snippet",
 "type": "recv",
 "content": "if ( req.url ) {\n set req.http.my-snippet-test-header = \"true\";\n}",
 "priority": 100,
 "dynamic": 0,
 "id": "56789exampleid",
 "created_at": "2016-09-09T20:34:51+00:00",
 "updated_at": "2016-09-09T20:34:51+00:00",
 "deleted_at": null
}

Viewing regular VCL Snippets in the web interface

You can view a list of regular 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 regular VCL Snippets

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

1. Log in to the Fastly web interface.
2. From the Home page, select the appropriate 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 available VCL snippets for your service.

   

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 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. A view source window appears.

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 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 regular VCL Snippets via the API

You can fetch regular VCL Snippets for a particular service via the API either singly or all at once.

Fetching an individual regular 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>/version/<Editable Version>/snippet/<Snippet Name e.g my_regular_snippet> -H "Fastly-Key:FASTLY_API_TOKEN"

Unlike fetching dynamic VCL Snippets you include the version in the URL and you must use the name of the snippet, not the ID.

Fetching a list of regular VCL Snippets

To list all regular 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/<Editable Version>/snippet/ -H "Fastly-Key:FASTLY_API_TOKEN"

Updating an existing regular VCL Snippet

You can update existing regular VCL Snippets via the web interface or via the API.

Via the web interface

To update an individual snippet via the web interface:

1. Log in to the Fastly web interface.
2. From the Home page, select the appropriate 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 the pencil next to the name of the snippet to be updated.

   

   The Edit snippet page appears.

   

6. Update the snippet's settings or VCL as appropriate.

7. Click Update to save your changes.

Via the API

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

$ curl -X PUT -s https://api.fastly.com/service/<Service ID>/version/<Editable Version>/snippet/<Snippet Name e.g my_regular_snippet> -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 regular VCL Snippet

You can update existing regular VCL Snippets via the web interface or via the API.

Via the web interface

1. Log in to the Fastly web interface.
2. From the Home page, select the appropriate 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 the trash to the right of the name of the snippet to be updated.

   

6. Click Confirm and Delete.

Via the API

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

$ curl -X DELETE -s https://api.fastly.com/service/<Service ID>/version/<Editable Version>/snippet/<Snippet Name e.g my_regular_snippet> -H "Fastly-Key:FASTLY_API_TOKEN"

Including regular snippets in custom VCL

Snippets will not be rendered in VCL if you select none (advanced) for the snippet type in the web interface or specify a location of none for the type parameter in the API. This allows you to manually 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: location-based redirection

Say that you work at a large content publisher and you want to redirect users to different editions of your publication depending on which country their request comes from. Say also that you want the ability to override the edition you deliver to them based on a cookie.

Using regular VCL snippets, you could add a new object with the relevant VCL as follows:

1
2
3
4
5
6
7
8
9
10

if (req.http.Cookie:edition == "US" || client.geo.country_code == "US") {
  set req.http.Edition = "US";
  set req.backend = F_US;
} elseif (req.http.Cookie:edition == "Europe" || server.region ~ "^EU-" ) {
  set req.http.Edition = "EU";
  set req.backend = F_European;
} else {
  set req.http.Edition = "INT";
  set req.backend = F_International;
}

This would create an Edition header in VCL, but allow you to override it by setting a condition. You would add the Edition header into Vary and then add a false condition (e.g., !reg.url) to your other backends to ensure the correct edition of your publication gets delivered (Remember: VCL Snippets get added to VCL before backends are set.)