1# Cloudflare Cache Reserve
2 
3**Persistent cache storage built on R2 for long-term content retention**
4 
5## Smart Shield Integration
6 
7Cache Reserve is part of **Smart Shield**, Cloudflare's comprehensive security and performance suite:
8 
9- **Smart Shield Advanced tier**: Includes 2TB Cache Reserve storage
10- **Standalone purchase**: Available separately if not using Smart Shield
11- **Migration**: Existing standalone customers can migrate to Smart Shield bundles
12 
13**Decision**: Already on Smart Shield Advanced? Cache Reserve is included. Otherwise evaluate standalone purchase vs Smart Shield upgrade.
14 
15## Overview
16 
17Cache Reserve is Cloudflare's persistent, large-scale cache storage layer built on R2. It acts as the ultimate upper-tier cache, storing cacheable content for extended periods (30+ days) to maximize cache hits, reduce origin egress fees, and shield origins from repeated requests for long-tail content.
18 
19## Core Concepts
20 
21### What is Cache Reserve?
22 
23- **Persistent storage layer**: Built on R2, sits above tiered cache hierarchy
24- **Long-term retention**: 30-day default retention, extended on each access
25- **Automatic operation**: Works seamlessly with existing CDN, no code changes required
26- **Origin shielding**: Dramatically reduces origin egress by serving cached content longer
27- **Usage-based pricing**: Pay only for storage + read/write operations
28 
29### Cache Hierarchy
30 
31```
32Visitor Request
33    ↓
34Lower-Tier Cache (closest to visitor)
35    ↓ (on miss)
36Upper-Tier Cache (closest to origin)
37    ↓ (on miss)
38Cache Reserve (R2 persistent storage)
39    ↓ (on miss)
40Origin Server
41```
42 
43### How It Works
44 
451. **On cache miss**: Content fetched from origin �� written to Cache Reserve + edge caches simultaneously
462. **On edge eviction**: Content may be evicted from edge cache but remains in Cache Reserve
473. **On subsequent request**: If edge cache misses but Cache Reserve hits → content restored to edge caches
484. **Retention**: Assets remain in Cache Reserve for 30 days since last access (configurable via TTL)
49 
50## When to Use Cache Reserve
51 
52```
53Need persistent caching?
54├─ High origin egress costs → Cache Reserve ✓
55├─ Long-tail content (archives, media libraries) → Cache Reserve ✓
56├─ Already using Smart Shield Advanced → Included! ✓
57├─ Video streaming with seeking (range requests) → ✗ Not supported
58├─ Dynamic/personalized content → ✗ Use edge cache only
59├─ Need per-request cache control from Workers → ✗ Use R2 directly
60└─ Frequently updated content (< 10hr lifetime) → ✗ Not eligible
61```
62 
63## Asset Eligibility
64 
65Cache Reserve only stores assets meeting **ALL** criteria:
66 
67- Cacheable per Cloudflare's standard rules
68- Minimum 10-hour TTL (36000 seconds)
69- `Content-Length` header present
70- Original files only (not transformed images)
71 
72### Eligibility Checklist
73 
74Use this checklist to verify if an asset is eligible:
75 
76- [ ] Zone has Cache Reserve enabled
77- [ ] Zone has Tiered Cache enabled (required)
78- [ ] Asset TTL ≥ 10 hours (36,000 seconds)
79- [ ] `Content-Length` header present on origin response
80- [ ] No `Set-Cookie` header (or uses private directive)
81- [ ] `Vary` header is NOT `*` (can be `Accept-Encoding`)
82- [ ] Not an image transformation variant (original images OK)
83- [ ] Not a range request (no HTTP 206 support)
84- [ ] Not O2O (Orange-to-Orange) proxied request
85 
86**All boxes must be checked for Cache Reserve eligibility.**
87 
88### Not Eligible
89 
90- Assets with TTL < 10 hours
91- Responses without `Content-Length` header
92- Image transformation variants (original images are eligible)
93- Responses with `Set-Cookie` headers
94- Responses with `Vary: *` header
95- Assets from R2 public buckets on same zone
96- O2O (Orange-to-Orange) setup requests
97- **Range requests** (video seeking, partial content downloads)
98 
99## Quick Start
100 
101```bash
102# Enable via Dashboard
103https://dash.cloudflare.com/caching/cache-reserve
104# Click "Enable Storage Sync" or "Purchase" button
105```
106 
107**Prerequisites:**
108- Paid Cache Reserve plan or Smart Shield Advanced required
109- Tiered Cache required for optimal performance
110 
111## Essential Commands
112 
113```bash
114# Check Cache Reserve status
115curl -X GET "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/cache/cache_reserve" \
116  -H "Authorization: Bearer $API_TOKEN"
117 
118# Enable Cache Reserve
119curl -X PATCH "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/cache/cache_reserve" \
120  -H "Authorization: Bearer $API_TOKEN" \
121  -H "Content-Type: application/json" \
122  -d '{"value": "on"}'
123 
124# Check asset cache status
125curl -I https://example.com/asset.jpg | grep -i cache
126```
127 
128## In This Reference
129 
130| Task | Files |
131|------|-------|
132| Evaluate if Cache Reserve fits your use case | README.md (this file) |
133| Enable Cache Reserve for your zone | README.md + [configuration.md](./configuration.md) |
134| Use with Workers (understand limitations) | [api.md](./api.md) |
135| Setup via SDKs or IaC (TypeScript, Python, Terraform) | [configuration.md](./configuration.md) |
136| Optimize costs and debug issues | [patterns.md](./patterns.md) + [gotchas.md](./gotchas.md) |
137| Understand eligibility and troubleshoot | [gotchas.md](./gotchas.md) → [patterns.md](./patterns.md) |
138 
139**Files:**
140- [configuration.md](./configuration.md) - Setup, API, SDKs, and Cache Rules
141- [api.md](./api.md) - Purging, monitoring, Workers integration
142- [patterns.md](./patterns.md) - Best practices, cost optimization, debugging
143- [gotchas.md](./gotchas.md) - Common issues, limitations, troubleshooting
144 
145## See Also
146- [r2](../r2/) - Cache Reserve built on R2 storage
147- [workers](../workers/) - Workers integration with Cache API
148