Document and warn when max_fail and free are used (#72616)

Fixes #16666

changelogs/fragments/max_fail_free.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - Updated docs and added warning on max_fail_percentage and free strategy usage. fixes issue 16666.

lib/ansible/keyword_desc.yml

@@ -46,7 +46,7 @@ loop_control: |
 
     .. seealso:: :ref:`loop_control`
 
-max_fail_percentage: can be used to abort the run after a given percentage of hosts in the current batch has failed.
+max_fail_percentage: can be used to abort the run after a given percentage of hosts in the current batch has failed. This only wokrs on linear or linear derived strategies.
 module_defaults: Specifies default parameter values for modules.
 name: "Identifier. Can be used for documentation, or in tasks/handlers."
 no_log: Boolean that controls information disclosure.

lib/ansible/plugins/strategy/free.py

@@ -92,6 +92,9 @@ class StrategyModule(StrategyBase):
 
         self._set_hosts_cache(iterator._play)
 
+        if iterator._play.max_fail_percentage is not None:
+            display.warning("Using max_fail_percentage with the free strategy is not supported, as tasks are executed independently on each host")
+
         work_to_do = True
         while work_to_do and not self._tqm._terminated: