Serve buckets over S3¶

When you finish, the cluster accepts S3 connections and serves a versioned bucket named data-bucket, and your application holds an access key to sign its requests.

Before you start¶

A Qumulo cluster on Qumulo Core 7.0 or later, whose REST API on port 8000 you can reach from this machine
An admin account on the cluster for the connection profile
A local user for your application to act as, from local users and groups
Terraform 1.11 or later

1. Copy the configuration¶

Save this as main.tf in an empty directory.

terraform {
  required_version = ">= 1.11"
  required_providers {
    qumulo = {
      source  = "qumulo-terraform-registry.s3.us-east-1.amazonaws.com/qumulo/qumulo"
      version = "~> 1.0"
    }
  }
}

provider "qumulo" {
  connection_profiles = [
    {
      name                 = "cluster1"
      endpoint             = "https://cluster.example.com:8000" # <-- Replace with your cluster's REST API endpoint
      username             = "admin"
      password             = "YourClusterPassword123!" # <-- Replace with your admin password
      insecure_skip_verify = true
    },
  ]
}

resource "qumulo_s3_settings" "main" {
  connection_profile = "cluster1"

  enabled = true
}

resource "qumulo_s3_bucket" "data" {
  connection_profile = "cluster1"

  name           = "data-bucket"
  path           = "/s3-buckets/data-bucket"
  create_fs_path = true
  versioning     = "Enabled"

  depends_on = [qumulo_s3_settings.main]
}

resource "qumulo_s3_access_key" "app" {
  connection_profile = "cluster1"

  user {
    domain = "LOCAL"
    name   = "app-user" # <-- Replace with the local user your application signs in as
  }
}

output "access_key_id" {
  value = qumulo_s3_access_key.app.access_key_id
}

output "secret_access_key" {
  value     = qumulo_s3_access_key.app.secret_access_key
  sensitive = true
}

Replace the three values marked <-- Replace, and leave the rest as written. Delete insecure_skip_verify if the cluster's certificate is signed by a CA your machine trusts.

2. Choose how the bucket is protected¶

To accept only HTTPS connections, set secure = true in qumulo_s3_settings.
To keep the bucket from other S3 users, set private = true on it and grant access with a qumulo_s3_bucket_policy. Every S3 user can read and write a bucket's objects by default.
For write-once retention, set object_lock_enabled = true on the bucket and add a lock_config block with a default_retention period. Object Lock cannot be turned off once it is on.
For an Active Directory user, set the key's domain = "ACTIVE_DIRECTORY" and write name as DOMAIN\username or username@domain.
To serve more buckets, copy the qumulo_s3_bucket block with a new resource name, name, and path.

The plan in step 3 shows each change on the resource you edited.

3. Apply¶

terraform init -upgrade
terraform plan
terraform apply

The plan ends with Plan: 3 to add, 0 to change, 0 to destroy. The apply ends with Apply complete! Resources: 3 added, 0 changed, 0 destroyed., followed by the access_key_id output and secret_access_key = <sensitive>.

4. Hand the key to your application¶

terraform output -raw access_key_id
terraform output -raw secret_access_key

The commands print the key ID and its secret. The cluster returns the secret only once, at creation, and Terraform keeps it in state, so store it in your secrets manager and keep the state backend locked down.

Changing the key's user block later replaces the key and issues a new key pair.

Next¶

Bucket policy syntax and principal formats are in Qumulo's S3 access policy documentation, and the rest of the S3 API is in Qumulo's S3 documentation. The qumulo_s3_bucket reference lists every bucket attribute, Manage several clusters from one configuration serves the same buckets across a fleet, and the cluster troubleshooting guide helps if a step fails.