How to manage your own Fastly configuration (custom VCL)

Updated March 12, 2026 05:29

If your project utilizes an Upsun-provided Fastly CDN service, it comes pre-configured with basic optimizations and protections appropriate for your application type.

However, if you need to add application-specific caching rules, bot restrictions, or custom Varnish Configuration Language (VCL) snippets, you must manage these directly via the Fastly API. Because this is considered application logic, the Upsun support team does not write, debug, or support custom VCL.

⚠️ Important: Always test VCL changes on your staging or development branches first. Incorrect VCL can break your site or misroute live traffic. All environments with Fastly attached to production also have a separate Fastly service attached to staging for testing.

Prerequisites

To interact with Fastly, you will need:

The upsun CLI installed and authenticated.
The jq utility installed on your local machine.
(Recommended) The official Fastly CLI tool installed locally.

Step 1: Retrieve Fastly Credentials

Upsun securely injects your Fastly credentials into your application container as environment variables: $FASTLY_API_SERVICE and $FASTLY_API_TOKEN.

You can extract these directly into your local terminal session using the Upsun CLI:

Bash

# Fetch and export the Fastly credentials to your local terminal
export FASTLY_API_SERVICE=$(upsun ssh "echo \$FASTLY_API_SERVICE" | tr -d '[:space:]')
export FASTLY_API_TOKEN=$(upsun ssh "echo \$FASTLY_API_TOKEN" | tr -d '[:space:]')

Step 2: View Your Current VCL

Before making changes, it is highly recommended to download and review the current VCL that Upsun generated for you.

You can use curl to fetch the active VCL and save it locally as generated.vcl:

Bash

curl -s -H "Fastly-Key: $FASTLY_API_TOKEN" \
"https://api.fastly.com/service/${FASTLY_API_SERVICE}/version/active/generated_vcl" \
| jq -r ".content" > generated.vcl

Step 3: Modify Fastly Configuration

The safest and most efficient way to manipulate your Fastly service is using the Fastly CLI, rather than raw API calls.

Setup for Fastly CLI

The Fastly CLI looks for a specific environment variable named FASTLY_SERVICE_ID. Since Upsun exposes this as FASTLY_API_SERVICE, you will need to map it over:

Bash

export FASTLY_SERVICE_ID=$FASTLY_API_SERVICE

Safe Deployment Workflow

Fastly services are versioned. You cannot edit an "active" version. The standard workflow to add a custom VCL snippet is: Clone -> Edit -> Activate.

Bash

# 1. Clone the currently active version to create a new draft
fastly service-version clone --version=active

# 2. Upload your custom VCL snippet to the new draft version (replace "latest" with the draft version number if needed)
fastly vcl snippet create --version=latest --name="My Custom Rule" --content="./my_custom_rule.vcl"

# 3. Activate the new version to deploy your rules
fastly service-version activate --version=latest

Advanced: Managing IP Blocklists (ACLs)

If your support plan includes automated bot flood protection, Upsun may attach an Access Control List (ACL) to your production Fastly service, typically named Generated_by_IP_block_list.

You can interact with this ACL to view or manage blocked IPs via the Fastly API.

1. Find the ACL ID:

Bash

FASTLY_SERVICE_VERSION=$(curl -s -H "Fastly-Key: $FASTLY_API_TOKEN" "https://api.fastly.com/service/${FASTLY_API_SERVICE}/details" | jq -r ".active_version.number")

ACL_ID=$(curl -s -H "Fastly-Key: $FASTLY_API_TOKEN" "https://api.fastly.com/service/${FASTLY_API_SERVICE}/version/${FASTLY_SERVICE_VERSION}/acl/Generated_by_IP_block_list" | jq -r ".id")

2. List Blocked IPs:

Bash

curl -s -H "Fastly-Key: $FASTLY_API_TOKEN" \
"https://api.fastly.com/service/${FASTLY_API_SERVICE}/acl/${ACL_ID}/entries" \
| jq -r ".[] | {\"id\": .id, \"ip\": .ip, \"comment\": .comment } "

3. Manually Add an IP to the Blocklist:

Bash

curl -X POST -s -H "Fastly-Key: $FASTLY_API_TOKEN" \
-H "Content-Type: application/json" -H "Accept: application/json" \
"https://api.fastly.com/service/${FASTLY_API_SERVICE}/acl/${ACL_ID}/entry" \
-d '{"ip":"192.168.0.1", "comment":"Manual block"}'