Improve examples: use FQCNs and always add name: to tasks (#604)

* Improve examples: use FQCNs and always add name: to tasks.

* Improve formulation.

Co-authored-by: Don Naro <dnaro@redhat.com>

* Accidentally added a period.

---------

Co-authored-by: Don Naro <dnaro@redhat.com>

plugins/modules/acme_account_info.py

@@ -58,7 +58,7 @@ EXAMPLES = '''
     account_key_src: /etc/pki/cert/private/account.key
   register: account_data
 - name: Verify that account exists
-  assert:
+  ansible.builtin.assert:
     that:
       - account_data.exists
 - name: Print account URI
@@ -74,7 +74,7 @@ EXAMPLES = '''
     account_uri: "{{ acme_account_uri }}"
   register: account_data
 - name: Verify that account exists
-  assert:
+  ansible.builtin.assert:
     that:
       - account_data.exists
 - name: Print account contacts

plugins/modules/acme_certificate.py

@@ -315,14 +315,16 @@ EXAMPLES = r'''
 # perform the necessary steps to fulfill the challenge
 # for example:
 #
-# - copy:
+# - name: Copy http-01 challenge for sample.com
+#   ansible.builtin.copy:
 #     dest: /var/www/html/{{ sample_com_challenge['challenge_data']['sample.com']['http-01']['resource'] }}
 #     content: "{{ sample_com_challenge['challenge_data']['sample.com']['http-01']['resource_value'] }}"
 #   when: sample_com_challenge is changed and 'sample.com' in sample_com_challenge['challenge_data']
 #
 # Alternative way:
 #
-# - copy:
+# - name: Copy http-01 challenges
+#   ansible.builtin.copy:
 #     dest: /var/www/{{ item.key }}/{{ item.value['http-01']['resource'] }}
 #     content: "{{ item.value['http-01']['resource_value'] }}"
 #   loop: "{{ sample_com_challenge.challenge_data | dict2items }}"
@@ -354,7 +356,8 @@ EXAMPLES = r'''
 # perform the necessary steps to fulfill the challenge
 # for example:
 #
-# - community.aws.route53:
+# - name: Create DNS record for sample.com dns-01 challenge
+#   community.aws.route53:
 #     zone: sample.com
 #     record: "{{ sample_com_challenge.challenge_data['sample.com']['dns-01'].record }}"
 #     type: TXT
@@ -367,7 +370,8 @@ EXAMPLES = r'''
 #
 # Alternative way:
 #
-# - community.aws.route53:
+# - name: Create DNS records for dns-01 challenges
+#   community.aws.route53:
 #     zone: sample.com
 #     record: "{{ item.key }}"
 #     type: TXT

plugins/modules/certificate_complete_chain.py

@@ -83,7 +83,7 @@ EXAMPLES = '''
     - /etc/ca-certificates/
   register: www_ansible_com
 - name: Write root certificate to disk
-  copy:
+  ansible.builtin.copy:
     dest: /etc/ssl/csr/www.ansible.com-root.pem
     content: "{{ www_ansible_com.root }}"
 
@@ -98,11 +98,11 @@ EXAMPLES = '''
     - /etc/ca-certificates/
   register: www_ansible_com
 - name: Write complete chain to disk
-  copy:
+  ansible.builtin.copy:
     dest: /etc/ssl/csr/www.ansible.com-completechain.pem
     content: "{{ ''.join(www_ansible_com.complete_chain) }}"
 - name: Write root chain (intermediates and root) to disk
-  copy:
+  ansible.builtin.copy:
     dest: /etc/ssl/csr/www.ansible.com-rootchain.pem
     content: "{{ ''.join(www_ansible_com.chain) }}"
 '''

plugins/modules/get_certificate.py

@@ -195,7 +195,7 @@ EXAMPLES = '''
   register: cert
 
 - name: How many days until cert expires
-  debug:
+  ansible.builtin.debug:
     msg: "cert expires in: {{ expire_days }} days."
   vars:
     expire_days: "{{ (( cert.not_after | to_datetime('%Y%m%d%H%M%SZ')) - (ansible_date_time.iso8601 | to_datetime('%Y-%m-%dT%H:%M:%SZ')) ).days }}"

plugins/modules/openssl_csr_info.py

@@ -71,7 +71,7 @@ EXAMPLES = r'''
   register: result
 
 - name: Dump information
-  debug:
+  ansible.builtin.debug:
     var: result
 '''
 

plugins/modules/openssl_csr_pipe.py

@@ -44,7 +44,8 @@ EXAMPLES = r'''
     privatekey_path: /etc/ssl/private/ansible.com.pem
     common_name: www.ansible.com
   register: result
-- debug:
+- name: Print CSR
+  ansible.builtin.debug:
     var: result.csr
 
 - name: Generate an OpenSSL Certificate Signing Request with an inline CSR

plugins/modules/openssl_privatekey_pipe.py

@@ -69,11 +69,13 @@ EXAMPLES = r'''
   register: output
   no_log: true  # make sure that private key data is not accidentally revealed in logs!
 - name: Show generated key
-  debug:
+  ansible.builtin.debug:
     msg: "{{ output.privatekey }}"
   # DO NOT OUTPUT KEY MATERIAL TO CONSOLE OR LOGS IN PRODUCTION!
 
-- block:
+
+- name: Generate or update a Mozilla sops encrypted key
+  block:
     - name: Update sops-encrypted key with the community.sops collection
       community.crypto.openssl_privatekey_pipe:
         content: "{{ lookup('community.sops.sops', 'private_key.pem.sops') }}"
@@ -88,7 +90,7 @@ EXAMPLES = r'''
       when: output is changed
   always:
     - name: Make sure that output (which contains the private key) is overwritten
-      set_fact:
+      ansible.builtin.set_fact:
         output: ''
 '''
 

plugins/modules/openssl_signature.py

@@ -87,7 +87,7 @@ EXAMPLES = r'''
   register: verify
 
 - name: Make sure the signature is valid
-  assert:
+  ansible.builtin.assert:
     that:
       - verify.valid
 '''

plugins/modules/openssl_signature_info.py

@@ -80,7 +80,7 @@ EXAMPLES = r'''
   register: verify
 
 - name: Make sure the signature is valid
-  assert:
+  ansible.builtin.assert:
     that:
       - verify.valid
 '''

plugins/modules/x509_certificate.py

@@ -175,7 +175,8 @@ EXAMPLES = r'''
     path: /etc/ssl/csr/ansible.com.key
   register: result_privatekey
 
-- assert:
+- name: Check conditions on certificate, CSR, and private key
+  ansible.builtin.assert:
     that:
       # When private key was specified for assertonly, this was checked:
       - result.public_key == result_privatekey.public_key

plugins/modules/x509_certificate_info.py

@@ -114,7 +114,7 @@ EXAMPLES = r'''
   register: result
 
 - name: Validate that certificate is valid tomorrow, but not in three weeks
-  assert:
+  ansible.builtin.assert:
     that:
       - result.valid_at.point_1      # valid in one day
       - not result.valid_at.point_2  # not valid in three weeks