Feature: Added module for FHRP group assignments (#974)

* Added fhrp_group_assignment module
* Added fhrp groups creation to netbox-deploy
* Added tests for fhrp_group_assignment module
* Added netbox_fhrp_group_assignment to runtime.yml

Author: andrii-konts

meta/runtime.yml

@@ -38,6 +38,7 @@ action_groups:
     - netbox_device_type
     - netbox_export_template
     - netbox_fhrp_group
+    - netbox_fhrp_group_assignment
     - netbox_front_port
     - netbox_front_port_template
     - netbox_inventory_item

plugins/module_utils/netbox_ipam.py

@@ -21,6 +21,7 @@
 NB_AGGREGATES = "aggregates"
 NB_ASNS = "asns"
 NB_FHRP_GROUPS = "fhrp_groups"
+NB_FHRP_GROUP_ASSIGNMENTS = "fhrp_group_assignments"
 NB_IP_ADDRESSES = "ip_addresses"
 NB_PREFIXES = "prefixes"
 NB_IPAM_ROLES = "roles"
@@ -152,6 +153,7 @@ def run(self):
         - aggregates
         - asns
         - fhrp_groups
+        - fhrp_group_assignments
         - ipam_roles
         - ip_addresses
         - l2vpns
@@ -190,6 +192,12 @@ def run(self):
             name = data.get("asn")
         elif self.endpoint == "fhrp_groups":
             name = data.get("group_id")
+        elif self.endpoint == "fhrp_group_assignments":
+            name = "fhrp_group %s > %s %s" % (
+                data.get("group"),
+                data.get("interface_type"),
+                data.get("interface_id"),
+            )
         else:
             name = data.get("name")
 

plugins/module_utils/netbox_utils.py

@@ -89,6 +89,7 @@
         "aggregates",
         "asns",
         "fhrp_groups",
+        "fhrp_group_assignments",
         "ip_addresses",
         "l2vpns",
         "l2vpn_terminations",
@@ -133,6 +134,7 @@
     export_targets="name",
     export_template="name",
     fhrp_groups="group_id",
+    fhrp_group_assignments="id",
     group="slug",
     installed_device="name",
     inventory_item_role="name",
@@ -317,6 +319,7 @@
     "device_types": "device_type",
     "export_templates": "export_template",
     "fhrp_groups": "fhrp_group",
+    "fhrp_group_assignments": "fhrp_group_assignment",
     "front_ports": "front_port",
     "front_port_templates": "front_port_template",
     "journal_entries": "journal_entry",
@@ -421,6 +424,7 @@
     "fhrp_group": set(
         ["id", "group_id", "interface_type", "device", "virtual_machine"]
     ),
+    "fhrp_group_assignment": set(["group", "interface_type", "interface_id"]),
     "front_port": set(["name", "device", "rear_port"]),
     "front_port_template": set(["name", "device_type", "rear_port"]),
     "installed_device": set(["name"]),
@@ -550,6 +554,7 @@
     "cluster_type": "type",
     "cluster_group": "group",
     "contact_group": "group",
+    "fhrp_group": "group",
     "parent_contact_group": "parent",
     "parent_location": "parent",
     "parent_interface": "parent",

plugins/modules/netbox_fhrp_group_assignment.py

@@ -0,0 +1,143 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+# Copyright: (c) 2023, Andrii Konts (@andrii-konts) <andrew.konts@uk2group.com>
+# 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_fhrp_group_assignment
+short_description: Create, update or delete FHRP group assignments within NetBox
+description:
+  - Creates, updates or removes FHRP group assignments from NetBox
+notes:
+  - Tags should be defined as a YAML list
+  - This should be ran with connection C(local) and hosts C(localhost)
+author:
+  - Andrii Konts (@andrii-konts)
+requirements:
+  - pynetbox
+seealso:
+  - name: FHRP Group Model reference
+    description: NetBox Documentation for FHRP Group Model.
+    link: https://docs.netbox.dev/en/stable/models/ipam/fhrpgroupassignment/
+extends_documentation_fragment:
+  - netbox.netbox.common
+options:
+  data:
+    type: dict
+    description:
+      - Defines the FHRP group assignment configuration
+    suboptions:
+      fhrp_group:
+        description:
+          - FHRP Group ID
+        required: True
+        type: int
+      interface_type:
+        description:
+          - Interface type
+        required: True
+        choices:
+          - dcim.interface
+          - virtualization.vminterface
+        type: str
+      interface_id:
+        description:
+          - Interface ID
+        type: int
+        required: True
+      priority:
+        description:
+          - Priority (0 .. 255)
+        type: int
+    required: True
+"""
+
+EXAMPLES = r"""
+- hosts: localhost
+  connection: local
+  module_defaults:
+    group/netbox.netbox.netbox:
+      netbox_url: "http://netbox.local"
+      netbox_token: "thisIsMyToken"
+
+  tasks:
+    - name: "Create FHRP group assignment within netbox"
+      netbox.netbox.netbox_fhrp_group_assignment:
+        data:
+          fhrp_group: 3
+          interface_type: dcim.interface
+          interface_id: 5
+          priority: 1
+        state: present
+
+    - name: Delete FHRP group assignment within netbox
+      netbox.netbox.netbox_fhrp_group_assignment:
+        data:
+          fhrp_group: 3
+          interface_type: dcim.interface
+          interface_id: 5
+        state: absent
+
+"""
+
+RETURN = r"""
+fhrp_group:
+  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_ipam import (
+    NetboxIpamModule,
+    NB_FHRP_GROUP_ASSIGNMENTS,
+)
+
+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(
+                    fhrp_group=dict(required=True, type="int"),
+                    interface_type=dict(
+                        required=True,
+                        type="str",
+                        choices=["dcim.interface", "virtualization.vminterface"],
+                    ),
+                    interface_id=dict(required=True, type="int"),
+                    priority=dict(type="int"),
+                ),
+            ),
+        )
+    )
+    required_if = [("state", "present", ["priority"])]
+
+    module = NetboxAnsibleModule(argument_spec=argument_spec, required_if=required_if)
+
+    netbox_fhrp_group = NetboxIpamModule(module, NB_FHRP_GROUP_ASSIGNMENTS)
+    netbox_fhrp_group.run()
+
+
+if __name__ == "__main__":
+    main()

