diff --git a/changelogs/fragments/62929-module-return-value-elements.yml b/changelogs/fragments/62929-module-return-value-elements.yml new file mode 100644 index 00000000000..884a0f34d8c --- /dev/null +++ b/changelogs/fragments/62929-module-return-value-elements.yml @@ -0,0 +1,2 @@ +minor_changes: +- "ansible-test - module validation now allows ``elements:`` for return value documentation." diff --git a/docs/templates/plugin.rst.j2 b/docs/templates/plugin.rst.j2 index d8ea4800ed3..0d974f2ccab 100644 --- a/docs/templates/plugin.rst.j2 +++ b/docs/templates/plugin.rst.j2 @@ -288,7 +288,10 @@ Facts returned by this module are added/updated in the ``hostvars`` host facts a {% endfor %} @{ key }@ -
@{ value.type | documented_type }@
+
+ @{ value.type | documented_type }@ + {% if value.elements %} / elements=@{ value.elements | documented_type }@{% endif %} +
{% if value.version_added %}
added in @{value.version_added}@
{% endif %} @{ value.returned | html_ify }@ @@ -360,7 +363,10 @@ Common return values are documented :ref:`here `, the foll {% endfor %} @{ key }@ -
@{ value.type | documented_type }@
+
+ @{ value.type | documented_type }@ + {% if value.elements %} / elements=@{ value.elements | documented_type }@{% endif %} +
{% if value.version_added %}
added in @{value.version_added}@
{% endif %} @{ value.returned | html_ify }@ diff --git a/lib/ansible/modules/crypto/acme/acme_account_info.py b/lib/ansible/modules/crypto/acme/acme_account_info.py index 67a623d36f5..cb2c78ec8d8 100644 --- a/lib/ansible/modules/crypto/acme/acme_account_info.py +++ b/lib/ansible/modules/crypto/acme/acme_account_info.py @@ -91,12 +91,13 @@ account_uri: account: description: The account information, as retrieved from the ACME server. returned: if account exists - type: complex + type: dict contains: contact: description: the challenge resource that must be created for validation returned: always type: list + elements: str sample: "['mailto:me@example.com', 'tel:00123456789']" status: description: the account's status @@ -116,7 +117,7 @@ account: description: the public account key as a L(JSON Web Key,https://tools.ietf.org/html/rfc7517). returned: always type: str - sample: https://example.ca/account/1/orders + sample: '{"kty":"EC","crv":"P-256","x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4","y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM"}' orders: description: @@ -124,6 +125,7 @@ orders: - "If I(retrieve_orders) is C(url_list), this will be a list of URLs." - "If I(retrieve_orders) is C(object_list), this will be a list of objects." type: list + #elements: ... depends on retrieve_orders returned: if account exists, I(retrieve_orders) is not C(ignore), and server supports order listing contains: status: @@ -146,6 +148,7 @@ orders: description: - List of identifiers this order is for. type: list + elements: dict contains: type: description: Type of identifier. C(dns) or C(ip). @@ -176,12 +179,13 @@ orders: description: - In case an error occurred during processing, this contains information about the error. - The field is structured as a problem document (RFC7807). - type: complex + type: dict returned: when an error occurred authorizations: description: - A list of URLs for authorizations for this order. type: list + elements: str finalize: description: - A URL used for finalizing an ACME order. diff --git a/lib/ansible/modules/crypto/acme/acme_certificate.py b/lib/ansible/modules/crypto/acme/acme_certificate.py index 52546aadace..2f2da8bc02c 100644 --- a/lib/ansible/modules/crypto/acme/acme_certificate.py +++ b/lib/ansible/modules/crypto/acme/acme_certificate.py @@ -324,7 +324,8 @@ challenge_data: - Per identifier / challenge type challenge data. - Since Ansible 2.8.5, only challenges which are not yet valid are returned. returned: changed - type: complex + type: list + elements: dict contains: resource: description: The challenge resource that must be created for validation. @@ -366,14 +367,12 @@ challenge_data_dns: type: dict version_added: "2.5" authorizations: - description: ACME authorization data. + description: + - ACME authorization data. + - Maps an identifier to ACME authorization objects. See U(https://tools.ietf.org/html/rfc8555#section-7.1.4). returned: changed - type: complex - contains: - authorization: - description: ACME authorization object. See U(https://tools.ietf.org/html/rfc8555#section-7.1.4) - returned: success - type: dict + type: dict + sample: '{"example.com":{...}}' order_uri: description: ACME order URI. returned: changed @@ -397,6 +396,7 @@ all_chains: - See L(Section 7.4.2 of RFC8555,https://tools.ietf.org/html/rfc8555#section-7.4.2) for details. returned: when certificate was retrieved and I(retrieve_all_alternates) is set to C(yes) type: list + elements: dict contains: cert: description: diff --git a/lib/ansible/modules/crypto/certificate_complete_chain.py b/lib/ansible/modules/crypto/certificate_complete_chain.py index d418d342b34..77fbe2ee526 100644 --- a/lib/ansible/modules/crypto/certificate_complete_chain.py +++ b/lib/ansible/modules/crypto/certificate_complete_chain.py @@ -114,12 +114,14 @@ chain: - "Returned as a list of PEM certificates." returned: success type: list + elements: str complete_chain: description: - "The completed chain, including leaf, all intermediates, and root." - "Returned as a list of PEM certificates." returned: success type: list + elements: str ''' import os diff --git a/lib/ansible/modules/crypto/get_certificate.py b/lib/ansible/modules/crypto/get_certificate.py index 99883366a42..3aed838d681 100644 --- a/lib/ansible/modules/crypto/get_certificate.py +++ b/lib/ansible/modules/crypto/get_certificate.py @@ -86,6 +86,20 @@ extensions: description: Extensions applied to the cert returned: success type: list + elements: dict + contains: + critical: + returned: success + type: bool + description: Whether the extension is critical. + asn1_data: + returned: success + type: str + description: The Base64 encoded ASN.1 content of the extnesion. + name: + returned: success + type: str + description: The extension's name. issuer: description: Information about the issuer of the cert returned: success diff --git a/lib/ansible/modules/crypto/openssh_cert.py b/lib/ansible/modules/crypto/openssh_cert.py index 3bf22110769..44848449ec2 100644 --- a/lib/ansible/modules/crypto/openssh_cert.py +++ b/lib/ansible/modules/crypto/openssh_cert.py @@ -193,6 +193,7 @@ info: description: Information about the certificate. Output of C(ssh-keygen -L -f). returned: change or success type: list + elements: str ''' diff --git a/lib/ansible/modules/crypto/openssl_certificate_info.py b/lib/ansible/modules/crypto/openssl_certificate_info.py index 9ef343e2060..7fa82e354a9 100644 --- a/lib/ansible/modules/crypto/openssl_certificate_info.py +++ b/lib/ansible/modules/crypto/openssl_certificate_info.py @@ -116,6 +116,7 @@ basic_constraints: description: Entries in the C(basic_constraints) extension, or C(none) if extension is not present. returned: success type: list + elements: str sample: "[CA:TRUE, pathlen:1]" basic_constraints_critical: description: Whether the C(basic_constraints) extension is critical. @@ -125,6 +126,7 @@ extended_key_usage: description: Entries in the C(extended_key_usage) extension, or C(none) if extension is not present. returned: success type: list + elements: str sample: "[Biometric Info, DVCS, Time Stamping]" extended_key_usage_critical: description: Whether the C(extended_key_usage) extension is critical. @@ -133,7 +135,7 @@ extended_key_usage_critical: extensions_by_oid: description: Returns a dictionary for every extension OID returned: success - type: complex + type: dict contains: critical: description: Whether the extension is critical. @@ -158,6 +160,7 @@ subject_alt_name: description: Entries in the C(subject_alt_name) extension, or C(none) if extension is not present. returned: success type: list + elements: str sample: "[DNS:www.ansible.com, IP:1.2.3.4]" subject_alt_name_critical: description: Whether the C(subject_alt_name) extension is critical. @@ -182,6 +185,7 @@ issuer_ordered: description: The certificate's issuer as an ordered list of tuples. returned: success type: list + elements: list sample: '[["organizationName", "Ansible"], ["commonName": "ca.example.com"]]' version_added: "2.9" subject: @@ -195,6 +199,7 @@ subject_ordered: description: The certificate's subject as an ordered list of tuples. returned: success type: list + elements: list sample: '[["commonName", "www.example.com"], ["emailAddress": "test@example.com"]]' version_added: "2.9" not_after: @@ -265,6 +270,7 @@ authority_cert_issuer: - Is C(none) if the C(AuthorityKeyIdentifier) extension is not present. returned: success and if the pyOpenSSL backend is I(not) used type: list + elements: str sample: "[DNS:www.ansible.com, IP:1.2.3.4]" version_added: "2.9" authority_cert_serial_number: diff --git a/lib/ansible/modules/crypto/openssl_csr.py b/lib/ansible/modules/crypto/openssl_csr.py index a6266e68a25..84fbaa9cac2 100644 --- a/lib/ansible/modules/crypto/openssl_csr.py +++ b/lib/ansible/modules/crypto/openssl_csr.py @@ -365,26 +365,31 @@ subject: description: A list of the subject tuples attached to the CSR returned: changed or success type: list + elements: list sample: "[('CN', 'www.ansible.com'), ('O', 'Ansible')]" subjectAltName: description: The alternative names this CSR is valid for returned: changed or success type: list + elements: str sample: [ 'DNS:www.ansible.com', 'DNS:m.ansible.com' ] keyUsage: description: Purpose for which the public key may be used returned: changed or success type: list + elements: str sample: [ 'digitalSignature', 'keyAgreement' ] extendedKeyUsage: description: Additional restriction on the public key purposes returned: changed or success type: list + elements: str sample: [ 'clientAuth' ] basicConstraints: description: Indicates if the certificate belongs to a CA returned: changed or success type: list + elements: str sample: ['CA:TRUE', 'pathLenConstraint:0'] ocsp_must_staple: description: Indicates whether the certificate has the OCSP diff --git a/lib/ansible/modules/crypto/openssl_csr_info.py b/lib/ansible/modules/crypto/openssl_csr_info.py index 60ecc523950..cb80b55b017 100644 --- a/lib/ansible/modules/crypto/openssl_csr_info.py +++ b/lib/ansible/modules/crypto/openssl_csr_info.py @@ -82,6 +82,7 @@ basic_constraints: description: Entries in the C(basic_constraints) extension, or C(none) if extension is not present. returned: success type: list + elements: str sample: "[CA:TRUE, pathlen:1]" basic_constraints_critical: description: Whether the C(basic_constraints) extension is critical. @@ -91,6 +92,7 @@ extended_key_usage: description: Entries in the C(extended_key_usage) extension, or C(none) if extension is not present. returned: success type: list + elements: str sample: "[Biometric Info, DVCS, Time Stamping]" extended_key_usage_critical: description: Whether the C(extended_key_usage) extension is critical. @@ -99,7 +101,7 @@ extended_key_usage_critical: extensions_by_oid: description: Returns a dictionary for every extension OID returned: success - type: complex + type: dict contains: critical: description: Whether the extension is critical. @@ -124,6 +126,7 @@ subject_alt_name: description: Entries in the C(subject_alt_name) extension, or C(none) if extension is not present. returned: success type: list + elements: str sample: "[DNS:www.ansible.com, IP:1.2.3.4]" subject_alt_name_critical: description: Whether the C(subject_alt_name) extension is critical. @@ -148,6 +151,7 @@ subject_ordered: description: The CSR's subject as an ordered list of tuples. returned: success type: list + elements: list sample: '[["commonName", "www.example.com"], ["emailAddress": "test@example.com"]]' version_added: "2.9" public_key: @@ -187,6 +191,7 @@ authority_cert_issuer: - Is C(none) if the C(AuthorityKeyIdentifier) extension is not present. returned: success and if the pyOpenSSL backend is I(not) used type: list + elements: str sample: "[DNS:www.ansible.com, IP:1.2.3.4]" version_added: "2.9" authority_cert_serial_number: diff --git a/test/lib/ansible_test/_data/sanity/validate-modules/validate_modules/schema.py b/test/lib/ansible_test/_data/sanity/validate-modules/validate_modules/schema.py index 1b9848d8d15..d6b9c5c84fb 100644 --- a/test/lib/ansible_test/_data/sanity/validate-modules/validate_modules/schema.py +++ b/test/lib/ansible_test/_data/sanity/validate-modules/validate_modules/schema.py @@ -142,6 +142,8 @@ return_schema = Any( 'sample': Any(None, list, dict, int, float, *string_types), 'example': Any(None, list, dict, int, float, *string_types), 'contains': object, + # in case of type='list' elements define type of individual item in list + 'elements': Any(None, 'bits', 'bool', 'bytes', 'dict', 'float', 'int', 'json', 'jsonarg', 'list', 'path', 'raw', 'sid', 'str'), } } ),