new_module: netbox_aggregate

Author: FragmentedPacket

README.md

@@ -25,6 +25,7 @@
 
 ## Existing Modules
 
+- netbox_aggregate
 - netbox_device
 - netbox_device_interface
 - netbox_device_role

plugins/module_utils/netbox_ipam.py

@@ -24,6 +24,7 @@
     from netbox_utils import NetboxModule, ENDPOINT_NAME_MAPPING, SLUG_REQUIRED
 
 
+NB_AGGREGATES = "aggregates"
 NB_IP_ADDRESSES = "ip_addresses"
 NB_PREFIXES = "prefixes"
 NB_IPAM_ROLES = "roles"
@@ -124,6 +125,7 @@ def run(self):
         This function should have all necessary code for endpoints within the application
         to create/update/delete the endpoint objects
         Supported endpoints:
+        - aggregates
         - ipam_roles
         - ip_addresses
         - prefixes
@@ -145,7 +147,7 @@ def run(self):
 
         if self.endpoint == "ip_addresses":
             name = data.get("address")
-        elif self.endpoint == "prefixes":
+        elif self.endpoint in ["aggregates", "prefixes"]:
             name = data.get("prefix")
         else:
             name = data.get("name")

plugins/module_utils/netbox_utils.py

@@ -37,7 +37,17 @@
         "sites",
     ],
     extras=[],
-    ipam=["ip_addresses", "prefixes", "rirs", "roles", "vlans", "vlan_groups", "vrfs"],
+    ipam=[
+        "aggregates",
+        "ip_addresses",
+        "prefixes",
+        "services",
+        "rirs",
+        "roles",
+        "vlans",
+        "vlan_groups",
+        "vrfs",
+    ],
     secrets=[],
     tenancy=["tenants", "tenant_groups"],
     virtualization=["clusters"],
@@ -68,6 +78,7 @@
     tenant="name",
     tenant_group="slug",
     time_zone="timezone",
+    virtual_machine="name",
     vlan="name",
     vlan_group="slug",
     vlan_role="name",
@@ -82,6 +93,7 @@
     device_type="device_types",
     group="tenant_groups",
     interface="interfaces",
+    ip_addresses="ip_addresses",
     lag="interfaces",
     manufacturer="manufacturers",
     nat_inside="ip_addresses",
@@ -96,18 +108,21 @@
     rack_role="rack_roles",
     region="regions",
     rir="rirs",
+    services="services",
     site="sites",
     tagged_vlans="vlans",
     tenant="tenants",
     tenant_group="tenant_groups",
     untagged_vlan="vlans",
