Skip to content

Fastly Migration

Jump to bottom
Griffen Fargo edited this page Aug 20, 2026 · 1 revision

Fastly Migration

Guide for migrating firewall rules from Vercel Firewall to Fastly Next-Gen WAF using Doorman.

⚠️ Not yet available: doorman migrate does not exist in the current CLI. It's a spec'd, unbuilt roadmap item ("Phase 6" in RELEASE-2.0.md). Running any doorman migrate ... command shown below will fail with unknown command: migrate.

This page documents the planned automated migration workflow so you know what's coming. For migrating today, see Manual Migration (Available Now) below — you'll use doorman download, hand-edit the config using the Configuration reference and the compatibility matrix below, then doorman validate/doorman sync --provider fastly.

Before You Begin

  • Complete the Fastly Setup guide first
  • Back up your current Vercel configuration
  • Review the compatibility matrix below — some features don't translate 1:1

Important: Always test in a staging workspace before applying to production.

Compatibility Matrix

Feature Vercel Fastly Translation
Path/method/host matching ✅ ✅ Direct
Header/query/cookie matching ✅ ✅ Modified — becomes a multival condition requiring a key (the name), not a plain single condition
IP blocking ✅ ✅ Modified — becomes two workspace lists (doorman-managed-deny/doorman-managed-allow), replaced wholesale rather than per-IP rules. hostname/notes are dropped
User agent matching ✅ ✅ Direct
Country-level geo-blocking ✅ ✅ Direct
City/region/continent geo-blocking ✅ ❌ Removed — Fastly only exposes country-level geo matching
Rate limiting ✅ ✅ Modified — distinct rule type with its own config, and requires a pre-existing custom signal Doorman doesn't create automatically
Redirects ✅ ✅ Direct
Challenge actions ✅ Basic ✅ Maps to browser_challenge
Regex matching ✅ ✅ Direct, but Fastly's regex syntax may differ slightly — review after migrating
Rule evaluation order Best-effort (insertion order) ❌ Removed — Next-Gen WAF rules are evaluated independently, priority has no effect
Environment conditions ✅ ❌ Removed (Vercel-specific)
JA3/JA4 fingerprints ✅ ⚠️ Not yet mapped Fastly exposes a JA3 condition field, but Doorman's translator doesn't map it yet
Strict greater-than / less-than ✅ ⚠️ Approximated Fastly only has >=/<= — the boundary value also matches

Manual Migration (Available Now)

Until doorman migrate ships, migrate by hand using commands that exist today:

1. Back Up and Download Your Current Vercel Config

doorman backup
doorman download --provider vercel --config vercel-current.json

2. Hand-Translate to a Fastly Config

Open vercel-current.json and, using the Configuration reference and the compatibility matrix above, write out the equivalent rules in a new file (e.g. fastly.config.json) with "provider": "fastly" and Fastly-shaped conditions/actions. This is the step the planned migrate command will eventually automate.

3. Validate and Preview

doorman validate --config fastly.config.json
doorman sync --config fastly.config.json --provider fastly --dry-run

4. Sync to a Staging Workspace, Then Production

doorman sync --config fastly.config.json --provider fastly

Verify in the Fastly Next-Gen WAF control panel's Rules view, first against a staging workspace/token if you have one, then repeat against production once you're confident.

Migration Steps (Planned — Not Yet Available)

The rest of this page describes the automated doorman migrate workflow once it ships (see the roadmap warning at the top of this page).

1. Back Up

doorman backup
doorman export --format json --output vercel-backup.json

2. Preview the Migration

doorman migrate --from vercel --to fastly --dry-run

This shows which rules will migrate perfectly, which will be modified, and which can't migrate. No changes are made.

3. Generate the Fastly Config

doorman migrate --from vercel --to fastly --output fastly.config.json

The generated file includes:

  • Translated rules with Fastly provider settings
  • Migration metadata (source, date, warnings)
  • Notes on any rules that were modified or dropped

4. Review and Validate

Open fastly.config.json and review the translated rules, then:

doorman validate --config fastly.config.json
doorman status --config fastly.config.json

5. Test in Staging

doorman sync --config fastly.config.json --provider fastly

Verify in the Fastly Next-Gen WAF control panel's Rules view.

6. Deploy to Production

doorman sync --config fastly.config.json --provider fastly
doorman status --config fastly.config.json

7. Monitor

  • Check the workspace's request/event views in the Fastly control panel
  • Watch for false positives in the first few days
  • Adjust rules based on real traffic patterns

Handling Common Translation Changes

Header, Query, and Cookie Conditions

Vercel/unified conditions on header, query, or cookie need a key (the specific name to match) to translate to Fastly — a condition missing one is dropped with a warning rather than mistranslated:

// Works — has a key
{ "type": "header", "op": "eq", "value": "internal", "key": "X-Access-Level" }

// Dropped during translation — no key to match on
{ "type": "header", "op": "eq", "value": "internal" }

Rate Limiting Needs a Signal

Rate-limit rules translate automatically, but Fastly requires a custom signal to already exist in the workspace to count against. Create one named doorman-rate-limit-<rule-id> before syncing, or the rule will be rejected.

Geo-Blocking Below Country Level

Fastly has no equivalent to Vercel's geo_city/geo_continent/geo_country_region conditions — only geo_country. Rules using the finer-grained conditions need to be redesigned around country-level matching, or replicated using a different signal (e.g. an IP list).

Environment Conditions Removed

Fastly doesn't have an equivalent to Vercel's environment condition. Options:

  • Use separate config files per environment
  • Use workspace-based separation (different Fastly workspaces for staging vs production)

Rollback

Restore from Backup

doorman backup --list
doorman backup --restore backup-file.json
doorman sync --provider vercel

Reverse Migration

Not automated yet either (same doorman migrate roadmap item). Use the same manual approach as the forward migration: doorman download --provider fastly --config fastly-current.json, hand-translate to a Vercel-shaped config, then doorman validate/doorman sync --provider vercel.

Note: Fastly → Vercel translation has some limitations, especially around rules Fastly's translator only partially maps (e.g. rate limiting, multival conditions). Review the output carefully.

Gradual Migration

For large rule sets, consider migrating in phases:

  1. Critical security rules (bot blocking, IP blocking)
  2. Rate limiting rules (after the required signals exist)
  3. Remaining rules
  4. Optimize for Fastly-specific features

Post-Migration Checklist

  • All critical rules active in the Fastly workspace
  • IP blocking working correctly (check the doorman-managed-deny/doorman-managed-allow lists)
  • Rate limiting functioning as expected, with signals created
  • No false positives in legitimate traffic
  • Fastly's request/event views showing expected rule triggers
  • Team trained on Fastly-specific workflows
  • CI/CD pipelines updated for the Fastly provider
  • Backup procedures updated

Related Pages

Getting Started

Configuration

Commands

Guides

Clone this wiki locally