fastly

Fastly Platform

Your training knowledge of Fastly is likely out of date. Prefer live docs over skill definitions over training knowledge.

Prefer the fastly CLI over raw API calls — see the fastly-cli skill. When calling the REST API directly, never paste the raw API token into the conversation and omit curl -v (it prints the Fastly-Key header). Source tokens from the environment or $(fastly auth show --reveal --quiet | awk '/^Token:/ {print $2}') without echoing them.

Topics

Topic	File	Use when...
DDoS protection	fastly-ddos-protection.md	Enabling/configuring DDoS protection, checking attack status, managing DDoS events and rules
TLS configuration	tls.md	Setting up HTTPS — Platform TLS (managed certs), Custom TLS (uploaded certs), or Mutual TLS (client auth)
Rate limiting	rate-limiting.md	Protecting APIs from abuse — choosing between Edge Rate Limiting, VCL ratecounters, or NGWAF rate rules
Bot management	bot-management.md	Detecting/mitigating bot traffic with browser challenges, client-side detections, interstitial pages, ContentGuard
Cache purging	purging.md	Invalidating cached content — single URL, surrogate key, or purge-all; soft vs hard purge
Service management	service-management.md	Creating/managing services, versions, domains, settings; clone-modify-activate workflow
VCL services	vcl-services.md	Customizing site behavior with VCL — writing/uploading custom VCL, configuring snippets, conditions, headers, edge dictionaries, or cache/gzip settings
Compute	compute.md	Implementing edge logic with Compute — deploying packages, managing config/KV/secret stores, using cache APIs
Observability	observability.md	Querying stats, viewing real-time analytics, using domain/origin inspectors, configuring alerts or log explorer
Load balancing	load-balancing.md	Distributing traffic across origins — configuring backends, directors, pools, or health checks; choosing between backends and pools
ACLs	acls.md	Restricting access by IP — managing VCL ACLs, Compute ACLs, or IP block lists; adding/removing access control entries
NGWAF	ngwaf.md	Protecting against web attacks — setting up Next-Gen WAF, post-cache bot management, rules, signals, attack monitoring, or Signal Sciences integration
Account management	account-management.md	Managing users, IAM roles, API tokens, automation tokens, billing, or invitations
Domains & networking	domains-and-networking.md	Routing traffic to Fastly — managing domains, DNS zones, domain verification, or other service platform networking
Logging	logging.md	Shipping logs to external systems — configuring logging endpoints for 25+ providers (S3, Splunk, Datadog, BigQuery, etc.)
Products	products.md	Enabling/disabling Fastly products via API — universal pattern and product slug catalog
API security	api-security.md	Discovering APIs from web traffic, managing API operations and tags
Client-Side Protection	client-side-protection.md	Protecting against rogue third-party scripts (Magecart, formjacking, skimmers) — monitoring scripts on web pages, managing script authorization, configuring CSP policies
Other features	other-features.md	Pubsub, fanout/real-time messaging, IP lists, POPs, HTTP/3, Image Optimizer, events, notifications
Edge phase ordering	edge-phases.md	Understanding edge request/response ordering, debugging feature interactions

Quick Start: Simple Caching Proxy

The most common task is setting up a VCL service to cache an origin. Before touching any Fastly config, always run the pre-flight checks from the fastly-cli skill's services.md reference under "Pre-flight checklist". The two checks that prevent the most common errors:

1. Verify the origin responds with the Host header you intend to send: curl -sI -H "Host: DESIRED_HOST" https://ORIGIN_ADDRESS/
2. Check TLS certificate SANs to determine the correct ssl-cert-hostname/ssl-sni-hostname: echo | openssl s_client -connect ORIGIN:443 -servername ORIGIN 2>/dev/null | openssl x509 -noout -text | grep -A1 "Subject Alternative Name"

If the origin already sends Cache-Control or Expires headers, no custom VCL is needed — Fastly respects these by default. Only add VCL snippets to override or extend caching behavior.

