Deploy MinIO + Iceberg with the minio-iceberg template

Stand up MinIO and an Apache Iceberg REST catalog on a single Quake AI instance using the validated OpenTofu template minio-iceberg. You apply the template, read the bootstrap credentials, confirm MinIO and the REST catalog respond, and create a namespace through the REST API.

You run this stack yourself; it is a self-hosted lakehouse catalog, not a managed warehouse service.

Prerequisites#

You need:

• OpenTofu 1.6.0 or later (or Terraform 1.6.0 or later) installed locally.
• Your OpenStack credentials sourced into the shell (source openrc.sh). See the OpenStack CLI guide.
• An SSH keypair that already exists in your project. Record its name for the key_name variable.
• A copy of the minio-iceberg template directory from the template reference page.
• Your workstation's public IP address if you plan to reach MinIO and the REST catalog directly during setup. Find it with curl -sS https://api.ipify.org.

Step 1: Set the variables and apply the template#

MinIO and the REST catalog listen on ports 9000, 9001, and 8181. The template's security group restricts all three to api_allowed_cidr, which defaults to the private network only. To reach the services from your workstation during setup, set api_allowed_cidr to your own address.

Copy the template's example variables file and open it:

cp terraform.tfvars.example terraform.tfvars

Set key_name to the SSH keypair already in your project, and api_allowed_cidr to your workstation's public IP with a /32 suffix:

key_name           = "YOUR_KEY_NAME"
api_allowed_cidr   = "YOUR_IP/32"

Initialize the working directory, preview the plan, and apply:

tofu init
tofu plan
tofu apply

OpenTofu provisions a private network, a router, a security group, a block volume mounted at /var/lib/docker, an instance, and a floating IP. On first boot, cloud-init mounts the data volume, installs Docker Engine, generates MinIO credentials, creates the warehouse bucket, and starts MinIO plus the REST catalog.

When the apply finishes, read the outputs:

tofu output

Record floating_ip, minio_api_url, minio_console_url, and iceberg_rest_url.

Step 2: Read bootstrap credentials#

No credential ships with the template. cloud-init generates MinIO root credentials on first boot and writes them to the instance.

cloud-init takes a few minutes after the instance reaches ACTIVE. SSH to the host and read the bootstrap file:

ssh ubuntu@YOUR_FLOATING_IP "sudo cat /opt/lakehouse/.bootstrap-credentials"

The file lists minio_root_user, minio_root_password, and warehouse_bucket. Use these values for MinIO console login and S3 client configuration.

Confirm both containers are running:

ssh ubuntu@YOUR_FLOATING_IP "sudo docker ps --filter name=lakehouse"

Step 3: Verify MinIO and the REST catalog#

Open minio_console_url (for example http://YOUR_FLOATING_IP:9001) in your browser and sign in with the bootstrap credentials.

From your workstation, confirm the REST catalog responds:

curl -sS "http://YOUR_FLOATING_IP:8181/v1/config" | head

The response includes catalog configuration. Next, create an Iceberg namespace through the REST API:

curl -sS -X POST "http://YOUR_FLOATING_IP:8181/v1/namespaces" \
  -H "Content-Type: application/json" \
  -d '{"namespace": ["analytics"], "properties": {}}'

List namespaces to confirm registration:

curl -sS "http://YOUR_FLOATING_IP:8181/v1/namespaces"

You now have an open Iceberg catalog backed by MinIO. Query engines such as Spark, Flink, or Trino connect to iceberg_rest_url and read table metadata from the same warehouse URI.

What you built#

• Applied the minio-iceberg template to provision a network, security group, data volume, instance, and floating IP, and let cloud-init install Docker, MinIO, and the Iceberg REST catalog
• Read bootstrap credentials generated on first boot
• Verified MinIO and the REST catalog and registered an Iceberg namespace through the REST API

Scope of this deployment#

This template runs a single-VM lakehouse catalog and object store, not a managed warehouse. The instance is CPU-only and runs in one region. You operate MinIO, the REST catalog, and the data volume yourself: back them up, patch them, and watch disk use as table volume grows. For federated SQL over the tables you register here, add a Trino query host that points at the same REST endpoint and warehouse URI.

Next steps#

• MinIO + Iceberg lakehouse template: the template reference, parameters, and resource map
• Trino query engine template: federated SQL over Iceberg tables
• S3 storage with ACLs: provision a Quake AI Object Storage bucket as the durable lake target
• How to create S3 credentials: programmatic access to Object Storage

Clean up#

When you no longer need the deployment, destroy everything the template created:

tofu destroy

Because MinIO object data and catalog state live on the instance and its attached volume, tofu destroy removes them along with the infrastructure. Export any tables or buckets you want to keep before you destroy.