How R2 works

Cloudflare R2 is an S3-compatible object storage service with no egress fees, built on Cloudflare’s global network. It is strongly consistent and designed for high data durability.

R2 is ideal for storing and serving unstructured data that needs to be accessed frequently over the internet, without incurring egress fees. It’s a good fit for workloads like serving web assets, training AI models, and managing user-generated content.

Architecture

R2’s architecture is composed of multiple components:

• R2 Gateway: The entry point for all API requests that handles authentication and routing logic. This service is deployed across Cloudflare’s global network via Cloudflare Workers.

• Metadata Service: A distributed layer built on Durable Objects used to store and manage object metadata (e.g. object key, checksum) to ensure strong consistency of the object across the storage system. It includes a built-in cache layer to speed up access to metadata.

• Tiered Read Cache: A caching layer that sits in front of the Distributed Storage Infrastructure that speeds up object reads by using Cloudflare Tiered Cache to serve data closer to the client.

• Distributed Storage Infrastructure: The underlying infrastructure that persistently stores encrypted object data.

R2 supports multiple client interfaces including Cloudflare Workers Binding, S3-compatible API, and a REST API that powers the Cloudflare Dashboard and Wrangler CLI. All requests are routed through the R2 Gateway, which coordinates with the Metadata Service and Distributed Storage Infrastructure to retrieve the object data.

Write data to R2

When a write request (e.g. uploading an object) is made to R2, the following sequence occurs:

1. Request handling: The request is received by the R2 Gateway at the edge, close to the user, where it is authenticated.

2. Encryption and routing: The Gateway reaches out to the Metadata Service to retrieve the encryption key and determines which storage cluster to write the encrypted data to within the location set for the bucket.

3. Writing to storage: The encrypted data is written and stored in the distributed storage infrastructure, and replicated within the region (e.g. ENAM) for durability.

4. Metadata commit: Finally, the Metadata Service commits the object’s metadata, making it visible in subsequent reads. Only after this commit is an HTTP 200 success response sent to the client, preventing unacknowledged writes.

Read data from R2

When a read request (e.g. fetching an object) is made to R2, the following sequence occurs:

1. Request handling: The request is received by the R2 Gateway at the edge, close to the user, where it is authenticated.

2. Metadata lookup: The Gateway asks the Metadata Service for the object metadata.

3. Reading the object: The Gateway attempts to retrieve the encrypted object from the tiered read cache. If it’s not available, it retrieves the object from one of the distributed storage data centers within the region that holds the object data.

4. Serving to client: The object is decrypted and served to the user.

Performance

The performance of your operations can be influenced by factors such as the bucket's geographical location, request origin, and access patterns.

To further optimize R2 performance for object read requests, you can enable Cloudflare Cache when using a custom domain. When caching is enabled, read requests can bypass the R2 Gateway Worker and be served directly from Cloudflare’s edge cache, reducing latency. However, note that it may cause consistency trade-offs since cached data may not reflect the latest version immediately.

Learn more

Consistency Learn about R2's consistency model.

Durability Learn more about R2's durability guarantee.

Data location Learn how R2 determines where data is stored, and details on jurisdiction restrictions.

Data security Learn about R2's data security properties.