add warning for system-upgrade (#80)

ansibleguy · Jul 9, 2024 · d6f9f89 · d6f9f89
1 parent df0bc14
commit d6f9f89
Show file tree

Hide file tree

Showing 3 changed files with 32 additions and 2 deletions.
diff --git a/docs/source/modules/system.rst b/docs/source/modules/system.rst
@@ -13,6 +13,15 @@ System
 **API Docs**: `Core - Firmware <https://docs.opnsense.org/development/api/core/firmware.html>`_
 
 
+.. warning::
+
+    **Only** use the :code:`upgrade` action in **test-environments**!
+
+    When in production - use the WebUI to upgrade your boxes.
+
+    The box is rebooted while performing an update - it might be dead.
+
+
 Definition
 **********
 
@@ -58,10 +67,11 @@ Examples
           ansibleguy.opnsense.system:
             action: 'update'
 
-        - name: Start upgrade - will wait until finished
+        - name: Start upgrade - will wait until finished (WARNING: ONLY USE IN TEST-ENVIRONMENTS)
           ansibleguy.opnsense.system:
             action: 'upgrade'
             timeout: 120  # depends on your download speed and firmware-version
+            force_upgrade: true
 
         - name: Run audit
           ansibleguy.opnsense.system:

diff --git a/plugins/modules/system.py b/plugins/modules/system.py
@@ -28,11 +28,14 @@ def run_module():
     module_args = dict(
         action=dict(
             type='str', required=True,
-            choices=['poweroff', 'reboot', 'update', 'upgrade', 'audit']
+            choices=['poweroff', 'reboot', 'update', 'upgrade', 'audit'],
+            description="WARNING: Only use the 'upgrade' option in test-environments. "
+                        "In production you should use the WebUI to upgrade!"
         ),
         wait=dict(type='bool', required=False, default=True),
         wait_timeout=dict(type='int', required=False, default=90),
         poll_interval=dict(type='int', required=False, default=2),
+        force_upgrade=dict(type='bool', required=False, default=False),
         **OPN_MOD_ARGS
     )
 
@@ -47,6 +50,13 @@ def run_module():
         'timeout_exceeded': False,
     }
 
+    if module.params['action'] == 'upgrade' and not module.params['force_upgrade']:
+        module.fail_json(
+            "If you really want to perform an upgrade - you need to additionally supply the 'force_upgrade' argument. "
+            "WARNING: Using the 'upgrade' action is only recommended for test-environments. "
+            "In production you should use the WebUI to upgrade!"
+        )
+
     if not module.check_mode:
         with Session(module=module) as s:
             s.post({

diff --git a/tests/system.yml b/tests/system.yml
@@ -14,9 +14,19 @@
       ansibleguy.opnsense.system:
         action: 'update'
 
+    - name: Upgrade with wait - failing because not forced
+      ansibleguy.opnsense.system:
+        action: 'upgrade'
+        wait: true
+        timeout: 120
+        poll_interval: 2
+      register: opn_up1
+      failed_when: not opn_up1.failed
+
     - name: Upgrade with wait
       ansibleguy.opnsense.system:
         action: 'upgrade'
+        force_upgrade: true
         wait: true
         timeout: 120
         poll_interval: 2