TrueForm

A Terraform provider for managing TrueNAS Scale 25.04+ resources.

About

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.

Requirements

• Terraform >= 1.0
• Go >= 1.25 (for building from source)
• TrueNAS Scale 25.04 or later

Installation

Building from Source

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

Local Installation

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

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

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

Authentication

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)

Configuration

terraform {
  required_providers {
    trueform = {
      source = "registry.terraform.io/trueform/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"

Available Resources

Available Data Sources

Usage Examples

Create a Dataset

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

Create an SMB Share

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

Create a Virtual Machine

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"
}

Query Existing Resources

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

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

See the examples directory for more complete examples.

Development

Building

go build -o terraform-provider-trueform

Running Tests

go test ./...

Running Acceptance Tests

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

Releasing

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.

Technical Details

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

Contributing

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

License

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

Disclaimer

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.