tests/integration/netbox-deploy.py

@@ -173,6 +173,20 @@ def make_netbox_calls(endpoint, payload):
 ]
 created_vlans = make_netbox_calls(nb.ipam.vlans, vlans)
 
+## Create FHRP GROUPS
+fhrp_groups = [
+    {
+        "protocol": "other",
+        "group_id": 1,
+        "description": "Test FHRP Group 1",
+    },
+    {
+        "protocol": "glbp",
+        "group_id": 2,
+        "description": "Test FHRP Group 2",
+    },
+]
+created_fhrp_groups = make_netbox_calls(nb.ipam.fhrp_groups, fhrp_groups)
 
 ## Create IPAM Roles
 ipam_roles = [{"name": "Network of care", "slug": "network-of-care"}]

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

@@ -241,3 +241,12 @@
 
 - name: "NETBOX_FHRP_GROUP TESTS"
   include_tasks: "netbox_fhrp_group.yml"
+
+- name: "NETBOX_FHRP_GROUP_ASSIGNMENT TESTS"
+  include_tasks:
+    file: "netbox_fhrp_group_assignment.yml"
+    apply:
+      tags:
+        - netbox_fhrp_group_assignmen
+  tags:
+    - netbox_fhrp_group_assignmen

tests/integration/targets/v3.2/tasks/netbox_fhrp_group_assignment.yml

