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 web interface.

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 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 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 web interface and click the Configure link. The Configure page appears.
  2. Select the appropriate service from the service menu.
  3. Click the Edit configuration button and then select Clone active. The service version page appears.
  4. Click the Origins tab. The Origins page appears.
  5. Click the Create host button to create a new backend for your special API traffic. The Create a new host page appears.

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

  6. Fill out the Create a new host fields as follows:

    • In the Address field, type the address of your API server (for example, 867.53.0.9) and in the Port field, type 80.
    • Leave the Shielding and Health check controls set to their defaults.
    • From the Auto load balance menu, select No to exclude this server from the normal, automatic load balancing pool.
    • In the Description field, type the name of your API server (for example, Special API Set Header).
  7. Click the Create button. Your new host appears in the Host 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 Hosts area, click the Attach a condition link next to the name of the origin server you just created. The Add a condition to window appears.
  2. You can either select an available condition or you can click the Create a new request condition button. The Create a new request condition window appears.

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

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

    • In the Type field, the type of condition that you are creating appears.
    • 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 the Save and apply to button to create the new condition for the host.

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 tab. The Settings page appears.
  2. In the Cache Settings area, click the Create cache setting button. The Create a new cache setting page appears.

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

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

    • Leave the TTL (seconds) field set to its default value.
    • From the Action menu, select Pass.
    • Leave the Stale TTL (seconds) field set to its default value.
    • In the Description field, type a descriptive name for the new cache settings.
  4. Click the Create button.

Then, 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. The Add a condition to window appears.
  2. Click Create a new cache condition button. The Create a 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 Create a new condition fields as follows:

    • In the Type field, the type of condition you are creating appears.
    • In the Name field, type a descriptive name for the new condition (for example, Special API Set Header).
    • 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 the Save and apply to button 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.

  1. Click the Content tab. The Content page appears.
  2. In the Headers area, click the Create header button to create a new header. The Create a new header page appears.

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

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

    • From the Type menu, select Response and from the Action menu, select 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.
    • In the Description field, type a descriptive name for the new header (for example, Special API Set Header).
  4. Click Create. Once the header is created, create an associated condition to ensure that this header is only set on that special type of request.

  5. In the Headers area, click the Attach a condition link next to the name of the new header you just created. The Create a new request condition window appears.

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

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

    • In the Type field, the type of condition you are creating appears. Be aware that the type for an associated condition is inherited from the Type field in the header you create. Also, when you create a new condition for a header, you can change the type of condition applied (for example, if the condition type is Response, you can change it to Request or Cache).
    • 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.
  7. Click the Save and apply to button to create the new condition for the header.

Check your work

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


Back to Top