Managing Buckets

Buckets are created and managed through the Crusoe Cloud Console or CLI. They cannot be created or deleted through S3 client tools.

Bucket names must comply with the naming rules described in the Overview, including being globally unique across a Crusoe Cloud region and between 3–63 characters using only lowercase letters, numbers, and hyphens.

By default the buckets are only accessible by bucket owner via up to 2 Object Storage API keys.

Creating a Bucket

CLI

crusoe storage buckets create \
  --name my-training-data \
  --location us-east1-a

--name and --location are required. The bucket must be in the same location as the VMs that will access it.

UI

1. Visit the Crusoe Cloud Console.
2. Navigate to Storage > Buckets in the left navigation.
3. Click Create Bucket.
4. Enter a name for the bucket.
5. Select the location.
6. (Optional)Enable versioning and object lock if desired.
7. Click Create.

Terraform

Creating an Object Storage bucket is the first step to storing objects in Crusoe Cloud. The following is intended to help get you started in using Terraform to provision an S3-compatible bucket in Crusoe Cloud.

Copy and paste the code below in a text-editor of your choice and name the file main.tf. The example below creates a bucket:

// Crusoe Provider
terraform {
  required_providers {
    crusoe = {
      source = "registry.terraform.io/crusoecloud/crusoe"
    }
  }
}

resource "crusoe_storage_s3_bucket" "my_bucket" {
  name     = "my-bucket"
  location = "us-southcentral1-a"
}

name and location are required arguments.

name is a globally unique name for the bucket.

location is the Crusoe Cloud location where the bucket will be created.

After saving the code to a main.tf file, the following commands serve as the process to create a resource in Crusoe Cloud using Terraform:

terraform init - Initializes a working directory containing Terraform configuration files.

terraform plan - the output of this command will show the resources Terraform plans on creating.

terraform apply - this command will create the resources.

Listing Buckets

CLI

crusoe storage buckets list

Optional filters:

• --location <location> — Filter by location.
• --tag key=<key>,value=<value> — Filter by tag.

UI

1. Navigate to Storage > Buckets in the Console.
2. All buckets in your project are listed with their name, location, size, and creation date.

Terraform

To list existing buckets using Terraform, the following code snippet can be used to populate a Terraform data source using the Crusoe Terraform provider.

# list buckets
data "crusoe_storage_s3_buckets" "buckets" {}

output "crusoe_buckets" {
  value = data.crusoe_storage_s3_buckets.buckets
}

Getting Bucket Details

CLI

crusoe storage buckets get my-training-data

This returns the bucket's metadata including versioning state, object lock configuration, tags, and used capacity.

UI

1. Navigate to Storage > Buckets in the Console.
2. Click on a bucket name to view its details, including the S3 endpoint, Bucket URL, versioning state, object lock configuration, tags, and current size.

Terraform

To view the details of a specific bucket using Terraform, filter the crusoe_storage_s3_buckets data source by bucket name.

data "crusoe_storage_s3_buckets" "all" {}

output "bucket_details" {
  value = one([
    for bucket in data.crusoe_storage_s3_buckets.all.buckets :
    bucket if bucket.name == "my-training-data"
  ])
}

This returns the bucket's metadata including versioning state, object lock configuration, tags, and used capacity.

Managing Bucket Tags

CLI

Add tags:

crusoe storage buckets add-tags my-training-data \
  --tag key=environment,value=production \
  --tag key=team,value=ml-infra

Remove tags:

crusoe storage buckets remove-tags my-training-data \
  --tag key=environment,value=production

List tags:

crusoe storage buckets list-tags my-training-data

UI

1. Visit the Crusoe Cloud Console.
2. Navigate to Storage > Buckets in the left navigation.
3. Click on the bucket for which you want to add tags.
4. Click on the Edit Bucket Details button.
5. Enter the key-value pairs in the Tags section.
6. Click Update.

Terraform

To manage tags on an existing bucket using the Crusoe Terraform provider, add or update the tags field on your existing crusoe_storage_s3_bucket resource and run terraform apply.

