netbox-community · rodvand · Mar 4, 2025 · Sep 20, 2024 · Sep 20, 2024 · Sep 20, 2024
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -16,12 +16,12 @@ jobs:
         uses: psf/black@stable
 
   unit_testing:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     needs: linting
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10", "3.11"]
+        python-version: ["3.13"]
 
     steps:
 
@@ -39,7 +39,7 @@ jobs:
           virtualenvs-create: false
 
       - name: Install Python packages
-        run: poetry install
+        run: poetry install --no-root
 
       - name: Build and install collection
         run: |
@@ -62,17 +62,17 @@ jobs:
     runs-on: ubuntu-latest
     needs: unit_testing
     env:
-      python-version: "3.12"
+      python-version: "3.13"
     strategy:
       fail-fast: false
       matrix:
-        include:          
-          - VERSION: "v3.7"
-            NETBOX_DOCKER_VERSION: 2.7.0
+        include:                    
           - VERSION: "v4.0"
             NETBOX_DOCKER_VERSION: 2.9.1
           - VERSION: "v4.1"
             NETBOX_DOCKER_VERSION: 3.0.1
+          - VERSION: "v4.2"
+            NETBOX_DOCKER_VERSION: 3.1.0
 
     steps:
 
@@ -101,7 +101,7 @@ jobs:
           virtualenvs-create: false
 
       - name: Install Python packages
-        run: poetry install
+        run: poetry install --no-root
 
       - name: Build and install collection
         run: |

diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -1,7 +1,7 @@
 ---
 version: 2
-# sphinx:
-#   configuration: docs/conf.py
+sphinx:
+  configuration: docs/conf.py
 
 build:
   os: ubuntu-22.04

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -4,6 +4,34 @@ NetBox.NetBox Release Notes
 
 .. contents:: Topics
 
