nornir-collection 0.0.1__py3-none-any.whl

nornir_collection/netbox/update_fortinet_inventory_data.py

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+"""
+This module updates the serial numbers of Fortinet devices in NetBox using Nornir.
+The Main function is intended to import and execute by other scripts.
+"""
+
+
+from nornir.core import Nornir
+from nornir.core.filter import F
+from nornir.core.task import Task, Result
+from nornir_collection.nornir_plugins.inventory.utils import init_nornir
+from nornir_collection.fortinet.utils import get_fgt_resources
+from nornir_collection.netbox.utils import _nb_patch_resources, _nb_create_payload_patch_device_serials
+from nornir_collection.utils import (
+    print_task_title,
+    print_result,
+    task_name,
+    task_info,
+    exit_error,
+)
+
+
+__author__ = "Willi Kubny"
+__maintainer__ = "Willi Kubny"
+__version__ = "1.0"
+__license__ = "MIT"
+__email__ = "willi.kubny@dreyfusbank.ch"
+__status__ = "Production"
+
+
+def update_serial_number(task: Task) -> Result:
+    """
+    Update the device serial number in NetBox based on the serial number retrieved from the Fortinet device.
+
+    Args:
+        task (Task): The Nornir task object.
+
+    Returns:
+        Result: The Nornir result object.
+    """
+    task_text = "Update device serial number"
+
+    # Get the Fortinet device serial number from the Fortinet Rest API
+    response = get_fgt_resources(task=task, url="api/v2/monitor/system/ha-peer/")
+
+    # Verify the response code and return the result
+    if response.status_code != 200:
+        result = (
+            f"'{task.name}' -> APIResponse: <Success: False>\n"
+            + f"-> Response Status Code: {response.status_code}\n"
+            + f"-> Response Text: {response.text}"
+        )
+        # Return the Nornir result
+        return Result(host=task.host, result=result, changed=False, failed=True)
+
+    # Create the serials dict to us in the function _nb_create_payload_patch_device_serials
+    serials = {}
+    if task.host["virtual_chassis"]:
+        # Create a serials dict to map the serials to the virtual chassis member hostname
+        response = {serial["hostname"]: serial["serial_no"] for serial in response.json()["results"]}
+        # Create the serials dict for a HA cluster
+        serials["1"] = response[f"{task.host['virtual_chassis']['master']['name']}"]
+        if "members" in task.host["virtual_chassis"]:
+            for num, member in enumerate(task.host["virtual_chassis"]["members"], start=2):
+                serials[str(num)] = response[f"{member['name']}"]
+    else:
+        # Create the serials dict for a single device
+        serials["1"] = response.json()["serial"]
+
+    # Create the API payload to update the device serial number or return the Nornir result as failed
+    payload = _nb_create_payload_patch_device_serials(task=task, task_text=task_text, serials=serials)
+
+    # Get the NetBox url from the inventory options and update the device serial number in NetBox
+    url = f"{task.nornir.config.inventory.options['nb_url']}/api/dcim/devices/"
+    result = _nb_patch_resources(task=task, task_text=task_text, url=url, payload=payload)
+    result += f"\n-> Serials: {[item['serial'] for item in payload]}"
+
+    # Return the result
+    return Result(host=task.host, result=result, changed=False, failed=False)
+
+
+def update_fortinet_inventory_data(nr: Nornir) -> bool:
+    """
+    Update NetBox Cisco Device Inventory Data. This function runs a Nornir task to update the serial number
+    of Fortinet devices in NetBox. The Nornir inventory is filtered by device manufacturer (fortinet). If any
+    of the tasks fail, the function returns True, otherwise it returns False.
+
+    Args:
+        nr: The Nornir inventory object.
+
+    Returns:
+        bool: True if any of the tasks failed, False otherwise.
+    """
+    # pylint: disable=invalid-name
+    # Track if one of the tasks has failed
+    failed = False
+
+    print_task_title(title="Update NetBox Fortinet Device Inventory Data")
+
+    # Filter Nornir inventory by device manufacturer (a device can have only one manufacturer)
+    nr_fortinet = nr.filter(
+        F(device_type__manufacturer__slug__contains="fortinet") & F(status__value="active")
+    )
+    task_text = "Filter nornir inventory"
+    print(task_name(text=task_text))
+    print(task_info(text=task_text, changed=False))
+    print(
+        f"'{task_text}' -> NornirResult <Success: True>\n"
+        + "-> Filter condition: Device manufacturer slug contains 'fortinet'\n"
+        + "                     & Device status value is 'active'"
+    )
+
+    # Run the custom Nornir task update_serial_number
+    name = "NETBOX update device serial number"
+    result = nr_fortinet.run(name=name, task=update_serial_number, on_failed=True)
+    # Print the whole result for each host
+    print_result(result)
+    if result.failed:
+        failed = True
+
+    return failed
+
+
+def main(nr_config: str) -> None:
+    """
+    Main function is intended to import and execute by other scripts.
+    It initialize Nornir and update Fortinet inventory data in NetBox.
+
+    * Args:
+        * nr_config (str): Path to the Nornir configuration file.
+
+    * Steps:
+        * Initializes the Nornir inventory object using the provided configuration file.
+        * Runs the task to update Fortinet inventory data in NetBox.
+        * Checks the result of the update task and exits the script with an error message if the task failed.
+
+    * Exits:
+        * Exits with code 1 if the Nornir configuration file is empty or if any task fails.
+    """
+    # pylint: disable=invalid-name
+
+    #### Initialize Nornir ##################################################################################
+
+    # Initialize, transform and filter the Nornir inventory are return the filtered Nornir object
+    # Define data to load from NetBox in addition to the base Nornir inventory plugin
+    add_netbox_data = {"load_virtual_chassis_data": True}
+    nr = init_nornir(config_file=nr_config, add_netbox_data=add_netbox_data)
+
+    #### Run Nornir Cisco Support Plugin Update Tasks #######################################################
+
+    # Update NetBox Fortigate inventory data
+    result_failed = update_fortinet_inventory_data(nr=nr)
+
+    # Check the result and exit the script with exit code 1 and a error message
+    if result_failed:
+        text = "Update NetBox Fortinet Device Inventory Data with Nornir"
+        print(task_name(text=text))
+        exit_error(
+            task_text=f"{text} Failed",
+            msg="Check the result details for failed Nornir tasks",
+        )

