Bucket Synchronization Policies

A bucket sync policy selects which individual Object Buckets replicate between two zones of a multi-site Ceph object storage configuration, so that only the buckets you name are copied to the second site rather than the whole zone. It solves the problem of a multi-site object cluster where the two sites do not need the same data: a bucket holding regulated records has to exist at both sites, while a bucket of scratch data or local build artifacts should stay where it is and not consume capacity or replication bandwidth at the far end. Sync policies are enforced by the Ceph RADOS Gateway (RGW), and you can manage them from the QuantaStor web interface and the CLI.

Everything on this page lives under the Remote Replication tab, in the Bucket Sync Policies section. Bucket sync policies apply only to scale-out object storage -- see Scale-out Object Setup (ceph) for building the object cluster and the multi-site pairing that this feature depends on.

Section	Purpose
Choosing between bucket sync, remote replication and backup policies	Which QuantaStor replication feature solves your problem
The multi-site model	Zones, zone groups, and the two multi-site modes that decide whether bucket sync policies are possible at all
Multi-site topologies	Worked diagrams of full zone replication, selective bucket sync, and storage class behaviour
Requirements	What must be in place before you can create a policy
Creating a bucket sync policy	The Create dialog, field by field
Policy Status and Direction	What the two enumerations mean, and whether sync is one-way or two-way
What the create operation does on the appliance	The RGW commands issued, and the limits and preconditions enforced
Modifying a bucket sync policy	What can and cannot be changed after creation
Deleting a bucket sync policy	What is removed, and what is left behind
Viewing policies and discovering existing ones	The grid columns, and picking up policies made outside QuantaStor
Scheduling, conflicts and failures	Why there is no schedule, how conflicting writes are handled, and where failures appear
Managing bucket sync policies from the CLI	The five `qs` commands and their arguments

Choosing between bucket sync, remote replication and backup policies

QuantaStor has three unrelated mechanisms for getting data to a second location, and they operate on different objects. Pick by what you are copying.

Feature	Copies	Between	Driven by
Bucket sync policies (this page)	S3 objects in an Object Bucket	Two zones of one RGW multi-site zone group	Continuous RGW multi-site sync; no schedule
Remote replication	Storage Volumes and Network Shares	Two Storage Pools on different QuantaStor systems	Replication schedules, block-level incremental, with replica checkpoints and DR failover
Backup policies	Files in a Network Share	A Network Share and an NFS/SMB export or a Cloud Container	Backup schedules, file-level, with per-run Backup Job objects

Two distinctions catch people out:

A bucket sync policy is not a DR feature in the Remote replication sense. There is no replica checkpoint to activate, no failover or failback operation, and no schedule to trigger. Ceph keeps the two zones converged continuously, and both zones are live members of the same zone group rather than a source and a standby.
A Cloud Container is also about buckets, but it points the other way: it maps one external bucket onto a QuantaStor Network Share so that NFS and SMB clients can read and write object storage as a file share. It is a gateway into somebody else's object storage, not replication between two QuantaStor object clusters. Bucket sync policies never involve a Cloud Container, cloud provider credentials, or a Network Share.

Bucket sync policies act on Object Buckets in a QuantaStor-managed Ceph cluster. Buckets themselves are created and managed under the Scale-out Storage Configuration tab; this page covers only the replication of their contents.

The multi-site model

Scale-out object storage in QuantaStor is organized as RGW zones inside a zone group. Each zone corresponds to one Object Storage Pool Group on one Ceph cluster, fronted by an RGW gateway. Pairing two of them into a zone group is what makes replication possible at all, and it is done once, from the Setup Object Storage Multi-Site Configuration dialog -- see Scale-out Object Setup (ceph).

The choice you make when pairing the zones decides whether bucket sync policies are usable. The Multi-Site Setup dialog has a Bucket Sync Settings section with two radio options:

