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 for installation and local authentication. REST examples require curl and network access to Fastly APIs; origin TLS checks also require openssl.

Use the user's locally configured credentials. If authentication is missing, direct the user to local CLI login or environment configuration, never to paste an API key in chat. For REST calls, source tokens from the environment or $(fastly auth token) without echoing them. Omit curl -v and shell tracing because they print credentials.

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	TTFB percentiles from the metrics platform, alert definitions and history, log explorer queries
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

Traffic numbers are not in this table. Cache hit ratio, bandwidth, request and status-code counts, error rates, real-time request rate, origin latency, per-domain traffic, account usage and billing totals belong to the fastly-stats skill.

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 HTTPS cert validation cannot be made correct but HTTP with the intended Host works, use an HTTP backend or fix the origin cert; never disable backend cert verification as the workaround.

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.