Terraform Provider UniFi Development

Expert guidance for developing and maintaining the Terraform provider for UniFi network infrastructure management.

What This Skill Does

This skill provides comprehensive knowledge for working on the `terraform-provider-unifi` codebase, including:

Implementing new resources and data sources

Writing acceptance tests with controller compatibility handling

Following provider architecture patterns (auto-relogin client, error handling)

Managing write-only fields and nested attributes

Ensuring compatibility across UniFi OS (UDM) and legacy controllers

Project Structure

```

internal/provider/

├── provider.go # Provider configuration and initialization

├── client.go # Auto-relogin client with retry logic

├── utils.go # Pointer helpers, error handling

├── traffic_types.go # Shared nested types for traffic rules/routes

├── *_resource.go # Resource implementations

├── *_data_source.go # Data source implementations

├── *_test.go # Acceptance tests

├── testutils_test.go # Shared test utilities

└── sweep_test.go # Test resource cleanup sweepers

```

Implementation Steps

Creating a New Resource

1. **Define the Model Struct**

- Use `tfsdk` tags for Terraform state mapping

- Mark sensitive fields (passwords, secrets) as `Sensitive: true`

- Use `types.String`, `types.Bool`, `types.Int64`, `types.List`, etc.

2. **Implement Schema Method**

- Use **ListNestedAttribute** or **SingleNestedAttribute** (NOT blocks)

- Add validators from `terraform-plugin-framework-validators`

- Add `UseStateForUnknown()` plan modifier for write-only fields

- Include `MarkdownDescription` for documentation generation

3. **Implement Conversion Functions**

- `planToSDK(plan *Model, diags *diag.Diagnostics) *sdktype.Request`

- `sdkToState(resp *sdktype.Response, priorState *Model) diag.Diagnostics`

- Handle write-only fields by preserving prior state values

4. **Implement CRUD Methods**

- `Create()` - Call API, handle errors with `handleSDKError()`, use `sdkToState()`

- `Read()` - Fetch resource, use `isNotFoundError()` for drift detection

- `Update()` - Call update API, handle partial updates if needed

- `Delete()` - Call delete API, handle already-deleted gracefully

- `ImportState()` - Use passthrough ID import

5. **Handle Write-Only Fields**

- Save value from plan before `sdkToState()`, restore after

- In `Read()`, pass `priorState` to preserve values not returned by API

- Resources with this pattern: `unifi_wlan`, `unifi_radius_profile`, `unifi_dynamic_dns`

Creating a New Data Source

1. **Reuse Resource Model** - Same struct but all fields marked `Computed: true`

2. **Add Lookup Field Validators** - Use `AtLeastOneOf` for id/name/key/hostname/description

3. **Implement Read Method**

- If ID provided, fetch directly

- Otherwise, list all resources and filter by lookup field

- Return error if not found or multiple matches

4. **Reuse sdkToState()** - Use resource's conversion function where possible

Writing Acceptance Tests

1. **Test Coverage Requirements**

- Basic creation test

- All attribute combinations

- Default value verification

- Update/modification scenarios

- Import state verification

- Destruction/cleanup verification

2. **Test Naming Convention**

- Function: `TestAcc{Resource}_{scenario}` (e.g., `TestAccNetworkResource_basic`)

- Resource names: `tf-acc-test-{resource}` prefix

- VLAN IDs: Use 3900+ range

- Rule indices: Use 2000+ range

3. **Controller Compatibility**

- Use `testAccPreCheckZoneBasedFirewall()` for v2 API features

- Implement skip logic for unsupported controllers

- Document compatibility in resource table

4. **Use Test Helpers**

- `testAccPreCheck(t)` - Standard pre-check

- `testAccCheckResourceDestroy()` - Verify cleanup

- Config builders for consistent test configs

5. **Implement Sweepers** - Add cleanup functions in `sweep_test.go`

Key Architectural Patterns

Auto-Relogin Client

