Hear from Slack, the ACLU, TED, & more at our customer summit in San Francisco Register
LOG IN SIGN UP
Documentation

Using regular VCL Snippets

  Last updated May 12, 2017

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 and click the Configure link.
  2. From the service menu, select the appropriate service.
  3. Click the VCL Snippets link. The VCL Snippets page appears.
  4. Click Create Snippet. The Create a VCL snippet page appears.

    a blank Create a VCL snippet page

  5. In the Name field, type an appropriate name (for example, Example Snippet).
  6. 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.
  7. In the VCL field, type the snippet of VCL logic to be inserted for your service version.
  8. 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:

{
 "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 and click the Configure link.
  2. From the service menu, select the appropriate service.
  3. Click the VCL Snippets link. The VCL Snippets page appears listing all available VCL snippets for your service.

    an example listing of VCL snippets attached to a 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 and click the Configure link.
  2. From the service menu, select the appropriate service.
  3. Click the VCL Snippets link. The VCL Snippets page appears.
  4. Click the View Source link 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 and click the Configure link.
  2. From the service menu, select the appropriate service.
  3. Click the VCL Snippets link. The VCL Snippets page appears.
  4. Click the Show in Generated VCL link 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 and click the Configure link.
  2. From the service menu, select the appropriate service.
  3. Click the VCL Snippets link. The VCL Snippets page appears.
  4. Click the pencil icon next to the name of the snippet to be updated.

    the pencil icon to click when updating an existing regular VCL Snippet

    The Edit snippet page appears.

    an Edit snippet page

  5. Update the snippet's settings or VCL as appropriate.
  6. 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 and click the Configure link.
  2. From the service menu, select the appropriate service.
  3. Click the VCL Snippets link. The VCL Snippets page appears.
  4. Click the Delete link to the right of the name of the snippet to be updated.

    an existing regular VCL Snippet

    A confirmation window appears.

    a regular VCL Snippet deletion confirmation

  5. 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:

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


Back to Top