Skip to main content
API Reference

Manage buckets

Our customer interface Cockpit allows you to create and manage our "Object Storage" product in a self service fashion.

All locations are physically located in Switzerland — see Datacenter Locations for details.

Create Buckets​

Buckets can be managed via the Cockpit, nctl, or the API. When creating a bucket, you must always provide a unique name and a location.

The following settings are optional:

  • Versioning: The files are stored versioned. This takes up more storage space, but protects the data from being overwritten.
  • Public readable: The bucket's data can be accessed or downloaded without authentication.
  • Public list: A list of the files in the bucket can be retrieved using the specified public URL. The option requires that "Public readable" has been enabled.
  • Location: Defines the location of the data.

All options, except for "Location", can be adjusted later as needed.

You create buckets under the Bucket tab.

Bucket Permissions​

After creating a bucket, you can specify which users should have access to the bucket. Users can be granted read (reader) access or write (writer) access. Only users from the same "Location" where the bucket was created can be selected.

Permissions can be managed under the Bucket tab by selecting a bucket and configuring user access.

Lifecycle Policies​

Lifecycle policies allow you to set automatic expiration and retention rules for objects inside a bucket based on prefixes.

note

Lifecycle policies can be managed via nctl or the API. They are currently not configurable in the Cockpit.

note

Each --lifecycle-policy flag creates its own separate policy. Key-value pairs within a policy are separated by ;.

  1. Creating a bucket with lifecycle policies:

    # Single policy (e.g. for `logs/`)
    nctl create bucket my-bucket --lifecycle-policy prefix=logs/;expire-after-days=7;is-live=true

    # Multiple policies (repeat the flag)
    nctl create bucket my-bucket --lifecycle-policy prefix=tmp/;expire-after=72h;is-live=true \
      --lifecycle-policy prefix=archive/;expire-after-days=365;is-live=false

  2. Updating or removing lifecycle policies on an existing bucket:

    # Remove a specific policy by exact definition
    nctl update bucket my-bucket \
      --delete-lifecycle-policy prefix=tmp/;expire-after=72h;is-live=true

    # Clear all policies, then add two fresh ones in a single run
    nctl update bucket my-bucket \
      --clear-lifecycle-policies \
      --lifecycle-policy prefix=logs/;expire-after-days=7;is-live=true \
      --lifecycle-policy prefix=archive/;expire-after-days=365;is-live=false

How non-current version expiration timing works​

A lifecycle policy that combines is-live=false with expire-after-days maps to the S3 NoncurrentVersionExpiration action, where NoncurrentDays is set to the value of expire-after-days.

For versioned buckets, the expiration period starts when an object version becomes non-current, not when that version was originally uploaded.

A version becomes non-current when:

  • a new version of the same object is written, replacing the current version, or
  • the object is deleted, creating a delete marker that makes the previous version non-current.

For example:

nctl update bucket my-bucket --lifecycle-policy 'prefix=data/;expire-after-days=1;is-live=false'

This policy expires non-current versions under data/ one day after they become non-current. The expiration period is counted from when the version was superseded by a newer version or a delete marker, rather than from its original upload time.

If an object is uploaded on day 0 and deleted on day 30, its current version becomes non-current on day 30. With a 14-day expiration policy, that version is expected to expire around day 44, not day 14.

note

Expiration is not necessarily processed immediately when the configured period is reached. Actual deletion can occur with some additional delay.

CORS Configuration​

Cross-Origin Resource Sharing (CORS) defines how web applications running at one origin can interact with resources in your bucket.

note

The --cors flag can be repeated and entries are merged deterministically. Key-value pairs are separated with ; and multiple values with ,.

  1. Creating a bucket with CORS configuration:

    # Single flag
    nctl create bucket my-bucket --cors origins=https://example.com,https://app.example.com;response-headers=X-My-Header,ETag;max-age=3600

    # Multiple flags (merged deterministically)
    nctl create bucket my-bucket --cors origins=https://example.com;response-headers=ETag \
      --cors origins=https://app.example.com;response-headers=X-My-Header \
      --cors max-age=3600

  2. Updating or deleting CORS configuration on an existing bucket:

    # Update CORS configuration
    nctl update bucket my-bucket \
      --cors origins=https://example.com;response-headers=ETag \
      --cors origins=https://app.example.com;response-headers=X-My-Header \
      --cors max-age=3600

    # Delete specific CORS entries (by key/value)
    nctl update bucket my-bucket \
      --delete-cors origins=https://app.example.com;response-headers=ETag

Custom Hostnames​

You can attach or manage custom domain names for your bucket.

  1. Updating custom hostnames:

    # Remove one hostname
    nctl update bucket my-bucket \
      --delete-custom-hostnames assets.example.com

    # Clear all hostnames and set a new one in a single run
    nctl update bucket my-bucket \
      --clear-custom-hostnames \
      --custom-hostnames media.example.com

Getting Bucket Details​

A bucket's configuration can be checked anytime through the Cockpit, nctl, or the API.

Bucket details are available under the Bucket tab.

Accessing Buckets​

See Object Storage Client Tools for how to access your buckets via the S3-compatible API or HTTP, including configuration examples for common client tools.