Option	What it configures	Bucket sync policies
Sync selected buckets (default)	A zone-level policy named `default-deny-<primary zone>-<secondary zone>` with status allowed. Nothing replicates until you say what should.	Required. This is the mode this page is about.
Full zone replication (no individual bucket sync)	A zone-level policy named `default-enabled-<primary zone>-<secondary zone>` with status enabled, with a symmetrical flow across both zones. Everything in the zone replicates.	Refused. Creating one fails with "Cannot add individual bucket sync policies. Multi-site setup cannot be in full zone replication mode."

The equivalent CLI argument is --symmetrical on qs object-pool-group-multi-site-setup, whose help text describes full zone replication as being for "a full copy of the zone group in a secondary site for disaster recovery purposes".

Two consequences of how the default rule is created are worth knowing before you plan a topology:

The bucket exists in both zones either way. Bucket names are zone-group-wide, so a bucket created in one zone shows up in the other as soon as the zone group knows about it. What a sync policy governs is whether the object data inside it is copied. In Sync selected buckets mode you will see empty buckets at the second site until a policy enables them.
Only the pair you configured gets a default rule. Multi-site setup pairs one primary zone with one secondary zone, so if you pair a primary with two secondaries, the two secondary zones have no default rule between them and no sync between them. Establishing sync directly between two secondary zones needs a zone-level policy covering that pair, created deliberately.

RGW does not support replicating a bucket to another bucket within the same zone, so a policy always crosses zones. The Create dialog enforces this by refusing to offer the source cluster as its own destination.

Multi-site topologies

These diagrams work through the combinations of multi-site mode and bucket sync policy, using one primary zone (us-east-1) and two secondary zones (us-west-1, us-west-2). A shaded bucket holds object data; an unshaded bucket exists but is empty. <<<>>> marks a symmetrical policy and >>> a directional one.

The storage class behavior in the last two diagrams is the most common surprise. Policies created by QuantaStor never name a storage class, so the first of the two applies: objects arrive at the destination zone in whatever storage class they had at the source, and any auto-tiering or lifecycle rules configured at the destination are not applied to them on arrival.

Requirements

Two Ceph clusters, each with an Object Storage Pool Group and an RGW gateway. A policy's destination must be a different Ceph cluster from its source; the Create dialog will not offer the source cluster as the destination.
A multi-site zone group spanning those two zones. Until a zone group contains more than one zone, the Create dialog reports "No Ceph Cluster Multi-site Configurations are available." and closes.
The zone pair configured for Sync selected buckets, not full zone replication. See The multi-site model.
At least one Object Bucket in the source cluster to attach the policy to.
A valid license. Create, modify and delete are all license-checked operations.

Creating a bucket sync policy

Navigation: Remote Replication → Bucket Sync Policies → Create (toolbar)

The same dialog is on the right-click menu of the Bucket Sync Policies grid. The dialog is wide because it does two jobs at once: the left panel searches the source cluster for candidate buckets, and the right panel holds the policy settings and the bucket you picked.

Search Criteria

This panel finds the bucket the policy will apply to. Wildcards are accepted in the bucket name: * matches any number of characters and ? matches a single character.

Bucket Name -- enabled by default, with a match mode of Match Any and a pattern of *, so an immediate Search returns everything. Narrow it if the cluster holds a large namespace.
Source Ceph Cluster -- always required, and deliberately not switchable off. The checkbox is checked and greyed out because every candidate bucket in the result list has to come from one cluster; the cluster you choose here becomes the policy's source. Choosing it also filters the Destination Ceph Cluster list on the right to exclude it.
Tenant -- off by default. Enable it to restrict the search to buckets owned by one multitenancy tenant. Tenant-owned buckets are addressed to RGW as <tenant>/<bucket>, and the policy records them that way.
Max Results -- 25 by default. This is a page size, not a cap; use Next > below the bucket list to page through the rest.
Offset -- 0 by default. The starting position in the result set.

Search runs the query and fills the left-hand bucket list; Clear resets the fields and empties both lists. The Range Start, Range End and Total Matches fields under the bucket list report where you are in the result set.

Policy Settings

