dcnm_image_upgrade (ready to merge).

.github/workflows/main.yml

@@ -124,7 +124,7 @@ jobs:
       run: ansible-galaxy collection install .cache/collection-tarballs/*.tar.gz
 
     - name: Run DCNM Unit tests
-      run: coverage run --source=. -m pytest tests/unit/modules/dcnm/. -vvvv
+      run: coverage run --source=. -m pytest tests/unit/. -vvvv
       working-directory: /home/runner/.ansible/collections/ansible_collections/cisco/dcnm
       env:
         PYTHONPATH: /home/runner/.ansible/collections

README.md

@@ -34,6 +34,7 @@ Name | Description
 ### Modules
 Name | Description
 --- | ---
+[cisco.dcnm.dcnm_image_upgrade](https://github.com/CiscoDevNet/ansible-dcnm/blob/main/docs/cisco.dcnm.dcnm_image_upgrade_module.rst)|Image management for Nexus switches
 [cisco.dcnm.dcnm_interface](https://github.com/CiscoDevNet/ansible-dcnm/blob/main/docs/cisco.dcnm.dcnm_interface_module.rst)|DCNM Ansible Module for managing interfaces.
 [cisco.dcnm.dcnm_inventory](https://github.com/CiscoDevNet/ansible-dcnm/blob/main/docs/cisco.dcnm.dcnm_inventory_module.rst)|Add and remove Switches from a DCNM managed VXLAN fabric.
 [cisco.dcnm.dcnm_links](https://github.com/CiscoDevNet/ansible-dcnm/blob/main/docs/cisco.dcnm.dcnm_links_module.rst)|DCNM ansible module for managing Links.

plugins/action/dcnm_image_upgrade.py

@@ -0,0 +1,62 @@
+# Copyright (c) 2024 Cisco and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import absolute_import, division, print_function
+
+__metaclass__ = type
+
+from ansible_collections.ansible.netcommon.plugins.action.network import (
+    ActionModule as ActionNetworkModule,
+)
+from ansible.utils.display import Display
+
+display = Display()
+
+
+class ActionModule(ActionNetworkModule):
+    def run(self, tmp=None, task_vars=None):
+
+        connection = self._connection
+        persistent_connect_timeout = connection.get_option("persistent_connect_timeout")
+        persistent_command_timeout = connection.get_option("persistent_command_timeout")
+
+        timeout = 1000
+
+        if (persistent_command_timeout < timeout or persistent_connect_timeout < timeout):
+            display.warning(
+                "PERSISTENT_COMMAND_TIMEOUT is %s"
+                % str(persistent_command_timeout),
+                self._play_context.remote_addr,
+            )
+            display.warning(
+                "PERSISTENT_CONNECT_TIMEOUT is %s"
+                % str(persistent_connect_timeout),
+                self._play_context.remote_addr,
+            )
+            msg = (
+                "PERSISTENT_COMMAND_TIMEOUT and PERSISTENT_CONNECT_TIMEOUT"
+            )
+            msg += " must be set to {0} seconds or higher when using dcnm_image_upgrade module.".format(timeout)
+            msg += " Current persistent_command_timeout setting:" + str(
+                persistent_command_timeout
+            )
+            msg += " Current persistent_connect_timeout setting:" + str(
+                persistent_connect_timeout
+            )
+            return {"failed": True, "msg": msg}
+
+        if self._task.args.get('state') == 'merged':
+            display.warning("Upgrading switches can take a while.  Please be patient...")
+        self.result = super(ActionModule, self).run(task_vars=task_vars)
+        return self.result

plugins/module_utils/common/controller_version.py

@@ -0,0 +1,283 @@
+"""
+Class to retrieve and return information about an NDFC controller
+"""
+#
+# Copyright (c) 2024 Cisco and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import absolute_import, division, print_function
+
+__metaclass__ = type
+__copyright__ = "Copyright (c) 2024 Cisco and/or its affiliates."
+__author__ = "Allen Robel"
+
+import logging
+
+from ansible_collections.cisco.dcnm.plugins.module_utils.image_upgrade.api_endpoints import \
+    ApiEndpoints
+from ansible_collections.cisco.dcnm.plugins.module_utils.image_upgrade.image_upgrade_common import \
+    ImageUpgradeCommon
+from ansible_collections.cisco.dcnm.plugins.module_utils.network.dcnm.dcnm import \
+    dcnm_send
+
+
+class ControllerVersion(ImageUpgradeCommon):
+    """
+    Return image version information from the Controller
+
+    NOTES:
+    1.  considered using dcnm_version_supported() but it does not return
+        minor release info, which is needed due to key changes between
+        12.1.2e and 12.1.3b.  For example, see ImageStage().commit()
+
+    Endpoint:
+        /appcenter/cisco/ndfc/api/v1/fm/about/version
+
+    Usage (where module is an instance of AnsibleModule):
+
+    instance = ControllerVersion(module)
+    instance.refresh()
+    if instance.version == "12.1.2e":
+        do 12.1.2e stuff
+    else:
+        do other stuff
+
+    Response:
+        {
+            "version": "12.1.2e",
+            "mode": "LAN",
+            "isMediaController": false,
+            "dev": false,
+            "isHaEnabled": false,
+            "install": "EASYFABRIC",
+            "uuid": "f49e6088-ad4f-4406-bef6-2419de914ff1",
+            "is_upgrade_inprogress": false
+        }
+    """
+
+    def __init__(self, ansible_module):
+        super().__init__(ansible_module)
+        self.class_name = self.__class__.__name__
+
+        self.log = logging.getLogger(f"dcnm.{self.class_name}")
+        self.log.debug("ENTERED ControllerVersion()")
+
+        self.endpoints = ApiEndpoints()
+        self._init_properties()
+
+    def _init_properties(self):
+        self.properties = {}
+        self.properties["data"] = None
+        self.properties["result"] = None
+        self.properties["response"] = None
+
+    def refresh(self):
+        """
+        Refresh self.response_data with current version info from the Controller
+        """
+        path = self.endpoints.controller_version.get("path")
+        verb = self.endpoints.controller_version.get("verb")
+        self.properties["response"] = dcnm_send(self.ansible_module, verb, path)
+        self.properties["result"] = self._handle_response(self.response, verb)
+
+        if self.result["success"] is False or self.result["found"] is False:
+            msg = f"{self.class_name}.refresh() failed: {self.result}"
+            self.ansible_module.fail_json(msg)
+
+        self.properties["response_data"] = self.response.get("DATA")
+        if self.response_data is None:
+            msg = f"{self.class_name}.refresh() failed: response "
+            msg += "does not contain DATA key. Controller response: "
+            msg += f"{self.response}"
+            self.ansible_module.fail_json(msg)
+
+    def _get(self, item):
+        return self.make_boolean(self.make_none(self.response_data.get(item)))
+
+    @property
+    def dev(self):
+        """
+        Return True if the Controller is running a development release.
+        Return False if the Controller is not running a development release.
+        Return None otherwise
+
+        Possible values:
+            True
+            False
+            None
+        """
+        return self._get("dev")
+
+    @property
+    def install(self):
+        """
+        Return the value of install, if it exists.
+        Return None otherwise
+
+        Possible values:
+            EASYFABRIC
+            (probably other values)
+            None
+        """
+        return self._get("install")
+
+    @property
+    def is_ha_enabled(self):
+        """
+        Return True if Controller is high-availability enabled.
+        Return False if Controller is not high-availability enabled.
+        Return None otherwise
+
+        Possible values:
+            True
+            False
+            None
+        """
+        return self.make_boolean(self._get("isHaEnabled"))
+
+    @property
+    def is_media_controller(self):
+        """
+        Return True if Controller is a media controller.
+        Return False if Controller is not a media controller.
+        Return None otherwise
+
+        Possible values:
+            True
+            False
+            None
+        """
+        return self.make_boolean(self._get("isMediaController"))
+
+    @property
+    def is_upgrade_inprogress(self):
+        """
+        Return True if a Controller upgrade is in progress.
+        Return False if a Controller upgrade is not in progress.
+        Return None otherwise
+
+        Possible values:
+            True
+            False
+            None
+        """
+        return self.make_boolean(self._get("is_upgrade_inprogress"))
+
+    @property
+    def response_data(self):
+        """
+        Return the data retrieved from the request
+        """
+        return self.properties.get("response_data")
+
+    @property
+    def result(self):
+        """
+        Return the GET result from the Controller
+        """
+        return self.properties.get("result")
+
+    @property
+    def response(self):
+        """
+        Return the GET response from the Controller
+        """
+        return self.properties.get("response")
+
+    @property
+    def mode(self):
+        """
+        Return the controller mode, if it exists.
+        Return None otherwise
+
+        Possible values:
+            LAN
+            None
+        """
+        return self._get("mode")
+
+    @property
+    def uuid(self):
+        """
+        Return the value of uuid, if it exists.
+        Return None otherwise
+
+        Possible values:
+            uuid e.g. "f49e6088-ad4f-4406-bef6-2419de914df1"
+            None
+        """
+        return self._get("uuid")
+
+    @property
+    def version(self):
+        """
+        Return the controller version, if it exists.
+        Return None otherwise
+
+        Possible values:
+            version, e.g. "12.1.2e"
+            None
+        """
+        return self._get("version")
+
+    @property
+    def version_major(self):
+        """
+        Return the controller major version, if it exists.
+        Return None otherwise
+
+        We are assuming semantic versioning based on:
+        https://semver.org
+
+        Possible values:
+            if version is 12.1.2e, return 12
+            None
+        """
+        if self.version is None:
+            return None
+        return (self._get("version").split("."))[0]
+
+    @property
+    def version_minor(self):
+        """
+        Return the controller minor version, if it exists.
+        Return None otherwise
+
+        We are assuming semantic versioning based on:
+        https://semver.org
+
+        Possible values:
+            if version is 12.1.2e, return 1
+            None
+        """
+        if self.version is None:
+            return None
+        return (self._get("version").split("."))[1]
+
+    @property
+    def version_patch(self):
+        """
+        Return the controller minor version, if it exists.
+        Return None otherwise
+
+        We are assuming semantic versioning based on:
+        https://semver.org
+
+        Possible values:
+            if version is 12.1.2e, return 2e
+            None
+        """
+        if self.version is None:
+            return None
+        return (self._get("version").split("."))[2]