fix: add flag to run boot_once idempotently without breaking the previous behavior and add deprecation warning

plugins/modules/hpilo_boot.py

@@ -9,13 +9,14 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
 
-DOCUMENTATION = r"""
+DOCUMENTATION = '''
+---
 module: hpilo_boot
 author: Dag Wieers (@dagwieers)
 short_description: Boot system using specific media through HP iLO interface
 description:
-  - 'This module boots a system through its HP iLO interface. The boot media can be one of: V(cdrom), V(floppy), V(hdd), V(network),
-    or V(usb).'
+  - "This module boots a system through its HP iLO interface. The boot media
+    can be one of: cdrom, floppy, hdd, network or usb."
   - This module requires the hpilo python module.
 extends_documentation_fragment:
   - community.general.attributes
@@ -42,32 +43,33 @@ options:
     type: str
   media:
     description:
-      - The boot media to boot the system from.
-    choices: ["cdrom", "floppy", "rbsu", "hdd", "network", "normal", "usb"]
+      - The boot media to boot the system from
+    choices: [ "cdrom", "floppy", "rbsu", "hdd", "network", "normal", "usb" ]
     type: str
   image:
     description:
-      - The URL of a cdrom, floppy or usb boot media image in the form V(protocol://username:password@hostname:port/filename).
-      - V(protocol) is either V(http) or V(https).
-      - V(username:password) is optional.
-      - V(port) is optional.
+      - The URL of a cdrom, floppy or usb boot media image.
+        protocol://username:password@hostname:port/filename
+      - protocol is either 'http' or 'https'
+      - username:password is optional
+      - port is optional
     type: str
   state:
     description:
       - The state of the boot media.
-      - 'V(no_boot): Do not boot from the device.'
-      - 'V(boot_once): Boot from the device once and then notthereafter.'
-      - 'V(boot_always): Boot from the device each time the server is rebooted.'
-      - 'V(connect): Connect the virtual media device and set to boot_always.'
-      - 'V(disconnect): Disconnects the virtual media device and set to no_boot.'
-      - 'V(poweroff): Power off the server.'
+      - "no_boot: Do not boot from the device"
+      - "boot_once: Boot from the device once and then notthereafter"
+      - "boot_always: Boot from the device each time the server is rebooted"
+      - "connect: Connect the virtual media device and set to boot_always"
+      - "disconnect: Disconnects the virtual media device and set to no_boot"
+      - "poweroff: Power off the server"
     default: boot_once
     type: str
-    choices: ["boot_always", "boot_once", "connect", "disconnect", "no_boot", "poweroff"]
+    choices: [ "boot_always", "boot_once", "connect", "disconnect", "no_boot", "poweroff" ]
   force:
     description:
-      - Whether to force a reboot (even when the system is already booted).
-      - As a safeguard, without force, hpilo_boot will refuse to reboot a server that is already running.
+    - Whether to force a reboot (even when the system is already booted).
+    - As a safeguard, without force, hpilo_boot will refuse to reboot a server that is already running.
     default: false
     type: bool
   ssl_version:
@@ -75,16 +77,21 @@ options:
       - Change the ssl_version used.
     default: TLSv1
     type: str
-    choices: ["SSLv3", "SSLv23", "TLSv1", "TLSv1_1", "TLSv1_2"]
+    choices: [ "SSLv3", "SSLv23", "TLSv1", "TLSv1_1", "TLSv1_2" ]
+  idempotent_boot_once:
+    description:
+      This makes the boot_once idempotent see github PR: https://github.com/ansible-collections/community.general/pull/9646
+    type: bool
+    default: false
 requirements:
-  - python-hpilo
+- python-hpilo
 notes:
-  - To use a USB key image you need to specify floppy as boot media.
-  - This module ought to be run from a system that can access the HP iLO interface directly, either by using C(local_action)
-    or using C(delegate_to).
-"""
+- To use a USB key image you need to specify floppy as boot media.
+- This module ought to be run from a system that can access the HP iLO
+  interface directly, either by using C(local_action) or using C(delegate_to).
+'''
 
-EXAMPLES = r"""
+EXAMPLES = r'''
 - name: Task to boot a system using an ISO from an HP iLO interface only if the system is an HP server
   community.general.hpilo_boot:
     host: YOUR_ILO_ADDRESS
@@ -102,11 +109,11 @@ EXAMPLES = r"""
     password: YOUR_ILO_PASSWORD
     state: poweroff
   delegate_to: localhost
-"""
+'''
 
-RETURN = r"""
+RETURN = '''
 # Default return values
-"""
+'''
 
 import time
 import traceback
@@ -138,6 +145,7 @@ def main():
             image=dict(type='str'),
             state=dict(type='str', default='boot_once', choices=['boot_always', 'boot_once', 'connect', 'disconnect', 'no_boot', 'poweroff']),
             force=dict(type='bool', default=False),
+            idempotent_boot_once=dict(type='bool', default=False),
             ssl_version=dict(type='str', default='TLSv1', choices=['SSLv3', 'SSLv23', 'TLSv1', 'TLSv1_1', 'TLSv1_2']),
         )
     )
@@ -152,6 +160,7 @@ def main():
     image = module.params['image']
     state = module.params['state']
     force = module.params['force']
+    idempotent_boot_once = module.params['idempotent_boot_once'] 
     ssl_version = getattr(hpilo.ssl, 'PROTOCOL_' + module.params.get('ssl_version').upper().replace('V', 'v'))
 
     ilo = hpilo.Ilo(host, login=login, password=password, ssl_version=ssl_version)
@@ -187,12 +196,21 @@ def main():
 
         power_status = ilo.get_host_power_status()
 
-        if not force and power_status == 'ON':
-           pass
-        elif power_status == 'ON':
-            ilo.warm_boot_server()
-#            ilo.cold_boot_server()
-            changed = True
+        if power_status == 'ON':
+            if not force and not idempotent_boot_once:
+                module.deprecate(
+                    'The failure of the module when the server is already powered on is being deprecated.'
+                    ' Please set the parameter "idempotent_boot_once=true" to start using the new behavior.',
+                    version='11.0.0',
+                    collection_name='community.general'
+                )
+                module.fail_json(msg='HP iLO (%s) reports that the server is already powered on !' % host)
+            elif not force and idempotent_boot_once:
+                pass
+            elif force:
+                ilo.warm_boot_server()
+    #            ilo.cold_boot_server()
+                changed = True
         else:
             ilo.press_pwr_btn()
 #            ilo.reset_server()