Azure Appgw

---
name: azure-appgw
description: "Expert coverage of Azure Application Gateway V2 and WAF v2: autoscaling, zone-redundant deployment, URL-based routing, SSL offload, WAF managed rule sets, bot protection, custom rules, Key Vault certificate integration, V1 to V2 migration, and Bicep/Terraform IaC. Use for \"Azure Application Gateway\", \"App Gateway\", \"Azure WAF\", \"WAF v2\", \"Azure load balancer L7\", \"App Gateway V2\", \"V1 EOL\", \"DRS 2.1\", \"Azure SSL offload\". Do NOT use for cross-vendor comparison, platform selection, or category-wide architecture -- use the `load-balancing` skill."
license: MIT
---

# Azure Application Gateway V2

This skill covers Azure Application Gateway V2 and WAF v2. Areas of expertise include:

- V2 architecture: Autoscaling, zone-redundant deployment, static VIP, Key Vault integration
- Routing: URL path-based routing, multi-site hosting, URL rewrite, HTTP-to-HTTPS redirect
- SSL/TLS: SSL offload, end-to-end TLS, mTLS, TLS 1.3, Key Vault certificate rotation
- WAF v2: DRS 2.1/2.2 managed rule sets, custom rules, per-site policies, bot protection, exclusion lists
- Listeners: Basic, multi-site (SNI-based), wildcard hostname
- Backend pools: VM, VMSS, App Service, AKS, IP-based backends
- Rewrite rules: Header rewrite, URL path/query rewrite, server variable access
- Health probes: Custom probes, default probes, probe matching conditions
- V1 EOL: Migration from V1 (EOL April 28, 2026), AzAppGWMigration tooling
- IaC: ARM templates, Bicep, Terraform (azurerm_application_gateway), Azure CLI

## How to Approach Tasks

1. **Classify** the request:
   - **Architecture** -- Load `references/architecture.md` for V2 internals, sizing, AZ deployment
   - **Routing** -- Listener + rule + URL path map configuration
   - **WAF** -- Rule set selection, custom rules, exclusions, per-site policies, bot protection
   - **SSL/TLS** -- Certificate management, Key Vault integration, cipher policy, mTLS
   - **Migration** -- V1 to V2 migration planning, AzAppGWMigration script
   - **Troubleshooting** -- Health probe failures, WAF false positives, routing issues
   - **IaC** -- Bicep, Terraform, ARM template configuration

2. **Confirm V2** -- All new deployments should use V2. If V1 is mentioned, prioritize migration guidance (V1 EOL: April 28, 2026).

3. **Load context** -- Read `references/architecture.md` for deep V2 and WAF knowledge.

4. **Analyze** -- Apply Azure-specific reasoning. Consider subnet sizing (/24 minimum for V2), WAF CU-based pricing, and Azure networking constraints.

5. **Recommend** -- Provide actionable guidance with Azure CLI, Bicep, or Terraform templates.

6. **Verify** -- Suggest validation (health probe status, WAF logs, Application Gateway metrics in Azure Monitor).

## V2 Architecture

### Key V2 Capabilities

| Capability | V1 | V2 |
|---|---|---|
| **Autoscaling** | Manual instance count | Automatic (0-125 instances) |
| **Zone redundancy** | No | Yes (spans multiple AZs) |
| **Static VIP** | VIP could change on restart | Stable frontend IP |
| **Key Vault** | Manual cert upload | Automatic cert rotation from Key Vault |
| **HTTP/2** | Limited | Full end-to-end support |
| **Performance** | Fixed capacity | Scale to handle traffic spikes |
| **Header rewrite** | No | Yes (request and response) |
| **Custom error pages** | No | Yes (4xx/5xx) |

### Subnet Requirements

- V2 requires a **dedicated subnet** with minimum size **/24** (recommended /24)
- No other resources can be deployed in the App Gateway subnet
- Network Security Group (NSG) must allow: GatewayManager service tag, inbound 65200-65535 (management)
- V1 used smaller subnets; migration requires subnet change

## Routing

### Listeners

| Type | Description | Use Case |
|---|---|---|
| **Basic** | Single hostname (or any); catches all requests to frontend IP:port | Single-site deployments |
| **Multi-site** | Specific hostname; SNI-based routing | Multiple sites on same App Gateway |
| **Wildcard** | Wildcard hostname (`*.example.com`) | Wildcard certificate hosting |

### Rules

| Type | Description |
|---|---|
| **Basic rule** | Listener -> backend pool (no URL-based routing) |
| **Path-based rule** | Listener -> URL path map -> multiple backend pools |

### Path-Based Routing

```
Listener: https://app.example.com:443
  |
  +-- /images/* -> images-backend-pool
  +-- /video/*  -> video-backend-pool
  +-- /api/*    -> api-backend-pool
  +-- default   -> web-backend-pool
```

