LOG IN SIGN UP
Documentation

Using conditions

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

About request, response, and cache conditions

Conditions can occur in various stages of caching: when a request is being processed, when a response to that request is being processed, and when a response from your origin serve arrives but before that information is (potentially) cached. Each stage of caching has access to a different set of VCL variables (as described in the Varnish-Cache.org documentation) that can be used to create conditions.

To help distinguish conditions during these stages we group them into three types: request, response, and cache. Configuration objects also only apply in various stages of the pipeline and can have different types of conditions associated with them.

The following list of the condition types describes the objects to which conditions can apply and the VCL variable types that are available to them:

These conditions allow you to control your configuration with minimal programming.

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 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 application, 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 requests to that origin server.
  3. Create a new cache setting object and then a new condition that applies that object at the appropriate time.
  4. Create a new header to track the specific type of API requests.
  5. Create a new cache condition to make sure that the header is only set on specific type of request.
  6. Check your work.

Create a new origin server

To create a new origin server that will handle the special API traffic, follow the steps below.

  1. Log in to the Fastly application.
  2. Click the configure tab to access the control panel.
  3. Select the appropriate service from the Service menu.
  4. Click the blue Configure button to the right of the service name.
  5. Select the Host pane from the list on the left.
  6. In the Backends area click the New button to create a new backend for your special API traffic. The New Backend window appears.

    the new backend window for adding a specific backend with no load balancing to which requests will be routed

  7. Fill out the New Backend window as follows:

    • In the Address field, type the address of your API server (for example, 127.0.0.3).
    • In the Port field, type 80.
    • In the Name field, type the name of your API server (for example, Special API Server).
    • From the Auto Load Balance menu, select No to exclude this server from the normal, automatic load balancing pool.
    • Leave the Shielding control set to its default.
  8. Click Create. The new origin server appears in the Backends area.

Create a request condition

Once you've created a new origin serve 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 Backends area, click the gear icon next to the name of the origin server you just created, then select Conditions. The Choose Conditions window appears.
  2. Click the New button to create a new condition. The New Condition window appears.

    the new condition window that tells the cache how to route requests to the new backend based on a special URL prefix

  3. Fill out the New Condition window as follows:

    • In the Name field, type a descriptive name for the new condition (for example Special API Request).
    • In the Apply if field, type the appropriate request condition that will be applied (for example, req.url ~ "^/special/" to address all requests related to the special API server).
    • Leave the Priority field set to its default value.
  4. Click Create.

Create a cache settings object and its condition

The requests now are being properly routed to the new origin, you need to make sure that it doesn't cache any responses from PUT, POST, or DELETE requests because they are special for this particular API and send back extra, time dependent, meta-information in each response. To do this, create a cache settings object in the configuration.

  1. Click the Settings pane. The Settings appear.
  2. In the Cache Settings area, click the New button to create a cache settings object. The New Cache Settings window appears.

    the new cache settings window that ensures the backend doesn't cache responses from special requests

  3. Fill out the New Cache Settings window as follow:

    • In the Name field, type a descriptive name for the new cache settings (for example, Special API Pass Settings).
    • Leave the TTL and Stale TTL fields set to their default values.
    • From the Action menu, select Pass.
  4. Click Create to create the new cache setting.

Then, create a new condition that specifies when the cache settings object should be applied.

  1. In the Cache Settings area, click the gear icon next to the name of the cache setting you just created, then select Conditions. The Choose Conditions window appears.
  2. Click the New button to create a new condition. The New Condition window appears.

    the new condition window that ensures the cache settings only apply when responses come from the special API

  3. Fill out the New Condition window as follows:

    • In the Name field, type a descriptive name for the new condition (for example, Special API Pass Condition).
    • In the Apply if field, type the appropriate request condition that will be applied (for example, req.request ~ "PUT|POST|DELETE" && beresp.status == 200).
    • Leave the Priority field set to its default value.
  4. Click Create to create the new condition for the cache setting.

Create a new header and its condition

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.

To set the condition:

  1. Click the Content pane. The Content controls appear.
  2. In the Headers area, click the New button to create a new header. The New Header window appears.

    the new header window that sets a special header for information gathering purposes

  3. Fill out the New Header window as follows:

    • In the Name field, type a descriptive name for the new header (for example, Special API Set Header).
    • From the Type/Action menus select Response and Set.
    • In the Destination field, type the name of the header that will be affected by the action (for example, http.super).
    • In the Source field, type 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 to create the new header.

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

  1. In the Headers area, click the gear icon next to the name of the new header you just created, then select Conditions. The Choose Conditions window appears.
  2. Click the New button to create a new condition. The New Condition window appears.

    the new condition window that ensures the new header only applied when responses come from the special API

  3. Fill out the New Condition window as follows:

    • In the Name field, type a descriptive name for the new condition (for example, Special API Response Condition).
    • In the Apply if field, type the appropriate request condition that will be applied (for example, req.url ~ "^/special" && resp.status == 200).
    • Leave the Priority field set to its default value.
  4. Click Create to create the new condition for the header.

Check your work

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

# 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:

if (req.request ~ "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:

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