> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onebucket.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Policies

> How a policy maps one OneBucket to peer buckets at your endpoints, and how modes, permissions and quorum decide where reads and writes go.

A **policy** is the rule behind every OneBucket. It names a OneBucket, maps it to one or more **peer buckets** at your [endpoints](https://docs.onebucket.io/setup.md#add-an-endpoint), says how each peer takes part in reads and writes, and lists the **core access keys** allowed to use it. Clients never see any of this: they talk to one bucket over S3 or MCP, and the policy decides what happens behind it.

Policies are created in the [OneBucket console](https://app.onebucket.io) (see [Setup](https://docs.onebucket.io/setup.md) for the walkthrough) or through the [management API](https://docs.onebucket.io/reference/apis.md#management-api), so policy changes can live in your own scripts and pipelines. Active policies apply account-wide, in every region.

## Anatomy of a policy

| Part | What it sets |
| - | - |
| **OneBucket name** | The bucket name clients use. `*` matches any peer bucket at your endpoints, which suits clients that create and name their own buckets. Cannot be changed after creation. |
| **Encoding** | Optional inline compression, `gzip` or `brotli`, applied as objects pass through. |
| **Peer buckets** | One or more buckets at your endpoints that back this OneBucket, each with its own mode, permissions and credentials. |
| **Sync quorum** | How many write-enabled synchronous peers must acknowledge a write before it succeeds. |
| **Core access keys** | The OneBucket keys allowed to use this OneBucket over S3 or MCP. |

## Peer buckets

Each peer bucket is configured independently.

| Setting | Meaning |
| - | - |
| **Endpoint** | Which backend holds this peer, for example `AWS`, `WASABI`, or an on-prem store. |
| **Access key** | The endpoint's own credential used to reach it. It stays in the OneBucket vault and is never given to clients. |
| **Peer bucket name** | `*` keeps bucket names identical to the OneBucket name. A prefix or suffix, such as `backup-*`, renames buckets on this backend only. |
| **Mode** | `sync`, `async` or `cache` (below). |
| **Permissions** | Any combination of **Read**, **Write** and **Delete**. |
| **Active** | Turns the peer on or off without deleting it. Deactivating is reversible. |
| **Opportunistic replication** | Copies existing objects into this peer as they are read through OneBucket. |
| **Required** | Forces every write to succeed on this peer, regardless of quorum. |
| **Sequence** | The order in which OneBucket tries peers. |

Every policy needs at least one synchronous peer.

### Modes

> **sync**
>
> The write lands on this peer before the request returns. Counts toward the quorum.

> **async**
>
> The write is acknowledged first and copied to this peer in the background.

> **cache**
>
> Holds copies of what has been read or prefetched, so repeat reads are served locally. The source stays authoritative.

### Quorum and required peers

The **quorum** is the minimum number of synchronous peers with write permission that must acknowledge a PUT for it to succeed. With three such peers, a quorum of `2` means a write survives one peer being unavailable; a quorum of `3` means every copy must land. The quorum is the dial between durability and latency, set per OneBucket.

Marking a peer **Required** adds a hard rule on top: that specific peer must succeed, whatever the quorum says. Use it when one copy has to exist in a particular place, such as a jurisdiction.

## What a policy decides, and what it does not

> [!NOTE]
>
> Placement is set **per OneBucket**, not per object. Every object in a OneBucket follows the same policy; objects are not routed individually by prefix, tag or content. To place data differently, put it in a different OneBucket with its own policy.

Within that scope, a policy decides where writes land, which copies must exist before a write is acknowledged, where reads are served from, and which keys may do what.

## Changing a policy while it serves

Policies can be edited at any time and take effect without touching clients: the endpoint, keys and application configuration stay the same. That is what makes these patterns a policy change rather than a project:

* **Add a provider**: add a peer, turn on opportunistic replication, and it fills as data is read.
* **Shift writes**: clear **Write** and **Delete** on one peer, and new objects go only to the others while it still serves reads.
* **Retire a backend**: deactivate the peer, validate, then delete it.
* **Restrict a key**: assign a key to a policy with read-only permissions, and its next write is refused, with the attempt visible in [events](https://docs.onebucket.io/mcp/overview.md#events).

> [!WARNING]
>
> Deleting a peer removes OneBucket's route to that backend. Objects that exist only there become unreachable through this OneBucket. Confirm the remaining peers hold what you need first.

The [CloudPools migration guide](https://docs.onebucket.io/guides/cloudpools-migration.md) walks through every one of these steps with screenshots.

## Keeping objects readable without OneBucket

With the peer bucket name left as `*` and encoding off, objects are stored on each backend unchanged: same bucket names, same keys, same bytes. Any S3 client can read them directly from the backend, and you can remove OneBucket from the path at any time. Enabling encoding or a renamed peer bucket trades that property for compression or separation.

## Related

> **[Federation](https://docs.onebucket.io/concepts/federation.md)**
>
> How many backends become one namespace.

> **[Scenarios](https://docs.onebucket.io/scenarios/overview.md)**
>
> Policies applied to migration, replication, placement and caching.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.