Destination Ceph Cluster -- the cluster holding the zone the bucket replicates to. The list excludes whatever you selected as the source.
Name -- pre-filled with the next free bucket-sync-policy-<n>. This becomes the RGW sync group id, so keep it to a plain identifier. A name must be unique for the bucket: reusing one fails with "Object Sync Policy with name '...', already exists for bucket '...'".
Description -- free text, stored by QuantaStor only. It is never passed to RGW.
Policy Status -- Enabled (default), Allowed or Forbidden. See Policy Status and Direction.
Direction -- Symmetrical (default) or Directional. See Policy Status and Direction.
Select the Object Bucket to Replicate -- move the bucket from the search results on the left into the selected list on the right. Exactly one bucket is allowed. Selecting none fails with "Invalid Object Bucket selection, no Buckets were selected for the sync operation." and selecting more than one with "...only one bucket can be selected for the sync operation." To replicate several buckets, create one policy per bucket.

Once a bucket and both clusters are chosen, a Bucket Sync Summary line appears under the two panels showing the resulting data flow, in the form bucket (source zone) << >> bucket (destination zone) for a symmetrical policy, or >>>> in place of << >> for a directional one. It is worth reading before clicking OK -- it is the only place the dialog spells out which zone is which.

OK starts an asynchronous task; the dialog closes and the task appears in the Tasks pane.

Policy Status and Direction

These two fields carry straight through to RGW, and they are the substance of the policy.

Policy Status sets the sync group's status:

Value	Meaning
Enabled (default)	Sync is active for this policy. This is what you want for a policy whose bucket should be replicating now.
Allowed	Sync is permitted but not itself active. This is the status the zone-level `default-deny-` policy uses: it opens the door without moving any data, so that bucket-level policies can opt individual buckets in.
Forbidden	Sync is blocked for this policy's scope. Use it to stop a bucket replicating without deleting the policy, so the configuration is preserved and can be switched back.

Status is the one setting Modify can change after the fact, which makes Forbidden the practical way to pause a bucket's replication.

Direction sets the data flow, and cannot be changed after the policy is created:

Value	Flow	Behaviour
Symmetrical (default)	Two-way	Both zones accept writes to the bucket and each replicates to the other. The summary line shows `<< >>`.
Directional	One-way	Only writes at the source zone replicate outward; writes made at the destination zone are not sent back. The summary line shows `>>>>`.

Choose Directional when one site is authoritative and the other is a read copy -- it is also the safer choice, because it removes the possibility of the same object being written at both ends. To change a policy's direction, delete it and create a replacement.

What the create operation does on the appliance

Knowing what the task actually runs makes a failed task readable. Creating a policy issues three radosgw-admin commands in sequence, against the bucket for a bucket-level policy:

radosgw-admin sync group create --group-id=<name> --status=<enabled|allowed|forbidden> --bucket=<bucket>
radosgw-admin sync group flow create --group-id=<name> --flow-id=<name> --flow-type=<symmetrical|directional> ... --bucket=<bucket>
radosgw-admin sync group pipe create --group-id=<name> --pipe-id=<name> --source-zones=... --dest-zones=... --source-bucket=<bucket> --bucket=<bucket>

A symmetrical flow is created with --zones=<source>,<destination> and a pipe spanning all zones; a directional flow names --source-zone and --dest-zone explicitly and pipes only between those two.

Three behaviours follow from this that are not visible in the dialog:

The operation runs on the appliance that owns the master object zone, whichever grid member you launch it from. QuantaStor redirects the request there, because that is where the sync group has to be defined.
A bucket-level policy does not require an RGW period commit, and none is issued. A zone-level policy -- one created with no bucket, which the CLI can do and the web interface cannot -- is followed by radosgw-admin period update --commit.
Policies are capped at 2,000 per appliance. Beyond that, create fails with "Only 2,000 bucket sync policies are allowed. Please contact support."

Modifying a bucket sync policy

Navigation: Remote Replication → Bucket Sync Policies → Modify (toolbar)