resource "crusoe_storage_s3_bucket" "my_bucket" {
  # ... existing bucket configuration ...

  tags = {
    environment = "production"
    team        = "ml"
  }
}

To remove all tags, remove the tags field or set it to an empty map:

resource "crusoe_storage_s3_bucket" "my_bucket" {
  # ... existing bucket configuration ...

  tags = {}
}

After making any changes, save the code and then perform the following commands:

terraform plan - the output of this command will show the planned changes to the bucket's tags.

terraform apply - this command will apply the changes.

Enabling Versioning

Versioning preserves every version of every object in the bucket, protecting against accidental overwrites and deletions.

Warning

Once versioning is enabled, it cannot be disabled or suspended.

CLI

crusoe storage buckets enable-versioning my-training-data

UI

1. Visit the Crusoe Cloud Console.
2. Navigate to Storage > Buckets in the left navigation.
3. Click on the bucket for which you want to Enable Versioning.
4. Click on the Edit Bucket Details button.
5. Click on the Versioning radio button.
6. Click Update.

Terraform

To enable versioning on a bucket using the Crusoe Terraform provider, set the versioning_enabled field to true on a crusoe_storage_s3_bucket resource and run terraform apply.

terraform {
  required_providers {
    crusoe = {
      source = "registry.terraform.io/crusoecloud/crusoe"
    }
  }
}

resource "crusoe_storage_s3_bucket" "my_bucket" {
  name               = "my-bucket"
  location           = "us-southcentral1-a"
  versioning_enabled = true
}

danger

Enabling versioning is irreversible. Once versioning is enabled on a bucket, it cannot be disabled.

After making any changes, save the code and then perform the following commands:

terraform plan - the output of this command will show the resources Terraform plans on creating.

terraform apply - this command will apply the changes.

Enabling Object Lock

Object lock protects objects from being deleted or overwritten for a specified retention period. Enabling object lock automatically enables versioning.

Warning

Once object lock is enabled on a bucket, it cannot be disabled, and versioning cannot be suspended.

CLI

crusoe storage buckets enable-locking my-training-data \
  --retention 30d

The --retention flag accepts values like 7d (7 days) or 1y (1 year).

UI

1. Visit the Crusoe Cloud Console.
2. Navigate to Storage > Buckets in the left navigation.
3. Click on the bucket for which you want to Enable Object Lock.
4. Click on the Versioning radio button.
5. Click on the Object Lock radio button.
6. Click Update.

Terraform

To enable object locking on a bucket using the Crusoe Terraform provider, set versioning_enabled, object_lock_enabled, retention_period, and retention_period_unit on a crusoe_storage_s3_bucket resource and run terraform apply.

terraform {
  required_providers {
    crusoe = {
      source = "registry.terraform.io/crusoecloud/crusoe"
    }
  }
}

resource "crusoe_storage_s3_bucket" "my_bucket" {
  name                 = "my-bucket"
  location             = "us-southcentral1-a"
  versioning_enabled   = true
  object_lock_enabled  = true
  retention_period     = 30
  retention_period_unit = "days"
}

versioning_enabled must be set to true because object locking requires versioning.

object_lock_enabled enables object locking on the bucket.

retention_period is the duration for which objects are locked.

retention_period_unit is the unit for the retention period (e.g., days).

danger

Enabling object locking is irreversible. Both versioning and object locking cannot be disabled once enabled.

After making any changes, save the code and then perform the following commands:

terraform plan - the output of this command will show the resources Terraform plans on creating.

terraform apply - this command will apply the changes.

Deleting a Bucket

Warning

A bucket must be empty before it can be deleted. Deleting a bucket is a permanent action.

CLI

crusoe storage buckets delete --name my-training-data

UI

1. Navigate to Storage > Buckets in the Console.
2. Click the delete icon next to the bucket you wish to delete.
3. Enter the name of the bucket to confirm and click Delete

Terraform

A bucket can be deleted by using the terraform destroy command provided by the Terraform CLI tool.