Using conditions

Conditions use the Varnish Configuration Language (VCL) to define when a configuration object should be applied while processing requests to a cache server. Once you understand some basics about conditions, use this guide to learn about how to create conditions using the Fastly web interface and when to use them.

Where to find conditions

Conditions appear in two areas of Fastly's web interface:

• The Manage conditions page lists all conditions available to your configuration settings.
• Each configuration object displays conditions specifically attached to them.

Conditions on the Manage conditions page

The Manage conditions page provides an overview of all the conditions currently available to your service. You can see at a glance which conditions are mapped to configuration objects. It allows you to create new conditions and search for existing ones.

To view conditions on the Manage conditions page:

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 Conditions. A list of all conditions for your service appears.

For example, this service has one request condition available:

The Example Request Condition shown above currently isn't applied to a configuration object (as indicated by "Not applied to anything"). If it was, it would instead appear similar to this:

Conditions attached directly to a configuration object

Configuration objects appear differently in the web interface when conditions are attached to them. For example, this request setting has no condition attached to it:

Once you click the Attach a condition link to create a new condition or attach an existing condition, however, the web interface changes how the configuration object appears:

By default, configuration objects hide the majority of details for any attached conditions. You can unhide those details by clicking the Show details link. When expanded, the details vary depending on the type of condition.

Parts of a properly configured condition

Conditions require only a few parameters, making them appear deceptively simple. Specifically, they require:

• a Type parameter that classifies the condition being added. If added via the Manage conditions page, the type can always be manually selected. If added via the Attach a condition link on a configuration object, the type is automatically applied whenever possible.
• a Name parameter that serves human-readable identifier of the condition.
• an Apply if statement containing the logical expression to execute in VCL to determine if condition resolves as True or False.

Most problems with conditions occur in the Apply if parameter.

Performing matches on basic logical expressions

Properly configured conditions can perform matches on complicated logical expressions specified in the Apply if parameter. For example:

The client.ip, req.http.host, req.method, and req.url conditions shown above all represent configuration variables in VCL.

Using operators to perform matches on complex logical expressions

You could also get creative and create a more complex condition used by Fastly that might have an Apply if parameter that looked like this:

req.http.host == "www.example.com" && (req.url !~ "/foo" && req.url !~ "/bar" && req.url !~ "^/baz")

This condition tells the cache server that the Host should equal www.example.com and the URL cannot match /foo or /bar or /baz. You might use this type of condition when you have multiple variables or options and want to fine-tune your results. In this example, you are indicating that you don't want URLs that contain foo, bar, or baz by using the following operators:

An example of adding conditions

The scenario: You want to add a new origin server that handles a specific portion of your API requests. Some requests to this API must be cached differently than other requests to your API, so you want to set special headers for specific types of requests. Specifically, you don't want your new origin server to cache PUT, POST, or DELETE requests because they're special for this particular API and send back extra, time dependent, meta-information in each response. And finally, you want to track the effectiveness of doing this. To accomplish all of this using conditions via the Fastly web interface, you would:

1. Create a new origin server to handle the special API traffic.
2. Create a new condition that tells the cache how to route some of the API requests to that origin server.
3. Create a new cache setting object to ensure the origin server caches only the correct responses.
4. Create a new condition that specifies when the cache settings object should be applied.
5. Create a new header to track the specific type of API requests.
6. Create a new response condition to make sure that the header is only set on specific type of request.
7. Check your work.

Create a new origin server

To create a new origin server that will handle the special API traffic, follow the instructions for working with hosts. You'll add specific details about your API server when you fill out the Create a host fields:

• In the Name field, enter a name for your API server (for example, Special API Server).
• In the Address field, enter the IP address (or hostname) of the API server.

Create a request condition

Once you've created a new origin server to handle the special API traffic, tell the cache how to route requests to this origin server by creating a request condition.

1. In the Hosts area, click Attach a condition next to the name of the origin server you just created.

2. You can either select an available condition or you can click Create a new request condition.

   

3. Fill out the Create a new request condition fields as follows:

   • In the Name field, enter a descriptive name for the new condition (for example Special API Request).
   • In the Apply if field, enter the appropriate request condition that will be applied (for example, req.url ~ "^/special/" could address all requests related to the special API server).

4. Click Save and apply to. The new condition for the host is created.

Create a cache settings object

Requests are now are being properly routed to the new origin server. Next, create a cache settings object to ensure Fastly doesn't cache any responses from PUT, POST, or DELETE requests. They're special for this particular API and send back extra, time dependent, meta-information in each response.

1. Click Settings.

2. In the Cache Settings area, click the Create cache setting.

   

3. Fill out the Create a cache setting fields as follow:

   • In the Name field, enter a descriptive name for the new cache settings.
   • Leave the TTL (seconds) field set to its default value.
   • From the Action menu, select Pass (do not cache).
   • Leave the Stale TTL (seconds) field set to its default value.

4. Click Create.

Create and apply a condition to the cache settings object

Create a new condition that specifies when the cache settings object should be applied.

1. In the Cache Settings area, click the Attach a condition link next to the name of the cache setting you just created.

2. Click Create a new cache condition.

   

3. Fill out the Create a new cache condition fields as follows:

   • In the Name field, enter a descriptive name for the new condition (for example, Special API Origin Response).
   • In the Apply if field, enter the appropriate request condition that will be applied (for example, req.method ~ "PUT|POST|DELETE" && beresp.status == 200).

4. Click Save and apply to. The new condition for the cache setting is created.

Create a new header

To make sure you can track the effectiveness the new API, create a new header so you can use it to gather information about the special API requests as they happen.

1. Click Content.

2. In the Headers area, click the Create header button to create a new header.

   

3. Fill out the Create a header fields as follows:

   • In the Name field, enter a descriptive name for the new header (for example, Special API Set Header).
   • From the Type menu, select Response and from the Action menu, select Set.
   • In the Destination field, enter the name of the header that will be affected by the action (for example, http.super).
   • In the Source field, enter a description of the source where the content for this header comes from (for example, "Thanks for asking!").
   • Leave the Ignore if set and Priority fields set to their default settings.

4. Click Create.

Create a response condition for the new header

Once the header is created, create an associated condition to ensure this header is only set on that special type of request.

1. In the Headers area, click Attach a condition next to the name of the new header you just created.

   

2. Fill out the Create a new response condition fields as follows:

   • In the Name field, enter a descriptive name for the new condition (for example, Special API Response Condition).
   • In the Apply if field, enter the appropriate request condition that will be applied (for example, req.url ~ "^/special" && resp.status == 200).

3. Click Save and apply to. The new condition for the header is created.

Check your work

Before activating the configuration, review the generated VCL to see how Fastly converted the objects and conditions into actual VCL. For the example shown above, the VCL for the request condition appears as:

1
2
3
4
5

# Condition: Special API Request Prio: 10
if (req.url ~ "^/special/") {
  set req.backend = F_Special_API_Server;
}
#end condition

The cache settings and condition VCL appears as:

1
2
3
4
5

if (req.method ~ "PUT|POST|DELETE" && beresp.status == 200) {
  set beresp.ttl = 0s;
  set beresp.grace = 0s;
  return(pass);
}

And the new header response condition VCL appears as:

1
2
3
4
5
6

# Condition Special API Response Condition Prio: 10
if (req.url ~ "^/special" && resp.status == 200) {

  # Header rewrite Special API Set Header: 10
  set resp.http.super = "Thanks for asking!";
}

As you become more familiar with the VCL syntax and programming, look at the generated VCL to see if the configuration is doing what you think it is doing (most VCL is pretty simple once you know what the variables are referring to).