fix(netbox_device_interface): fail on read-only mac_address for NetBox v4.2+

[ldrozdz93]

What this fixes

On NetBox 4.2 and later, setting mac_address on netbox_device_interface reported changed with a before/after diff on every run, but NetBox was never actually updated. Users believed the MAC address was stored when it wasn't.

NetBox 4.2 moved MAC addresses to a standalone MACAddress model and made the interface's legacy mac_address field read-only, so the API silently drops any value sent to it. Because the module decides changed by comparing the requested data against the serialized object locally, the dropped value reappeared as a phantom change on every run — including in check mode.

Behaviour after this change

On NetBox 4.2+, a task that sets the legacy mac_address field now fails with a clear, actionable message instead of reporting a change that never happened:

The 'mac_address' field is read-only on NetBox v4.2 and later, so the value is silently dropped and never stored. Use the 'primary_mac_address' option of this module to set the interface's primary MAC address, and the 'netbox_mac_address' module to manage MAC address objects.

The reported result now matches what NetBox actually stores, in both normal and check mode. NetBox versions before 4.2, where mac_address is still writable, are unaffected.

Why fail rather than store the MAC under the hood

primary_mac_address only links an existing MACAddress; creating and assigning one automatically would be a larger change with its own idempotency surface. Failing loudly is the smallest fix that guarantees the reported state matches NetBox and gives the user an unambiguous next step. The module documentation for mac_address now states it is for NetBox < 4.2 and points to the replacements.

Tests

• Unit — _fail_on_read_only_mac_address is covered across NetBox 3.7 / 4.1 (allowed), 4.2 / 4.4.8 / 4.5 (fail), plus the no-MAC and null-MAC cases.
• Integration — netbox_device_interface plays for v4.2–v4.5 assert that a legacy mac_address task fails with the replacement guidance and reports no change, in both normal and check mode.

Fixes #1502

[Copilot]

Pull request overview

This PR fixes a NetBox v4.2+ idempotency/accuracy issue where netbox_device_interface could report changed for the legacy mac_address field even though NetBox silently discards the write. The module now fails early with actionable guidance so the reported result matches what NetBox can actually persist.

Changes:

• Add a version-gated guard that fails when mac_address is set for device interfaces on NetBox v4.2+ (read-only field).
• Update netbox_device_interface documentation to clarify mac_address support (<4.2) and point users to primary_mac_address + netbox_mac_address.
• Add unit + integration tests validating failure behavior (including check mode) and add a changelog fragment.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
plugins/module_utils/netbox_utils.py	Adds _fail_on_read_only_mac_address() helper to fail on NetBox v4.2+ when legacy mac_address is set.
plugins/module_utils/netbox_dcim.py	Invokes the new guard for the interfaces endpoint to prevent phantom changes.
plugins/modules/netbox_device_interface.py	Documents that mac_address is only supported on NetBox < 4.2 and points to replacements.
tests/unit/module_utils/netbox_utils/test_netbox_module.py	Adds unit coverage for the new read-only MAC guard across versions and edge cases.
tests/integration/targets/v4.2/tasks/netbox_device_interface.yml	Adds integration assertions that legacy mac_address fails (unchanged) on v4.2, including check mode.
tests/integration/targets/v4.3/tasks/netbox_device_interface.yml	Adds the same failure assertions for v4.3.
tests/integration/targets/v4.4/tasks/netbox_device_interface.yml	Adds the same failure assertions for v4.4.
tests/integration/targets/v4.5/tasks/netbox_device_interface.yml	Adds the same failure assertions for v4.5.
changelogs/fragments/1502-device-interface-mac-address-readonly.yml	Adds a bugfix changelog entry describing the new behavior and guidance.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.