fastly

What this skill does

# 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](references/fastly-ddos-protection.md) | Enabling/configuring DDoS protection, checking attack status, managing DDoS events and rules                                                                              |
| TLS configuration      | [tls.md](references/tls.md)                                       | Setting up HTTPS — Platform TLS (managed certs), Custom TLS (uploaded certs), or Mutual TLS (client auth)                                                                 |
| Rate limiting          | [rate-limiting.md](references/rate-limiting.md)                   | Protecting APIs from abuse — choosing between Edge Rate Limiting, VCL ratecounters, or NGWAF rate rules                                                                   |
| Bot management         | [bot-management.md](references/bot-management.md)                 | Detecting/mitigating bot traffic with browser challenges, client-side detections, interstitial pages, ContentGuard                                                        |
| Cache purging          | [purging.md](references/purging.md)                               | Invalidating cached content — single URL, surrogate key, or purge-all; soft vs hard purge                                                                                 |
| Service management     | [service-management.md](references/service-management.md)         | Creating/managing services, versions, domains, settings; clone-modify-activate workflow                                                                                   |
| VCL services           | [vcl-services.md](references/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](references/compute.md)                               | Implementing edge logic with Compute — deploying packages, managing config/KV/secret stores, using cache APIs                                                             |
| Observability          | [observability.md](references/observability.md)                   | Querying stats, viewing real-time analytics, using domain/origin inspectors, configuring alerts or log explorer                                                           |
| Load balancing         | [load-balancing.md](references/load-balancing.md)                 | Distributing traffic across origins — configuring backends, directors, pools, or health checks; choosing between backends and pools                                       |
| ACLs                   | [acls.md](references/acls.md)                                     | Restricting access by IP — managing VCL ACLs, Compute ACLs, or IP block lists; adding/removing access control entries                                                     |
| NGWAF                  | [ngwaf.md](references/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](references/account-management.md)         | Managing users, IAM roles, API tokens, automation tokens, billing, or invitations                                                                                         |
| Domains & networking   | [domains-and-networking.md](references/domains-and-networking.md) | Routing traffic to Fastly — managing domains, DNS zones, domain verification, or other service platform networking                                                        |
| Logging                | [logging.md](references/logging.md)                               | Shipping logs to external systems — configuring logging endpoints for 25+ providers (S3, Splunk, Datadog, BigQuery, etc.)                                                 |
| Products               | [products.md](references/products.md)                             | Enabling/disabling Fastly products via API — universal pattern and product slug catalog                                                                                   |
| API security           | [api-security.md](references/api-security.md)                     | Discovering APIs from web traffic, managing API operations and tags                                                                                                       |
| Client-Side Protection | [client-side-protection.md](references/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](references/other-features.md)                 | Pubsub, fanout/real-time messaging, IP lists, POPs, HTTP/3, Image Optimizer, events, notifications                                                                        |
| Edge phase ordering    | [edge-phases.md](references/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.

```vcl
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 dimensi