[Bug][zos_apf] Ensure idempotency in zos_apf when a library is added or removed

changelogs/fragments/1893-zos_apf-fails-for-already-existing-file.yml

@@ -0,0 +1,4 @@
+bugfixes:
+  - zos_apf - When trying to add a library into the APF list that was already added, the module would fail.
+    Fix now will not fail the module, and will inform the user that the library is already on the APF list.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/1893)

plugins/module_utils/zoau_version_checker.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright (c) IBM Corporation 2022, 2024
+# Copyright (c) IBM Corporation 2022, 2025
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at

plugins/modules/zos_apf.py

@@ -1,7 +1,7 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# Copyright (c) IBM Corporation 2020, 2024
+# Copyright (c) IBM Corporation 2020, 2025
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -298,7 +298,8 @@
 from ansible.module_utils._text import to_text
 from ansible.module_utils.basic import AnsibleModule
 from ansible_collections.ibm.ibm_zos_core.plugins.module_utils import (
-    better_arg_parser, data_set, backup as Backup)
+    better_arg_parser, zoau_version_checker, data_set, backup as Backup)
+
 from ansible_collections.ibm.ibm_zos_core.plugins.module_utils.import_handler import (
     ZOAUImportError,
 )
@@ -400,7 +401,14 @@ def make_apf_command(library, opt, volume=None, sms=None, force_dynamic=None, pe
     str
         APF command.
     """
-    operation = "-A" if opt == "add" else "-D"
+    # -i is  available in ZOAU version 1.3.4
+    # before that all versions will not be able to use -i
+    if zoau_version_checker.is_zoau_version_higher_than("1.3.4"):
+        operation = "-i -A" if opt == "add" else "-i -D"
+
+    else:
+        operation = "-A" if opt == "add" else "-D"
+
     operation_args = library
 
     if volume:
@@ -448,7 +456,12 @@ def make_apf_batch_command(batch, force_dynamic=None, persistent=None):
     command = "apfadm"
 
     for item in batch:
-        operation = "-A" if item["opt"] == "add" else "-D"
+        if zoau_version_checker.is_zoau_version_higher_than("1.3.4"):
+            operation = "-i -A" if item["opt"] == "add" else "-i -D"
+
+        else:
+            operation = "-A" if item["opt"] == "add" else "-D"
+
         operation_args = item["dsname"]
 
         volume = item.get("volume")
@@ -692,7 +705,10 @@ def main():
     result['stdout'] = operOut
 
     if operation != 'list' and operRc == 0:
-        result['changed'] = True
+        if operErr.strip():
+            result['changed'] = False
+        else:
+            result['changed'] = True
 
     if operation == 'list':
         try:

plugins/modules/zos_gather_facts.py

@@ -1,7 +1,7 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# Copyright (c) IBM Corporation 2022, 2024
+# Copyright (c) IBM Corporation 2022, 2025
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at

tests/functional/modules/test_zos_apf_func.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 
-# Copyright (c) IBM Corporation 2020, 2024
+# Copyright (c) IBM Corporation 2020, 2025
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -12,6 +12,7 @@
 # limitations under the License.
 
 from __future__ import absolute_import, division, print_function
+import re
 import pytest
 from ibm_zos_core.tests.helpers.dataset import get_tmp_ds_name
 from ibm_zos_core.tests.helpers.volumes import Volume_Handler
@@ -404,7 +405,17 @@ def test_operation_list_with_filter(ansible_zos_module, volumes_with_vvds):
 #
 # Negative tests
 #
-
+def get_zoa_version(ansible_zos_module):
+    cmd_str = "zoaversion"
+    version_results = ansible_zos_module.all.shell(cmd=cmd_str)
+    zoa_version = None        
+    for result in version_results.contacted.values():
+        output = result.get("stdout")
+        if output:
+            match = re.search(r'v(\d+\.\d+\.\d+\.\d+)', output)
+            if match:
+                zoa_version = match.group(1)
+    return zoa_version
 
 def test_add_already_present(ansible_zos_module, volumes_with_vvds):
     try:
@@ -438,10 +449,20 @@ def test_add_already_present(ansible_zos_module, volumes_with_vvds):
         results = hosts.all.zos_apf(**test_info)
         for result in results.contacted.values():
             assert result.get("rc") == 0
+        # Second call to zos_apf, same as first but with different expectations
         results = hosts.all.zos_apf(**test_info)
         for result in results.contacted.values():
+            # RC 0 should be allowed for ZOAU >= 1.3.4, 
+            # in zoau < 1.3.4 -i is not recognized  in apfadm 
             # Return code 16 if ZOAU < 1.2.0 and RC is 8 if ZOAU >= 1.2.0
-            assert result.get("rc") == 16 or result.get("rc") == 8
+            zoa_version = get_zoa_version(hosts) or "0.0.0.0" 
+            rc = result.get("rc")            
+            if zoa_version >= "1.3.4.0":
+                assert rc == 0
+            elif zoa_version >= "1.2.0.0":
+                assert rc == 8
+            else:
+                assert rc == 16 
         test_info['state'] = 'absent'
         hosts.all.zos_apf(**test_info)
     finally:
@@ -479,8 +500,17 @@ def test_del_not_present(ansible_zos_module, volumes_with_vvds):
         test_info['state'] = 'absent'
         results = hosts.all.zos_apf(**test_info)
         for result in results.contacted.values():
+            # RC 0 should be allowed for ZOAU >= 1.3.4, 
+            # in zoau < 1.3.4 -i is not recognized  in apfadm 
             # Return code 16 if ZOAU < 1.2.0 and RC is 8 if ZOAU >= 1.2.0
-            assert result.get("rc") == 16 or result.get("rc") == 8
+            zoa_version = get_zoa_version(hosts) or "0.0.0.0" 
+            rc = result.get("rc")            
+            if zoa_version >= "1.3.4.0":
+                assert rc == 0
+            elif zoa_version >= "1.2.0.0":
+                assert rc == 8
+            else:
+                assert rc == 16
     finally:
         clean_test_env(hosts, test_info)