### URL Rewrite

Rewrite rules modify request/response before forwarding:

- **URL path rewrite** -- Change `/old-api/v1/*` to `/api/v1/*`
- **Query string rewrite** -- Add, modify, or remove query parameters
- **Header rewrite** -- Add/remove/modify request and response headers
- **Server variables** -- Access `var_host`, `var_uri`, `var_request_query` in rewrite expressions

### Redirect

| Type | Description |
|---|---|
| **Permanent (301)** | HTTP to HTTPS redirect |
| **Temporary (302)** | Maintenance redirect |
| **External** | Redirect to external URL |
| **Path-based** | Redirect specific paths |

## SSL/TLS

### SSL Offload

```
Client ---[HTTPS/TLS 1.3]--> App Gateway ---[HTTP]--> Backend Pool
                                   |
                          SSL terminated here
                          WAF inspection possible
```

### End-to-End TLS

```
Client ---[HTTPS]--> App Gateway ---[HTTPS]--> Backend Pool
                          |
                  Decrypt, inspect (WAF), re-encrypt
```

- Backend authentication: Validate backend server certificate
- Allow self-signed backend certs by uploading root CA
- Or use trusted CA certificates (no upload needed for public CAs)

### Key Vault Integration

- TLS certificates stored in Azure Key Vault
- App Gateway automatically fetches certificate on creation
- **Automatic rotation**: App Gateway polls Key Vault every 4 hours; rotates certificate when new version detected
- Managed identity required for Key Vault access (system-assigned or user-assigned)

### TLS Policy

| Policy | Min TLS | Cipher Suites |
|---|---|---|
| **AppGwSslPolicy20220101** | TLS 1.2 | Modern ciphers only |
| **AppGwSslPolicy20220101S** | TLS 1.2 | Strict (no CBC) |
| **CustomV2** | Configurable | Select individual ciphers |

### Mutual TLS (mTLS)

- Client certificate validation at the App Gateway
- Upload trusted client CA certificate
- Client cert info forwarded to backend via headers
- Use cases: Zero Trust, B2B API authentication

## WAF v2

### Managed Rule Sets

| Rule Set | Base | Status |
|---|---|---|
| **DRS 2.1** | OWASP CRS 3.3 + Microsoft additions | Recommended (current default) |
| **DRS 2.2** | OWASP CRS 3.3.4 + refinements | Latest available |
| **CRS 3.2** | OWASP CRS 3.2 | Legacy (still supported) |
| **CRS 3.1 / 2.2.9** | Older OWASP | Deprecated for new policies |

### WAF Policy Model

- **WAF Policy** -- Standalone Azure resource; contains rule sets and custom rules
- **Per-site policy** -- Different WAF policies for different hostnames on same App Gateway
- **Per-listener association** -- Attach policy to specific listener for granular control
- **Global association** -- Attach policy to entire App Gateway

### WAF Modes

| Mode | Behavior |
|---|---|
| **Detection** | Log violations but do not block (learning mode) |
| **Prevention** | Block requests matching rules (enforcement mode) |

**Best practice**: Deploy in Detection mode for 2-4 weeks, analyze logs, create exclusions for false positives, then switch to Prevention mode.

### Custom Rules

Custom rules evaluate **before** managed rule sets:

```json
{
  "name": "BlockBadIPs",
  "priority": 1,
  "ruleType": "MatchRule",
  "matchConditions": [
    {
      "matchVariable": "RemoteAddr",
      "operator": "IPMatch",
      "matchValues": ["203.0.113.0/24", "198.51.100.0/24"]
    }
  ],
  "action": "Block"
}
```

### Match Variables

| Variable | Description |
|---|---|
| `RemoteAddr` | Client IP address |
| `RequestMethod` | HTTP method |
| `RequestUri` | Full request URI |
| `RequestHeaders` | Specific header (e.g., `User-Agent`) |
| `RequestBody` | POST body content |
| `RequestCookies` | Cookie values |
| `QueryString` | URL query string |
| `PostArgs` | POST form parameters |
| `GeoLocation` | Client country code |

### Bot Protection

- **Bot Manager Rule Set** -- Microsoft-maintained bot classification
- **Bad bots**: Scrapers, attackers -> Block
- **Good bots**: Googlebot, Bingbot -> Allow
- **Unknown bots**: Configurable (Log, Block)
- Requires DRS 3.2+ or Bot Manager 1.0+
- Available in both Prevention and Detection modes

### Exclusion Lists

Prevent false positives by excluding specific request attributes from WAF inspection:

- **Scope**: Per rule group or per individual rule ID
- **Variables**: Request header, cookie, query string argument, request body field
- **Match type**: Equals, starts with, ends with, contains

