How do I use CloudFront to route requests to specific origins?

Resolution

Define path patterns

When you create the CloudFront distribution, define a cache behavior. If you define more than one, then each behavior must have a unique path pattern. CloudFront then matches the request path against the path patterns in the order that you list them in the distribution.

The following examples show how path patterns match their associated request paths:

• /images/* matches /images/cat.jpg and /images/dog.png
• /en/* matches /en/about and /en/contact
• /app1/* matches /app1/index.html but not /app1app2/index.html

Important:

• Path patterns are case sensitive. For example, /images/cat.jpg doesn't match /Images/cat.jpg.
• CloudFront handles the # character as a fragment identifier and doesn't include fragment identifiers in the path pattern match. Create a CloudFront function to match URLs that contain the # character.
• CloudFront normalizes paths before it matches them. For example, /path//file matches the pattern /path/.

Use multiple origins

By default, you can associate only one origin with each path pattern in a cache behavior.

To route requests with the same path pattern to multiple origins, complete the following steps:

1. Use a query string parameter to differentiate your origins. For example, use /.jpg?origin=origin1 and /*.jpg?origin=origin2.
2. Create a separate CloudFront distribution for each origin that you want to use with the same path pattern.
3. Use CloudFront Functions or Lambda@Edge to write custom code that inspects the request and dynamically routes the request to your origin.

Route requests based on geographic location

Use a CloudFront function to inspect the cloudfront-viewer-country header and route requests to different origins based on the viewer's geographic location.

The following example code shows a CloudFront function that redirects requests from specific countries to a different cache behavior:

function handler(event) {
  var request = event.request;
  var headers = request.headers;
  var country = headers['cloudfront-viewer-country'];

  // List of country codes to route to the first origin
  var allowedCountries = ['US', 'CA'];

  // Create the new URI to redirect to
  var newUri = request.uri.replace('/api/', '/api-geo/');

  if (allowedCountries.includes(country.value)) {
    return request;
  } else {
    var response = {
      statusCode: 302,
      statusDescription: 'Found',
      headers: {
        location: {
          value: newUri
        }
      }
    };
    return response;
  }
}

The function checks whether the viewer's country is on the allowedCountries list. If the country is on the list, then the function allows the request to proceed to the /api/ behavior. If the country isn't on the list, then the function redirects the request to the /api-geo/ behavior. To perform the redirect, the function creates a new URI and returns a 302 redirect response.

Prevent caching issues

By default, CloudFront caches responses based on the request URI and certain headers. If you use CloudFront Functions or Lambda@Edge to modify the request URI or headers before they reach the origin, then you might get caching inconsistencies.

To prevent caching issues, take one of the following actions:

• If you must modify requests only before they reach the origin and you want to keep your current caching strategy, then use a Lambda@Edge function. The origin request event must trigger the function. It's a best practice to move the request modification logic to a Lambda@Edge function. The function must run on the origin request trigger that's activated after the cache lookup. The cache key is then based on the original request that comes from the viewer.
• To create separate cache entries based on specific request attributes for more control over caching, create a custom cache policy. Include additional request headers or query strings in the cache key so that you have unique cache keys for different requests.

If you change the caching behavior, then it's a best practice to remove the existing cached files that CloudFront served. Your caching behavior updates can then immediately take effect.

Related information

All distribution settings reference

Cache content based on query string parameters

Leverage Amazon CloudFront geolocation headers for state level geo-targeting