Fastly S3 Integration

Tutorial for Fastly integration with S3 to deliver and cache assets (text files, images and other binaries) stored in multiple S3 buckets through the Fastly CDN using the following setup:

The main goal of this tutorial is to describe how to set up a Fastly service to implement the following request forwarding schema:


Which is based on S3 virtual hosted-style URLs, instead of using the path-style URLs, which will be soon deprecated by AWS.

Fastly Service Setup

Manual Setup

Perform the following steps in Fastly:

  1. Create a new service.

  2. Create a domain (or several) for the service. A free TLS option provided by Fastly can be used entering <name> as domain name.

  3. Create an origin host for the desired S3 regional endpoint (s3.<aws_region>

  4. Create the regular VCL snippets described below:

    • Name => Parse URL
    • Priority => 100
    • Type => recv (within subroutine -> recv (vcl_recv))
    • VCL:
     if (req.url ~ "/([^/]+)/(.*)$") {
       set req.http.X-Bucket =;
       set req.url = "/";
    • Name => Set S3 Bucket Host
    • Priority => 100
    • Type => miss (within subroutine -> miss (vcl_miss))
    • VCL:
     if (req.http.X-Bucket) {
       set = req.http.X-Bucket ".s3.<aws_region>";

IaC Setup through Terraform

  1. Download the configuration file in the path you want:

    $ wget
  2. Execute the following commands from the folder in which the configuration file has been downloaded:

    $ export FASTLY_API_KEY=<account_api_key>
    $ terraform apply [-var fastly_service_name=<custom_name>] [-var fastly_domain=<custom_domain>] [-var aws_region=<region_code>]

Example VCL File

An example VCL file is included in this project so that it can be used as reference.

* IMPORTANT: This example VCL file is not suitable to be directly uploaded as a custom VCL file to an existing Fastly service (Uploading custom VCL).