terrifi

README

terrifi

Yet another Terraform provider for UniFi

Introduction

This is my attempt at making a working Terraform provider to manage my home UniFi network.

Full disclosure, much of this code is written by and with help from various AI coding agents (Claude code in particular).

Compared to existing UniFi providers (paultyng, filipowm, ubiquiti-community), Terrifi is a nearly-from-scratch implementation with a particular focus on extensive testing, including hardware-in-the-loop testing.

CLI

Terrifi includes a CLI tool for generating Terraform import blocks from a live UniFi controller.

Install

go install github.com/alexklibisz/terrifi/cmd/terrifi@latest

Usage

Set the same UNIFI_* environment variables used by the provider, then run:

terrifi generate-imports terrifi_client_device
terrifi generate-imports terrifi_dns_record
terrifi generate-imports terrifi_firewall_zone
terrifi generate-imports terrifi_firewall_policy
terrifi generate-imports terrifi_network
terrifi generate-imports terrifi_wlan

This outputs Terraform import {} and resource {} blocks to stdout, which you can redirect to a .tf file.

Docs

• Usage docs: docs/index.md

TODO

This project is very much a work-in-progress. Here's a rough list of features that I'm looking to implement:

• terrifi_dns_record resource working on real hardware.
• terrifi_network resource working on real hardware.
• terrifi_firewall_zone resource working on real hardware.
• terrifi_client_device resource working on real hardware.
• terrifi_wifi resource working on real hardware.
• terrifi_firewall_policy resource working on real hardware.
• terrifi_client_group resource working on real hardware.
• CLI for generating imports working with real hardware.
• End-to-end working with my home UniFi network.
• Publish to Terraform and Opentofu registries.

Background

Starting from scratch

There is some prior-art when it comes to unofficial Terraform providers for UniFi: paultyng, filipowm, ubiquiti-community. Rather than forking and fixing one of the existing providers, I decided to start from scratch. Notably, I'm still using go-unifi under the hood.

Maybe starting over is a dumb idea, but here is my reasoning:

• I tried to import my home network into each of the existing providers and found errors and issues with each of them.
• It seems the existing providers are either un-maintained or very sparsely maintained at this point. That's not to disparage the maintainers; we all have busy lives and other things to do. I just wanted to avoid the overhead of maintaining a fork with no real feedback on when it might get merged in.
• I want to place a particular focus on hardware-in-the-loop testing. So I've spun up a hardware-in-the-loop test environment with a UniFi Gateway Lite, a UniFi AC Pro, and a mini PC running the UniFi OS Server control plane.
• I just wanted to learn how to implement a Terraform provider. I've used Terraform for years, but have never had the opportunity to implement a provider.

Releasing

1. Go to the Tag workflow in GitHub Actions.
2. Click "Run workflow", enter the version tag (e.g., v0.1.0), and run it.
3. The tag workflow creates and pushes the tag, which triggers the Release workflow.
4. The release workflow builds binaries for linux/darwin (amd64/arm64) and publishes them as a GitHub Release.