Variable Timout for Katello Module + Documentation (#41834)

* Changed Foreman timeout to be setable via a parameter
Added a Parameter to set the timout to wait for the started Foreman actions
by the user instead of using the hard coded 1000 Seconds

* katello module screamed for more docu :)

* fix docu + some ci findings
made docu better and moved chices in relations to other options to the description

* added a quote to description and removed wrong combination of param product

* Removed choices from params
also removed katello from a ignore file

lib/ansible/modules/remote_management/foreman/katello.py

@@ -40,11 +40,66 @@ options:
     entity:
         description:
             - The Foreman resource that the action will be performed on (e.g. organization, host).
+        choices:
+
+            - repository
+            - manifest
+            - repository_set
+            - sync_plan
+            - content_view
+            - lifecycle_environment
+            - activation_key
+
         required: true
+    action:
+        description:
+            - action associated to the entity resource to set or edit in dictionary format.
+            - Possible Action in relation to Entitys.
+            - "sync (available when entity=product or entity=repository)"
+            - "publish (available when entity=content_view)"
+            - "promote (available when entity=content_view)"
+        choices:
+            - sync
+            - publish
+            - promote
+        required: false
     params:
         description:
-            - Parameters associated to the entity resource to set or edit in dictionary format (e.g. name, description).
+            - Parameters associated to the entity resource and action, to set or edit in dictionary format.
+            - Each choice may be only available with specific entitys and actions.
+            - "Possible Choices are in the format of param_name ([entry,action,action,...],[entity,..],...)."
+            - The action "None" means no action specified.
+            - Possible Params in relation to entity and action.
+            - "name ([product,sync,None], [repository,sync], [repository_set,None], [sync_plan,None],"
+            - "[content_view,promote,publish,None], [lifecycle_environment,None], [activation_key,None])"
+            - "organization ([product,sync,None] ,[repository,sync,None], [repository_set,None], [sync_plan,None], "
+            - "[content_view,promote,publish,None], [lifecycle_environment,None], [activation_key,None])"
+            - "content ([manifest,None])"
+            - "product ([repository,sync,None], [repository_set,None], [sync_plan,None])"
+            - "basearch ([repository_set,None])"
+            - "releaserver ([repository_set,None])"
+            - "sync_date ([sync_plan,None])"
+            - "interval ([sync_plan,None])"
+            - "repositories ([content_view,None])"
+            - "from_environment ([content_view,promote])"
+            - "to_environment([content_view,promote])"
+            - "prior ([lifecycle_environment,None])"
+            - "content_view ([activation_key,None])"
+            - "lifecycle_environment ([activation_key,None])"
         required: true
+    task_timeout:
+        description:
+            - The timeout in seconds to wait for the started Foreman action to finish.
+            - If the timeout is reached and the Foreman action did not complete, the ansible task fails. However the foreman action does not get canceled.
+        default: 1000
+        version_added: "2.7"
+        required: false
+    verify_ssl:
+        description:
+            - verify the ssl/https connection (e.g for a valid certificate)
+        default: false
+        type: bool
+        required: false
 '''
 
 EXAMPLES = '''
@@ -124,6 +179,43 @@ EXAMPLES = '''
         organization: Default Organization
         basearch: x86_64
         releasever: 7
+
+- include: katello.yml
+  vars:
+      name: Promote Contentview Environment with longer timout
+      task_timeout: 10800
+      entity: content_view
+      action: promote
+      params:
+        name: MyContentView
+        organization: MyOrganisation
+        from_environment: Testing
+        to_environment: Production
+
+# Best Practices
+
+# In Foreman, things can be done in paralell.
+# When a conflicting action is already running,
+# the task will fail instantly instead of waiting for the already running action to complete.
+# So you sould use a "until success" loop to catch this.
+
+- name: Promote Contentview Environment with increased Timeout
+  katello:
+  username: ansibleuser
+  password: supersecret
+  task_timeout: 10800
+  entity: content_view
+  action: promote
+  params:
+    name: MyContentView
+    organization: MyOrganisation
+    from_environment: Testing
+    to_environment: Production
+  register: task_result
+  until: task_result is success
+  retries: 9
+  delay: 120
+
 '''
 
 RETURN = '''# '''
@@ -144,11 +236,11 @@ from ansible.module_utils._text import to_native
 
 
 class NailGun(object):
-    def __init__(self, server, entities, module):
+    def __init__(self, server, entities, module, task_timeout):
         self._server = server
         self._entities = entities
         self._module = module
-        entity_mixins.TASK_TIMEOUT = 1000
+        entity_mixins.TASK_TIMEOUT = task_timeout
 
     def find_organization(self, name, **params):
         org = self._entities.Organization(self._server, name=name, **params)
@@ -448,9 +540,11 @@ def main():
             server_url=dict(type='str', required=True),
             username=dict(type='str', required=True, no_log=True),
             password=dict(type='str', required=True, no_log=True),
-            entity=dict(type='str', required=True),
-            action=dict(type='str'),
+            entity=dict(type='str', required=True,
+                        choices=['repository', 'manifest', 'repository_set', 'sync_plan', 'content_view', 'lifecycle_environment', 'activation_key']),
+            action=dict(type='str', choices=['sync', 'publish', 'promote']),
             verify_ssl=dict(type='bool', default=False),
+            task_timeout=dict(type='int', default=1000),
             params=dict(type='dict', required=True, no_log=True),
         ),
         supports_check_mode=True,
@@ -466,13 +560,14 @@ def main():
     action = module.params['action']
     params = module.params['params']
     verify_ssl = module.params['verify_ssl']
+    task_timeout = module.params['task_timeout']
 
     server = ServerConfig(
         url=server_url,
         auth=(username, password),
         verify=verify_ssl
     )
-    ng = NailGun(server, entities, module)
+    ng = NailGun(server, entities, module, task_timeout)
 
     # Lets make an connection to the server with username and password
     try:

test/sanity/validate-modules/ignore.txt

@@ -1041,8 +1041,6 @@ lib/ansible/modules/packaging/os/yum_repository.py E324
 lib/ansible/modules/packaging/os/zypper.py E326
 lib/ansible/modules/remote_management/foreman/foreman.py E322
 lib/ansible/modules/remote_management/foreman/foreman.py E325
-lib/ansible/modules/remote_management/foreman/katello.py E322
-lib/ansible/modules/remote_management/foreman/katello.py E325
 lib/ansible/modules/remote_management/hpilo/hpilo_boot.py E324
 lib/ansible/modules/remote_management/hpilo/hpilo_boot.py E326
 lib/ansible/modules/remote_management/ipmi/ipmi_boot.py E326