The dialog carries three fields:

Bucket Sync Policy -- the policy to change. It is pre-selected if you had one selected in the grid; otherwise pick it here, and the other two fields refresh to that policy's current values.
Policy Status -- Enabled, Allowed or Forbidden, pre-set to the policy's current status. Changing it is the only part of this dialog that reaches RGW, as radosgw-admin sync group modify --status=<status>. If you leave it alone, no RGW command is issued at all.
Description -- free text held by QuantaStor only.

Everything else about a policy is fixed once created. There is no way to change the source or destination cluster, the bucket, the name, or the Direction -- the dialog has no field for any of them. To change those, delete the policy and create a new one.

Deleting a bucket sync policy

Navigation: Remote Replication → Bucket Sync Policies → Delete (toolbar)

Pick the policy in the Bucket Sync Policy list. The read-only Summary field below it restates the flow in the same notation the Create dialog uses, so you can confirm you are removing the policy you meant to before the confirmation prompt. Deleting runs radosgw-admin sync group remove --group-id=<name> for the policy's bucket.

Deleting a policy removes only the policy. The Object Buckets stay, and objects already replicated to the destination zone stay there -- what stops is any further syncing. If the intent is to remove the copy at the far site as well, delete the bucket there separately.

If you only want to stop replication temporarily, set the policy's status to Forbidden with Modify instead, which keeps the configuration intact.

Viewing policies and discovering existing ones

Navigation: Remote Replication → Bucket Sync Policies

The grid shows Name, Source Bucket, Bucket Sync Summary, Policy Status and Description by default. Eight further columns are available from the column menu on any header: State, Source Ceph Cluster, Destination Bucket, Destination Ceph Cluster, Direction, Source Zone, Destination Zone and Storage System.

Two things about those columns are easy to misread:

Zone-level policies appear here too, including the default-deny- or default-enabled- policy that multi-site setup created. They are the rows with an empty Source Bucket, and their Bucket Sync Summary names the two zones rather than a bucket. Do not delete them -- they are what makes the zone pair work.
Source Zone and Destination Zone are blank for policies created from the web interface, which does not send zone names, and Destination Bucket reads * because no separate destination bucket was requested. Populated values in those columns indicate a policy that was discovered from RGW or created from the CLI with the zone arguments given.

Picking up policies created outside QuantaStor

Policies created directly with radosgw-admin are found by bucket detail discovery, which reads each bucket's policy with radosgw-admin sync group get --bucket=<bucket>. Discovery is skipped entirely unless at least one policy whose name contains deny- already exists for the local system, which is the same test as saying the zone pair is in selective-sync rather than full-zone-replication mode. In full zone replication mode there are no per-bucket policies to find, so nothing is scanned.

To force a rescan, use Rescan Object Storage Buckets in the same toolbar group, select Deep Scan, and tick Enable Sync Policies under Deep Scan Options. The default Quick Scan refreshes bucket usage only and will not pick up policy changes. Note the dialog's own warning: a deep scan can take hours on a large namespace and continues in the background after the task is reported complete. The CLI equivalent is qs bucket-rescan.

Scheduling, conflicts and failures

There is no schedule, and that is by design. None of the three dialogs has a schedule field and the API has no schedule parameter, because a bucket sync policy is not a job that runs -- it is a standing rule. Once a policy is Enabled, RGW's own multi-site sync copies objects continuously in the background, and the two zones converge without anything on the QuantaStor side triggering a run. This is the sharpest practical difference from remote replication and backup policies, both of which are schedule-driven and produce a per-run object you can inspect.

Conflicting writes are resolved by RGW, not by QuantaStor. A symmetrical policy makes the bucket writable in both zones, and QuantaStor adds no conflict detection or resolution of its own -- it only tells RGW which buckets and zones are in scope. If concurrent writes to the same object from two sites are a possibility you need to reason about, use Directional so that only one zone is authoritative. The resolution rules RGW itself applies are outside what this page documents.