```json
{
  "matchVariable": "RequestHeaderNames",
  "selectorMatchOperator": "Equals",
  "selector": "X-Custom-Token",
  "exclusionManagedRuleSets": [
    {
      "ruleSetType": "Microsoft_DefaultRuleSet",
      "ruleSetVersion": "2.1",
      "ruleGroups": [
        {
          "ruleGroupName": "REQUEST-942-APPLICATION-ATTACK-SQLI",
          "rules": [{ "ruleId": "942100" }]
        }
      ]
    }
  ]
}
```

## Health Probes

### Default Probes

If no custom probe is configured, App Gateway sends default probes:

- **Protocol**: Same as backend HTTP setting
- **Path**: `/`
- **Interval**: 30 seconds
- **Timeout**: 30 seconds
- **Unhealthy threshold**: 3

### Custom Probes

```json
{
  "name": "api-health-probe",
  "protocol": "Https",
  "host": "api.example.com",
  "path": "/healthz",
  "interval": 15,
  "timeout": 10,
  "unhealthyThreshold": 3,
  "match": {
    "statusCodes": ["200-299"],
    "body": "\"status\":\"healthy\""
  }
}
```

### Probe Best Practices

- Always configure custom probes (default probe uses `/` which may be slow or require auth)
- Match body content for deeper health validation
- Set interval to 15-30 seconds (balance between detection speed and backend load)
- Use the same hostname in probe as in backend HTTP setting

## Backend Pools

| Target Type | Description |
|---|---|
| **VM/VMSS** | Azure Virtual Machines or Scale Sets |
| **App Service** | Azure Web Apps (use FQDN, not IP) |
| **AKS** | Azure Kubernetes Service pods (via AGIC) |
| **IP address** | On-premises servers via VPN/ExpressRoute |
| **FQDN** | DNS-resolvable hostname |

### Application Gateway Ingress Controller (AGIC)

- Kubernetes Ingress Controller that programs Azure App Gateway
- Watches Ingress resources; translates to App Gateway configuration
- Supports: path-based routing, SSL termination, WAF, health probes
- Deployed as AKS add-on or Helm chart

## V1 End of Life

**Azure Application Gateway V1 EOL: April 28, 2026.**

### Migration Planning

1. **Assess V1 configuration** -- Document listeners, rules, backend pools, WAF config, SSL certs
2. **Provision V2 subnet** -- V2 requires /24 dedicated subnet (V1 used smaller)
3. **Run AzAppGWMigration** -- PowerShell module for automated migration
4. **Test V2 configuration** -- Verify routing, WAF behavior, SSL, health probes
5. **Update DNS/Traffic Manager** -- Point traffic to new V2 VIP
6. **Decommission V1** -- Remove V1 after validation period

### Key Migration Differences

| Aspect | V1 | V2 |
|---|---|---|
| **Subnet** | Smaller subnets OK | /24 minimum required |
| **Pricing** | Fixed size tiers | CU-based (consumption) |
| **WAF** | Embedded WAF config | Standalone WAF Policy resource |
| **VIP** | Could change | Static VIP |
| **Autoscale** | Manual | Automatic |

### AzAppGWMigration PowerShell

```powershell
Install-Module -Name AzureAppGWMigration
Import-Module AzureAppGWMigration

# Validate V1 gateway
Test-AzAppGWMigration -AppGatewayName "v1-appgw" -ResourceGroupName "rg-network"

# Migrate
Start-AzAppGWMigration -AppGatewayName "v1-appgw" -ResourceGroupName "rg-network" `
  -SubnetId "/subscriptions/.../subnets/appgw-v2-subnet"
```

## Common Pitfalls

1. **Subnet too small** -- V2 requires /24 minimum. Deploying in a smaller subnet causes provisioning failures or scaling limitations.

2. **NSG blocking management traffic** -- V2 requires inbound access on ports 65200-65535 from GatewayManager service tag. Missing this rule causes App Gateway health degradation.

3. **WAF in Detection mode permanently** -- Detection mode provides monitoring but zero protection. After tuning exclusions, switch to Prevention mode.

4. **Default health probe on complex apps** -- Default probe hits `/` which may redirect, require auth, or timeout. Always configure custom health probes.

5. **Key Vault access denied** -- App Gateway managed identity must have `Get` and `List` permissions on Key Vault secrets and certificates. Missing permissions cause certificate fetch failures.

6. **Ignoring V1 EOL** -- V1 gateways will be retired after April 28, 2026. Start migration planning immediately if running V1.

7. **Per-site WAF policy not applied** -- WAF policies must be explicitly associated with listeners or the App Gateway. An unassociated policy has no effect.

8. **Backend using self-signed certs without root CA upload** -- End-to-end TLS with self-signed backend certs requires uploading the root CA certificate to App Gateway. Without it, backend health probes fail.

## Reference Files

Load these when you need deep knowledge:

- `references/architecture.md` -- V2 internals, WAF rule set details, SSL architecture, routing mechanics, V1 migration details. Read for "how does X work" questions.