A Terraform provider for managing TrueNAS Scale 25.04+ and TrueNAS 26 (beta) resources.

There didn't appear to be any published Terraform providers for TrueNAS Scale for versions 25 and greater (due to the recent change in how the API works), so I decided to burn my Claude Code trial by generating one. It has been mostly written by Claude Code by pointing it at the TrueNAS 25 documentation.

The name TrueForm is taking "form" from Terraform, and "true" from TrueNAS.

• Terraform >= 1.0
• Go >= 1.25 (for building from source)
• TrueNAS Scale 25.04+, or TrueNAS 26 (beta) — the provider detects the server version at runtime and uses the correct API for each (verified end-to-end against 25.10.4 and 26.0.0-BETA.2)

git clone https://github.com/dev-dull/terraform-provider-trueform.git
cd terraform-provider-trueform
go build -o terraform-provider-trueform

After building, move the binary to your Terraform plugins directory:

mkdir -p ~/.terraform.d/plugins/registry.terraform.io/dev-dull/trueform/0.1.0/darwin_arm64/
mv terraform-provider-trueform ~/.terraform.d/plugins/registry.terraform.io/dev-dull/trueform/0.1.0/darwin_arm64/

Adjust the path for your OS/architecture (e.g., linux_amd64, darwin_amd64).

The provider uses API key authentication. To create an API key in TrueNAS:

1. Log into your TrueNAS web interface
2. Click on your username in the top-right corner
3. Select API Keys
4. Click Add and give your key a name
5. Copy the generated key (you won't be able to see it again)

terraform {
  required_providers {
    trueform = {
      source = "dev-dull/trueform"
    }
  }
}

provider "trueform" {
  host       = "truenas.local"      # Your TrueNAS hostname or IP
  api_key    = var.truenas_api_key  # Your API key
  verify_ssl = true                 # Set to false for self-signed certs
}

You can also use environment variables:

export TRUENAS_HOST="truenas.local"
export TRUENAS_API_KEY="your-api-key"
export TRUENAS_VERIFY_SSL="true"

resource "trueform_dataset" "media" {
  pool        = "tank"
  name        = "media"
  compression = "LZ4"
  quota       = 1099511627776  # 1TB in bytes
  comments    = "Media storage"
}

resource "trueform_share_smb" "media" {
  path      = "/mnt/tank/media"
  name      = "media"
  comment   = "Media share"
  enabled   = true
  browsable = true
  guestok   = false
}

resource "trueform_vm" "ubuntu" {
  name        = "ubuntu-server"
  description = "Ubuntu Server VM"
  vcpus       = 2
  cores       = 1
  threads     = 1
  memory      = 4096  # MB
  bootloader  = "UEFI"
  autostart   = true
}

resource "trueform_vm_device" "ubuntu_disk" {
  vm        = trueform_vm.ubuntu.id
  dtype     = "DISK"
  disk_path = "zvol/tank/vms/ubuntu-boot"
  disk_type = "VIRTIO"
}

resource "trueform_vm_device" "ubuntu_nic" {
  vm         = trueform_vm.ubuntu.id
  dtype      = "NIC"
  nic_type   = "VIRTIO"
  nic_attach = "br0"
}

data "trueform_pool" "main" {
  name = "tank"
}

output "pool_free_space" {
  value = data.trueform_pool.main.free
}

See the examples directory for more complete examples.

go build -o terraform-provider-trueform

go test ./...

Acceptance tests run against a real TrueNAS instance:

export TRUENAS_HOST="your-truenas-host"
export TRUENAS_API_KEY="your-api-key"
TF_ACC=1 go test ./... -v

This project uses Semantic Versioning:

• MAJOR — breaking changes to resource schemas or provider configuration
• MINOR — new resources, data sources, or features
• PATCH — bug fixes, documentation updates, lint fixes

To cut a release:

1. Push your changes to main.
2. Wait for CI (lint, build, and tests) to pass.
3. Tag the passing commit:

   git tag v0.X.Y
   git push origin v0.X.Y

The Terraform Registry picks up new versions via GitHub tag-creation webhooks. Do not force-push tags — if a tag needs to be revised, create a new patch version instead.

This provider communicates with TrueNAS using the WebSocket JSON-RPC 2.0 API introduced in TrueNAS Scale 25.04. The connection flow is:

1. Establish WebSocket connection to wss://<host>/api/current
2. Authenticate using auth.login_ex with the API_KEY_PLAIN mechanism (falls back to auth.login_with_api_key for older TrueNAS versions)
3. Execute JSON-RPC calls for resource operations

Contributions are welcome! Please feel free to submit issues and pull requests.

This project is provided as-is without any specific license. Use at your own risk.

This provider is not officially affiliated with or endorsed by iXsystems or the TrueNAS project. Use at your own risk and always test in a non-production environment first.