New Module: netbox_site_group (#547)

Author: andybro19

plugins/module_utils/netbox_dcim.py

@@ -43,6 +43,7 @@
 NB_REAR_PORT_TEMPLATES = "rear_port_templates"
 NB_REGIONS = "regions"
 NB_SITES = "sites"
+NB_SITE_GROUPS = "site_groups"
 NB_VIRTUAL_CHASSIS = "virtual_chassis"
 
 
@@ -79,6 +80,7 @@ def run(self):
         - power_ports
         - power_port_templates
         - sites
+        - site_groups
         - racks
         - rack_roles
         - rack_groups

plugins/module_utils/netbox_utils.py

@@ -109,6 +109,7 @@
     nat_inside="address",
     nat_outside="address",
     parent_region="slug",
+    parent_site_group="slug",
     parent_tenant_group="slug",
     power_panel="name",
     power_port="name",
@@ -184,6 +185,7 @@
     "parent_interface": "interfaces",
     "parent_vm_interface": "interfaces",
     "parent_region": "regions",
+    "parent_site_group": "site_groups",
     "parent_tenant_group": "tenant_groups",
     "platforms": "platforms",
     "power_panel": "power_panels",
@@ -345,6 +347,7 @@
     "parent_interface": set(["name"]),
     "parent_vm_interface": set(["name"]),
     "parent_region": set(["slug"]),
+    "parent_site_group": set(["slug"]),
     "parent_tenant_group": set(["slug"]),
     "platform": set(["slug"]),
     "power_feed": set(["name", "power_panel"]),
@@ -440,6 +443,7 @@
     "parent_interface": "parent",
     "parent_vm_interface": "parent",
     "parent_region": "parent",
+    "parent_site_group": "parent",
     "parent_tenant_group": "parent",
     "power_port_template": "power_port",
     "prefix_role": "role",

plugins/modules/netbox_site_group.py

@@ -0,0 +1,181 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+# Copyright: (c) 2021, Andrew Simmons (@andybro19) <andrewkylesimmons@gmail.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
+
+ANSIBLE_METADATA = {
+    "metadata_version": "1.1",
+    "status": ["preview"],
+    "supported_by": "community",
+}
+
+DOCUMENTATION = r"""
+---
+module: netbox_site_group
+short_description: Create, update, or delete site groups within NetBox
+description:
+  - Creates, updates, or deletes site groups within NetBox
+notes:
+  - Tags should be defined as a YAML list
+  - This should be ran with connection C(local) and hosts C(localhost)
+author:
+  - Andrew Simmons (@andybro19)
+requirements:
+  - pynetbox
+version_added: '4.0.0'
+options:
+  netbox_url:
+    description:
+      - URL of the NetBox instance resolvable by Ansible control host
+    required: true
+    type: str
+  netbox_token:
+    description:
+      - The token created within NetBox to authorize API access
+    required: true
+    type: str
+  cert:
+    description:
+      - Certificate path
+    required: false
+    type: raw
+  data:
+    type: dict
+    description:
+      - Defines the site group configuration
+    suboptions:
+      name:
+        description:
+          - Name of the site group to be created
+        required: true
+        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
+      parent_site_group:
+        description:
+          - The parent site group the site group will be associated with
+        required: false
+        type: raw
+      description:
+        description: 
+          - The description of the site group
+        required: false
+        type: str
+    required: true
+  state:
+    description:
+      - Use C(present) or C(absent) for adding or removing.
+    choices: [ absent, present ]
+    default: present
+    type: str
+  query_params:
+    description:
+      - This can be used to override the specified values in ALLOWED_QUERY_PARAMS that is defined
+      - in plugins/module_utils/netbox_utils.py and provides control to users on what may make
+      - an object unique in their environment.
+    required: false
+    type: list
+    elements: str
+  validate_certs:
+    description:
+      - |
+        If C(no), SSL certificates will not be validated.
+        This should only be used on personally controlled sites using self-signed certificates.
+    default: true
+    type: raw
+"""
+
+EXAMPLES = r"""
+- name: "Test NetBox site group module"
+  connection: local
+  hosts: localhost
+  gather_facts: False
+  tasks:
+    - name: Create site group within NetBox with only required information
+      netbox.netbox.netbox_site_group:
+        netbox_url: http://netbox.local
+        netbox_token: thisIsMyToken
+        data:
+          name: Site group
+        state: present
+
+    - name: Create site group within NetBox with a parent site group
+      netbox.netbox.netbox_site_group:
+        netbox_url: http://netbox.local
+        netbox_token: thisIsMyToken
+        data:
+          name: Child site group
+          parent_site_group: Site group
+        state: present
+
+    - name: Delete site group within NetBox
+      netbox.netbox.netbox_site_group:
+        netbox_url: http://netbox.local
+        netbox_token: thisIsMyToken
+        data:
+          name: Site group
+        state: absent
+"""
+
+RETURN = r"""
+site_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_dcim import (
+    NetboxDcimModule,
+    NB_SITE_GROUPS,
+)
+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"),
+                    slug=dict(required=False, type="str"),
+                    parent_site_group=dict(required=False, type="raw"),
+                    description=dict(required=False, type="str"),
+                ),
+            ),
+        )
+    )
+
+    required_if = [("state", "present", ["name"]), ("state", "absent", ["name"])]
+
+    module = NetboxAnsibleModule(
+        argument_spec=argument_spec, supports_check_mode=True, required_if=required_if
+    )
+
+    netbox_site_group = NetboxDcimModule(module, NB_SITE_GROUPS)
+    netbox_site_group.run()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

tests/integration/targets/v2.11/tasks/main.yml

@@ -17,6 +17,9 @@
 - name: "NETBOX_SITE TESTS"
   include_tasks: "netbox_site.yml"
 
+- name: "NETBOX_SITE_GROUP TESTS"
+  include_tasks: "netbox_site_group.yml"
+
 - name: "NETBOX_TENTANT TESTS"
   include_tasks: "netbox_tenant.yml"
 

tests/integration/targets/v2.11/tasks/netbox_site_group.yml

@@ -0,0 +1,81 @@
+---
+##
+##
+### NETBOX_SITE_GROUP
+##
+##
+- name: "SITE_GROUP 1: Necessary info creation"
+  netbox.netbox.netbox_site_group:
+    netbox_url: http://localhost:32768
+    netbox_token: 0123456789abcdef0123456789abcdef01234567
+    data:
+      name: Site Group
+    state: present
+  register: test_one
+
+- name: "SITE_GROUP 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['site_group']['name'] == "Site Group"
+      - test_one['site_group']['slug'] == "site-group"
+      - test_one['msg'] == "site_group Site Group created"
+
+- name: "SITE_GROUP 2: Create duplicate"
+  netbox.netbox.netbox_site_group:
+    netbox_url: http://localhost:32768
+    netbox_token: 0123456789abcdef0123456789abcdef01234567
+    data:
+      name: Site Group
+    state: present
+  register: test_two
+
+- name: "SITE_GROUP 2: ASSERT - Create duplicate"
+  assert:
+    that:
+      - not test_two['changed']
+      - test_two['site_group']['name'] == "Site Group"
+      - test_two['site_group']['slug'] == "site-group"
+      - test_two['msg'] == "site_group Site Group already exists"
+
+- name: "SITE_GROUP 3: Update"
+  netbox.netbox.netbox_site_group:
+    netbox_url: http://localhost:32768
+    netbox_token: 0123456789abcdef0123456789abcdef01234567
+    data:
+      name: Site Group
+      parent_site_group: Test Site Group
+      description: This is a site group
+    state: present
+  register: test_three
+
+- name: "SITE_GROUP 3: ASSERT - Update"
+  assert:
+    that:
+      - test_three is changed
+      - test_three['diff']['after']['parent'] == 1
+      - test_three['diff']['after']['description'] == "This is a site group"
+      - test_three['site_group']['name'] == "Site Group"
+      - test_three['site_group']['slug'] == "site-group"
+      - test_three['site_group']['parent'] == 1
+      - test_three['site_group']['description'] == "This is a site group"
+      - test_three['msg'] == "site_group Site Group updated"
+
+- name: "SITE_GROUP 4: Delete"
+  netbox.netbox.netbox_site_group:
+    netbox_url: http://localhost:32768
+    netbox_token: 0123456789abcdef0123456789abcdef01234567
+    data:
+      name: Site Group
+    state: absent
+  register: test_four
+
+- name: "SITE_GROUP 4: ASSERT - Delete"
+  assert:
+    that:
+      - test_four is changed
+      - test_four['diff']['before']['state'] == "present"
+      - test_four['diff']['after']['state'] == "absent"
+      - test_four['msg'] == "site_group Site Group deleted"

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

@@ -17,6 +17,9 @@
 - name: "NETBOX_SITE TESTS"
   include_tasks: "netbox_site.yml"
 
+- name: "NETBOX_SITE_GROUP TESTS"
+  include_tasks: "netbox_site_group.yml"
+
 - name: "NETBOX_TENTANT TESTS"
   include_tasks: "netbox_tenant.yml"