data "openstack_images_image_v2" "os" {
  name        = var.image_name
  most_recent = true
}

data "openstack_networking_network_v2" "external" {
  name = var.external_network
}

resource "openstack_networking_network_v2" "private" {
  name           = "${var.app_name}-net"
  admin_state_up = true
}

resource "openstack_networking_subnet_v2" "private" {
  name            = "${var.app_name}-subnet"
  network_id      = openstack_networking_network_v2.private.id
  cidr            = var.private_cidr
  ip_version      = 4
  dns_nameservers = ["1.1.1.1", "8.8.8.8"]
}

resource "openstack_networking_router_v2" "main" {
  name                = "${var.app_name}-router"
  external_network_id = data.openstack_networking_network_v2.external.id
}

resource "openstack_networking_router_interface_v2" "private" {
  router_id = openstack_networking_router_v2.main.id
  subnet_id = openstack_networking_subnet_v2.private.id
}

resource "openstack_networking_secgroup_v2" "mlflow" {
  name        = "${var.app_name}-sg"
  description = "SSH and HTTP/HTTPS for a reverse proxy; MLflow UI port 5000 restricted"
}

resource "openstack_networking_secgroup_rule_v2" "ssh" {
  direction         = "ingress"
  ethertype         = "IPv4"
  protocol          = "tcp"
  port_range_min    = 22
  port_range_max    = 22
  remote_ip_prefix  = "0.0.0.0/0"
  security_group_id = openstack_networking_secgroup_v2.mlflow.id
}

# 80 and 443 carry the UI when it is served over a domain with automatic TLS
# through a reverse proxy (Caddy or Nginx). They are not used until you put a
# proxy in front of MLflow; see the reference page.
resource "openstack_networking_secgroup_rule_v2" "http" {
  direction         = "ingress"
  ethertype         = "IPv4"
  protocol          = "tcp"
  port_range_min    = 80
  port_range_max    = 80
  remote_ip_prefix  = "0.0.0.0/0"
  security_group_id = openstack_networking_secgroup_v2.mlflow.id
}

resource "openstack_networking_secgroup_rule_v2" "https" {
  direction         = "ingress"
  ethertype         = "IPv4"
  protocol          = "tcp"
  port_range_min    = 443
  port_range_max    = 443
  remote_ip_prefix  = "0.0.0.0/0"
  security_group_id = openstack_networking_secgroup_v2.mlflow.id
}

# Raw tracking UI HTTP on 5000 is restricted to ui_allowed_cidr (the private
# network by default). Prefer a domain with TLS on 443 for routine access.
resource "openstack_networking_secgroup_rule_v2" "ui" {
  direction         = "ingress"
  ethertype         = "IPv4"
  protocol          = "tcp"
  port_range_min    = 5000
  port_range_max    = 5000
  remote_ip_prefix  = var.ui_allowed_cidr
  security_group_id = openstack_networking_secgroup_v2.mlflow.id
}

resource "openstack_networking_port_v2" "mlflow" {
  name               = "${var.app_name}-port"
  network_id         = openstack_networking_network_v2.private.id
  security_group_ids = [openstack_networking_secgroup_v2.mlflow.id]

  fixed_ip {
    subnet_id = openstack_networking_subnet_v2.private.id
  }

  depends_on = [openstack_networking_router_interface_v2.private]
}

resource "openstack_blockstorage_volume_v3" "data" {
  name = "${var.app_name}-data"
  size = var.volume_size
}

resource "openstack_compute_instance_v2" "mlflow" {
  name        = var.app_name
  flavor_name = var.flavor_name
  key_pair    = var.key_name

  user_data = templatefile("${path.module}/cloud-init/mlflow.yaml.tftpl", {
    app_name        = var.app_name
    postgres_host   = var.postgres_host
    postgres_db     = var.postgres_db
    postgres_user   = var.postgres_user
    artifact_bucket = var.artifact_bucket
    artifact_prefix = var.artifact_prefix
    s3_endpoint     = var.s3_endpoint
  })

  block_device {
    uuid                  = data.openstack_images_image_v2.os.id
    source_type           = "image"
    destination_type      = "volume"
    volume_size           = 30
    boot_index            = 0
    delete_on_termination = true
  }

  network {
    port = openstack_networking_port_v2.mlflow.id
  }
}

resource "openstack_compute_volume_attach_v2" "data" {
  instance_id = openstack_compute_instance_v2.mlflow.id
  volume_id   = openstack_blockstorage_volume_v3.data.id
}

resource "openstack_networking_floatingip_v2" "mlflow" {
  pool = var.external_network
}