@@ -0,0 +1,92 @@
+---
+##
+##
+### NETBOX_FHRP_GROUP_ASSIGNMENT
+##
+##
+- name: "FHRP group assignment 1: Test FHRP group assignment creation"
+  netbox.netbox.netbox_fhrp_group_assignment:
+    netbox_url: http://localhost:32768
+    netbox_token: 0123456789abcdef0123456789abcdef01234567
+    data:
+      fhrp_group: 1
+      interface_type: dcim.interface
+      interface_id: 1
+      priority: 1
+    state: present
+  register: test_one
+
+- name: "FHRP group assignment: ASSERT - Necessary info creation"
+  ansible.builtin.assert:
+    that:
+      - test_one is changed
+      - test_one['diff']['before']['state'] == "absent"
+      - test_one['diff']['after']['state'] == "present"
+      - test_one['fhrp_group_assignment']['group'] == 1
+      - test_one['fhrp_group_assignment']['interface_type'] == "dcim.interface"
+      - test_one['fhrp_group_assignment']['interface_id'] == 1
+      - test_one['fhrp_group_assignment']['priority'] ==  1
+      - test_one['msg'] == "fhrp_group_assignment fhrp_group 1 > dcim.interface 1 created"
+
+- name: "FHRP group assignment 2: Create duplicate"
+  netbox.netbox.netbox_fhrp_group_assignment:
+    netbox_url: http://localhost:32768
+    netbox_token: 0123456789abcdef0123456789abcdef01234567
+    data:
+      fhrp_group: 1
+      interface_type: dcim.interface
+      interface_id: 1
+      priority: 1
+    state: present
+  register: test_two
+
+- name: "FHRP group assignment 2: ASSERT - Create duplicate"
+  ansible.builtin.assert:
+    that:
+      - not test_two['changed']
+      - test_two['fhrp_group_assignment']['group'] == 1
+      - test_two['fhrp_group_assignment']['interface_type'] == "dcim.interface"
+      - test_two['fhrp_group_assignment']['interface_id'] == 1
+      - test_two['fhrp_group_assignment']['priority'] ==  1
+      - test_two['msg'] == "fhrp_group_assignment fhrp_group 1 > dcim.interface 1 already exists"
+
+- name: "FHRP group assignment 3: Update FHRP group assignment"
+  netbox.netbox.netbox_fhrp_group_assignment:
+    netbox_url: http://localhost:32768
+    netbox_token: 0123456789abcdef0123456789abcdef01234567
+    data:
+      fhrp_group: 1
+      interface_type: dcim.interface
+      interface_id: 1
+      priority: 2
+    state: present
+  register: test_three
+
+- name: "FHRP group assignment 3: ASSERT - Update FHRP group assignment"
+  ansible.builtin.assert:
+    that:
+      - test_three is changed
+      - test_three['fhrp_group_assignment']['group'] == 1
+      - test_three['fhrp_group_assignment']['interface_type'] == "dcim.interface"
+      - test_three['fhrp_group_assignment']['interface_id'] == 1
+      - test_three['fhrp_group_assignment']['priority'] ==  2
+      - test_three['msg'] == "fhrp_group_assignment fhrp_group 1 > dcim.interface 1 updated"
+
+- name: "FHRP group assignment 4: Delete FHRP group assignment"
+  netbox.netbox.netbox_fhrp_group_assignment:
+    netbox_url: http://localhost:32768
+    netbox_token: 0123456789abcdef0123456789abcdef01234567
+    data:
+      fhrp_group: 1
+      interface_type: dcim.interface
+      interface_id: 1
+    state: absent
+  register: test_four
+
+- name: "FHRP group assignment 3: ASSERT - Delete FHRP group assignment"
+  ansible.builtin.assert:
+    that:
+      - test_four is changed
+      - test_four['diff']['before']['state'] == "present"
+      - test_four['diff']['after']['state'] == "absent"
+      - test_four['msg'] == "fhrp_group_assignment fhrp_group 1 > dcim.interface 1 deleted"

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

@@ -270,3 +270,12 @@
 
 - name: "NETBOX_FHRP_GROUP TESTS"
   include_tasks: "netbox_fhrp_group.yml"
+
+- name: "NETBOX_FHRP_GROUP_ASSIGNMENT TESTS"
+  include_tasks:
+    file: "netbox_fhrp_group_assignment.yml"
+    apply:
+      tags:
+        - netbox_fhrp_group_assignmen
+  tags:
+    - netbox_fhrp_group_assignmen