extend open_iscsi to allow rescanning a session to discover new mapped LUN's #3763 (#3765)

* <!--- Describe the change below, including rationale and design decisions -->

<!--- HINT: Include "Fixes #nnn" if you are fixing an existing issue -->

According to issue 3767, adding a session rescan flag to add and utilize mapped_luns after login into a portal and target.

<!--- Pick one below and delete the rest -->
- Feature Pull Request

<!--- Write the short name of the module, plugin, task or feature below -->
open_iscsi rescan flag

<!--- Include additional information to help people understand the change here -->
<!--- A step-by-step reproduction of the problem is helpful if there is no related issue -->

<!--- Paste verbatim command output below, e.g. before and after your change -->
``` yaml
      - name: Rescan Targets
        open_iscsi:
          rescan: true
          target: "{{ item.0 }}"
        register: iscsi_rescan
        loop:
          - iqn.1994-05.com.redhat:8c4ea31d28e
        tags:
          - rescan
```
```bash
    TASK [Rescan Targets] ********************************************************************************************************************************************************************
    changed: [node1] => (item=['iqn.1994-05.com.redhat:8c4ea31d28e'])
    changed: [node2] => (item=['iqn.1994-05.com.redhat:8c4ea31d28e'])

    TASK [Output rescan output] **************************************************************************************************************************************************************
    ok: [node1] => {
        "iscsi_rescan": {
            "changed": true,
            "msg": "All items completed",
            "results": [
                {
                    "ansible_loop_var": "item",
                    "changed": true,
                    "failed": false,
                    "invocation": {
                        "module_args": {
                            "auto_node_startup": null,
                            "discover": false,
                            "login": null,
                            "node_auth": "CHAP",
                            "node_pass": null,
                            "node_user": null,
                            "port": "3260",
                            "portal": null,
                            "rescan": true,
                            "show_nodes": false,
                            "target": "iqn.1994-05.com.redhat:8c4ea31d28e'"
                        }
                    },
                    "item": [
                        "iqn.1994-05.com.redhat:8c4ea31d28e"
                    ],
                    "sessions": [
                        "Rescanning session [sid: 3, target: iqn.1994-05.com.redhat:8c4ea31d28e, portal: 127.0.0.1,3260]",
                        "Rescanning session [sid: 1, target: iqn.1994-05.com.redhat:8c4ea31d28e, portal: 127.0.0.2,3260]",
                        "Rescanning session [sid: 2, target: iqn.1994-05.com.redhat:8c4ea31d28e, portal: 127.0.0.3,3260]",
                        ""
                    ]
                }
            ]
        }
    }
    ok: [node2] => {
        "iscsi_rescan": {
            "changed": true,
            "msg": "All items completed",
            "results": [
                {
                    "ansible_loop_var": "item",
                    "changed": true,
                    "failed": false,
                    "invocation": {
                        "module_args": {
                            "auto_node_startup": null,
                            "discover": false,
                            "login": null,
                            "node_auth": "CHAP",
                            "node_pass": null,
                            "node_user": null,
                            "port": "3260",
                            "portal": null,
                            "rescan": true,
                            "show_nodes": false,
                            "target": "iqn.1994-05.com.redhat:8c4ea31d28e"
                        }
                    },
                    "item": [
                        "iqn.1994-05.com.redhat:8c4ea31d28e"
                    ],
                    "sessions": [
                        "Rescanning session [sid: 3, target: iqn.1994-05.com.redhat:8c4ea31d28e, portal: 127.0.0.1,3260]",
                        "Rescanning session [sid: 2, target: iqn.1994-05.com.redhat:8c4ea31d28e, portal: 127.0.0.2,3260]",
                        "Rescanning session [sid: 1, target: iqn.1994-05.com.redhat:8c4ea31d28e, portal: 127.0.0.3,3260]",
                        ""
                    ]
                }
            ]
        }
    }
```

* minor_changes:
  - open_iscsi - extended module to allow rescanning of established session for one or all targets. (https://github.com/ansible-collections/community.general/issues/3763)

* * fixed commend according to the recommendation.

* Update plugins/modules/system/open_iscsi.py

Co-authored-by: Felix Fontein <felix@fontein.de>

changelogs/fragments/3765-extend-open_iscsi-with-rescan.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - open_iscsi - extended module to allow rescanning of established session for one or all targets (https://github.com/ansible-collections/community.general/issues/3763).

plugins/modules/system/open_iscsi.py

@@ -86,6 +86,14 @@ options:
         - Whether the list of nodes in the persistent iSCSI database should be returned by the module.
         type: bool
         default: false
+    rescan:
+        description:
+        - Rescan an established session for discovering new targets.
+        - When I(target) is omitted, will rescan all sessions.
+        type: bool
+        default: false
+        version_added: 4.1.0
+
 '''
 
 EXAMPLES = r'''
@@ -124,6 +132,11 @@ EXAMPLES = r'''
     portal: 10.1.1.250
     auto_portal_startup: false
     target: iqn.1986-03.com.sun:02:f8c1f9e0-c3ec-ec84-c9c9-8bfb0cd5de3d
+
+- name: Rescan one or all established sessions to discover new targets (omit target for all sessions)
+  community.general.open_iscsi:
+    rescan: true
+    target: iqn.1986-03.com.sun:02:f8c1f9e0-c3ec-ec84-c9c9-8bfb0cd5de3d
 '''
 
 import glob
@@ -179,6 +192,15 @@ def iscsi_discover(module, portal, port):
     module.run_command(cmd, check_rc=True)
 
 
+def iscsi_rescan(module, target=None):
+    if target is None:
+        cmd = [iscsiadm_cmd, '--mode', 'session', '--rescan']
+    else:
+        cmd = [iscsiadm_cmd, '--mode', 'node', '--rescan', '-T', target]
+    rc, out, err = module.run_command(cmd)
+    return out
+
+
 def target_loggedon(module, target, portal=None, port=None):
     cmd = [iscsiadm_cmd, '--mode', 'session']
     rc, out, err = module.run_command(cmd)
@@ -305,6 +327,7 @@ def main():
             auto_portal_startup=dict(type='bool'),
             discover=dict(type='bool', default=False),
             show_nodes=dict(type='bool', default=False),
+            rescan=dict(type='bool', default=False),
         ),
 
         required_together=[['node_user', 'node_pass'], ['node_user_in', 'node_pass_in']],
@@ -330,6 +353,7 @@ def main():
     automatic_portal = module.params['auto_portal_startup']
     discover = module.params['discover']
     show_nodes = module.params['show_nodes']
+    rescan = module.params['rescan']
 
     check = module.check_mode
 
@@ -421,6 +445,10 @@ def main():
             result['changed'] |= True
             result['automatic_portal_changed'] = True
 
+    if rescan is not False:
+        result['changed'] = True
+        result['sessions'] = iscsi_rescan(module, target)
+
     module.exit_json(**result)