resource "openstack_networking_floatingip_associate_v2" "mlflow" {
  floating_ip = openstack_networking_floatingip_v2.mlflow.address
  port_id     = openstack_networking_port_v2.mlflow.id
}

variable "key_name" {
  description = "SSH keypair name (must already exist in your project)"
  type        = string
}

variable "flavor_name" {
  description = "Instance size. The MLflow tracking server runs comfortably on 2 vCPU and 2 GiB RAM. Size up when many concurrent clients log runs."
  type        = string
  default     = "s1a.small"
}

variable "image_name" {
  description = "Operating system image. Ubuntu 24.04 is the recommended base."
  type        = string
  default     = "Ubuntu-24.04"
}

variable "app_name" {
  description = "Display name prefix for compute and network resources"
  type        = string
  default     = "mlflow"
}

variable "volume_size" {
  description = "Block volume size in GiB, mounted at /var/lib/docker so Docker state lives on a volume you can grow rather than on the boot disk."
  type        = number
  default     = 20
}

variable "external_network" {
  description = "Shared external network for router gateway and floating IPs; defaults to PublicStatic (persisted FIP / production pattern). Override with PublicEphemeral for ephemeral demos."
  type        = string
  default     = "PublicStatic"
}

variable "private_cidr" {
  description = "CIDR for the private tenant network the instance lives in"
  type        = string
  default     = "10.40.0.0/24"
}

variable "ui_allowed_cidr" {
  description = "CIDR allowed to reach the MLflow UI on port 5000. Defaults to the private network only, so the raw UI is not exposed to the public internet. Reach it over an SSH tunnel, or (recommended) serve it over a domain with HTTPS on 443 behind a reverse proxy. To allow direct access from your workstation, set this to YOUR_IP/32."
  type        = string
  default     = "10.40.0.0/24"
}

variable "postgres_host" {
  description = "PostgreSQL host for experiment metadata (for example the private IP of a self-managed-postgres instance). The password is never set here: add POSTGRES_PASSWORD to /opt/mlflow/.env on the instance and restart."
  type        = string
}

variable "postgres_db" {
  description = "PostgreSQL database name for MLflow metadata"
  type        = string
  default     = "mlflow"
}

variable "postgres_user" {
  description = "PostgreSQL user for MLflow metadata. The password is never set here: add POSTGRES_PASSWORD to /opt/mlflow/.env on the instance and restart."
  type        = string
  default     = "mlflow"
}

variable "artifact_bucket" {
  description = "Object Storage bucket name for MLflow artifacts (models, plots, run files). Provision the bucket with the s3-storage-acl template or an existing container."
  type        = string
}

variable "artifact_prefix" {
  description = "Key prefix inside the artifact bucket where MLflow stores run artifacts"
  type        = string
  default     = "mlflow"
}

variable "s3_endpoint" {
  description = "S3-compatible endpoint URL for Object Storage (for example https://us-east-1.rumble.cloud). Credentials are never set here: add AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY to /opt/mlflow/.env on the instance."
  type        = string
}

# Required: SSH keypair must already exist in your project
key_name = "YOUR_KEY_NAME"

# Required: external PostgreSQL for experiment metadata and Object Storage for artifacts
postgres_host   = "10.50.0.12"
postgres_db     = "mlflow"
postgres_user     = "mlflow"
artifact_bucket = "my-ml-artifacts"
s3_endpoint     = "https://us-east-1.rumble.cloud"

# Recommended: restrict the MLflow UI (port 5000) to your workstation IP.
# Leave unset to keep 5000 reachable only from the private network and tunnel
# over SSH, or put a reverse proxy in front and use HTTPS on 443.
# ui_allowed_cidr = "203.0.113.10/32"

# artifact_prefix = "mlflow"
# flavor_name = "s1a.small"
# image_name = "Ubuntu-24.04"
# app_name = "mlflow"
# volume_size = 20
# external_network = "PublicStatic"
# private_cidr = "10.40.0.0/24"

#cloud-config
package_update: true
packages:
  - ca-certificates
  - curl