Wraps SDK with automatic re-authentication

Channel-based semaphore for context-aware rate limiting

Thread-safe concurrent request handling

Error Handling

Use `handleSDKError()` for consistent error messages

Use `isNotFoundError()` to detect 404s for graceful deletion

`planToSDK()` accepts `*diag.Diagnostics` for conversion errors

`sdkToState()` returns `diag.Diagnostics` for propagating errors

Nested Attributes (Not Blocks)

Always use `ListNestedAttribute`/`SingleNestedAttribute` for new implementations.

**Schema:**

```go

"servers": schema.ListNestedAttribute{

Optional: true,

NestedObject: schema.NestedAttributeObject{

Attributes: map[string]schema.Attribute{...},

}

```

**HCL (with = and brackets):**

```hcl

servers = [{

ip = "10.0.0.1"

port = 1812

}]

```

Controller Compatibility

|----------------|----------|---------------------|--------------|

| UniFi OS (UDM, Network 10.x) | `/proxy/network/api/` | ✅ | ❌ |

| Legacy (standalone) | `/api/` | ❌ | ✅ |

Zone-based resources (`firewall_policy`, `firewall_zone`, `nat_rule`, `traffic_route`, `traffic_rule`, `static_dns`) require v2 API

Tests auto-skip on unsupported controllers

Known Limitations

| Resource | Limitation | Reason |

|----------|------------|--------|

| `unifi_firewall_zone` | No `site_id` attribute | API doesn't return it |

| `unifi_firewall_policy` | No `site_id` attribute | API doesn't return it |

| `unifi_wlan` | Import loses passphrase | Write-only field |

| `unifi_radius_profile` | Import loses server secrets | Write-only field |

| `unifi_dynamic_dns` | Import loses password | Write-only field |

Build & Test Commands

```bash

make build # Build provider

make test # Unit tests

make testacc # All acceptance tests

make testacc-run TEST=TestAccName # Run specific test

make sweep # Clean up test resources

make docs # Generate documentation

make fmt # Format code

```

Environment Setup

Create `.env` from `.env.example`:

```bash

UNIFI_BASE_URL=https://192.168.1.1

UNIFI_API_KEY=your-api-key # Recommended

UNIFI_USERNAME=admin # Alternative

UNIFI_PASSWORD=your-password # Alternative

UNIFI_INSECURE=true

```

API key authentication takes priority over username/password.

Post-Implementation Summary

After completing tasks, provide:

**Files Created**: New files with brief descriptions

**Files Modified**: Changed files and what was updated

**Key Details**: Test coverage, scope, or metrics

Code Preferences

**Minimal comments** - No inline comments unless truly necessary

**No over-engineering** - Don't add abstractions or features beyond requirements

**No Claude citations** - Exclude co-author tags from commits

**Use Context7 MCP** - Fetch current library/API docs when needed

**Use Playwright MCP** - For browser automation, web testing, or scraping tasks

Dependencies

[UniFi Go SDK](https://github.com/resnickio/unifi-go-sdk) - API client

terraform-plugin-framework v1.17.0+ - Provider framework

terraform-plugin-framework-validators - Schema validation

terraform-plugin-framework-timeouts - Timeout support

terraform-plugin-testing v1.14.0+ - Acceptance tests

terraform-plugin-docs - Documentation generation

Versioning

**v0.x.x** - Development phase, breaking changes allowed in minor versions

**v1.0.0+** - Stable API, breaking changes only in major versions

Use semantic versioning: MAJOR.MINOR.PATCH

Tag releases: `git tag -a vX.Y.Z -m "Release description"`

Important Notes

Always use nested **attributes**, not blocks, for new schema implementations

Implement sweepers for test resource cleanup

Document controller compatibility for new resources

Handle write-only fields with state preservation

Use standard error handling utilities (`handleSDKError`, `isNotFoundError`)

Follow test naming conventions and use appropriate ID ranges

terraform-provider-unifi