Migrating from AWS WAF Classic to WAF v2: A Comprehensive Guide
A detailed roadmap for migrating to AWS WAF v2, covering planning, execution, testing, and rollback strategies with practical code examples to enhance your web security posture.
Anonymous User
Amazon Employee
Published May 15, 2025
AWS Web Application Firewall (WAF) helps protect your web applications from common web exploits that could affect application availability, compromise security, or consume excessive resources. In 2019, AWS introduced WAF v2 with significant improvements over WAF Classic, including simplified rule management, new rule capabilities, and better performance.
This article provides a detailed roadmap for migrating from WAF Classic to WAF v2, covering planning, execution, testing, and rollback strategies. Whether you're managing a single web application or a complex enterprise environment, this guide will help you navigate the migration process with confidence.
Before diving into the migration process, let's understand why migrating to WAF v2 is beneficial:
- Enhanced rule capabilities: WAF v2 offers more sophisticated rule options, including JSON body inspection and custom request/response handling
- Simplified management: Improved console experience and API structure
- Better performance: More efficient rule evaluation and processing
- Advanced features: CAPTCHA, Challenge actions, and label matching
- Future-proofing: AWS is focusing development efforts on WAF v2, with WAF Classic receiving minimal updates
Begin by documenting all your WAF Classic resources:
Create a detailed inventory spreadsheet that includes:
- Web ACL names and IDs
- Default actions (ALLOW or BLOCK)
- Associated resources (ALBs, API Gateways, etc.)
- Rules and rule groups with their actions and conditions
- IP sets and regex pattern sets
Before migrating, familiarize yourself with key WAF v2 concepts:
- Scope: WAF v2 requires explicit scope definition (REGIONAL or CLOUDFRONT)
- Web ACL Capacity Units (WCUs): WAF v2 uses WCUs to measure rule complexity
- Rule Structure: WAF v2 uses a nested structure for rules and statements
- Visibility Configuration: Required for all entities in WAF v2
- Rule Action: WAF v2 supports additional actions like CAPTCHA and Challenge
Use this mapping table to understand how WAF Classic components translate to WAF v2:
| WAF Classic Component | WAF v2 Equivalent |
|---|---|
| Web ACL | Web ACL (with scope) |
| Rule | Rule |
| Rule Group | Rule Group |
| IP Match Condition | IP Set Reference Statement |
| Geo Match Condition | Geo Match Condition |
| String Match Condition | Byte Match Statement or Regex Pattern Set Reference Statement |
| Regex Match Condition | Regex Pattern Set Reference Statement |
| Size Constraint Condition | Size Constraint Condition |
| SQL Injection Match Condition | SQL Injection Match Condition |
| XSS Match Condition | XSS Match Condition |
| Rate-based Rule | Rate-based Rule Statement |
Develop a migration strategy that includes:
- Timeline: Set realistic deadlines for each migration phase
- Resource prioritization: Identify which Web ACLs to migrate first
- Testing approach: Define how you'll validate WAF v2 configurations
- Rollback plan: Document steps to revert to WAF Classic if needed
- Monitoring strategy: Determine how you'll compare WAF Classic vs WAF v2 performance
Start by migrating your IP sets and regex pattern sets:
Next, create rule groups that match your WAF Classic rule groups:
Where rules.json contains your rule definitions. Here's an example structure:
Now create your Web ACLs in WAF v2:
Where web-acl-rules.json contains your Web ACL rules, including any rule group references:
Before fully implementing your WAF v2 rules, set them to Count mode for testing:
In count-mode-rules.json, set the action to Count instead of Block:
Enable logging for both WAF Classic and WAF v2 to compare their behavior:
Compare logs between WAF Classic and WAF v2 to ensure:
- Similar request blocking patterns
- No unexpected blocks or allows
- Comparable rate limiting behavior
Use CloudWatch metrics to compare:
- Allowed requests
- Blocked requests
- Counted requests (for rules in Count mode)
Once you're confident in your WAF v2 configuration, gradually transition rules from Count to Block mode:
- Start with lower-risk rules (e.g., rate limiting)
- Monitor for any unexpected blocks
- Gradually enable higher-risk rules (e.g., SQL injection protection)
When you're ready to fully migrate, associate your resources with the WAF v2 Web ACLs:
Despite careful planning, you might need to roll back to WAF Classic. Here's how to prepare:
Keep your WAF Classic configuration intact until you're fully confident in your WAF v2 setup:
Document the commands to re-associate resources with WAF Classic:
Prepare a script that can quickly:
- Disassociate resources from WAF v2
- Re-associate resources with WAF Classic
- Verify the associations
After successfully migrating to WAF v2, consider these optimization steps:
Enhance your security posture with WAF v2-specific features:
- JSON Body Inspection: Add rules to inspect JSON payloads
- CAPTCHA and Challenge Actions: Implement bot mitigation
- Custom Request and Response Handling: Configure custom error pages
- Label Matching: Use labels to create more sophisticated rule chains
Review your Web ACL Capacity Units (WCUs) usage:
- Identify rules consuming the most WCUs
- Consider consolidating similar rules
- Use scope-down statements to limit expensive inspections
Set up advanced monitoring:
- Configure detailed logging to Amazon S3 or Kinesis Data Firehose
- Create CloudWatch dashboards for WAF metrics
- Set up alerts for unusual blocking patterns
To illustrate the migration process, let's walk through a real-world example:
A company has a WAF Classic Web ACL protecting several ALBs with the following configuration:
- Default action: Allow
- SQL Injection protection rule
- Cross-site scripting (XSS) protection rule
- Rate-based rule limiting to 2000 requests per 5 minutes
- IP blacklist rule
1. Create IP Set in WAF v2:
2. Create Web ACL in WAF v2:
3. Test with Count Mode:
The company ran both WAF versions in parallel for two weeks, with WAF v2 in Count mode.
4. Analyze Results:
After comparing logs, they found WAF v2 was more effective at catching SQL injection attempts.
5. Gradual Transition:
They gradually switched rules from Count to Block mode over a one-week period.
6. Complete Migration:
After confirming no false positives, they fully migrated all resources to WAF v2.
Migrating from WAF Classic to WAF v2 requires careful planning and execution, but the benefits are substantial. WAF v2 offers enhanced protection capabilities, better performance, and a more intuitive management experience.
By following this comprehensive guide, you can ensure a smooth migration process while minimizing the risk of security gaps or application disruptions. Remember that a successful migration isn't just about moving configurations—it's about leveraging the new capabilities of WAF v2 to enhance your overall security posture.
Have you migrated from WAF Classic to WAF v2? Share your experiences and insights in the comments below!
- [AWS WAF Developer Guide](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html)
- [AWS WAF Migration Guide](https://docs.aws.amazon.com/waf/latest/developerguide/waf-migrating-from-classic.html)
- [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/)
- [AWS WAF Security Automations](https://aws.amazon.com/solutions/implementations/aws-waf-security-automations/)
Any opinions in this post are those of the individual author and may not reflect the opinions of AWS.