nornir_collection/netbox/update_purestorage_inventory_data.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""
+This module updates the serial number of Pure Storage devices in NetBox using Nornir.
+The Main function is intended to import and execute by other scripts.
+"""
+
+
+from nornir.core import Nornir
+from nornir.core.filter import F
+from nornir.core.task import Task, Result
+from nornir_collection.nornir_plugins.inventory.utils import init_nornir
+from nornir_collection.purestorage.utils import _purestorage_get_connection
+from nornir_collection.netbox.utils import _nb_patch_resources
+from nornir_collection.utils import (
+    print_task_title,
+    print_result,
+    task_name,
+    task_info,
+    exit_error,
+)
+
+
+__author__ = "Willi Kubny"
+__maintainer__ = "Willi Kubny"
+__version__ = "1.0"
+__license__ = "MIT"
+__email__ = "willi.kubny@dreyfusbank.ch"
+__status__ = "Production"
+
+
+def update_serial_number(task: Task) -> Result:
+    """
+    Update the serial number of a device in NetBox with the one retrieved from a Pure Storage FlashArray.
+
+    Args:
+        task (Task): A Nornir task object representing the device to update.
+
+    Returns:
+        Result: A Nornir result object with the outcome of the operation.
+    """
+    task_text = "Update device serial number"
+
+    # Manually create the PureStorage connection or return the Nornir result as failed
+    conn = _purestorage_get_connection(task=task)
+
+    # Get all hardware details from the FlashArray
+    response = conn.get_hardware()
+    # Get the serial number of the chassis
+    serial = [item["serial"] for item in response.items if item["type"] == "chassis"][0]
+    if not serial:
+        # Return the Nornir result as failed
+        result = f"'{task_text}' -> APIResponse: <Success: False>\n-> Device serial not found in API response"
+        return Result(host=task.host, result=result, failed=True)
+
+    # Create the API payload to update the device serial number
+    payload = [{"id": task.host["id"], "serial": serial}]
+
+    # Get the NetBox url from the inventory options and update the device serial number in NetBox
+    url = f"{task.nornir.config.inventory.options['nb_url']}/api/dcim/devices/"
+    result = _nb_patch_resources(task=task, task_text=task_text, url=url, payload=payload)
+    result += f"\n-> Serial: {serial}"
+
+    # Return the result
+    return Result(host=task.host, result=result, failed=False)
+
+
+def update_purestorage_inventory_data(nr: Nornir) -> bool:
+    """
+    Update Pure-Storage device inventory data in NetBox. This function runs a custom Nornir task to update
+    the serial number of each Pure-Storage device in NetBox.
+
+    Args:
+        nr (Nornir): The Nornir object representing the inventory.
+
+    Returns:
+        bool: True if any of the tasks failed, False otherwise.
+    """
+    # pylint: disable=invalid-name
+    # Track if one of the tasks has failed
+    failed = False
+
+    print_task_title(title="Update NetBox Pure-Storage Device Inventory Data")
+
+    # Filter Nornir inventory by device manufacturer (a device can have only one manufacturer)
+    nr_purestorage = nr.filter(
+        F(device_type__manufacturer__slug__contains="pure-storage") & F(status__value="active")
+    )
+    task_text = "Filter nornir inventory"
+    print(task_name(text=task_text))
+    print(task_info(text=task_text, changed=False))
+    print(
+        f"'{task_text}' -> NornirResult <Success: True>\n"
+        + "-> Filter condition: Device manufacturer slug contains 'pure-storage'",
+    )
+
+    # Run the custom Nornir task update_serial_number
+    name = "NETBOX update device serial number"
+    result = nr_purestorage.run(name=name, task=update_serial_number, on_failed=True)
+    # Print the whole result for each host
+    print_result(result)
+    if result.failed:
+        failed = True
+
+    return failed
+
+
+def main(nr_config: str) -> None:
+    """
+    Main function is intended to import and execute by other scripts.
+    It initialize Nornir and update NetBox Pure-Storage inventory data.
+
+    * Args:
+        * nr_config (str): Path to the Nornir configuration file.
+
+    * Steps:
+        * Initializes the Nornir inventory object using the provided configuration file.
+        * Executes the task to update NetBox Pure-Storage inventory data.
+        * Checks the result of the update task and exits the script with an error message if the task failed.
+
+    * Exits:
+        * Exits with code 1 if the Nornir configuration file is empty or if any task fails.
+    """
+    # pylint: disable=invalid-name
+
+    #### Initialize Nornir ##################################################################################
+
+    # Initialize, transform and filter the Nornir inventory are return the filtered Nornir object
+    # Define data to load from NetBox in addition to the base Nornir inventory plugin
+    add_netbox_data = {"load_virtual_chassis_data": True}
+    nr = init_nornir(config_file=nr_config, add_netbox_data=add_netbox_data)
+
+    #### Run Nornir Cisco Support Plugin Update Tasks #######################################################
+
+    # Update NetBox Pure-Storate inventory data
+    result_failed = update_purestorage_inventory_data(nr=nr)
+
+    # Check the result and exit the script with exit code 1 and a error message
+    if result_failed:
+        text = "Update NetBox Pure-Storage Device Inventory Data with Nornir"
+        print(task_name(text=text))
+        exit_error(
+            task_text=f"{text} Failed",
+            msg="Check the result details for failed Nornir tasks",
+        )

nornir_collection/netbox/utils.py

@@ -0,0 +1,261 @@
+#!/usr/bin/env python3
+"""
+This module contains general functions and tasks related to NetBox.
+
+The functions are ordered as followed:
+- Helper Functions
+- Task Helper Functions
+- Single Nornir tasks
+- Nornir tasks in regular function
+"""
+
+
+import os
+import argparse
+import json
+from typing import Tuple, Union, Any, Dict, List
+import __main__
+import requests
+import pynetbox
+from nornir.core.task import Task, Result
+from nornir_collection.utils import (
+    CustomArgParse,
+    CustomArgParseWidthFormatter,
+    get_env_vars,
+    print_task_name,
+    task_info,
+)
+
+
+#### Helper Functions #######################################################################################
+
+
+def init_pynetbox(nb_url: str, ssl_verify=False) -> Tuple[pynetbox.api, pynetbox.api]:
+    """
+    This function instantiate a Pynetbox API object, print the result and returns the API object
+    """
+    task_text = "Initialize PyNetBox"
+    print_task_name(text=task_text)
+
+    # Load environment variables or raise a TypeError when is None
+    env_vars = get_env_vars(envs=["NB_TOKEN"], task_text=task_text)
+
+    # Instantiate the NetBox API
+    session = requests.Session()
+    session.verify = ssl_verify
+    nb = pynetbox.api(url=nb_url, token=env_vars["NB_TOKEN"], threading=False)
+    nb.http_session = session
+
+    # Print success result
+    print(task_info(text=task_text, changed=False))
+    print(f"'{task_text}' -> Pynetbox.Api <Success: True>")
+    print(f"-> Instantiate the PyNetBox API for '{nb_url}'")
+
+    return nb
+
+
+def init_args_for_nornir_config_filepath() -> str:
+    """
+    This function initialze arguments to specify which NetBox instance and Nornir config filepath to use.
+    """
+    task_text = "Argparse verify arguments"
+    print_task_name(text=task_text)
+
+    # Load environment variables or raise a TypeError when is None
+    env_vars = get_env_vars(envs=["NR_CONFIG_PROD", "NR_CONFIG_TEST"], task_text=task_text)
+    nr_config_prod = env_vars["NR_CONFIG_PROD"]
+    nr_config_test = env_vars["NR_CONFIG_TEST"]
+
+    # Define the arguments which needs to be given to the script execution
+    argparser = CustomArgParse(
+        prog=os.path.basename(__main__.__file__),
+        description="Specify the NetBox PROD or TEST instance and Nornir config filepath to be used",
+        epilog="One of the two mandatory arguments is required.",
+        argument_default=argparse.SUPPRESS,
+        formatter_class=CustomArgParseWidthFormatter,
+    )
+    # Add a argparser group for mutual exclusive arguments
+    group = argparser.add_mutually_exclusive_group(required=True)
+    # Add the test argument
+    group.add_argument(
+        "--prod",
+        action="store_true",
+        default=False,
+        help=f"use the NetBox 'PROD' instance and Nornir config '{nr_config_prod}'",
+    )
+    # Add the test argument
+    group.add_argument(
+        "--test",
+        action="store_true",
+        default=False,
+        help=f"use the NetBox 'TEST' instance and Nornir config '{nr_config_test}'",
+    )
+    # Verify the provided arguments and print the custom argparse error message in case of an error
+    args = argparser.parse_args()
+
+    # Set the NetBox instance and the Nornir config file based on the arguments
+    nb_instance = "TEST" if args.test else "PROD"
+    nr_config = nr_config_test if args.test else nr_config_prod
+
+    # If argparser.parse_args() is successful -> no argparse error message
+    print(task_info(text=task_text, changed=False))
+    print(f"'{task_text}' -> ArgparseResponse <Success: True>")
+    print(f"-> Run on the NetBox '{nb_instance}' instance and Nornir config '{nr_config}'")
+
+    return nr_config
+
+
+def get_nb_resources(  # pylint: disable=dangerous-default-value
+    url: str, params: Dict[str, Any] = {}
+) -> List[Dict[str, Any]]:
+    """
+    TBD
+    """
+    # Define the resource list
+    resources: List[Dict[str, Any]] = []
+    headers = {
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+        "Authorization": f"Token {os.environ.get('NB_TOKEN')}",
+    }
+    # While there is a next page continue the loop
+    while url:
+        # Do the http request
+        response = requests.get(  # nosec
+            url=url, headers=headers, params=params, verify=False, timeout=(3.05, 27)
+        )
+        # Verify the response code
+        if not response.status_code == 200:
+            print(response.status_code)
+            print(response.text)
+            raise ValueError(f"Failed to get data from NetBox instance {url}")
+        # Extract the json data from the http response
+        resp = response.json()
+        # Add the response to the resource list
+        resources.extend(resp.get("results"))
+        # Get the url of the next page
+        url = resp.get("next")
+
+    # Retrun the resources list
+    return resources
+
+
+def post_nb_resources(url: str, payload: List[Dict]) -> requests.Response:
+    """
+    TBD
+    """
+    headers = {
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+        "Authorization": f"Token {os.environ.get('NB_TOKEN')}",
+    }
+    # Do the http request and return the result
+    return requests.post(  # nosec
+        url=url, headers=headers, data=json.dumps(payload), verify=False, timeout=(3.05, 27)
+    )
+
+
+def patch_nb_resources(url: str, payload: List[Dict]) -> requests.Response:
+    """
+    TBD
+    """
+    headers = {
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+        "Authorization": f"Token {os.environ.get('NB_TOKEN')}",
+    }
+    # Do the http request and return the result
+    return requests.patch(  # nosec
+        url=url, headers=headers, data=json.dumps(payload), verify=False, timeout=(3.05, 27)
+    )
+
+
+def delete_nb_resources(url: str, payload: List[Dict]) -> requests.Response:
+    """
+    TBD
+    """
+    headers = {
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+        "Authorization": f"Token {os.environ.get('NB_TOKEN')}",
+    }
+    # Do the http request and return the result
+    return requests.delete(  # nosec
+        url=url, headers=headers, data=json.dumps(payload), verify=False, timeout=(3.05, 27)
+    )
+
+
+#### Task Helper Functions ##################################################################################
+
+
+def _nb_patch_resources(task: Task, task_text: str, url: str, payload: list) -> Union[str, Result]:
+    """
+    Sends a PATCH request to update the resources of a device in NetBox.
+    Args:
+        task (Task): The Nornir task object.
+        task_text (str): The description of the task.
+        payload (list): A list of dictionaries containing the resources to be updated.
+    Returns:
+        tuple: A tuple containing the result string and a boolean indicating whether the task failed.
+    """
+    # POST request to update the Cisco Support Plugin desired release
+    response = patch_nb_resources(url=url, payload=payload)
+
+    # Verify the response code and return the result
+    if response.status_code != 200:
+        result = (
+            f"'{task_text}' -> NetBoxResponse: <Success: False>\n"
+            + f"-> Response Status Code: {response.status_code}\n"
+            + f"-> Response Text: {response.text}\n"
+            + f"-> Payload: {payload}"
+        )
+        # Return the Nornir result
+        return Result(host=task.host, result=result, changed=False, failed=True)
+
+    # Return the result string
+    result = f"'{task_text}' -> NetBoxResponse: <Success: True>"
+    return result
+
+
+def _nb_create_payload_patch_device_serials(task: Task, task_text: str, serials: dict) -> Union[list, Result]:
+    """
+    Create a payload for patching device serial numbers in NetBox.
+    Args:
+        task (Task): The Nornir task object.
+        task_text (str): The task description.
+        serials (dict): A dictionary containing the serial numbers for the devices.
+    Returns:
+        Union[List, Result]: A list of dictionaries containing the device IDs and serial numbers,
+        or a Nornir Result object if an error occurs.
+    """
+    try:
+        # Create a list of dicts. Multiple dicts if its a virtual chassis
+        payload = []
+
+        # Add the device depending if its a virtual chassis in NetBox or not
+        if "virtual_chassis" in task.host and task.host["virtual_chassis"] is not None:
+            # Add the master
+            payload.append({"id": task.host["virtual_chassis"]["master"]["id"], "serial": serials["1"]})
+
+            # Add all members to the payload if available
+            if "members" in task.host["virtual_chassis"]:
+                # Start enumerate with 2 as 1 is the virtual chassis master
+                for num, member in enumerate(task.host["virtual_chassis"]["members"], start=2):
+                    payload.append({"id": member["id"], "serial": serials[str(num)]})
+        else:
+            # Add the device (no virtual chassis)
+            payload.append({"id": task.host["id"], "serial": serials["1"]})
+
+        # Return the payload
+        return payload
+
+    except KeyError as error:
+        result = f"'{task_text}' -> PythonResponse <Success: False>\n-> Dictionary key {error} not found"
+        # Return the Nornir result
+        return Result(host=task.host, result=result, changed=False, failed=True)
+
+
+#### Nornir Tasks ###########################################################################################
+
+
+#### Nornir Tasks ###########################################################################################