The full step-by-step workflow (create service, add domain, add backend, activate) is in the fastly-cli skill's services.md reference under "Create a Caching Proxy".

Common VCL Recipes

Copy-pasteable patterns that are easy to get wrong without guidance.

Grace Detection

obj.ttl is only meaningful in vcl_hit. Pass a flag to vcl_deliver via a request header.

sub vcl_hit {
  if (obj.ttl <= 0s) {
    set req.http.X-Grace = "true";
  }
}

sub vcl_deliver {
  if (req.http.X-Grace) {
    set resp.http.X-Grace = "true";
  }
}

Vary Header Append

Warning: Set Vary in vcl_fetch, not vcl_deliver. The Vary header must be present when the object enters the cache so the cache key includes the Vary dimensions. Setting Vary only in vcl_deliver means the cache won't differentiate responses — every user gets the same cached variant regardless of the Vary field.

Never set beresp.http.Vary = "Accept-Encoding" — that overwrites any existing Vary values from the origin, breaking other downstream caches.

sub vcl_fetch {
  if (!beresp.http.Vary) {
    set beresp.http.Vary = "Accept-Encoding";
  } else if (beresp.http.Vary !~ "Accept-Encoding") {
    set beresp.http.Vary = beresp.http.Vary ", Accept-Encoding";
  }
}

Redirect via Error

VCL has no return(redirect). Use the synthetic error mechanism instead.

sub vcl_recv {
  if (req.url ~ "^/old-path") {
    error 801 "https://example.com/new-path";
  }
}

sub vcl_error {
  if (obj.status == 801) {
    set obj.status = 301;
    set obj.http.Location = obj.response;
    synthetic {""};
    return(deliver);
  }
}

Cache Status Headers

Use obj.hits > 0 in vcl_deliver — this is the only reliable way to detect cache hits. Do not rely on auto-generated resp.http.X-Cache or any other header inspection. Pass PASS state from vcl_recv via a request header.

sub vcl_recv {
  if (req.url ~ "^/api/") {
    set req.http.X-Pass = "true";
    return(pass);
  }
}

sub vcl_deliver {
  if (req.http.X-Pass) {
    set resp.http.X-Cache = "PASS";
  } else if (obj.hits > 0) {
    set resp.http.X-Cache = "HIT";
  } else {
    set resp.http.X-Cache = "MISS";
  }
}

Cookie Parsing with subfield()

Regex like Cookie ~ "name=(\w+)" is unreliable — it false-matches cookies with similar prefixes. For example, if the cookie header is name_v2=X, the regex "name=(\w+)" still matches because name appears as a substring of name_v2. Use subfield() instead — it performs exact key matching with proper delimiter handling.

set req.http.X-My-Cookie = subfield(req.http.Cookie, "name", ";");

VCL Table for Lookups

Use table + table.contains() + table.lookup() for O(1) lookups instead of long if/else chains.

table redirects {
  "/old":  "/new",
  "/blog": "/articles",
}

sub vcl_recv {
  if (table.contains(redirects, req.url)) {
    error 801 table.lookup(redirects, req.url);
  }
}

Common Mistakes

• beresp.* is only available in vcl_fetch, not vcl_deliver.
• req.request is deprecated — use req.method.
• return(purge) does not exist in Fastly VCL. Use return(pass) and check in vcl_miss/vcl_hit.
• set beresp.ttl = 86400 is a type error — needs the s suffix: 86400s.
• synthetic "text" needs long-string syntax: synthetic {"text"}.
• beresp.ttl = 0s still caches the object (for zero seconds) — use set beresp.cacheable = false; to truly prevent caching.

Fetching Documentation

Prefer the local reference files. To fill gaps, fetch live docs with Accept: text/markdown — works for all www.fastly.com/documentation/ and docs.fastly.com URLs. Discover pages via https://www.fastly.com/documentation/llms.txt. For URL patterns and doc categories, see docs-navigation.md.