New Modules: Add modules for power management (#235)

Author: toerb

README.md

@@ -35,6 +35,12 @@ To keep the code simple, we only officially support the two latest releases of N
 - netbox_ipam_role
 - netbox_manufacturer
 - netbox_platform
+- netbox_power_feed
+- netbox_power_outlet
+- netbox_power_outlet_template
+- netbox_power_panel
+- netbox_power_port
+- netbox_power_port_template
 - netbox_prefix
 - netbox_provider
 - netbox_rack_group

plugins/module_utils/netbox_dcim.py

@@ -24,6 +24,12 @@
 NB_INVENTORY_ITEMS = "inventory_items"
 NB_MANUFACTURERS = "manufacturers"
 NB_PLATFORMS = "platforms"
+NB_POWER_FEEDS = "power_feeds"
+NB_POWER_OUTLETS = "power_outlets"
+NB_POWER_OUTLET_TEMPLATES = "power_outlet_templates"
+NB_POWER_PANELS = "power_panels"
+NB_POWER_PORTS = "power_ports"
+NB_POWER_PORT_TEMPLATES = "power_port_templates"
 NB_RACKS = "racks"
 NB_RACK_ROLES = "rack_roles"
 NB_RACK_GROUPS = "rack_groups"
@@ -48,6 +54,12 @@ def run(self):
         - inventory_items
         - manufacturers
         - platforms
+        - power_feeds
+        - power_outlets
+        - power_outlet_templates
+        - power_panels
+        - power_ports
+        - power_port_templates
         - sites
         - racks
         - rack_roles

plugins/module_utils/netbox_utils.py

@@ -43,6 +43,12 @@
         "inventory_items",
         "manufacturers",
         "platforms",
+        "power_feeds",
+        "power_outlets",
+        "power_outlet_templates",
+        "power_panels",
+        "power_ports",
+        "power_port_templates",
         "racks",
         "rack_groups",
         "rack_roles",
@@ -83,6 +89,8 @@
     nat_inside="address",
     nat_outside="address",
     parent_region="slug",
+    power_panel="name",
+    power_port="name",
     platform="slug",
     prefix_role="slug",
     primary_ip="address",
@@ -128,6 +136,8 @@
     nat_outside="ip_addresses",
     platform="platforms",
     parent_region="regions",
+    power_panel="power_panels",
+    power_port="power_ports",
     prefix_role="roles",
     primary_ip="ip_addresses",
     primary_ip4="ip_addresses",
@@ -169,6 +179,12 @@
     "ip_addresses": "ip_address",
     "manufacturers": "manufacturer",
     "platforms": "platform",
+    "power_feeds": "power_feed",
+    "power_outlets": "power_outlet",
+    "power_outlet_templates": "power_outlet_template",
+    "power_panels": "power_panel",
+    "power_ports": "power_port",
+    "power_port_templates": "power_port_template",
     "prefixes": "prefix",
     "providers": "provider",
     "racks": "rack",
@@ -210,6 +226,12 @@
     "nat_inside": set(["vrf", "address"]),
     "parent_region": set(["slug"]),
     "platform": set(["slug"]),
+    "power_feed": set(["name", "power_panel"]),
+    "power_outlet": set(["name", "device"]),
+    "power_outlet_template": set(["name", "device_type"]),
+    "power_panel": set(["name", "site"]),
+    "power_port": set(["name", "device"]),
+    "power_port_template": set(["name", "device_type"]),
     "prefix": set(["prefix", "vrf"]),
     "primary_ip4": set(["address", "vrf"]),
     "primary_ip6": set(["address", "vrf"]),
@@ -255,6 +277,11 @@
     "interfaces": set(["form_factor", "mode", "type"]),
     "ip_addresses": set(["status", "role"]),
     "prefixes": set(["status"]),
+    "power_feeds": set(["status", "type", "supply", "phase"]),
+    "power_outlets": set(["type", "feed_leg"]),
+    "power_outlet_templates": set(["type", "feed_leg"]),
+    "power_ports": set(["type"]),
+    "power_port_templates": set(["type"]),
     "racks": set(["status", "outer_unit", "type"]),
     "services": set(["protocol"]),
     "sites": set(["status"]),
@@ -443,7 +470,9 @@ def _convert_identical_keys(self, data):
             if data.get("form_factor"):
                 temp_dict["type"] = data["form_factor"]
         for key in data:
-            if key in CONVERT_KEYS:
+            if self.endpoint == "power_panels" and key == "rack_group":
+                temp_dict[key] = data[key]
+            elif key in CONVERT_KEYS:
                 new_key = CONVERT_KEYS[key]
                 temp_dict[new_key] = data[key]
             else:

plugins/modules/netbox_power_feed.py

@@ -0,0 +1,265 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+# © 2020 Nokia
+# Licensed under the GNU General Public License v3.0 only
+# SPDX-License-Identifier: GPL-3.0-only
+
+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_power_feed
+short_description: Create, update or delete power feeds within Netbox
+description:
+  - Creates, updates or removes power feeds from Netbox
+notes:
+  - Tags should be defined as a YAML list
+  - This should be ran with connection C(local) and hosts C(localhost)
+author:
+  - Tobias Groß (@toerb)
+requirements:
+  - pynetbox
+version_added: '0.2.3'
+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
+  data:
+    type: dict
+    required: true
+    description:
+      - Defines the power feed configuration
+    suboptions:
+      power_panel:
+        description:
+          - The power panel the power feed is terminated on
+        required: true
+        type: raw
+      rack:
+        description:
+          - The rack the power feed is assigned to
+        required: false
+        type: raw
+      name:
+        description:
+          - The name of the power feed
+        required: true
+        type: str
+      status:
+        description:
+          - The status of the power feed
+        choices:
+          - offline
+          - active
+          - planned
+          - failed
+        required: false
+        type: str
+      type:
+        description:
+          - The type of the power feed
+        choices:
+          - primary
+          - redundant
+        required: false
+        type: str
+      supply:
+        description:
+          - The supply type of the power feed
+        choices:
+          - ac
+          - dc
+        required: false
+        type: str
+      phase:
+        description:
+          - The phase type of the power feed
+        choices:
+          - single-phase
+          - three-phase
+        required: false
+        type: str
+      voltage:
+        description:
+          - The voltage of the power feed
+        required: false
+        type: int
+      amperage:
+        description:
+          - The amperage of the power feed
+        required: false
+        type: int
+      max_utilization:
+        description:
+          - The maximum permissible draw of the power feed in percent
+        required: false
+        type: int
+      comments:
+        description:
+          - Comments related to the power feed
+        required: false
+        type: str
+      tags:
+        description:
+          - Any tags that the power feed may need to be associated with
+        required: false
+        type: list
+      custom_fields:
+        description:
+          - must exist in Netbox
+        required: false
+        type: dict
+  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
+  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 modules"
+  connection: local
+  hosts: localhost
+  gather_facts: False
+
+  tasks:
+    - name: Create power feed within Netbox with only required information
+      netbox_power_feed:
+        netbox_url: http://netbox.local
+        netbox_token: thisIsMyToken
+        data:
+          name: Test Power Feed
+          power_panel: Test Power Panel
+        state: present
+
+    - name: Update power feed with other fields
+      netbox_power_feed:
+        netbox_url: http://netbox.local
+        netbox_token: thisIsMyToken
+        data:
+          name: Test Power Feed
+          power_panel: Test Power Panel
+          status: offline
+          type: primary
+          supply: ac
+          phase: single-phase
+          voltage: 230
+          amperage: 16
+          max_utilization: 80
+          comments: normal power feed
+        state: present
+
+    - name: Delete power feed within netbox
+      netbox_power_feed:
+        netbox_url: http://netbox.local
+        netbox_token: thisIsMyToken
+        data:
+          name: Test Power Feed
+          power_panel: Test Power Panel
+        state: absent
+"""
+
+RETURN = r"""
+power_feed:
+  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_POWER_FEEDS,
+)
+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(
+                    power_panel=dict(required=True, type="raw"),
+                    rack=dict(required=False, type="raw"),
+                    name=dict(required=True, type="str"),
+                    status=dict(
+                        required=False,
+                        choices=["offline", "active", "planned", "failed"],
+                        type="str",
+                    ),
+                    type=dict(
+                        required=False, choices=["primary", "redundant"], type="str"
+                    ),
+                    supply=dict(required=False, choices=["ac", "dc"], type="str"),
+                    phase=dict(
+                        required=False,
+                        choices=["single-phase", "three-phase"],
+                        type="str",
+                    ),
+                    voltage=dict(required=False, type="int"),
+                    amperage=dict(required=False, type="int"),
+                    max_utilization=dict(required=False, type="int"),
+                    comments=dict(required=False, type="str"),
+                    tags=dict(required=False, type="list"),
+                    custom_fields=dict(required=False, type="dict"),
+                ),
+            ),
+        )
+    )
+
+    required_if = [
+        ("state", "present", ["power_panel", "name"]),
+        ("state", "absent", ["power_panel", "name"]),
+    ]
+
+    module = NetboxAnsibleModule(
+        argument_spec=argument_spec, supports_check_mode=True, required_if=required_if
+    )
+
+    netbox_power_feed = NetboxDcimModule(module, NB_POWER_FEEDS)
+    netbox_power_feed.run()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()