Search the docs

Adding a Shared Bucket

The shared bucket is the data path between sites. Add it from every participating site, with identical OSV settings (see The Shared Object Storage Volume in Depth). The first site to add the bucket writes a registration key into it, which simplifies setup for the remaining sites.

Only one bucket is required, though multiple are supported and recommended for resilience. Access to the bucket must be allowed for all Anvil and DSX nodes from every site; as a security best practice, limit access to those nodes only.

Adding a Shared Bucket Using the GUI

Before you begin (GUI)

  • Accept the self-signed certificate. The Anvil GUI is served over HTTPS with a self-signed certificate. The first time you browse to https://<anvil-ip>:8443 the browser shows a “Your connection is not private” warning; accept it and proceed to the site before logging in.

  • The object storage system must already exist. This procedure adds a volume (bucket) to an object/cloud storage system that has already been added. If it has not, add it first: Infrastructure › Storage Systems › Add Storage System, choose Object Storage, select the vendor Type, and supply the endpoint, access key, and secret key. The Add Volume wizard cannot add the storage system itself.

  • The bucket must already exist on the object store. The Add Volume wizard only selects existing buckets — it cannot create one. Create the bucket on the object store first (from the vendor’s console or CLI), using the same bucket name at every site.

  1. In the Anvil GUI, go to Infrastructure › Storage Systems.

  2. If you just created the bucket on the object store, click the Rescan action (the circular-arrow icon in the Actions column) for the object storage system and wait for its volume count to update. Hammerspace discovers buckets on a cached, periodic scan, so a newly created bucket does not appear until the storage system is re-scanned (see A newly created bucket (or other object) doesn’t appear in the GUI).

  3. Click + Volume for the object storage system to open the Add Volume wizard.

  4. On the Selections step, search for and select your bucket, then click Next Step.

  5. On the Data step, confirm the Shared Volume checkbox is selected — it is checked by default, so leave it checked. On the second and any additional sites the GUI also shows a red warning icon indicating the bucket is already in use by another Anvil; this is expected in a multi-site configuration. Click Next Step.

  6. Step through Capacity, Capability, and IP; the defaults are appropriate for a shared OSV. Click Next Step on each.

  7. On Review & Add, confirm that Shared shows Yes, then click Add Volume. The volume is added with shared: true and comes up with operState: UP.

A newly created bucket (or other object) doesn’t appear in the GUI

Hammerspace scans an object storage system for its buckets on a cached, periodic basis; it does not re-read the object store every time you open the Add Volume wizard. If you create a bucket and it is missing from the wizard’s list, close the wizard, click the Rescan action for that storage system on Infrastructure › Storage Systems, wait for the volume count to increase, then reopen the wizard. More generally, whenever you expect a newly added object to appear in the GUI and it does not, re-scan (or refresh) the underlying resource before assuming the operation failed.

Adding a Shared Bucket Using the CLI

Add the --shared option to object-volume-add to mark the bucket as a shared resource. If --shared is not used when the bucket is first added, other sites cannot add it. The flag can only be set when the object volume is added. The same Storage System name (ObjectStorage) and bucket name (sharedbucket) are used on all three sites here for simplicity; this is not required.

Before you begin (CLI)

The CLI has the same prerequisites as the GUI procedure above:

  • The object storage system must already exist at this site. object-volume-add adds a bucket to a storage system that has already been registered. If it has not, register it first with object-storage-add, for example object-storage-add --name ObjectStorage --type GENERIC_S3 --endpoint http://<object-store-host>:9000 --access-id <access key> --secret <secret key>. Every site that will share the bucket must register the same object store.

  • The bucket must already exist on the object store. object-volume-add only selects an existing bucket; it cannot create one. Create the bucket from the vendor’s console or CLI first, using the same bucket name at every site.

  • Refresh the storage system after creating the bucket. Hammerspace discovers buckets on a cached, periodic scan, so a bucket created a moment ago is not yet visible to object-volume-add. Run node-refresh --name ObjectStorage (the CLI equivalent of the GUI’s Rescan action) before adding the volume.

Command:

object-volume-add --shared --node-name ObjectStorage --logical-volume-name sharedbucket

Expected output:

ID:                      <uuid>
Name:                    ObjectStorage::sharedbucket
Internal ID:             268435473
State:                   OK
Node:                    ObjectStorage
Oper state:              Up
Admin state:             Up
Capabilities:            High threshold:           75%
                         Low threshold:            60%
                         Availability:             99.99%
                         Availability (effective): 99.99%
                         Availability drop:        Disabled
                         Durability:               99.9999999%
                         Durability (effective):   99.9999999%
                         Online delay:             5 minutes
Total capacity:          Unlimited
Naming type:             Hash named
Compression type:        No compression
Chunking type:           Fixed-size
Encrypt using KMS:       None. No Kms Configured.
Created:                 <timestamp>
Modified:                <timestamp>
Locations:
                         [Type: Node, ID: <uuid>, Name: ObjectStorage]
                         [Type: Object Storage Volume, ID: <uuid>, Name: ObjectStorage::sharedbucket]
                         [Type: Volume Group, ID: <uuid>, Name: all]
Logical volume:          Type:                    Object Store Logical Volume
                         ID:                      <uuid>
                         Name:                    sharedbucket
                         Ownership:               Shared
                         Client certificate:
                                                  (certificate detail, same shape as in local-site-config)
GC status:               Enabled

After Site B (and Site C) also add the bucket, this site’s Locations list grows a shared-object-volumes group entry, and every site’s output gains a Shared with: block listing the other participating sites.

Run the same command on Site B and Site C.

5.3 adds a Storage class field (seen value: Standard) that doesn’t exist in 5.2 — confirmed by directly comparing this command’s output on a live 5.3.1-1201 site against a live query of the 5.2 pair’s existing shared bucket the same day. It’s a real, configurable field, not purely informational — confirmed in the mgmt/CLI source: it’s backed by a StorageClass enum with two values today, STANDARD (the default; valid for any backend) and AWS_GLACIER_INSTANT_RETRIEVAL (AWS S3 only; an archive-tier class that’s excluded from object-volume and shared-object-volume groups, and requires a matching feature flag on the bucket’s identity file). Set it explicitly at add time with --storage-class on object-volume-add; omit it to get Standard.
Re-running this command on an already-configured bucket

If the object volume has already been added at this site — for example, if you’re unsure whether a previous attempt succeeded — running object-volume-add --shared again with the same --node-name and --logical-volume-name does not silently succeed or duplicate the volume. It returns a clear error instead:

object-volume-add: The Object storage volume sharedbucket is already in use by this site.
Advanced OSV features differ by interface: only compression is available in the GUI; encryption and chunking (native mode) must be configured through the CLI or API. Configure these features identically on the same bucket at every site.