Improve documentation, in particular of ACME modules (#181)

* Use B(...) instead of RST formatting (which does not work for options). * Improve the documentation on acme_directory. It now mentions the ACME v1 deprecation for Let's Encrypt, and mentions that ZeroSSL works. * Improve ACME module documentation. * Update plugins/doc_fragments/acme.py
2021-02-02 19:29:49 +01:00 · 2021-02-02 19:29:49 +01:00 · 4b638a9608
parent b0dbccaf3c
commit 4b638a9608
5 changed files with 45 additions and 27 deletions
--- a/plugins/doc_fragments/acme.py
+++ b/plugins/doc_fragments/acme.py
@ -32,11 +32,11 @@ options:
      - "Path to a file containing the ACME account RSA or Elliptic Curve
         key."
      - "Private keys can be created with the
-         M(community.crypto.openssl_privatekey) module. If the requisites
-         (pyOpenSSL or cryptography) are not available, keys can also be
-         created directly with the C(openssl) command line tool: RSA keys
-         can be created with C(openssl genrsa ...). Elliptic curve keys can be
-         created with C(openssl ecparam -genkey ...). Any other tool creating
+         M(community.crypto.openssl_privatekey) or M(community.crypto.openssl_privatekey_pipe)
+         modules. If the requisites (pyOpenSSL or cryptography) are not available,
+         keys can also be created directly with the C(openssl) command line tool:
+         RSA keys can be created with C(openssl genrsa ...). Elliptic curve keys
+         can be created with C(openssl ecparam -genkey ...). Any other tool creating
         private keys in PEM format can be used as well."
      - "Mutually exclusive with C(account_key_content)."
      - "Required if C(account_key_content) is not used."
@ -47,7 +47,7 @@ options:
      - "Content of the ACME account RSA or Elliptic Curve key."
      - "Mutually exclusive with C(account_key_src)."
      - "Required if C(account_key_src) is not used."
-      - "*Warning:* the content will be written into a temporary file, which will
+      - "B(Warning:) the content will be written into a temporary file, which will
         be deleted by Ansible when the module completes. Since this is an
         important private key — it can be used to change the account key,
         or to revoke your certificates without knowing their private keys
@ -66,40 +66,52 @@ options:
  acme_version:
    description:
      - "The ACME version of the endpoint."
-      - "Must be 1 for the classic Let's Encrypt and Buypass ACME endpoints,
-         or 2 for standardized ACME v2 endpoints."
-      - "The default value is 1. Note that in community.crypto 2.0.0, this
-         option *will be required* and will no longer have a default."
+      - "Must be C(1) for the classic Let's Encrypt and Buypass ACME endpoints,
+         or C(2) for standardized ACME v2 endpoints."
+      - "The default value is C(1). Note that in community.crypto 2.0.0, this
+         option B(will be required) and will no longer have a default."
      - "Please also note that we will deprecate ACME v1 support eventually."
    type: int
    choices: [ 1, 2 ]
  acme_directory:
    description:
      - "The ACME directory to use. This is the entry point URL to access
-         CA server API."
+         the ACME CA server API."
      - "For safety reasons the default is set to the Let's Encrypt staging
         server (for the ACME v1 protocol). This will create technically correct,
         but untrusted certificates."
-      - "The default value is U(https://acme-staging.api.letsencrypt.org/directory).
-         Note that in community.crypto 2.0.0, this option *will be required* and
-         will no longer have a default."
+      - "The default value is C(https://acme-staging.api.letsencrypt.org/directory).
+         Note that in community.crypto 2.0.0, this option B(will be required) and
+         will no longer have a default. Note that the default is the Let's Encrypt
+         staging server for the ACME v1 protocol, which is deprecated and will
+         be disabled in May 2021 (see
+         L(here,https://community.letsencrypt.org/t/end-of-life-plan-for-acmev1/88430/7)
+         for details)."
      - "For Let's Encrypt, all staging endpoints can be found here:
         U(https://letsencrypt.org/docs/staging-environment/). For Buypass, all
         endpoints can be found here:
         U(https://community.buypass.com/t/63d4ay/buypass-go-ssl-endpoints)"
-      - "For Let's Encrypt, the production directory URL for ACME v1 is
-         U(https://acme-v01.api.letsencrypt.org/directory), and the production
-         directory URL for ACME v2 is U(https://acme-v02.api.letsencrypt.org/directory)."
-      - "For Buypass, the production directory URL for ACME v2 and v1 is
+      - "For B(Let's Encrypt), the production directory URL for ACME v2 is
+         U(https://acme-v02.api.letsencrypt.org/directory).
+         (The production directory URL for ACME v1 is
+         U(https://acme-v01.api.letsencrypt.org/directory) and will be
+         disabled in July 2021.)"
+      - "For B(Buypass), the production directory URL for ACME v2 and v1 is
         U(https://api.buypass.com/acme/directory)."
-      - "*Warning:* So far, the module has only been tested against Let's Encrypt
-         (staging and production), Buypass (staging and production), and
-         L(Pebble testing server,https://github.com/letsencrypt/Pebble)."
+      - "For B(ZeroSSL), the production directory URL for ACME v2 is
+         U(https://acme.zerossl.com/v2/DV90)."
+      - "B(Warning:) So far, the ACME modules have only been tested against Let's Encrypt
+         (staging and production), Buypass (staging and production), ZeroSSL (production),
+         and L(Pebble testing server,https://github.com/letsencrypt/Pebble). If you
+         experience problems with another ACME server, please
+         L(create an issue,https://github.com/ansible-collections/community.crypto/issues/new/choose)
+         to help us supporting it. Feedback that an ACME server not mentioned does work
+         is also appreciated."
    type: str
  validate_certs:
    description:
      - Whether calls to the ACME directory will validate TLS certificates.
-      - "*Warning:* Should *only ever* be set to C(no) for testing purposes,
+      - "B(Warning:) Should B(only ever) be set to C(no) for testing purposes,
         for example when testing against a local Pebble server."
    type: bool
    default: yes
--- a/plugins/doc_fragments/module_csr.py
+++ b/plugins/doc_fragments/module_csr.py
@ -183,7 +183,7 @@ options:
    name_constraints_excluded:
        description:
            - For CA certificates, this specifies a list of identifiers which describe
-              subtrees of names that this CA is *not* allowed to issue certificates for.
+              subtrees of names that this CA is B(not) allowed to issue certificates for.
            - Values must be prefixed by their options. (i.e., C(email), C(URI), C(DNS), C(RID), C(IP), C(dirName),
              C(otherName) and the ones specific to your CA).
        type: list
--- a/plugins/doc_fragments/module_privatekey.py
+++ b/plugins/doc_fragments/module_privatekey.py
@ -20,7 +20,7 @@ description:
    - "Please note that the module regenerates private keys if they don't match
      the module's options. In particular, if you provide another passphrase
      (or specify none), change the keysize, etc., the private key will be
-      regenerated. If you are concerned that this could **overwrite your private key**,
+      regenerated. If you are concerned that this could B(overwrite your private key),
      consider using the I(backup) option."
    - "The module can use the cryptography Python library, or the pyOpenSSL Python
      library. By default, it tries to detect which one is available. This can be
@ -103,7 +103,7 @@ options:
            - The value C(auto) selects a fromat based on the key format. The value C(auto_ignore) does the same,
              but for existing private key files, it will not force a regenerate when its format is not the automatically
              selected one for generation.
-            - Note that if the format for an existing private key mismatches, the key is *regenerated* by default.
+            - Note that if the format for an existing private key mismatches, the key is B(regenerated) by default.
              To change this behavior, use the I(format_mismatch) option.
            - The I(format) option is only supported by the C(cryptography) backend. The C(pyopenssl) backend will
              fail if a value different from C(auto_ignore) is used.
--- a/plugins/modules/acme_account.py
+++ b/plugins/modules/acme_account.py
@ -31,6 +31,8 @@ seealso:
    description: Retrieves facts about an ACME account.
  - module: community.crypto.openssl_privatekey
    description: Can be used to create a private account key.
+  - module: community.crypto.openssl_privatekey_pipe
+    description: Can be used to create a private account key without writing it to disk.
  - module: community.crypto.acme_inspect
    description: Allows to debug problems.
 extends_documentation_fragment:
--- a/plugins/modules/acme_certificate.py
+++ b/plugins/modules/acme_certificate.py
@ -62,8 +62,12 @@ seealso:
    description: Helps preparing C(tls-alpn-01) challenges.
  - module: community.crypto.openssl_privatekey
    description: Can be used to create private keys (both for certificates and accounts).
+  - module: community.crypto.openssl_privatekey_pipe
+    description: Can be used to create private keys without writing it to disk (both for certificates and accounts).
  - module: community.crypto.openssl_csr
    description: Can be used to create a Certificate Signing Request (CSR).
+  - module: community.crypto.openssl_csr_pipe
+    description: Can be used to create a Certificate Signing Request (CSR) without writing it to disk.
  - module: community.crypto.certificate_complete_chain
    description: Allows to find the root certificate for the returned fullchain.
  - module: community.crypto.acme_certificate_revoke
@ -117,7 +121,7 @@ options:
  csr:
    description:
      - "File containing the CSR for the new certificate."
-      - "Can be created with C(openssl req ...)."
+      - "Can be created with M(community.crypto.openssl_csr) or C(openssl req ...)."
      - "The CSR may contain multiple Subject Alternate Names, but each one
         will lead to an individual challenge that must be fulfilled for the
         CSR to be signed."
@ -131,7 +135,7 @@ options:
  csr_content:
    description:
      - "Content of the CSR for the new certificate."
-      - "Can be created with C(openssl req ...)."
+      - "Can be created with M(community.crypto.openssl_csr_pipe) or C(openssl req ...)."
      - "The CSR may contain multiple Subject Alternate Names, but each one
         will lead to an individual challenge that must be fulfilled for the
         CSR to be signed."