#770 Add module inventory item role (#885)

* Add module for inventory item role

Author: rodvand

meta/runtime.yml

@@ -39,6 +39,7 @@ action_groups:
     - netbox_front_port
     - netbox_front_port_template
     - netbox_inventory_item
+    - netbox_inventory_item_role
     - netbox_ip_address
     - netbox_ipam_role
     - netbox_l2vpn

plugins/module_utils/netbox_dcim.py

@@ -28,6 +28,7 @@
 NB_INTERFACES = "interfaces"
 NB_INTERFACE_TEMPLATES = "interface_templates"
 NB_INVENTORY_ITEMS = "inventory_items"
+NB_INVENTORY_ITEM_ROLES = "inventory_item_roles"
 NB_LOCATIONS = "locations"
 NB_MANUFACTURERS = "manufacturers"
 NB_PLATFORMS = "platforms"
@@ -79,6 +80,7 @@ def run(self):
         - interfaces
         - interface_templates
         - inventory_items
+        - inventory_item_roles
         - locations
         - manufacturers
         - platforms

plugins/module_utils/netbox_utils.py

@@ -55,6 +55,7 @@
         "interfaces",
         "interface_templates",
         "inventory_items",
+        "inventory_item_roles",
         "locations",
         "manufacturers",
         "platforms",
@@ -127,6 +128,7 @@
     export_template="name",
     group="slug",
     installed_device="name",
+    inventory_item_role="name",
     import_targets="name",
     l2vpn="name",
     location="slug",
@@ -308,6 +310,7 @@
     "interfaces": "interface",
     "interface_templates": "interface_template",
     "inventory_items": "inventory_item",
+    "inventory_item_roles": "inventory_item_role",
     "ip_addresses": "ip_address",
     "l2vpns": "l2vpn",
     "locations": "location",
@@ -407,6 +410,7 @@
     "interface_b": set(["name", "device"]),
     "interface_template": set(["name", "device_type"]),
     "inventory_item": set(["name", "device"]),