+v3.21.0
+=======
+
+Minor Changes
+-------------
+
+- Add `label`, `description` and `enabled` to `netbox_device_interface_template` (https://github.com/netbox-community/ansible_modules/issues/1333)
+- Add example for using ansible variables in lookup
+- Add name as option to netbox_fhrp_group
+- Add support for custom headers
+- netbox_cluster - Add options scope and scope_type for NetBox 4.2+
+- netbox_device_interface - Add primary_mac_address option for NetBox 4.2+
+- netbox_prefix - Add options scope and scope_type for NetBox 4.2+
+- netbox_vm_interface - Add primary_mac_address option for NetBox 4.2+
+
+Bugfixes
+--------
+
+- Fix missing netbox_config_template module in module_defaults
+- Fixed an isssue with module_default parameter inheritance for modules netbox_config_template, netbox_custom_field_choice_set, netbox_permission, netbox_token, netbox_user, and netbox_user_group.
+- fix call /api/status/ instead /api/status in nb_inventory plugin. (https://github.com/netbox-community/ansible_modules/issues/1335).
+- netbox_ip_address - Fixed the problem preventing assignment of an IP address to a network interface
+
+New Modules
+-----------
+
+- netbox.netbox.netbox_mac_address - Create, update or delete MAC addresses within NetBox
+
 v3.20.0
 =======
 

diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@ This Ansible collection consists of a set of modules to define the intended netw
 ## Requirements
 
 - You must be running one of the two most recent releases of NetBox
-- A NetBox write-enabled API token when using modules or a read-only token for the `nb_lookup ` and `nb_inventory` plugins.
+- A NetBox write-enabled API token when using modules or a read-only token for the `nb_lookup` and `nb_inventory` plugins.
 - Python 3.10+
 - Python modules:
   - pytz
@@ -152,7 +152,7 @@ Customers of NetBox Labs and Ansible using the officially certified version of t
 The collection release notes and changelog can be found [here](https://github.com/netbox-community/ansible_modules/releases).
 
 ## Related Information
-Some extra resources you might find useful for both the Anisble collection and for NetBox itself:
+Some extra resources you might find useful for both the Ansible collection and for NetBox itself:
 - [NetBox Zero to Hero](https://netboxlabs.com/zero-to-hero/) - free 12 part course that takes you from an empty NetBox through to a fully deployed branch site, using the Ansible collection extensively along the way.
 - [Network Configuration Assurance with NetBox and Ansible](https://netboxlabs.com/blog/network-configuration-assurance-with-netbox-and-ansible/) - blog post featuring the Inventory plugin being used in a simple network automation use case to compare actual network state Vs intended state as defined in NetBox.
 - Official NetBox [documentation](https://docs.netbox.dev/en/stable/).

diff --git a/changelogs/changelog.yaml b/changelogs/changelog.yaml
@@ -3,14 +3,14 @@
  0.1.0:
    changes:
      breaking_changes:
      - Changed ``group`` to ``tenant_group`` in ``netbox_tenant.py`` (https://github.com/netbox-community/ansible_modules/issues/9)
      - Changed ``role`` to ``prefix_role`` in ``netbox_prefix.py`` (https://github.com/netbox-community/ansible_modules/issues/9)
      - Module failures when required fields arent provided (https://github.com/netbox-community/ansible_modules/issues/24)
      - Renamed ``netbox_interface`` to ``netbox_device_interface`` (https://github.com/netbox-community/ansible_modules/issues/9)
      minor_changes:
      - Add ``primary_ip4/6`` to ``netbox_ip_address`` (https://github.com/netbox-community/ansible_modules/issues/10)
    modules:
    - description: Creates or removes aggregates from NetBox
      name: netbox_aggregate
      namespace: ''
    - description: Create, update or delete circuits within NetBox
@@ -94,28 +94,28 @@
  0.1.1:
    changes:
      bugfixes:
      - Fixed issue with netbox_vm_interface where it would fail if different virtual
        machine had the same interface name (https://github.com/netbox-community/ansible_modules/issues/40)
      - Updated netbox_ip_address to find interfaces on virtual machines correctly
        (https://github.com/netbox-community/ansible_modules/issues/40)
  0.1.10:
    changes:
      bugfixes:
      - Updated inventory plugin name from netbox.netbox.netbox to netbox.netbox.nb_inventory
        (https://github.com/netbox-community/ansible_modules/pull/129)
  0.1.2:
    changes:
      bugfixes:
      - Allow endpoint choices to be an integer of the choice rather than attempting
        to dynamically determine the choice ID (https://github.com/netbox-community/ansible_modules/issues/47)
  0.1.3:
    changes:
      bugfixes:
      - Add error handling for invalid key_file for lookup plugin (https://github.com/netbox-community/ansible_modules/issues/52)
  0.1.5:
    changes:
      bugfixes:
      - Add argument specs for every module to validate data passed in. Fixes some
        idempotency issues. POSSIBLE BREAKING CHANGE (https://github.com/netbox-community/ansible_modules/issues/68)
      - Allow name updates to manufacturers (https://github.com/netbox-community/ansible_modules/issues/76)
      - Builds slug for netbox_device_type from model which is now required and slug
@@ -129,13 +129,13 @@
        a /32 and pass to NetBox. Fixes idempotency cidr notation is not provided
        (https://github.com/netbox-community/ansible_modules/issues/78)
    modules:
    - description: Creates or removes service from NetBox
      name: netbox_service
      namespace: ''
  0.1.6:
    changes:
      bugfixes:
      - Fixed vlan searching with vlan_group for netbox_prefix (https://github.com/netbox-community/ansible_modules/issues/85)
      - Removed static choices from netbox_utils and now pulls the choices for each
        endpoint from the NetBox API at call time (https://github.com/netbox-community/ansible_modules/issues/67)
      minor_changes:
@@ -815,6 +815,42 @@
       name: netbox_user_group
       namespace: ''
     release_date: '2024-09-12'
+  3.21.0:
+    changes:
+      bugfixes:
+      - Fix missing netbox_config_template module in module_defaults
+      - Fixed an isssue with module_default parameter inheritance for modules netbox_config_template,
+        netbox_custom_field_choice_set, netbox_permission, netbox_token, netbox_user,
+        and netbox_user_group.
+      - fix call /api/status/ instead /api/status in nb_inventory plugin. (https://github.com/netbox-community/ansible_modules/issues/1335).
+      - netbox_ip_address - Fixed the problem preventing assignment of an IP address
+        to a network interface
+      minor_changes:
+      - Add `label`, `description` and `enabled` to `netbox_device_interface_template`
+        (https://github.com/netbox-community/ansible_modules/issues/1333)
+      - Add example for using ansible variables in lookup
+      - Add name as option to netbox_fhrp_group
+      - Add support for custom headers
+      - netbox_cluster - Add options scope and scope_type for NetBox 4.2+
+      - netbox_device_interface - Add primary_mac_address option for NetBox 4.2+
+      - netbox_prefix - Add options scope and scope_type for NetBox 4.2+
+      - netbox_vm_interface - Add primary_mac_address option for NetBox 4.2+
+    fragments:
+    - 1323-fixing-bug-#975.yml
+    - 1327-add-custom-headers.yml
+    - 1332-add-hostname_field-option.yml
+    - 1333-feature-netbox_device_interface_template.yml
+    - 1335-api-status-page-not-found.yml
+    - 1339-name-to-fhrp-group.yml
+    - 1356-add-modules-to-action-groups.yml
+    - action_groups_config_template.yml
+    - netbox_mac_address.yml
+    - scope_prefix_cluster.yml
+    modules:
+    - description: Create, update or delete MAC addresses within NetBox
+      name: netbox_mac_address
+      namespace: ''
+    release_date: '2025-03-04'
   3.3.0:
     changes:
       minor_changes:

diff --git a/docs/conf.py b/docs/conf.py
@@ -27,7 +27,7 @@
 author = "Mikhail Yohman <@FragmentedPacket>"
 
 # The full version, including alpha/beta/rc tags
-release = "3.20.0"
+release = "3.21.0"
 
 
 # -- General configuration ---------------------------------------------------

diff --git a/docs/plugins/environment_variables.rst b/docs/plugins/environment_variables.rst
@@ -44,6 +44,13 @@ Environment variables used by the ansible-core configuration are documented in :
 
     *Used by:*
     :ansplugin:`netbox.netbox.nb\_lookup lookup plugin <netbox.netbox.nb_lookup#lookup>`
+.. envvar:: NETBOX_HEADERS
+
+    Dictionary of headers to be passed to the NetBox API.
+
+    *Used by:*
+    :ansplugin:`netbox.netbox.nb\_inventory inventory plugin <netbox.netbox.nb_inventory#inventory>`,
+    :ansplugin:`netbox.netbox.nb\_lookup lookup plugin <netbox.netbox.nb_lookup#lookup>`
 .. envvar:: NETBOX_TOKEN
 
     See the documentations for the options where this environment variable is used.

diff --git a/docs/plugins/index.rst b/docs/plugins/index.rst
@@ -7,7 +7,7 @@
 Netbox.Netbox
 =============
 
-Collection version 3.20.0
+Collection version 3.21.0
 
 .. contents::
    :local:
@@ -92,6 +92,7 @@ Modules
 * :ansplugin:`netbox_l2vpn module <netbox.netbox.netbox_l2vpn#module>` -- Create, update or delete L2VPNs within NetBox
 * :ansplugin:`netbox_l2vpn_termination module <netbox.netbox.netbox_l2vpn_termination#module>` -- Create, update or delete L2VPNs terminations within NetBox
 * :ansplugin:`netbox_location module <netbox.netbox.netbox_location#module>` -- Create, update or delete locations within NetBox
+* :ansplugin:`netbox_mac_address module <netbox.netbox.netbox_mac_address#module>` -- Create, update or delete MAC addresses within NetBox
 * :ansplugin:`netbox_manufacturer module <netbox.netbox.netbox_manufacturer#module>` -- Create or delete manufacturers within NetBox
 * :ansplugin:`netbox_module module <netbox.netbox.netbox_module#module>` -- Create, update or delete module within NetBox
 * :ansplugin:`netbox_module_bay module <netbox.netbox.netbox_module_bay#module>` -- Create, update or delete module bay within NetBox
@@ -184,6 +185,7 @@ Modules
     netbox_l2vpn_module
     netbox_l2vpn_termination_module
     netbox_location_module
+    netbox_mac_address_module
     netbox_manufacturer_module
     netbox_module_module
     netbox_module_bay_module

diff --git a/docs/plugins/nb_inventory_inventory.rst b/docs/plugins/nb_inventory_inventory.rst
@@ -22,7 +22,7 @@ netbox.netbox.nb_inventory inventory -- NetBox inventory source
 .. Collection note
 
 .. note::
-    This inventory plugin is part of the `netbox.netbox collection <https://galaxy.ansible.com/ui/repo/published/netbox/netbox/>`_ (version 3.20.0).
+    This inventory plugin is part of the `netbox.netbox collection <https://galaxy.ansible.com/ui/repo/published/netbox/netbox/>`_ (version 3.21.0).
 
     It is not included in ``ansible-core``.
     To check whether it is installed, run :code:`ansible-galaxy collection list`.
@@ -421,7 +421,7 @@ Parameters
 
         <div class="ansible-option-cell">
 
-      Prefix to use for cache plugin files/tables
+      Prefix to use for cache plugin files/tables.
 
 
       .. rst-class:: ansible-option-line
@@ -486,7 +486,7 @@ Parameters
 
         <div class="ansible-option-cell">
 
-      Cache duration in seconds
+      Cache duration in seconds.
 
 
       .. rst-class:: ansible-option-line
@@ -1162,6 +1162,54 @@ Parameters
 
       :ansible-option-default-bold:`Default:` :ansible-option-default:`{}`
 
+      .. raw:: html
+
+        </div>
+
+  * - .. raw:: html
+
+        <div class="ansible-option-cell">
+        <div class="ansibleOptionAnchor" id="parameter-headers"></div>
+
+      .. _ansible_collections.netbox.netbox.nb_inventory_inventory__parameter-headers:
+
+      .. rst-class:: ansible-option-title
+
+      **headers**
+
+      .. raw:: html
+
+        <a class="ansibleOptionLink" href="#parameter-headers" title="Permalink to this option"></a>
+
+      .. ansible-option-type-line::
+
+        :ansible-option-type:`string`
+
+
+
+
+      .. raw:: html
+
+        </div>
+
+    - .. raw:: html
+
+        <div class="ansible-option-cell">
+
+      Dictionary of headers to be passed to the NetBox API.
+
+
+      .. rst-class:: ansible-option-line
+
+      :ansible-option-default-bold:`Default:` :ansible-option-default:`{}`
+
+      .. rst-class:: ansible-option-line
+
+      :ansible-option-configuration:`Configuration:`
+
+      - Environment variable: :envvar:`NETBOX\_HEADERS`
+
+
       .. raw:: html
 
         </div>
@@ -1427,7 +1475,7 @@ Parameters
 
         <div class="ansible-option-indent-desc"></div><div class="ansible-option-cell">
 
-      The key from input dictionary used to generate groups
+      The key from input dictionary used to generate groups.
 
 
       .. raw:: html
@@ -1472,7 +1520,7 @@ Parameters
 
         <div class="ansible-option-indent-desc"></div><div class="ansible-option-cell">
 
-      parent group for keyed group
+      parent group for keyed group.
 
 
       .. raw:: html
@@ -1517,7 +1565,7 @@ Parameters
 
         <div class="ansible-option-indent-desc"></div><div class="ansible-option-cell">
 
-      A keyed group name will start with this prefix
+      A keyed group name will start with this prefix.
 
 
       .. rst-class:: ansible-option-line
@@ -1566,7 +1614,7 @@ Parameters
 
         <div class="ansible-option-indent-desc"></div><div class="ansible-option-cell">
 
-      separator used to build the keyed group name
+      separator used to build the keyed group name.
 
 
       .. rst-class:: ansible-option-line
@@ -1618,7 +1666,7 @@ Parameters
 
         <div class="ansible-option-indent-desc"></div><div class="ansible-option-cell">
 
-      Set this option to :ansval:`False` to omit the :ansopt:`netbox.netbox.nb\_inventory#inventory:keyed\_groups[].separator` after the host variable when the value is an empty string.
+      Set this option to :ansval:`false` to omit the :ansopt:`netbox.netbox.nb\_inventory#inventory:keyed\_groups[].separator` after the host variable when the value is an empty string.
 
       This option is mutually exclusive with :ansopt:`netbox.netbox.nb\_inventory#inventory:keyed\_groups[].default\_value`.
 
@@ -1669,13 +1717,13 @@ Parameters
 
         <div class="ansible-option-cell">
 
-      Use in conjunction with keyed\_groups.
+      Use in conjunction with :ansopt:`netbox.netbox.nb\_inventory#inventory:keyed\_groups`.
 
       By default, a keyed group that does not have a prefix or a separator provided will have a name that starts with an underscore.
 
-      This is because the default prefix is "" and the default separator is "\_".
+      This is because the default prefix is :ansval:`""` and the default separator is :ansval:`"\_"`.
 
-      Set this option to False to omit the leading underscore (or other separator) if no prefix is given.
+      Set this option to :ansval:`false` to omit the leading underscore (or other separator) if no prefix is given.
 
       If the group name is derived from a mapping the separator is still used to concatenate the items.
 
@@ -2586,6 +2634,8 @@ Examples
     device_query_filters:
       - has_primary_ip: 'true'
       - tenant__n: internal
+    headers:
+      Cookie: "{{ auth_cookie }}"
 
     # has_primary_ip is a useful way to filter out patch panels and other passive devices
     # Adding '__n' to a field searches for the negation of the value.