+    virtual_machine="virtual_machines",
     vlan="vlans",
     vlan_group="vlan_groups",
     vlan_role="roles",
     vrf="vrfs",
 )
 
 ENDPOINT_NAME_MAPPING = {
+    "aggregates": "aggregate",
     "devices": "device",
     "device_roles": "device_role",
     "device_types": "device_type",
@@ -121,6 +136,7 @@
     "rack_roles": "rack_role",
     "rirs": "rir",
     "roles": "role",
+    "services": "services",
     "sites": "site",
     "tenants": "tenant",
     "tenant_groups": "tenant_group",
@@ -151,6 +167,8 @@
 
 VLAN_STATUS = dict(active=1, reserved=2, deprecated=3)
 
+SERVICE_PROTOCOL = dict(tcp=6, udp=17)
+
 RACK_TYPE = {
     "2-post frame": 100,
     "4-post frame": 200,
@@ -226,11 +244,13 @@
 INTF_MODE = {"access": 100, "tagged": 200, "tagged all": 300}
 
 ALLOWED_QUERY_PARAMS = {
+    "aggregate": set(["prefix", "rir"]),
     "device": set(["name"]),
     "device_role": set(["slug"]),
     "device_type": set(["slug"]),
     "interface": set(["name", "device"]),
     "ip_address": set(["address", "vrf"]),
+    "ip_addresses": set(["address", "vrf", "device"]),
     "lag": set(["name"]),
     "manufacturer": set(["name", "slug"]),
     "nat_inside": set(["vrf", "address"]),
@@ -241,6 +261,7 @@
     "rack_role": set(["slug"]),
     "rir": set(["slug"]),
     "role": set(["slug"]),
+    "services": set(["device", "virtual_machine", "name"]),
     "site": set(["slug"]),
     "tagged_vlans": set(["name", "site", "vlan_group", "tenant"]),
     "tenant": set(["name"]),
@@ -251,7 +272,9 @@
     "vrf": set(["name", "tenant"]),
 }
 
-QUERY_PARAMS_IDS = set(["device", "group", "vrf", "site", "vlan_group", "tenant"])
+QUERY_PARAMS_IDS = set(
+    ["device", "group", "rir", "vrf", "site", "vlan_group", "tenant"]
+)
 
 # This is used when converting static choices to an ID value acceptable to Netbox API
 REQUIRED_ID_FIND = {
@@ -261,6 +284,7 @@
     "ip_addresses": [{"status": IP_ADDRESS_STATUS, "role": IP_ADDRESS_ROLE}],
     "prefixes": [{"status": PREFIX_STATUS}],
     "racks": [{"status": RACK_STATUS, "outer_unit": RACK_UNIT, "type": RACK_TYPE}],
+    "services": [{"protocol": SERVICE_PROTOCOL}],
     "sites": [{"status": SITE_STATUS}],
     "vlans": [{"status": VLAN_STATUS}],
 }
@@ -420,6 +444,12 @@ def _build_query_params(self, parent, module_data, child=None):
         elif parent == "prefix" and module_data.get("parent"):
             query_dict.update({"prefix": module_data["parent"]})
 
+        elif parent == "ip_addreses":
+            if isinstance(module_data["device"], int):
+                query_dict.update({"device_id": module_data["device"]})
+            else:
+                query_dict.update({"device": module_data["device"]})
+
         return query_dict
 
     def _change_choices_id(self, endpoint, data):

plugins/modules/netbox_aggregate.py

@@ -0,0 +1,149 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+# Copyright: (c) 2019, Mikhail Yohman (@FragmentedPacket) <mikhail.yohman@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_aggregate
+short_description: Creates or removes aggregates from Netbox
+description:
+  - Creates or removes aggregates from Netbox
+notes:
+  - Tags should be defined as a YAML list
+  - This should be ran with connection C(local) and hosts C(localhost)
+author:
+  - Mikhail Yohman (@FragmentedPacket)
+requirements:
+  - pynetbox
+version_added: '0.1.0'
+options:
+  netbox_url:
+    description:
+      - URL of the Netbox instance resolvable by Ansible control host
+    required: true
+  netbox_token:
+    description:
+      - The token created within Netbox to authorize API access
+    required: true
+  data:
+    description:
+      - Defines the aggregate configuration
+    suboptions:
+      prefix:
+        description:
+          - The aggregate prefix
+      rir:
+        description:
+          - The RIR the aggregate will be assigned to
+      date_added:
+        description:
+          - Date added, format: YYYY-MM-DD
+      description:
+        description:
+          - The description of the aggregate
+      tags:
+        description:
+          - Any tags that the aggregate may need to be associated with
+      custom_fields:
+        description:
+          - must exist in Netbox
+    required: true
+  state:
+    description:
+      - The state of the aggregate
+    choices: [ present, absent ]
+    default: present
+  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: 'yes'
+    type: bool
+"""
+
+EXAMPLES = r"""
+- name: "Test Netbox aggregate module"
+  connection: local
+  hosts: localhost
+  gather_facts: False
+
+  tasks:
+    - name: Create aggregate within Netbox with only required information
+      netbox_aggregate:
+        netbox_url: http://netbox.local
+        netbox_token: thisIsMyToken
+        data:
+          prefix: 192.168.0.0/16
+          rir: Test RIR
+        state: present
+
+    - name: Create aggregate with several specified options
+      netbox_aggregate:
+        netbox_url: http://netbox.local
+        netbox_token: thisIsMyToken
+        data:
+          prefix: 192.168.0.0/16
+          rir: Test RIR
+          date_added: 1989-01-18
+          description: Test description
+          tags:
+            - Schnozzberry
+        state: present
+
+    - name: Delete aggregate within netbox
+      netbox_aggregate:
+        netbox_url: http://netbox.local
+        netbox_token: thisIsMyToken
+        data:
+          prefix: 192.168.0.0/16
+        state: absent
+"""
+
+RETURN = r"""
+aggregate:
+  description: Serialized object as created or already existent within Netbox
+  returned: on creation
+  type: dict
+msg:
+  description: Message indicating failure or info about what has been achieved
+  returned: always
+  type: str
+"""
+
+from ansible.module_utils.basic import AnsibleModule
+from ansible_collections.fragmentedpacket.netbox_modules.plugins.module_utils.netbox_ipam import (
+    NetboxIpamModule,
+    NB_AGGREGATES,
+)
+
+
+def main():
+    """
+    Main entry point for module execution
+    """
+    argument_spec = dict(
+        netbox_url=dict(type="str", required=True),
+        netbox_token=dict(type="str", required=True, no_log=True),
+        data=dict(type="dict", required=True),
+        state=dict(required=False, default="present", choices=["present", "absent"]),
+        validate_certs=dict(type="bool", default=True),
+    )
+
+    module = AnsibleModule(argument_spec=argument_spec, supports_check_mode=True)
+
+    netbox_aggregate = NetboxIpamModule(module, NB_AGGREGATES)
+    netbox_aggregate.run()
+
+
+if __name__ == "__main__":
+    main()