+    "inventory_item_role": set(["name"]),
     "ip_address": set(["address", "vrf", "device", "interface", "assigned_object"]),
     "ip_addresses": set(["address", "vrf", "device", "interface", "assigned_object"]),
     "ipaddresses": set(
@@ -560,6 +564,7 @@
     "contact_roles",
     "device_roles",
     "device_types",
+    "inventory_item_roles",
     "ipam_roles",
     "l2vpns",
     "locations",

plugins/modules/netbox_inventory_item_role.py

@@ -0,0 +1,146 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+# Copyright: (c) 2022, Martin Rødvand (@rodvand) <martin@rodvand.net>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+
+__metaclass__ = type
+
+DOCUMENTATION = r"""
+---
+module: netbox_inventory_item_role
+short_description: Create, update or delete devices roles within NetBox
+description:
+  - Creates, updates or removes devices roles from NetBox
+notes:
+  - Tags should be defined as a YAML list
+  - This should be ran with connection C(local) and hosts C(localhost)
+author:
+  - Martin Rødvand (@rodvand)
+requirements:
+  - pynetbox
+version_added: '3.10.0'
+extends_documentation_fragment:
+  - netbox.netbox.common
+options:
+  data:
+    description:
+      - Defines the inventory item role configuration
+    suboptions:
+      name:
+        description:
+          - The name of the inventory item role
+        required: true
+        type: str
+      description:
+        description:
+          - The description of the inventory item role
+        required: false
+        type: str
+      color:
+        description:
+          - Hexidecimal code for a color, ex. FFFFFF
+        required: false
+        type: str
+      slug:
+        description:
+          - The slugified version of the name or custom slug.
+          - This is auto-generated following NetBox rules if not provided
+        required: false
+        type: str      
+      tags:
+        description:
+          - The tags to add/update
+        required: false
+        type: list
+        elements: raw        
+      custom_fields:
+        description:
+          - Must exist in NetBox
+        required: false
+        type: dict        
+    required: true
+    type: dict
+"""
+
+EXAMPLES = r"""
+- name: "Test NetBox modules"
+  connection: local
+  hosts: localhost
+  gather_facts: False
+
+  tasks:
+    - name: Create inventory item role within NetBox with only required information
+      netbox.netbox.netbox_inventory_item_role:
+        netbox_url: http://netbox.local
+        netbox_token: thisIsMyToken
+        data:
+          name: Test Inventory Item role
+          color: FFFFFF
+        state: present
+
+    - name: Delete inventory item role within netbox
+      netbox.netbox.netbox_inventory_item_role:
+        netbox_url: http://netbox.local
+        netbox_token: thisIsMyToken
+        data:
+          name: Test Inventory Item role
+        state: absent
+"""
+
+RETURN = r"""
+inventory_item_role:
+  description: Serialized object as created or already existent within NetBox
+  returned: success (when I(state=present))
+  type: dict
+msg:
+  description: Message indicating failure or info about what has been achieved
+  returned: always
+  type: str
+"""
+from ansible_collections.netbox.netbox.plugins.module_utils.netbox_utils import (
+    NetboxAnsibleModule,
+    NETBOX_ARG_SPEC,
+)
+from ansible_collections.netbox.netbox.plugins.module_utils.netbox_dcim import (
+    NetboxDcimModule,
+    NB_INVENTORY_ITEM_ROLES,
+)
+from copy import deepcopy
+
+
+def main():
+    """
+    Main entry point for module execution
+    """
+    argument_spec = deepcopy(NETBOX_ARG_SPEC)
+    argument_spec.update(
+        dict(
+            data=dict(
+                type="dict",
+                required=True,
+                options=dict(
+                    name=dict(required=True, type="str"),
+                    description=dict(required=False, type="str"),
+                    color=dict(required=False, type="str"),
+                    slug=dict(required=False, type="str"),
+                    tags=dict(required=False, type="list", elements="raw"),
+                    custom_fields=dict(required=False, type="dict"),
+                ),
+            ),
+        )
+    )
+
+    required_if = [("state", "present", ["name"]), ("state", "absent", ["name"])]
+
+    module = NetboxAnsibleModule(
+        argument_spec=argument_spec, supports_check_mode=True, required_if=required_if
+    )
+
+    netbox_inventory_item_role = NetboxDcimModule(module, NB_INVENTORY_ITEM_ROLES)
+    netbox_inventory_item_role.run()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

tests/integration/targets/v3.3/tasks/main.yml

@@ -245,4 +245,13 @@
       tags:
         - netbox_l2vpn
   tags:
-    - netbox_l2vpn
+    - netbox_l2vpn
+
+- name: "NETBOX_INVENTORY_ITEM_ROLE TESTS"
+  include_tasks: 
+    file: "netbox_inventory_item_role.yml"
+    apply:
+      tags:
+        - netbox_inventory_item_role
+  tags:
+    - netbox_inventory_item_role

tests/integration/targets/v3.3/tasks/netbox_inventory_item_role.yml

@@ -0,0 +1,98 @@
+---
+##
+##
+### NETBOX_INVENTORY_ITEM_ROLE
+##
+##
+- name: "INVENTORY_ITEM_ROLE 1: Necessary info creation"
+  netbox.netbox.netbox_inventory_item_role:
+    netbox_url: http://localhost:32768
+    netbox_token: 0123456789abcdef0123456789abcdef01234567
+    data:
+      name: "Test Inventory Item Role"
+      color: "FFFFFF"
+    state: present
+  register: test_one
+
+- name: "INVENTORY_ITEM_ROLE 1: ASSERT - Necessary info creation"
+  assert:
+    that:
+      - test_one is changed
+      - test_one['diff']['before']['state'] == "absent"
+      - test_one['diff']['after']['state'] == "present"
+      - test_one['inventory_item_role']['name'] == "Test Inventory Item Role"
+      - test_one['inventory_item_role']['slug'] == "test-inventory-item-role"
+      - test_one['inventory_item_role']['color'] == "ffffff"
+      - test_one['msg'] == "inventory_item_role Test Inventory Item Role created"
+
+- name: "INVENTORY_ITEM_ROLE 2: Create duplicate"
+  netbox.netbox.netbox_inventory_item_role:
+    netbox_url: http://localhost:32768
+    netbox_token: 0123456789abcdef0123456789abcdef01234567
+    data:
+      name: "Test Inventory Item Role"
+      color: "FFFFFF"
+    state: present
+  register: test_two
+
+- name: "INVENTORY_ITEM_ROLE 2: ASSERT - Create duplicate"
+  assert:
+    that:
+      - not test_two['changed']
+      - test_two['inventory_item_role']['name'] == "Test Inventory Item Role"
+      - test_two['inventory_item_role']['slug'] == "test-inventory-item-role"
+      - test_two['inventory_item_role']['color'] == "ffffff"
+      - test_two['msg'] == "inventory_item_role Test Inventory Item Role already exists"
+
+- name: "INVENTORY_ITEM_ROLE 3: ASSERT - Update"
+  netbox.netbox.netbox_inventory_item_role:
+    netbox_url: http://localhost:32768
+    netbox_token: 0123456789abcdef0123456789abcdef01234567
+    data:
+      name: "Test Inventory Item Role"
+      color: "003EFF"      
+    state: present
+  register: test_three
+
+- name: "INVENTORY_ITEM_ROLE 3: ASSERT - Update"
+  assert:
+    that:
+      - test_three is changed
+      - test_three['diff']['after']['color'] == "003eff"      
+      - test_three['inventory_item_role']['name'] == "Test Inventory Item Role"
+      - test_three['inventory_item_role']['slug'] == "test-inventory-item-role"
+      - test_three['inventory_item_role']['color'] == "003eff"      
+      - test_three['msg'] == "inventory_item_role Test Inventory Item Role updated"
+
+- name: "INVENTORY_ITEM_ROLE 4: ASSERT - Delete"
+  netbox.netbox.netbox_inventory_item_role:
+    netbox_url: http://localhost:32768
+    netbox_token: 0123456789abcdef0123456789abcdef01234567
+    data:
+      name: Test Inventory Item Role
+    state: absent
+  register: test_four
+
+- name: "INVENTORY_ITEM_ROLE 4: ASSERT - Delete"
+  assert:
+    that:
+      - test_four is changed
+      - test_four['diff']['before']['state'] == "present"
+      - test_four['diff']['after']['state'] == "absent"
+      - test_four['msg'] == "inventory_item_role Test Inventory Item Role deleted"
+
+- name: "INVENTORY_ITEM_ROLE 5: ASSERT - Delete non existing"
+  netbox.netbox.netbox_inventory_item_role:
+    netbox_url: http://localhost:32768
+    netbox_token: 0123456789abcdef0123456789abcdef01234567
+    data:
+      name: Test Inventory Item Role
+    state: absent
+  register: test_five
+
+- name: "INVENTORY_ITEM_ROLE 5: ASSERT - Delete non existing`"
+  assert:
+    that:
+      - not test_five['changed']
+      - test_five['inventory_item_role'] == None
+      - test_five['msg'] == "inventory_item_role Test Inventory Item Role already absent"