terraform-provider-unifi/docs/resources/device.md

page_title, subcategory, description

page_title	subcategory	description
unifi_device Resource - terraform-provider-unifi		The unifi_device resource manages UniFi network devices such as access points, switches, gateways, etc. Devices must first be adopted by the UniFi controller before they can be managed through Terraform. This resource cannot create new devices, but instead allows you to manage existing devices that have already been adopted. The recommended approach is to adopt devices through the UniFi controller UI first, then import them into Terraform using the device's MAC address. This resource supports managing device names, port configurations, and other device-specific settings.

unifi_device (Resource)

The unifi_device resource manages UniFi network devices such as access points, switches, gateways, etc.

Devices must first be adopted by the UniFi controller before they can be managed through Terraform. This resource cannot create new devices, but instead allows you to manage existing devices that have already been adopted. The recommended approach is to adopt devices through the UniFi controller UI first, then import them into Terraform using the device's MAC address.

This resource supports managing device names, port configurations, and other device-specific settings.

Example Usage

data "unifi_port_profile" "disabled" {
  # look up the built-in disabled port profile
  name = "Disabled"
}

resource "unifi_port_profile" "poe" {
  name    = "poe"
  forward = "customize"

  native_networkconf_id = var.native_network_id
  tagged_networkconf_ids = [
    var.some_vlan_network_id,
  ]

  poe_mode = "auto"
}

resource "unifi_device" "us_24_poe" {
  # optionally specify MAC address to skip manually importing
  # manual import is the safest way to add a device
  mac = "01:23:45:67:89:AB"

  name = "Switch with POE"

  port_override {
    number          = 1
    name            = "port w/ poe"
    port_profile_id = unifi_port_profile.poe.id
  }

  port_override {
    number          = 2
    name            = "disabled"
    port_profile_id = data.unifi_port_profile.disabled.id
  }

  # port aggregation for ports 11 and 12
  port_override {
    number              = 11
    op_mode             = "aggregate"
    aggregate_num_ports = 2
  }
}

Schema

Optional

• allow_adoption (Boolean) Whether to automatically adopt the device when creating this resource. When true:

• The controller will attempt to adopt the device
• Device must be in a pending adoption state
• Device must be accessible on the network Set to false if you want to manage adoption manually. Defaults to true.

• forget_on_destroy (Boolean) Whether to forget (un-adopt) the device when this resource is destroyed. When true:

• The device will be removed from the controller
• The device will need to be readopted to be managed again
• Device configuration will be reset Set to false to keep the device adopted when removing from Terraform management. Defaults to true.

• mac (String) The MAC address of the device in standard format (e.g., 'aa:bb:cc:dd:ee:ff'). This is used to identify and manage specific devices that have already been adopted by the controller.
• name (String) A friendly name for the device that will be displayed in the UniFi controller UI. Examples:

• 'Office-AP-1' for an access point
• 'Core-Switch-01' for a switch
• 'Main-Gateway' for a gateway Choose descriptive names that indicate location and purpose.

• port_override (Block Set) A list of port-specific configuration overrides for UniFi switches. This allows you to customize individual port settings such as:
  • Port names and labels for easy identification
  • Port profiles for VLAN and security settings
  • Operating modes for special functions

Common use cases include:

• Setting up trunk ports for inter-switch connections
• Configuring PoE settings for powered devices
• Creating mirrored ports for network monitoring
• Setting up link aggregation between switches or servers (see below for nested schema)

• site (String) The name of the UniFi site where the device is located. If not specified, the default site will be used.

Read-Only

• disabled (Boolean) Whether the device is administratively disabled. When true, the device will not forward traffic or provide services.
• id (String) The unique identifier of the device in the UniFi controller.

Nested Schema for port_override

Required:

• number (Number) The physical port number on the switch to configure.

Optional:

• aggregate_num_ports (Number) The number of ports to include in a link aggregation group (LAG). Valid range: 2-8 ports. Used when:

• Creating switch-to-switch uplinks for increased bandwidth
• Setting up high-availability connections
• Connecting to servers requiring more bandwidth Note: All ports in the LAG must be sequential and have matching configurations.

• name (String) A friendly name for the port that will be displayed in the UniFi controller UI. Examples:
  • 'Uplink to Core Switch'
  • 'Conference Room AP'
  • 'Server LACP Group 1'
  • 'VoIP Phone Port'
• op_mode (String) The operating mode of the port. Valid values are:
  • switch - Normal switching mode (default)
    • Standard port operation for connecting devices
    • Supports VLANs and all standard switching features
  • mirror - Port mirroring for traffic analysis
    • Copies traffic from other ports for monitoring
    • Useful for network troubleshooting and security
  • aggregate - Link aggregation/bonding mode
    • Combines multiple ports for increased bandwidth
    • Used for switch uplinks or high-bandwidth servers Defaults to switch.
• poe_mode (String) The Power over Ethernet (PoE) mode for the port. Valid values are:

• auto - Automatically detect and power PoE devices (recommended)
  • Provides power based on device negotiation
  • Safest option for most PoE devices
• pasv24 - Passive 24V PoE
  • For older UniFi devices requiring passive 24V
  • Use with caution to avoid damage
• passthrough - PoE passthrough mode
  • For daisy-chaining PoE devices
  • Available on select UniFi switches
• off - Disable PoE on the port
  • For non-PoE devices
  • To prevent unwanted power delivery

• port_profile_id (String) The ID of a pre-configured port profile to apply to this port. Port profiles define settings like VLANs, PoE, and other port-specific configurations.