INSTALL OS: Add method that performs install of OS (#69)

 * `install_os` method added to all but `JunosDevice`.
    - File(s) must be on the device already.
    - Checks that image is not already booted on the device.
    - Ensures device is ready to install image.
    - Reboots the device if required for OS installation (F5Device does not)
    - Waits for device to reboot or finish installation.
    - Raises `OSInstallError if image is not confirmed installed.
    - Returns True if image was installed.
    - Returns False if device was already booted on the device.

 * F5Device:
    - Double default timeout value for image installation.
    - Implement hardened _wait_for_image_installed() method
    - Add NTCFileNotFoundError exception in case of attempts to install non-existing image file.

* NXOSDevice:
    -   Change Exception output for kickstart's `NTCFileNotFound` to use kickstart file instead of system file.

* ASADevice:
    - Add call to `save` method in `set_boot_options` to mimic behavior of `IOSDevice` and potentially avoid bug that was discovered there.

 * BaseDevice:
    - Update `install_os` docstring with updates required for method to actually be implemented.

Author: jmcgill298

pyntc/devices/asa_device.py

@@ -9,19 +9,18 @@
 from netmiko import ConnectHandler
 from netmiko import FileTransfer
 
-
+from pyntc.templates import get_structured_data
+from .base_device import BaseDevice, fix_docs
+from .system_features.file_copy.base_file_copy import FileTransferError
 from pyntc.errors import (
     CommandError,
     CommandListError,
     FileSystemNotFoundError,
     NTCError,
     NTCFileNotFoundError,
     RebootTimeoutError,
+    OSInstallError,
 )
-from pyntc.templates import get_structured_data
-from .base_device import BaseDevice, fix_docs
-from .system_features.file_copy.base_file_copy import FileTransferError
-
 
 @fix_docs
 class ASADevice(BaseDevice):
@@ -243,6 +242,19 @@ def get_boot_options(self):
 
         return dict(sys=boot_image)
 
+    def install_os(self, image_name, **vendor_specifics):
+        timeout = vendor_specifics.get("timeout", 3600)
+        if not self._image_booted(image_name):
+            self.set_boot_options(image_name, **vendor_specifics)
+            self.reboot(confirm=True)
+            self._wait_for_device_reboot(timeout=timeout)
+            if not self._image_booted(image_name):
+                raise OSInstallError(hostname=self.facts.get("hostname"), desired_boot=image_name)
+
+            return True
+
+        return False
+
     def open(self):
         if self._connected:
             try:
@@ -314,14 +326,16 @@ def set_boot_options(self, image_name, **vendor_specifics):
         file_system_files = self.show("dir {0}".format(file_system))
         if re.search(image_name, file_system_files) is None:
             raise NTCFileNotFoundError(
-                hostname=self.facts.get("hostname"), file=image_name, dir=file_system
+                # TODO: Update to use hostname
+                hostname=self.host, file=image_name, dir=file_system
             )
 
         current_images = current_boot.splitlines()
         commands_to_exec = ["no {0}".format(image) for image in current_images]
         commands_to_exec.append("boot system {0}/{1}".format(file_system, image_name))
         self.config_list(commands_to_exec)
 
+        self.save()
         if self.get_boot_options()["sys"] != image_name:
             raise CommandError(
                 command="boot system {0}/{1}".format(file_system, image_name),

pyntc/devices/base_device.py

@@ -191,6 +191,39 @@ def get_boot_options(self):
         """
         raise NotImplementedError
 
+    @abc.abstractmethod
+    def install_os(self, image_name, **vendor_specifics):
+        """Install the OS from specified image_name
+
+        Args:
+            image_name(str): The name of the image on the device to install.
+
+        Keyword Args:
+            kickstart (str): Option for ``NXOSDevice`` for devices that require a kickstart image.
+            volume (str): Option for ``F5Device`` to set the target boot volume.
+            file_system (str): Option for ``ASADevice``, ``EOSDevice``, ``IOSDevice``, and
+                ``NXOSDevice`` to set where the OS files are stored. The default will use
+                the ``_get_file_system`` method.
+            timeout (int): Option for ``IOSDevice`` and ``NXOSDevice`` to set the wait time for
+                device installation to complete.
+
+        Returns:
+            True if system has been installed during function's call, False if OS has not been installed
+
+        Raises:
+            OSInstallError: When device finishes installation process, but the running image
+                does not match ``image_name``.
+            CommandError: When sending a command to the device fails, or when the config status
+                after sending a command does not yield expected results.
+            CommandListError: When sending commands to the device fails.
+            NotEnoughFreeSpaceError: When the device does not have enough free space for install.
+            NTCFileNotFoundError: When the ``image_name`` is not found in the devices ``file_system``.
+            FileSystemNotFoundError: When the ``file_system`` is left to default,
+                and the ``file_system`` cannot be identified.
+            RebootTimeoutError: When device is rebooted and is unreachable longer than ``timeout`` period.
+        """
+        raise NotImplementedError
+
     @abc.abstractmethod
     def open(self):
         """Open a connection to the device.

pyntc/devices/eos_device.py

@@ -17,6 +17,7 @@
     NTCError,
     NTCFileNotFoundError,
     RebootTimeoutError,
+    OSInstallError,
 )
 
 from pyeapi import connect as eos_connect
@@ -180,6 +181,19 @@ def get_boot_options(self):
         image = image.replace('flash:', '')
         return dict(sys=image)
 
+    def install_os(self, image_name, **vendor_specifics):
+        timeout = vendor_specifics.get("timeout", 3600)
+        if not self._image_booted(image_name):
+            self.set_boot_options(image_name, **vendor_specifics)
+            self.reboot(confirm=True)
+            self._wait_for_device_reboot(timeout=timeout)
+            if not self._image_booted(image_name):
+                raise OSInstallError(hostname=self.facts.get("hostname"), desired_boot=image_name)
+
+            return True
+
+        return False
+
     def open(self):
         pass
 

pyntc/devices/f5_device.py

@@ -10,9 +10,10 @@
 import requests
 from f5.bigip import ManagementRoot
 
+from pyntc.errors import NotEnoughFreeSpaceError, OSInstallError, \
+    NTCFileNotFoundError
 from .base_device import BaseDevice
 from .system_features.file_copy.base_file_copy import FileTransferError
-from pyntc.errors import NotEnoughFreeSpaceError, OSInstallError
 
 
 class F5Device(BaseDevice):
@@ -338,7 +339,7 @@ def _wait_for_device_reboot(self, volume_name, timeout=600):
                 pass
         return False
 
-    def _wait_for_image_installed(self, image_name, volume, timeout=900):
+    def _wait_for_image_installed(self, image_name, volume, timeout=1800):
         """Waits for the device to install image on a volume
 
         Args:
@@ -353,8 +354,13 @@ def _wait_for_image_installed(self, image_name, volume, timeout=900):
 
         while time.time() < end_time:
             time.sleep(20)
-            if self.image_installed(image_name=image_name, volume=volume):
-                return
+            # Avoid race-conditions issues. Newly created volumes _might_ lack
+            # of .version attribute in first seconds of their live.
+            try:
+                if self.image_installed(image_name=image_name, volume=volume):
+                    return
+            except:
+                pass
 
         raise OSInstallError(hostname=self.facts.get("hostname"), desired_boot=volume)
 
@@ -395,7 +401,6 @@ def file_copy(self, src, dest=None, **kwargs):
         if not self.file_copy_remote_exists(src, dest, **kwargs):
             self._check_free_space(min_space=6)
             self._upload_image(image_filepath=src)
-
             if not self.file_copy_remote_exists(src, dest, **kwargs):
                 raise FileTransferError(
                     message="Attempted file copy, "
@@ -446,6 +451,22 @@ def image_installed(self, image_name, volume):
 
         return False
 
+    def install_os(self, image_name, **vendor_specifics):
+        volume = vendor_specifics.get('volume')
+        if not self.image_installed(image_name, volume):
+            self._check_free_space(min_space=6)
+            if not self._image_exists(image_name):
+                raise NTCFileNotFoundError(
+                    hostname=self._get_hostname(), file=image_name,
+                    dir='/shared/images'
+                )
+            self._image_install(image_name=image_name, volume=volume)
+            self._wait_for_image_installed(image_name=image_name, volume=volume)
+
+            return True
+
+        return False
+
     def open(self):
         pass
 
@@ -475,6 +496,11 @@ def save(self, filename=None):
     def set_boot_options(self, image_name, **vendor_specifics):
         volume = vendor_specifics.get('volume')
         self._check_free_space(min_space=6)
+        if not self._image_exists(image_name):
+            raise NTCFileNotFoundError(
+                hostname=self._get_hostname(), file=image_name,
+                dir='/shared/images'
+            )
         self._image_install(image_name=image_name, volume=volume)
         self._wait_for_image_installed(image_name=image_name, volume=volume)
 

pyntc/devices/ios_device.py

@@ -17,6 +17,7 @@
     FileSystemNotFoundError,
     NTCError,
     NTCFileNotFoundError,
+    OSInstallError,
     RebootTimeoutError,
 )
 
@@ -271,6 +272,19 @@ def get_boot_options(self):
 
         return {'sys': boot_image}
 
+    def install_os(self, image_name, **vendor_specifics):
+        timeout = vendor_specifics.get("timeout", 3600)
+        if not self._image_booted(image_name):
+            self.set_boot_options(image_name, **vendor_specifics)
+            self.reboot(confirm=True)
+            self._wait_for_device_reboot(timeout=timeout)
+            if not self._image_booted(image_name):
+                raise OSInstallError(hostname=self.facts.get("hostname"), desired_boot=image_name)
+
+            return True
+
+        return False
+
     def open(self):
         if self._connected:
             try:

pyntc/devices/jnpr_device.py

@@ -189,6 +189,9 @@ def file_copy_remote_exists(self, src, dest=None, **kwargs):
     def get_boot_options(self):
         return self.facts['os_version']
 
+    def install_os(self, image_name, **vendor_specifics):
+        raise NotImplementedError
+
     def open(self):
         if not self.connected:
             self.native.open()

pyntc/devices/nxos_device.py

@@ -12,6 +12,7 @@
     CommandListError,
     NTCFileNotFoundError,
     RebootTimeoutError,
+    OSInstallError,
 )
 
 from pynxos.device import Device as NXOSNative
@@ -102,6 +103,19 @@ def file_copy_remote_exists(self, src, dest=None, file_system='bootflash:'):
     def get_boot_options(self):
         return self.native.get_boot_options()
 
+    def install_os(self, image_name, **vendor_specifics):
+        timeout = vendor_specifics.get("timeout", 3600)
+        if not self._image_booted(image_name):
+            self.set_boot_options(image_name, **vendor_specifics)
+            self._wait_for_device_reboot(timeout=timeout)
+            if not self._image_booted(image_name):
+                raise OSInstallError(hostname=self.facts.get("hostname"), desired_boot=image_name)
+            self.save()
+
+            return True
+
+        return False
+
     def open(self):
         pass
 
@@ -134,10 +148,11 @@ def set_boot_options(self, image_name, kickstart=None, **vendor_specifics):
             raise NTCFileNotFoundError(
                 hostname=self.facts.get("hostname"), file=image_name, dir=file_system
             )
+
         if kickstart is not None:
             if re.search(kickstart, file_system_files) is None:
                 raise NTCFileNotFoundError(
-                    hostname=self.facts.get("hostname"), file=image_name, dir=file_system
+                    hostname=self.facts.get("hostname"), file=kickstart, dir=file_system
                 )
 
             kickstart = file_system + kickstart