Added common reboot_timeout option (#135)

Added the option reboot_timeout to modules that expose a reboot option.
This provides a way for the caller to define a custom reboot timeout
based on their environment specific details.

changelogs/fragments/reboot_timeout.yml

@@ -0,0 +1,5 @@
+minor_changes:
+  - microsoft.ad.domain_child - Added ``reboot_timeout`` option to control how long a reboot can go for.
+  - microsoft.ad.domain_controller - Added ``reboot_timeout`` option to control how long a reboot can go for.
+  - microsoft.ad.domain - Added ``reboot_timeout`` option to control how long a reboot can go for.
+  - microsoft.ad.membership - Added ``reboot_timeout`` option to control how long a reboot can go for.

plugins/doc_fragments/action_reboot.py

@@ -0,0 +1,29 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2024 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+
+class ModuleDocFragment:
+
+    # Common options for ansible_collections.microsoft.ad.plugins.plugin_utils._module_with_reboot
+    DOCUMENTATION = r"""
+options:
+  reboot:
+    description:
+    - If C(true), this will reboot the host if a reboot was required by the
+      module.
+    - If C(false), this will not reboot the host if a reboot was required and
+      instead sets the I(reboot_required) return value to C(true).
+    - This cannot be used with async mode.
+    type: bool
+    default: false
+  reboot_timeout:
+    description:
+    - Maximum seconds to wait for machine to re-appear after a reboot and respond to a test command.
+    - This timeout is evaluated separately for both the reboot verification and test command success so
+      the total timeout can be twice this value.
+    default: 600
+    type: int
+    version_added: 1.7.0
+"""

plugins/modules/domain.ps1

@@ -37,6 +37,10 @@ $spec = @{
             default = $false
             type = 'bool'
         }
+        reboot_timeout = @{
+            default = 600
+            type = 'int'
+        }
         safe_mode_password = @{
             no_log = $true
             required = $true

plugins/modules/domain.py

@@ -58,15 +58,6 @@
     - Specifies the fully qualified, non-UNC path to a directory on a fixed disk of the local computer where the log file for this operation is written.
     - If not set then the default path is C(%SYSTEMROOT%\NTDS).
     type: path
-  reboot:
-    description:
-    - If C(true), this will reboot the host if a reboot was required to configure the domain.
-    - If C(false), this will not reboot the host if a reboot was required and instead sets the I(reboot_required) return value to C(true).
-    - Multiple reboots may occur if the host required a reboot before the domain promotion.
-    - This cannot be used with async mode.
-    - To use this parameter, ensure the fully qualified module name is used in the task or the I(collections) keyword includes this collection.
-    type: bool
-    default: false
   safe_mode_password:
     description:
     - Safe mode password for the domain controller.
@@ -80,9 +71,14 @@
     type: path
 notes:
 - This module must be run on a Windows target host.
+- If using I(reboot=true), multiple reboots may occur if the host required a
+  reboot before the domain promotion. Also ensure the fully qualified module
+  name is used in the task or the I(collections) keyword includes this
+  collection.
 extends_documentation_fragment:
 - ansible.builtin.action_common_attributes
 - ansible.builtin.action_common_attributes.flow
+- microsoft.ad.action_reboot
 attributes:
   check_mode:
     support: full

plugins/modules/domain_child.ps1

@@ -46,6 +46,10 @@ $spec = @{
             default = $false
             type = 'bool'
         }
+        reboot_timeout = @{
+            default = 600
+            type = 'int'
+        }
         safe_mode_password = @{
             type = 'str'
             required = $true

plugins/modules/domain_child.yml

@@ -84,17 +84,6 @@ DOCUMENTATION:
           create a new domain tree in.
         - This can only be set when I(domain_type=tree).
       type: str
-    reboot:
-      description:
-        - If C(true), this will reboot the host if a reboot was create the
-          domain.
-        - If C(false), this will not reboot the host if a reboot was required
-          and instead sets the I(reboot_required) return value to C(true).
-        - Multiple reboots may occur if the host required a reboot before the
-          domain promotion.
-        - This cannot be used with async mode.
-      type: bool
-      default: false
     safe_mode_password:
       description:
         - Safe mode password for the domain controller.
@@ -117,9 +106,12 @@ DOCUMENTATION:
       state where it may not be possible for Ansible to reconnect in a
       subsequent task without a reboot.
     - This module must be run on a Windows target host.
+    - If using I(reboot=true), multiple reboots may occur if the host required
+      a reboot before the domain promotion.
   extends_documentation_fragment:
     - ansible.builtin.action_common_attributes
     - ansible.builtin.action_common_attributes.flow
+    - microsoft.ad.action_reboot
   attributes:
     check_mode:
       support: full

plugins/modules/domain_controller.ps1

@@ -44,6 +44,10 @@ $spec = @{
             default = $false
             type = 'bool'
         }
+        reboot_timeout = @{
+            default = 600
+            type = 'int'
+        }
         safe_mode_password = @{
             no_log = $true
             type = 'str'

plugins/modules/domain_controller.py

@@ -56,15 +56,6 @@
     - Whether to install the domain controller as a read only replica for an existing domain.
     type: bool
     default: no
-  reboot:
-    description:
-    - If C(true), this will reboot the host if a reboot was required to configure the server.
-    - If C(false), this will not reboot the host if a reboot was required and instead sets the I(reboot_required) return value to C(true).
-    - Multiple reboots may occur if the host required a reboot before the domain promotion.
-    - This cannot be used with async mode.
-    - To use this parameter, ensure the fully qualified module name is used in the task or the I(collections) keyword includes this collection.
-    type: bool
-    default: false
   safe_mode_password:
     description:
     - Safe mode password for the domain controller (required when I(state=domain_controller)).
@@ -93,9 +84,14 @@
   this module puts the host in a state where it may not be possible for Ansible to reconnect in a subsequent task
   without a reboot.
 - This module must be run on a Windows target host.
+- If using I(reboot=true), multiple reboots may occur if the host required a
+  reboot before the domain promotion. Also ensure the fully qualified module
+  name is used in the task or the I(collections) keyword includes this
+  collection.
 extends_documentation_fragment:
 - ansible.builtin.action_common_attributes
 - ansible.builtin.action_common_attributes.flow
+- microsoft.ad.action_reboot
 attributes:
   check_mode:
     support: full

plugins/modules/membership.ps1

@@ -34,6 +34,10 @@ $spec = @{
             default = $false
             type = 'bool'
         }
+        reboot_timeout = @{
+            default = 600
+            type = 'int'
+        }
         state = @{
             choices = 'domain', 'workgroup'
             required = $true

plugins/modules/membership.py

@@ -52,16 +52,6 @@
       and I(domain_ou_path).
     - It also cannot be used with I(hostname).
     type: str
-  reboot:
-    description:
-    - If C(true), this will reboot the host if a reboot was required to configure the domain.
-    - If C(false), this will not reboot the host if a reboot was required and instead sets the I(reboot_required) return value to C(true).
-    - If changing from a domain to workgroup, the connection account must be a local user that can connect to the host
-      after it has unjoined the domain.
-    - This cannot be used with async mode.
-    - To use this parameter, ensure the fully qualified module name is used in the task or the I(collections) keyword includes this collection.
-    type: bool
-    default: false
   state:
     description:
     - Whether the target host should be a member of a domain or workgroup.
@@ -79,9 +69,14 @@
     type: str
 notes:
 - This module must be run on a Windows target host.
+- If using I(reboot=true) and changing from a domain to workgroup, the connection
+  account must be a local user that can connect to the host after it has
+  unjoined the domain. Also ensure the fully qualified module name is used in
+  the task or the I(collections) keyword includes this collection.
 extends_documentation_fragment:
 - ansible.builtin.action_common_attributes
 - ansible.builtin.action_common_attributes.flow
+- microsoft.ad.action_reboot
 attributes:
   check_mode:
     support: full

plugins/plugin_utils/_module_with_reboot.py

@@ -111,6 +111,7 @@ def run(
 
         wrap_async = self._task.async_val and not self._connection.has_native_async
         reboot = self._task.args.get("reboot", False)
+        reboot_timeout = self._task.args.get("reboot_timeout", 600)
 
         if self._task.async_val > 0 and reboot:
             return {
@@ -136,6 +137,7 @@ def run(
                     reboot_res = reboot_host(
                         self._task.action,
                         self._connection,
+                        reboot_timeout=reboot_timeout,
                         previous_boot_time=previous_boot_time,
                     )