b9284f7758
* docs: add examples and recreate TF documentation * update readme * add information about experimental support of firewall zones
245 lines
9.6 KiB
Markdown
245 lines
9.6 KiB
Markdown
---
|
|
layout: ""
|
|
page_title: "Provider: UniFi"
|
|
description: |-
|
|
The UniFi provider enables management and automation of Ubiquiti UniFi network infrastructure through Terraform.
|
|
---
|
|
|
|
# UniFi Provider
|
|
|
|
The UniFi provider enables infrastructure-as-code management of [Ubiquiti's UniFi](https://www.ui.com/) network controllers and devices. This provider allows you to automate the configuration and management of your UniFi network infrastructure using Terraform.
|
|
|
|
## Supported Features
|
|
|
|
- Manage UniFi network resources using Infrastructure as Code
|
|
- Support for UniFi Controller version 6.x and later
|
|
- Compatible with UDM, UDM-Pro, UCG, and standard controller deployments
|
|
- Comprehensive resource management including:
|
|
- Network/WLAN configuration
|
|
- Firewall rules and groups
|
|
- Port forwarding
|
|
- DNS records
|
|
- User management
|
|
- Device management
|
|
- And more...
|
|
|
|
## Supported Platforms
|
|
|
|
* UniFi Controller version 6.x and later
|
|
* UniFi Dream Machine (UDM)
|
|
* UniFi Dream Machine Pro (UDM-Pro)
|
|
* UniFi Cloud Gateway (UCG)
|
|
* Standard UniFi Controller deployments
|
|
|
|
## Authentication
|
|
|
|
The provider supports two authentication methods:
|
|
|
|
* **Username/Password Authentication** (Traditional method)
|
|
* **API Key Authentication** (Recommended, requires controller version 9.0.108 or later)
|
|
|
|
!> Hard-coding credentials into any Terraform configuration is not recommended, and risks secret leakage should this file ever be committed to a public version control system.
|
|
|
|
### Security Recommendations
|
|
|
|
* Use API Key authentication instead of username/password
|
|
* Create a dedicated service account for Terraform with appropriate permissions
|
|
* Use a **Limited Admin** role with **Local Access Only**
|
|
* Enable HTTPS and valid SSL certificates for your controller
|
|
* Store credentials securely using Terraform variables or environment variables
|
|
* Two-factor authentication (2FA) is not supported
|
|
|
|
### Generating an API Key
|
|
|
|
1. Open your Site in UniFi Site Manager
|
|
2. Click on `Control Plane -> Admins & Users`.
|
|
3. Select your Admin user.
|
|
4. Click `Create API Key`.
|
|
5. Add a name for your API Key.
|
|
6. Copy the key and store it securely, as it will only be displayed once.
|
|
7. Click `Done` to ensure the key is hashed and securely stored.
|
|
8. Use the API Key 🎉
|
|
|
|
## Example Usage
|
|
|
|
Using API Key authentication:
|
|
```terraform
|
|
provider "unifi" {
|
|
api_key = var.api_key # optionally use UNIFI_API_KEY env var
|
|
api_url = var.api_url # optionally use UNIFI_API env var
|
|
|
|
# you may need to allow insecure TLS communications unless you have configured
|
|
# certificates for your controller
|
|
allow_insecure = var.insecure # optionally use UNIFI_INSECURE env var
|
|
|
|
# if you are not configuring the default site, you can change the site
|
|
# site = "foo" or optionally use UNIFI_SITE env var
|
|
}
|
|
```
|
|
|
|
Using Username/Password authentication:
|
|
```terraform
|
|
provider "unifi" {
|
|
username = var.username # optionally use UNIFI_USERNAME env var
|
|
password = var.password # optionally use UNIFI_PASSWORD env var
|
|
api_url = var.api_url # optionally use UNIFI_API env var
|
|
|
|
# you may need to allow insecure TLS communications unless you have configured
|
|
# certificates for your controller
|
|
allow_insecure = var.insecure # optionally use UNIFI_INSECURE env var
|
|
|
|
# if you are not configuring the default site, you can change the site
|
|
# site = "foo" or optionally use UNIFI_SITE env var
|
|
}
|
|
```
|
|
|
|
<!-- schema generated by tfplugindocs -->
|
|
## Schema
|
|
|
|
### Optional
|
|
|
|
- `allow_insecure` (Boolean) Skip verification of TLS certificates of API requests. You may need to set this to `true` if you are using your local API without setting up a signed certificate. Can be specified with the `UNIFI_INSECURE` environment variable.
|
|
- `api_key` (String, Sensitive) API Key for the user accessing the API. Can be specified with the `UNIFI_API_KEY` environment variable. Controller version 9.0.108 or later is required.
|
|
- `api_url` (String) URL of the controller API. Can be specified with the `UNIFI_API` environment variable. You should **NOT** supply the path (`/api`), the SDK will discover the appropriate paths. This is to support UDM Pro style API paths as well as more standard controller paths.
|
|
- `password` (String, Sensitive) Password for the user accessing the API. Can be specified with the `UNIFI_PASSWORD` environment variable.
|
|
- `site` (String) The site in the Unifi controller this provider will manage. Can be specified with the `UNIFI_SITE` environment variable. Default: `default`
|
|
- `username` (String) Local user name for the Unifi controller API. Can be specified with the `UNIFI_USERNAME` environment variable.
|
|
|
|
## Migrating from paultyng/terraform-provider-unifi
|
|
|
|
This provider is a fork of the original [paultyng/terraform-provider-unifi](https://github.com/paultyng/terraform-provider-unifi) with significant enhancements, improvements, and additional features. If you're currently using the original provider, this guide will help you migrate to this enhanced version.
|
|
|
|
### Key Differences and Improvements
|
|
|
|
| Feature | paultyng/unifi | filipowm/unifi |
|
|
|---------|---------------|----------------|
|
|
| Framework | Terraform SDK v2 | Terraform Plugin Framework |
|
|
| Controller Support | UniFi Controller v6.x | UniFi Controller v6.x and later (including v9.x) |
|
|
| Authentication | Username/Password | Username/Password and API Key |
|
|
| Resource Organization | Flat structure | Organized by domain (settings, dns, etc.) |
|
|
| Validation | Basic | Enhanced with custom validators |
|
|
| Documentation | Basic | Comprehensive with examples |
|
|
| Settings Resources | Limited | Expanded (IPS, Guest Access, etc.) |
|
|
| DNS Management | Limited | Enhanced with dedicated resources |
|
|
|
|
### Migration Steps
|
|
|
|
1. **Update Provider Configuration**
|
|
|
|
Change your provider source from `paultyng/unifi` to `filipowm/unifi`:
|
|
|
|
```hcl
|
|
terraform {
|
|
required_providers {
|
|
unifi = {
|
|
source = "filipowm/unifi"
|
|
version = "~> 0.0.1" # Use the latest version
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
2. **Authentication Updates**
|
|
|
|
The provider configuration remains compatible, but now offers API Key authentication as an alternative to username/password:
|
|
|
|
```hcl
|
|
# Using API Key (recommended for newer controllers)
|
|
provider "unifi" {
|
|
api_key = var.api_key
|
|
api_url = var.api_url
|
|
allow_insecure = var.insecure
|
|
}
|
|
|
|
# Using Username/Password (backward compatible)
|
|
provider "unifi" {
|
|
username = var.username
|
|
password = var.password
|
|
api_url = var.api_url
|
|
allow_insecure = var.insecure
|
|
}
|
|
```
|
|
|
|
3. **Resource State Migration**
|
|
|
|
Most resources maintain backward compatibility, so your existing state should migrate seamlessly. However, for resources with enhanced functionality, you may need to run `terraform import` to reconcile state differences.
|
|
|
|
```bash
|
|
# Example: Re-importing a network resource
|
|
terraform import unifi_network.my_network 5dc28e5e9106d105bdc87217
|
|
```
|
|
|
|
4. **Enhanced Resource Configuration**
|
|
|
|
Take advantage of new validation and configuration options:
|
|
|
|
- Use the new validators for attributes like URLs, emails, and hostnames
|
|
- Leverage nested attributes for more organized configuration
|
|
- Utilize new settings resources for comprehensive network management
|
|
|
|
### New and Enhanced Resources
|
|
|
|
#### New Settings Resources
|
|
|
|
- `unifi_setting_auto_speedtest` - Manage automatic speed test configuration
|
|
- `unifi_setting_country` - Configure country settings
|
|
- `unifi_setting_dpi` - Manage Deep Packet Inspection settings
|
|
- `unifi_setting_guest_access` - Configure guest network access settings
|
|
- `unifi_setting_ips` - Manage Intrusion Prevention System settings
|
|
- `unifi_setting_lcd_monitor` - Configure LCD monitor settings for devices
|
|
- `unifi_setting_locale` - Set locale preferences
|
|
- `unifi_setting_magic_site_to_site_vpn` - Configure site-to-site VPN
|
|
- `unifi_setting_mgmt` - Manage management settings
|
|
- `unifi_setting_network_optimization` - Configure network optimization
|
|
- `unifi_setting_ntp` - Manage NTP server settings
|
|
- `unifi_setting_radius` - Configure RADIUS server settings
|
|
- `unifi_setting_rsyslogd` - Manage remote syslog settings
|
|
- `unifi_setting_ssl_inspection` - Configure SSL inspection
|
|
- `unifi_setting_teleport` - Manage Teleport settings
|
|
- `unifi_setting_usg` - Configure UniFi Security Gateway settings
|
|
- `unifi_setting_usw` - Manage UniFi Switch settings
|
|
|
|
#### Enhanced DNS Management
|
|
|
|
- `unifi_dns_record` - Create and manage DNS records
|
|
|
|
#### Other Improvements
|
|
|
|
- Enhanced validation for all resources
|
|
- Better error messages and diagnostics
|
|
- Improved documentation with comprehensive examples
|
|
- Support for the latest UniFi Controller features
|
|
|
|
### Developer-Focused Improvements
|
|
|
|
For developers extending or customizing the provider:
|
|
|
|
1. **Framework Migration**
|
|
- Migrated from Terraform SDK v2 to Terraform Plugin Framework
|
|
- Better type safety and validation capabilities
|
|
- Enhanced testing infrastructure
|
|
|
|
2. **Code Organization**
|
|
- Resources organized by domain in separate packages
|
|
- Base types and utilities for consistent implementation
|
|
- Custom validators for common validation patterns
|
|
|
|
3. **Testing**
|
|
- Comprehensive acceptance tests
|
|
- Test helpers and utilities
|
|
- Improved test stability
|
|
|
|
### Compatibility Notes
|
|
|
|
- The provider maintains backward compatibility with existing configurations where possible
|
|
- Some advanced features may require updates to your configuration
|
|
- The provider follows semantic versioning for releases
|
|
|
|
### Getting Help
|
|
|
|
If you encounter issues during migration:
|
|
|
|
1. Check the [documentation](https://registry.terraform.io/providers/filipowm/unifi/latest/docs)
|
|
2. Review examples in the [GitHub repository](https://github.com/filipowm/terraform-provider-unifi)
|
|
3. Open an issue on GitHub for assistance
|