write_files:
  - path: /opt/mlflow/Dockerfile
    permissions: "0644"
    content: |
      FROM python:3.11-slim
      RUN pip install --no-cache-dir mlflow==2.22.0 psycopg2-binary boto3
      COPY entrypoint.sh /entrypoint.sh
      RUN chmod +x /entrypoint.sh
      EXPOSE 5000
      ENTRYPOINT ["/entrypoint.sh"]
  - path: /opt/mlflow/entrypoint.sh
    permissions: "0755"
    content: |
      #!/bin/bash
      set -euo pipefail
      : "$${POSTGRES_HOST:?Set POSTGRES_HOST in /opt/mlflow/.env}"
      : "$${POSTGRES_USER:?Set POSTGRES_USER in /opt/mlflow/.env}"
      : "$${POSTGRES_DB:?Set POSTGRES_DB in /opt/mlflow/.env}"
      : "$${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in /opt/mlflow/.env}"
      : "$${ARTIFACT_BUCKET:?Set ARTIFACT_BUCKET in /opt/mlflow/.env}"
      : "$${S3_ENDPOINT:?Set S3_ENDPOINT in /opt/mlflow/.env}"
      : "$${AWS_ACCESS_KEY_ID:?Set AWS_ACCESS_KEY_ID in /opt/mlflow/.env}"
      : "$${AWS_SECRET_ACCESS_KEY:?Set AWS_SECRET_ACCESS_KEY in /opt/mlflow/.env}"
      ARTIFACT_PREFIX="$${ARTIFACT_PREFIX:-mlflow}"
      export MLFLOW_S3_ENDPOINT_URL="$${S3_ENDPOINT}"
      exec mlflow server \
        --host 0.0.0.0 \
        --port 5000 \
        --backend-store-uri "postgresql://$${POSTGRES_USER}:$${POSTGRES_PASSWORD}@$${POSTGRES_HOST}:5432/$${POSTGRES_DB}" \
        --default-artifact-root "s3://$${ARTIFACT_BUCKET}/$${ARTIFACT_PREFIX}/"
  - path: /opt/mlflow/docker-compose.yml
    permissions: "0644"
    content: |
      services:
        mlflow:
          build: .
          restart: unless-stopped
          ports:
            - "5000:5000"
          env_file:
            - /opt/mlflow/.env
  - path: /opt/mlflow/.env
    permissions: "0600"
    content: |
      # MLflow tracking server for ${app_name}.
      # Metadata lives in PostgreSQL; artifacts live in Object Storage.
      # Add POSTGRES_PASSWORD, AWS_ACCESS_KEY_ID, and AWS_SECRET_ACCESS_KEY,
      # then run `docker compose up -d --build`.
      POSTGRES_HOST=${postgres_host}
      POSTGRES_DB=${postgres_db}
      POSTGRES_USER=${postgres_user}
      # POSTGRES_PASSWORD=
      ARTIFACT_BUCKET=${artifact_bucket}
      ARTIFACT_PREFIX=${artifact_prefix}
      S3_ENDPOINT=${s3_endpoint}
      # AWS_ACCESS_KEY_ID=
      # AWS_SECRET_ACCESS_KEY=
runcmd:
  - |
    set -e
    # The data volume attaches as /dev/sdb on this platform (not /dev/vdb).
    # Mount it at /var/lib/docker before Docker is installed so Docker state
    # lives on the resizable volume rather than the boot disk.
    DEV=/dev/sdb
    for i in $(seq 1 30); do [ -b "$DEV" ] && break; sleep 5; done
    if ! blkid "$DEV" >/dev/null 2>&1; then mkfs.ext4 -F -L mlflowdata "$DEV"; fi
    mkdir -p /var/lib/docker
    mount "$DEV" /var/lib/docker
    grep -q "$DEV" /etc/fstab || echo "$DEV /var/lib/docker ext4 defaults,nofail 0 2" >> /etc/fstab
    curl -fsSL https://get.docker.com | sh
    # MLflow does not start until credentials are added to /opt/mlflow/.env.
    # See the deployment walkthrough for the full first-boot sequence.

# MLflow experiment tracking

