> For the complete documentation index, see [llms.txt](https://docs.warpstream.com/warpstream/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.warpstream.com/warpstream/agent-setup/different-object-stores/multi-buckets.md).

# Multi Buckets

Combine several object storage buckets into one logical bucket that replicates writes across them for durability and availability.

A **multi bucket** combines several object storage buckets into a single logical bucket by **replicating** every write across them. It is a durability and availability feature: because each file is written to a quorum of buckets, the cluster can lose a full bucket (for example, an entire cloud region's object storage) without losing data or availability.

Multi buckets are configured through the same `-bucketURL` flag (`WARPSTREAM_BUCKET_URL`) as a normal single bucket — you just pass a `warpstream_multi://` URL instead of a plain `s3://` (or other provider) URL.

{% hint style="info" %}
If your goal is to scale **write throughput** past a single bucket's request-rate ceiling rather than to add redundancy, see [Striped Buckets](/warpstream/agent-setup/different-object-stores/striped-buckets.md) instead. Multi buckets replicate every object (N× storage and write cost); striped buckets store each object once.
{% endhint %}

## URL format

```
warpstream_multi://$BUCKET_1_URL<>$BUCKET_2_URL<>...<>$BUCKET_N_URL
```

The sub-buckets are separated by `<>`, and each sub-URL is constructed exactly as described on the [Object Storage Configuration](/warpstream/agent-setup/different-object-stores.md#bucket-url-construction) page. Any combination of providers and regions is allowed, though most deployments use the same provider across regions.

For example, three buckets spread across three AWS regions:

{% code overflow="wrap" %}

```bash
-bucketURL "warpstream_multi://s3://bucket-a?region=us-east-1<>s3://bucket-b?region=us-west-2<>s3://bucket-c?region=us-east-2"
```

{% endcode %}

## How it works

* **Writes** are sent to all sub-buckets and acknowledged as soon as a quorum (a majority) succeed, so a single slow or unavailable bucket does not block writes.
* **Reads** can be served from any sub-bucket that holds the file, so losing one bucket does not make data unreadable.

The net effect is that a multi bucket tolerates the loss of a minority of its sub-buckets with no data loss and no downtime.

## Primary use case: multi-region data planes

The most common reason to use a multi bucket is to spread a cluster's data plane across multiple cloud regions so it can survive a region-wide object storage outage with a Recovery Point Objective of 0. See [Multi-Region Clusters](/warpstream/kafka/advanced-agent-deployment-options/multi-region.md) for how this pairs with a multi-region control plane.

## Requirements

* Every WarpStream Agent must be able to read and write **all** of the sub-buckets.
* Each sub-bucket needs the same [permissions](/warpstream/agent-setup/different-object-stores.md#bucket-permissions) and [bucket configuration](/warpstream/agent-setup/different-object-stores.md#bucket-configuration) (no object retention policy, versioning, or soft deletion) as a normal WarpStream bucket.

## Migrating

Switching a cluster to or from a multi bucket is nothing special — it works exactly like [migrating between object storage buckets](/warpstream/agent-setup/different-object-stores.md#migrating-between-object-storage-buckets): point `-bucketURL` at the new destination (a `warpstream_multi://` URL, or a plain single-bucket URL when migrating off) and keep the previous bucket(s) in `-additionalBackgroundTasksBucketURLs` until the old data has drained. Existing files continue to be read from wherever they were written.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.warpstream.com/warpstream/agent-setup/different-object-stores/multi-buckets.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.