Failures surface as failed tasks. Create, modify and delete all run asynchronously and appear in the Tasks pane with descriptions of the form "Create Object Sync Policy '<name>' in Ceph Cluster '<cluster>'." A failed task carries the radosgw-admin command that failed together with its output and exit code, which is usually enough to diagnose it directly. Two failures have specific messages worth recognising:

"Cannot add individual bucket sync policies. Multi-site setup cannot be in full zone replication mode." -- the zone pair was configured with Full zone replication. Bucket-level policies are not possible against that pairing.
"Only 2,000 bucket sync policies are allowed. Please contact support." -- the per-appliance policy limit.

No alert type is defined for bucket sync policies, so nothing is raised through the Alert Manager for a policy or for the state of the sync itself. The policy object records the status you configured, not a runtime sync state or progress figure, so ongoing sync health is a question to put to Ceph on the appliance rather than to QuantaStor.

Managing bucket sync policies from the CLI

Five commands cover the feature. Each has a short alias.

Command	Alias	Purpose
qs bucket-sync-policy-create	`bsp-create`	Create a policy
qs bucket-sync-policy-list	`bsp-list`	List all policies
qs bucket-sync-policy-get	`bsp-get`	Show one policy in detail
qs bucket-sync-policy-modify	`bsp-modify`	Change status or description
qs bucket-sync-policy-delete	`bsp-delete`	Remove a policy

Create takes three mandatory arguments and seven optional ones:

qs bucket-sync-policy-create --source-ceph-cluster=<cluster> --destination-ceph-cluster=<cluster> \
     --bucket-sync-policy-name=<name> [--source-bucket=<bucket>] [--destination-bucket=<bucket>] \
     [--sync-policy-status=<allowed|enabled|forbidden>] [--direction=<directional|symmetrical>] \
     [--source-zone=<zone>] [--dest-zone=<zone>] [--description=<text>]

The defaults match the dialog: --sync-policy-status defaults to enabled and --direction to symmetrical. Four arguments have no equivalent in the web interface:

--source-bucket is optional here. Omitting it creates a zone-level policy covering the whole zone pair rather than one bucket -- the only supported way to create the zone-level policy that a secondary-to-secondary pairing needs. The web interface always requires exactly one bucket.
--destination-bucket replicates into a differently-named bucket at the destination. Left unset, the destination bucket matches the source and the policy records *.
--source-zone and --dest-zone name the flow's zones explicitly, which is what fills in the Source Zone and Destination Zone grid columns.

Modify and delete take the policy by name or ID, with the Ceph cluster optional:

qs bucket-sync-policy-modify --bucket-sync-policy=<name|id> [--ceph-cluster=<cluster>] \
     [--sync-policy-status=<allowed|enabled|forbidden>] [--description=<text>]
qs bucket-sync-policy-delete --bucket-sync-policy=<name|id> [--ceph-cluster=<cluster>]
qs bucket-sync-policy-list [--ceph-cluster=<cluster>] [--bucket=<bucket>] [--object-store-zone=<zone>]

On bucket-sync-policy-list, supplying both --bucket and --object-store-zone ignores the zone and filters by the bucket; supplying neither returns every policy in the cluster.

Related commands: qs bucket-list and qs object-zone-list to find the bucket and zone names to use, and qs object-pool-group-multi-site-setup to build the zone pairing in the first place.

Related pages

Scale-out Object Setup (ceph) -- building the object cluster, the Object Storage Pool Groups and RGW gateways, and the multi-site zone pairing this feature requires
Remote-replication (DR) -- replicating Storage Volumes and Network Shares between Storage Pools, on a schedule, with DR failover
Backup Policies -- file-level copy and auto-tiering between a Network Share and an NFS/SMB export or a Cloud Container
Cloud Containers / NAS Gateway -- presenting a single external object bucket as an NFS/SMB file share
Storage Pools -- the pools that back both object storage and the file and block features
QuantaStor CLI Command Reference -- full argument lists for the commands above

Verified against QuantaStor 6.9.0.