[minor_change] Add new module nd_site (#47)

Author: anvitha-jain

plugins/httpapi/nd.py

@@ -121,7 +121,10 @@ def login(self, username, password):
                         json_response = self._response_to_json(response_data)
                     self.error = dict(code=self.status, message="Authentication failed: {0}".format(json_response))
                     raise ConnectionError(json.dumps(self._verify_response(response, method, full_path, response_data)))
-                self.connection._auth = {"Authorization": "Bearer {0}".format(self._response_to_json(response_data).get("token"))}
+                self.connection._auth = {
+                    "Authorization": "Bearer {0}".format(self._response_to_json(response_data).get("token")),
+                    "Cookie": "AuthCookie={0}".format(self._response_to_json(response_data).get("token")),
+                }
 
             except ConnectionError as connection_err:
                 self.connection.queue_message("error", "login() - ConnectionError Exception: {0}".format(connection_err))

plugins/module_utils/constants.py

@@ -127,3 +127,5 @@
 TCP_FLAGS = {"ack": "ACKNOWLEDGEMENT", "est": "ESTABLISHED", "fin": "FINISH", "res": "RESET", "syn": "SYNCHRONIZED"}
 
 EPOCH_DELTA_TYPES = {"latest": 0, "last_15_min": 900, "last_hour": 3600, "last_2_hours": 7200, "last_6_hours": 21600, "last_day": 86400, "last_week": 604800}
+
+SITE_TYPE_MAP = {"aci": "ACI", "dcnm": "DCNM", "third_party": "ThirdParty", "cloud_aci": "CloudACI", "dcnm_ng": "DCNMNG", "ndfc": "NDFC"}

plugins/module_utils/nd.py

@@ -7,6 +7,7 @@
 # GNU General Public License v3.0+ (see LICENSE or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import absolute_import, division, print_function
+from functools import reduce
 
 __metaclass__ = type
 
@@ -462,3 +463,41 @@ def check_changed(self):
         if "password" in existing:
             existing["password"] = self.sent.get("password")
         return not issubset(self.sent, existing)
+
+    def get_diff(self, unwanted=None):
+        """Check if existing payload and sent payload and removing keys that are not required"""
+        if unwanted is None:
+            unwanted = []
+        if not self.existing and self.sent:
+            return True
+
+        existing = self.existing
+        sent = self.sent
+
+        for key in unwanted:
+            if type(key) is str:
+                if key in existing:
+                    try:
+                        del existing[key]
+                    except KeyError:
+                        pass
+                    try:
+                        del sent[key]
+                    except KeyError:
+                        pass
+            elif type(key) is list:
+                key_path, last = key[:-1], key[-1]
+                try:
+                    existing_parent = reduce(dict.get, key_path, existing)
+                    del existing_parent[last]
+                except KeyError:
+                    pass
+                try:
+                    sent_parent = reduce(dict.get, key_path, sent)
+                    del sent_parent[last]
+                except KeyError:
+                    pass
+        return not issubset(sent, existing)
+
+    def set_to_empty_string_when_none(self, val):
+        return val if val is not None else ""

plugins/modules/nd_site.py

@@ -0,0 +1,264 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# Copyright: (c) 2023, Anvitha Jain (@anvitha-jain) <[email protected]>
+# GNU General Public License v3.0+ (see LICENSE 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: nd_site
+short_description: Manage sites on Nexus Dashboard.
+description:
+- Manage sites on Nexus Dashboard which are then used by Nexus Dashboard Orchestrator (NDO) >= 2.2(2d).
+author:
+- Anvitha Jain (@anvitha-jain)
+options:
+  site_password:
+    description:
+    - The password for the APIC.
+    type: str
+  site_username:
+    description:
+    - The username for the APIC.
+    type: str
+  login_domain:
+    description:
+    - The AAA login domain for the username of the APIC.
+    type: str
+  inband_epg:
+    description:
+    - The In-Band Endpoint Group (EPG) used to connect Nexus Dashboard to the fabric.
+    type: str
+  site_name:
+    description:
+    - The name of the site.
+    type: str
+    aliases: [ name, fabric_name ]
+  # ToDo: To avail the securityDomains feature, ND v4 API update is required.
+  # security_domains:
+  #   description:
+  #   - The security_domains for this site.
+  #   type: list
+  #   elements: str
+  latitude:
+    description:
+    - The latitude of the location of the site.
+    type: float
+  longitude:
+    description:
+    - The longitude of the location of the site.
+    type: float
+  url:
+    description:
+    - The URL to reference the APICs.
+    type: str
+    aliases: [ host_name, ip_address, site_url]
+  site_type:
+    description:
+    - The site type of the APICs.
+    type: str
+    choices: [ aci, dcnm, third_party, cloud_aci, dcnm_ng, ndfc ]
+  re_register:
+    description:
+    - To modify the APIC parameters (site_username, site_password and login_domain).
+    - Using this option deletes the existing site and re-creates it.
+    type: bool
+    default: false
+  state:
+    description:
+    - Use C(present) or C(absent) for adding or removing.
+    - Use C(query) for listing an object or multiple objects.
+    type: str
+    choices: [ absent, present, query ]
+    default: present
+extends_documentation_fragment: cisco.nd.modules
+"""
+
+EXAMPLES = r"""
+- name: Add a new site
+  cisco.nd.nd_site:
+    url: SiteURL
+    site_username: SiteUsername
+    site_password: SitePassword
+    site_type: aci
+    location:
+      latitude: 50.887318
+      longitude: 4.447084
+    login_domain: "DefaultAuth"
+    inband_epg: In-Band-EPG
+    state: present
+  delegate_to: localhost
+
+- name: Remove a site
+  cisco.nd.nd_site:
+    site_name: north_europe
+    state: absent
+  delegate_to: localhost
+
+- name: Query a site
+  cisco.nd.nd_site:
+    site_name: north_europe
+    state: query
+  delegate_to: localhost
+  register: query_result
+
+- name: Query all sites
+  cisco.nd.nd_site:
+    state: query
+  delegate_to: localhost
+  register: query_result
+"""
+
+RETURN = r"""
+"""
+
+from ansible.module_utils.basic import AnsibleModule
+from ansible_collections.cisco.nd.plugins.module_utils.nd import NDModule, nd_argument_spec
+from ansible_collections.cisco.nd.plugins.module_utils.constants import SITE_TYPE_MAP
+import base64
+
+
+def main():
+    argument_spec = nd_argument_spec()
+    argument_spec.update(
+        site_password=dict(type="str", no_log=True),
+        site_username=dict(type="str"),
+        login_domain=dict(type="str"),
+        inband_epg=dict(type="str"),
+        site_name=dict(type="str", aliases=["name", "fabric_name"]),
+        url=dict(type="str", aliases=["host_name", "ip_address", "site_url"]),
+        site_type=dict(type="str", choices=list(SITE_TYPE_MAP.keys())),
+        # ToDo: To avail the securityDomains feature, ND v4 API update is required.
+        # security_domains=dict(type="list", elements="str"),
+        latitude=dict(type="float"),
+        longitude=dict(type="float"),
+        re_register=dict(type="bool", default=False),
+        state=dict(type="str", default="present", choices=["absent", "present", "query"]),
+    )
+
+    module = AnsibleModule(
+        argument_spec=argument_spec,
+        supports_check_mode=True,
+        required_if=[
+            ["state", "absent", ["site_name"]],
+            ["state", "present", ["site_name", "site_username", "site_password", "url", "site_type"]],
+        ],
+    )
+
+    nd = NDModule(module)
+
+    site_username = nd.params.get("site_username")
+
+    site_password = nd.params.get("site_password")
+    if site_password is not None:
+        # Make password base64 encoded
+        site_password = (base64.b64encode(str.encode(site_password))).decode("utf-8")
+
+    inband_epg = nd.set_to_empty_string_when_none(nd.params.get("inband_epg"))
+    if inband_epg != "":
+        inband_epg = "uni/tn-mgmt/mgmtp-default/inb-{0}".format(inband_epg)
+
+    login_domain = nd.set_to_empty_string_when_none(nd.params.get("login_domain"))
+    site_name = nd.params.get("site_name")
+    url = nd.params.get("url")
+    site_type = nd.params.get("site_type")
+    latitude = nd.set_to_empty_string_when_none(nd.params.get("latitude"))
+    longitude = nd.set_to_empty_string_when_none(nd.params.get("longitude"))
+    # ToDo: To avail the securityDomains feature, ND v4 API update is required.
+    # security_domains = nd.params.get("security_domains")
+    re_register = nd.params.get("re_register")
+    state = nd.params.get("state")
+
+    path = "/nexus/api/sitemanagement/v4/sites"
+    site_obj = nd.query_obj(path).get("items")
+
+    if site_name:
+        site_info = next((site_dict for site_dict in site_obj if site_dict.get("spec").get("name") == site_name), None)
+        if site_info:
+            site_path = "{0}/{1}".format(path, site_name)
+            nd.existing = site_info
+    else:
+        nd.existing = site_obj
+
+    nd.previous = nd.existing
+
+    if state == "query":
+        nd.exit_json()
+    elif state == "absent":
+        if nd.existing:
+            if not module.check_mode:
+                nd.request(site_path, method="DELETE")
+            nd.existing = {}
+    elif state == "present":
+        site_configuration = {}
+        if site_type == "aci" or site_type == "cloud_aci":
+            site_type_param = site_type
+            if site_type == "cloud_aci":
+                site_type_param = SITE_TYPE_MAP.get(site_type)
+            site_configuration.update(
+                {
+                    site_type_param: {
+                        "InbandEPGDN": inband_epg,
+                    }
+                }
+            )
+        elif site_type == "ndfc" or site_type == "dcnm":
+            site_configuration.update({site_type: {"fabricName": site_name, "fabricTechnology": "External", "fabricType": "External"}})
+
+        payload = {
+            "spec": {
+                "name": site_name,
+                "siteType": SITE_TYPE_MAP.get(site_type),
+                "host": url,
+                "userName": site_username,
+                "password": site_password,
+                "loginDomain": login_domain,
+                "latitude": str(latitude),
+                "longitude": str(longitude),
+                # ToDo: To avail the securityDomains feature, ND v4 API update is required.
+                # "securityDomains": security_domains if security_domains is not None else [],
+                "siteConfig": site_configuration,
+            },
+        }
+
+        nd.sanitize(payload, collate=True)
+
+        if not module.check_mode:
+            method = "POST"
+            if re_register:
+                nd.request(site_path, method="DELETE")
+                nd.existing = {}
+            if nd.existing and not re_register:
+                method = "PUT"
+                path = site_path
+
+            unwanted = [
+                "metadata",
+                "status",
+                ["spec", "annotation"],
+                ["spec", "host"],
+                ["spec", "userName"],
+                ["spec", "password"],
+                ["spec", "loginDomain"],
+                ["spec", "useProxy"],
+                ["spec", "secureVerify"],
+                ["spec", "internalOnboard"],
+            ]
+            if nd.get_diff(unwanted):
+                nd.existing = nd.request(path, method=method, data=payload)
+            else:
+                nd.has_modified = True
+
+    nd.existing = nd.proposed
+
+    nd.exit_json()
+
+
+if __name__ == "__main__":
+    main()