Buckets

A bucket holds your objects. It belongs to one project and one region, and its name is how S3 clients address it. To create one, see the Quickstart.

Create buckets through Nirvana

Create buckets with the Nirvana API, CLI or Terraform, not with an S3 client. An access key can also create a bucket directly over S3, for example with aws s3 mb, but Nirvana doesn’t track such a bucket: it doesn’t appear in the API, the CLI or Terraform, and you can’t manage or delete it there. Its data is still billed and counts toward your storage quota.

Naming Rules

A bucket name must:

• Be 3 to 63 characters long.
• Contain only lowercase letters, digits, dots (.) and hyphens (-).
• Start and end with a letter or a digit.
• Not contain two adjacent dots.
• Not be formatted as an IP address, such as 192.168.5.4.

The names admin and ops-api are reserved and can’t be used.

Bucket names are unique within your organization in each region. Two projects of the same organization can’t both have a bucket called my-bucket in us-sva-2, but either can have one in another region.

A name can’t be changed once the bucket is created. To use a new name, create a new bucket and copy the objects across.

Tip

Prefer names without dots. They work with path-style URLs, but not with virtual-hosted-style URLs. See URL Styles.

To check a name before you create the bucket, send the same body to POST /v1/storage/buckets/availability (or run nirvana storage:buckets:availability create). It returns 204 when the name and request are valid, the project has no bucket by that name, and the organization is under its storage quota.

A name used by another project of your organization is only found when the bucket is created: the create operation fails with the BUCKET_NAME_UNAVAILABLE error type.

Tags

Tags are labels you can use to organize and filter buckets. Set them when you create the bucket and change them at any time. Tags are the only thing you can change on a bucket.

A bucket can have up to 50 tags, with no duplicates. Each tag is 1 to 63 characters of letters, digits, hyphens (-), underscores (_) and colons (:), and starts and ends with a letter or digit.

An update replaces the bucket’s tags with the list you send, so include every tag you want to keep.

curl -X PATCH https://api.nirvanalabs.io/v1/storage/buckets/{bucket_id} \
  -H "Authorization: Bearer $NIRVANA_LABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["production", "logs"]}'

With the CLI, repeat --tag for each tag:

nirvana storage:buckets update --bucket-id <bucket_id> --tag production --tag logs

To filter by tag, pass tags to GET /v1/storage/buckets. Repeat it to require several tags: only buckets carrying all of them are returned.

Size and Object Count

A bucket reports size_bytes and object_count. Both are updated periodically, so they can lag behind recent writes.

Delete a Bucket

Deleting a bucket is asynchronous. The request returns 202 with an operation; follow it until its status is done or failed.

curl -X DELETE https://api.nirvanalabs.io/v1/storage/buckets/{bucket_id} \
  -H "Authorization: Bearer $NIRVANA_LABS_API_KEY"

nirvana storage:buckets delete --bucket-id <bucket_id>

By default, a bucket that still holds objects is not deleted. The operation fails with the BUCKET_NOT_EMPTY error type, and the bucket stays as it was. Delete its objects first, or delete the bucket with force.

Force Delete

With force, every object in the bucket, including all versions, is deleted before the bucket itself.

curl -X DELETE "https://api.nirvanalabs.io/v1/storage/buckets/{bucket_id}?force=true" \
  -H "Authorization: Bearer $NIRVANA_LABS_API_KEY"

nirvana storage:buckets delete --bucket-id <bucket_id> --force

Caution

Force delete is permanent and can’t be undone. Every object in the bucket is deleted. Copy out anything you need first.

If objects are written to the bucket while a force delete runs, the objects it already deleted stay deleted, but the bucket is kept. Stop writes to the bucket before you force delete it.

While a bucket is being created or deleted, a delete request fails with 409 and the BUCKET_NOT_DELETABLE error type. Wait for the current operation to finish and try again.

With Terraform

The nirvana_storage_bucket resource deletes without force, so terraform destroy fails on a bucket that still holds objects. Empty the bucket first. Changing a bucket’s name, project_id or region in Terraform replaces the bucket, which deletes the old one, so the same applies.