Merge branch 'ansible-collections:main' into ipa-pwpolicy-passwordgra…

…celimit

.github/workflows/codeql-analysis.yml

@@ -28,9 +28,9 @@ jobs:
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v2
+      uses: github/codeql-action/init@v3
       with:
         languages: python
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v2
+      uses: github/codeql-action/analyze@v3

changelogs/fragments/7578-irc-tls.yml

@@ -0,0 +1,4 @@
+deprecated_features:
+  - "irc - the defaults ``false`` for ``use_tls`` and ``validate_certs`` have been deprecated and will change to ``true`` in community.general 10.0.0
+     to improve security. You can already improve security now by explicitly setting them to ``true``. Specifying values now disables the deprecation
+     warning (https://github.com/ansible-collections/community.general/pull/7578)."

changelogs/fragments/7696-avoid-attempt-to-delete-non-existing-user.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - keycloak_user - when ``force`` is set, but user does not exist, do not try to delete it (https://github.com/ansible-collections/community.general/pull/7696).

changelogs/fragments/7703-ssh_config_add_keys_to_agent_option.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - ssh_config - new feature to set ``AddKeysToAgent`` option to ``yes`` or ``no`` (https://github.com/ansible-collections/community.general/pull/7703).

changelogs/fragments/7704-ssh_config_identities_only_option.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - ssh_config - new feature to set ``IdentitiesOnly`` option to ``yes`` or ``no`` (https://github.com/ansible-collections/community.general/pull/7704).

plugins/doc_fragments/onepassword.py

@@ -58,7 +58,11 @@ class ModuleDocFragment(object):
 '''
 
     LOOKUP = r'''
-options: {}
+options:
+  service_account_token:
+    env:
+      - name: OP_SERVICE_ACCOUNT_TOKEN
+        version_added: 8.2.0
 notes:
   - This lookup will use an existing 1Password session if one exists. If not, and you have already
     performed an initial sign in (meaning C(~/.op/config), C(~/.config/op/config) or C(~/.config/.op/config) exists), then only the

plugins/lookup/bitwarden.py

@@ -25,7 +25,10 @@
         type: list
         elements: str
       search:
-        description: Field to retrieve, for example V(name) or V(id).
+        description:
+          - Field to retrieve, for example V(name) or V(id).
+          - If set to V(id), only zero or one element can be returned.
+            Use the Jinja C(first) filter to get the only list element.
         type: str
         default: name
         version_added: 5.7.0
@@ -39,37 +42,40 @@
 """
 
 EXAMPLES = """
-- name: "Get 'password' from Bitwarden record named 'a_test'"
+- name: "Get 'password' from all Bitwarden records named 'a_test'"
   ansible.builtin.debug:
     msg: >-
       {{ lookup('community.general.bitwarden', 'a_test', field='password') }}
 
-- name: "Get 'password' from Bitwarden record with id 'bafba515-af11-47e6-abe3-af1200cd18b2'"
+- name: "Get 'password' from Bitwarden record with ID 'bafba515-af11-47e6-abe3-af1200cd18b2'"
   ansible.builtin.debug:
     msg: >-
-      {{ lookup('community.general.bitwarden', 'bafba515-af11-47e6-abe3-af1200cd18b2', search='id', field='password') }}
+      {{ lookup('community.general.bitwarden', 'bafba515-af11-47e6-abe3-af1200cd18b2', search='id', field='password') | first }}
 
-- name: "Get 'password' from Bitwarden record named 'a_test' from collection"
+- name: "Get 'password' from all Bitwarden records named 'a_test' from collection"
   ansible.builtin.debug:
     msg: >-
       {{ lookup('community.general.bitwarden', 'a_test', field='password', collection_id='bafba515-af11-47e6-abe3-af1200cd18b2') }}
 
-- name: "Get full Bitwarden record named 'a_test'"
+- name: "Get list of all full Bitwarden records named 'a_test'"
   ansible.builtin.debug:
     msg: >-
       {{ lookup('community.general.bitwarden', 'a_test') }}
 
-- name: "Get custom field 'api_key' from Bitwarden record named 'a_test'"
+- name: "Get custom field 'api_key' from all Bitwarden records named 'a_test'"
   ansible.builtin.debug:
     msg: >-
       {{ lookup('community.general.bitwarden', 'a_test', field='api_key') }}
 """
 
 RETURN = """
   _raw:
-    description: List of requested field or JSON object of list of matches.
+    description:
+      - A one-element list that contains a list of requested fields or JSON objects of matches.
+      - If you use C(query), you get a list of lists. If you use C(lookup) without C(wantlist=true),
+        this always gets reduced to a list of field values or JSON objects.
     type: list
-    elements: raw
+    elements: list
 """
 
 from subprocess import Popen, PIPE

plugins/modules/consul.py

@@ -122,6 +122,16 @@
         description:
           - Name for the service check. Required if standalone, ignored if
             part of service definition.
+    check_node:
+        description:
+          - Node name.
+          # TODO: properly document!
+        type: str
+    check_host:
+        description:
+          - Host name.
+          # TODO: properly document!
+        type: str
     ttl:
         type: str
         description:

plugins/modules/irc.py

@@ -85,8 +85,10 @@
         was exlusively called O(use_ssl). The latter is now an alias of O(use_tls).
       - B(Note:) for security reasons, you should always set O(use_tls=true) and
         O(validate_certs=true) whenever possible.
+      - The option currently defaults to V(false). The default has been B(deprecated) and will
+        change to V(true) in community.general 10.0.0. To avoid deprecation warnings, explicitly
+        set this option to a value (preferably V(true)).
     type: bool
-    default: false
     aliases:
       - use_ssl
   part:
@@ -108,7 +110,9 @@
         if the network between between Ansible and the IRC server is known to be safe.
       - B(Note:) for security reasons, you should always set O(use_tls=true) and
         O(validate_certs=true) whenever possible.
-    default: false
+      - The option currently defaults to V(false). The default has been B(deprecated) and will
+        change to V(true) in community.general 10.0.0. To avoid deprecation warnings, explicitly
+        set this option to a value (preferably V(true)).
     type: bool
     version_added: 8.1.0
 
@@ -309,8 +313,8 @@ def main():
             passwd=dict(no_log=True),
             timeout=dict(type='int', default=30),
             part=dict(type='bool', default=True),
-            use_tls=dict(type='bool', default=False, aliases=['use_ssl']),
-            validate_certs=dict(type='bool', default=False),
+            use_tls=dict(type='bool', aliases=['use_ssl']),
+            validate_certs=dict(type='bool'),
         ),
         supports_check_mode=True,
         required_one_of=[['channel', 'nick_to']]
@@ -334,6 +338,25 @@ def main():
     style = module.params["style"]
     validate_certs = module.params["validate_certs"]
 
+    if use_tls is None:
+        module.deprecate(
+            'The default of use_tls will change to true in community.general 10.0.0.'
+            ' Set a value now (preferably true, if possible) to avoid the deprecation warning.',
+            version='10.0.0',
+            collection_name='community.general',
+        )
+        use_tls = False
+
+    if validate_certs is None:
+        if use_tls:
+            module.deprecate(
+                'The default of validate_certs will change to true in community.general 10.0.0.'
+                ' Set a value now (prefarably true, if possible) to avoid the deprecation warning.',
+                version='10.0.0',
+                collection_name='community.general',
+            )
+        validate_certs = False
+
     try:
         send_msg(msg, server, port, channel, nick_to, key, topic, nick, color, passwd, timeout, use_tls, validate_certs, part, style)
     except Exception as e:

plugins/modules/keycloak_user.py

@@ -481,7 +481,7 @@ def main():
 
     else:
         after_user = {}
-        if force:  # If the force option is set to true
+        if force and before_user:  # If the force option is set to true
             # Delete the existing user
             kc.delete_user(user_id=before_user["id"], realm=realm)
 

plugins/modules/mail.py

@@ -205,10 +205,11 @@
     body: System {{ ansible_hostname }} has been successfully provisioned.
     secure: starttls
 
-- name: Sending an e-mail using StartTLS, remote server, custom EHLO
+- name: Sending an e-mail using StartTLS, remote server, custom EHLO, and timeout of 10 seconds
   community.general.mail:
     host: some.smtp.host.tld
     port: 25
+    timeout: 10
     ehlohost: my-resolvable-hostname.tld
     to: John Smith <[email protected]>
     subject: Ansible-report

plugins/modules/manageiq_provider.py

@@ -75,6 +75,7 @@
 
   provider:
     description: Default endpoint connection information, required if state is true.
+    type: dict
     suboptions:
       hostname:
         type: str
@@ -104,9 +105,30 @@
       certificate_authority:
         type: str
         description: The CA bundle string with custom certificates. defaults to None.
+      path:
+        type: str
+        description:
+          - TODO needs documentation.
+      project:
+        type: str
+        description:
+          - TODO needs documentation.
+      role:
+        type: str
+        description:
+          - TODO needs documentation.
+      subscription:
+        type: str
+        description:
+          - TODO needs documentation.
+      uid_ems:
+        type: str
+        description:
+          - TODO needs documentation.
 
   metrics:
     description: Metrics endpoint connection information.
+    type: dict
     suboptions:
       hostname:
         type: str
@@ -139,9 +161,26 @@
       path:
         type: str
         description: Database name for oVirt metrics. Defaults to V(ovirt_engine_history).
+      project:
+        type: str
+        description:
+          - TODO needs documentation.
+      role:
+        type: str
+        description:
+          - TODO needs documentation.
+      subscription:
+        type: str
+        description:
+          - TODO needs documentation.
+      uid_ems:
+        type: str
+        description:
+          - TODO needs documentation.
 
   alerts:
     description: Alerts endpoint connection information.
+    type: dict
     suboptions:
       hostname:
         type: str
@@ -171,9 +210,30 @@
       certificate_authority:
         type: str
         description: The CA bundle string with custom certificates. defaults to None.
+      path:
+        type: str
+        description:
+          - TODO needs documentation.
+      project:
+        type: str
+        description:
+          - TODO needs documentation.
+      role:
+        type: str
+        description:
+          - TODO needs documentation.
+      subscription:
+        type: str
+        description:
+          - TODO needs documentation.
+      uid_ems:
+        type: str
+        description:
+          - TODO needs documentation.
 
   ssh_keypair:
     description: SSH key pair used for SSH connections to all hosts in this provider.
+    type: dict
     suboptions:
       hostname:
         type: str
@@ -191,6 +251,43 @@
         type: bool
         default: true
         aliases: [ verify_ssl ]
+      security_protocol:
+        type: str
+        choices: ['ssl-with-validation','ssl-with-validation-custom-ca','ssl-without-validation', 'non-ssl']
+        description:
+          - TODO needs documentation.
+      certificate_authority:
+        type: str
+        description:
+          - TODO needs documentation.
+      password:
+        type: str
+        description:
+          - TODO needs documentation.
+      path:
+        type: str
+        description:
+          - TODO needs documentation.
+      project:
+        type: str
+        description:
+          - TODO needs documentation.
+      role:
+        type: str
+        description:
+          - TODO needs documentation.
+      subscription:
+        type: str
+        description:
+          - TODO needs documentation.
+      uid_ems:
+        type: str
+        description:
+          - TODO needs documentation.
+      port:
+        type: int
+        description:
+          - TODO needs documentation.
 '''
 
 EXAMPLES = '''

plugins/modules/proxmox.py

@@ -48,6 +48,7 @@
         [,replicate=<1|0>] [,ro=<1|0>] [,shared=<1|0>] [,size=<DiskSize>])."
       - See U(https://pve.proxmox.com/wiki/Linux_Container) for a full description.
       - This option has no default unless O(proxmox_default_behavior) is set to V(compatibility); then the default is V(3).
+      - Should not be used in conjunction with O(storage).
     type: str
   cores:
     description:
@@ -96,6 +97,7 @@
   storage:
     description:
       - target storage
+      - Should not be used in conjunction with O(disk).
     type: str
     default: 'local'
   ostype:
@@ -248,6 +250,18 @@
     hostname: example.org
     ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'
 
+- name: Create new container with minimal options specifying disk storage location and size
+  community.general.proxmox:
+    vmid: 100
+    node: uk-mc02
+    api_user: root@pam
+    api_password: 1q2w3e
+    api_host: node1
+    password: 123456
+    hostname: example.org
+    ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'
+    disk: 'local-lvm:20'
+
 - name: Create new container with hookscript and description
   community.general.proxmox:
     vmid: 100