Single compute instance running [MLflow](https://mlflow.org), an open-source experiment-tracking and model-registry platform (a self-hosted alternative to Weights & Biases or Neptune), on infrastructure you control. After apply, you add the PostgreSQL password and Object Storage credentials on the instance, start the tracking server, and log runs from notebooks or training jobs.


**Network class:** production — `external_network` defaults to `PublicStatic` for persisted floating IPs and multi-tier stacks; override with `PublicEphemeral` for ephemeral demos.

The instance provisions a private network, a floating IP, and a block volume mounted at `/var/lib/docker` so Docker state lives on a resizable volume. cloud-init installs Docker Engine and writes the MLflow compose stack on first boot. Metadata lives in an external PostgreSQL database; artifacts live in Object Storage.

## Where this fits

MLflow is the experiment-tracking layer for ML platform teams: it records parameters, metrics, and artifacts from training and evaluation jobs, and exposes a model registry for promoted models. This template hosts the tracking server only. GPU training runs on an external backend you operate; the tracking server itself is CPU-only and fits Quake AI's CPU-only compute tier cleanly.

## Prerequisites

- OpenTofu >= 1.6.0 or Terraform >= 1.6.0
- Quake AI account with OpenStack credentials
- An existing SSH keypair in your project (the value of `key_name` must match that keypair)
- An external PostgreSQL database (for example [self-managed PostgreSQL](/resources/iac-templates/self-managed-postgres)) with a database and user for MLflow metadata
- An Object Storage bucket and S3 credentials (for example from the [S3 Storage with ACLs](/resources/iac-templates/s3-storage-acl) template)

## Resource baseline

The MLflow tracking server runs on 2 vCPU and 2 GiB RAM. The default `s1a.small` flavor leaves headroom for Docker plus moderate concurrent logging from notebooks or batch jobs.

## Usage

1. Clone or copy this template directory
2. Copy `terraform.tfvars.example` to `terraform.tfvars` and fill in your values
3. Source your OpenStack credentials: `source openrc.sh`
4. Initialize: `tofu init`
5. Preview: `tofu plan`
6. Apply: `tofu apply`

After apply, SSH to the instance, add `POSTGRES_PASSWORD`, `AWS_ACCESS_KEY_ID`, and `AWS_SECRET_ACCESS_KEY` to `/opt/mlflow/.env`, then run `docker compose up -d --build`. No credential ships with this template.

## UI access and security

The tracking UI listens on port 5000 over plain HTTP. The security group restricts 5000 to `ui_allowed_cidr`, which defaults to the private network only. Choose one of:

- **Recommended:** put a reverse proxy (Caddy or Nginx) in front of MLflow and serve the UI over HTTPS on 443. Point the domain's DNS A record at `floating_ip`.
- **SSH tunnel:** `ssh -L 5000:localhost:5000 ubuntu@<floating_ip>`, then open `http://localhost:5000`.
- **Direct, scoped:** set `ui_allowed_cidr` to your workstation IP (`YOUR_IP/32`) to reach 5000 directly from one address.

Ports 80 and 443 stay open for the reverse proxy you put in front; they carry no traffic until you add one.

## Metadata and artifacts

- **PostgreSQL:** experiment metadata (runs, parameters, metrics, registry entries) lives in the external database you point at with `postgres_host`, `postgres_db`, and `postgres_user`. Add `POSTGRES_PASSWORD` to `/opt/mlflow/.env` on the instance.
- **Object Storage:** run artifacts (models, plots, files) land in the bucket named by `artifact_bucket` under the prefix `artifact_prefix`. Add S3 credentials to `/opt/mlflow/.env`. Set `s3_endpoint` to your region's Object Storage endpoint.

## Variables

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `key_name` | string | yes | n/a | SSH keypair name (must already exist in your project) |
| `postgres_host` | string | yes | n/a | PostgreSQL host for metadata |
| `artifact_bucket` | string | yes | n/a | Object Storage bucket for artifacts |
| `s3_endpoint` | string | yes | n/a | S3-compatible endpoint URL |
| `flavor_name` | string | no | `s1a.small` | Instance size (tracking server on 2 vCPU / 2 GiB) |
| `image_name` | string | no | `Ubuntu-24.04` | Operating system image |
| `app_name` | string | no | `mlflow` | Display name prefix for resources |
| `volume_size` | number | no | `20` | Block volume size in GiB, mounted at `/var/lib/docker` |
| `external_network` | string | no | `PublicStatic` | Persisted FIP / production default; override with `PublicEphemeral` for demos |
| `private_cidr` | string | no | `10.40.0.0/24` | CIDR for the private subnet |
| `ui_allowed_cidr` | string | no | `10.40.0.0/24` | CIDR allowed to reach the UI on port 5000 |
| `postgres_db` | string | no | `mlflow` | PostgreSQL database name |
| `postgres_user` | string | no | `mlflow` | PostgreSQL user |
| `artifact_prefix` | string | no | `mlflow` | Key prefix inside the artifact bucket |

## Outputs

| Name | Description |
| --- | --- |
| `floating_ip` | Public floating IP assigned to the instance |
| `private_ip` | Private IP address of the instance |
| `tracking_url` | MLflow tracking UI URL on port 5000 |
| `instance_id` | Compute instance ID |

## Scope

This is a single-VM MLflow tracking host that you operate, not a managed experiment-tracking cloud. It is CPU-only and runs in one region. It records experiments and hosts the model registry; it does not run GPU training. Point training jobs at an external GPU backend and set `MLFLOW_TRACKING_URI` to this server.

## Documentation

See also: [self-managed PostgreSQL](/resources/iac-templates/self-managed-postgres), [S3 Storage with ACLs](/resources/iac-templates/s3-storage-acl), [JupyterHub notebook server](/resources/iac-templates/jupyterhub)