Repository: ansible/ansible

Issue:
letsencrypt module should be renamed (to avoid violating Let's Encrypt's trademark policy)
##### ISSUE TYPE
Bug Report

##### COMPONENT NAME
letsencrypt

##### ANSIBLE VERSION
2.6

##### SUMMARY
In letsencrypt/website#303, @cpu pointed out that according to the [Let's Encrypt trademark policy](https://letsencrypt.org/trademarks/), we should better rename the `letsencrypt` module.



Discussion:
Files identified in the description:
* [lib/ansible/modules/web_infrastructure/letsencrypt.py](https://github.com/ansible/ansible/blob/devel/lib/ansible/modules/web_infrastructure/letsencrypt.py)

If these files are inaccurate, please update the `component name` section of the description or use the `!component` bot command.

[click here for bot help](https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md)
<!--- boilerplate: components_banner --->
@felixfontein Greetings! Thanks for taking the time to open this issue. In order for the community to handle your issue effectively, we need a bit more information. 

Here are the items we could not find in your description:
- ansible version

Please set the description of this issue with this template:
https://raw.githubusercontent.com/ansible/ansible/devel/.github/ISSUE_TEMPLATE.md

[click here for bot help](https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md)
<!--- boilerplate: issue_missing_data --->
cc @mgruener @resmo
[click here for bot help](https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md)
<!--- boilerplate: notify --->
An idea for renaming:
* `acme_certificate` for whats currently `letsencrypt`;
* `acme_account` for the new module in #37275 (currently called `letsencrypt_account`);
* `acme_certificate_revoke` or simply `acme_revoke` for the new module planned in #36345;
* the `module_utils` module would be simply `acme` (or is this too general?), same as the documentation fragment (both will appear in #37275).
@resmo @gundalow Do you know of a precedent where a module has been renamed? Is there a mechanism to guide users to the new name (except by listing it in the changelog, which not everyone reads)?
So the way to rename a module is to deprecated the current module by renaming the module with a prefix of _. e.g. `_letsencrypt` see and update with some infos about deprecation https://github.com/ansible/ansible/commit/5700b0961063085c9c08f7e9df60eedc4c320cea#diff-5f9ddb1cdcdbea7c187daee24f186436

Note that the deprecation doc block format has changed in the meanwhile. See https://github.com/ansible/ansible/commit/a23c95023b3e4d79b971b75cc8c5878c62ebf501#diff-5f9ddb1cdcdbea7c187daee24f186436

The deprecated module would be removed in version 2.10 (next release + 4 minors = 2.6 + 4 minors)
1) rename the module
2) create symlink to old name, but add a leading `_` underscore, this shows the alias is deprecated
3) ...
4) $$$
@bcoca @resmo Do I understand it correctly that the deprecation info is not necessary if there's a symlink?

@resmo What do you think about the name `acme_certificate`? Do you have other ideas?
(Also, with a symlink, the documentation and examples will mention only the new module name.)
I noticed that some symlinked modules use code like this (after `AnsibleModule` is instanciated):
```
    if module._name == 'os_server_actions':
        module.deprecate("The 'os_server_actions' module is being renamed 'os_server_action'", version=2.8)
```
While looking at some renamed modules, it also seems that the documentation for the old module name vanishes (so there's no hint there that the module is renamed, you simply get a 404).
As @bcoca mentioned, when the functionality is identical (just a simple rename of module) the symlink variant is probably easier. acme_certificate sounds good to me. 

Not sure about the docs issue.

Resolving patch:
diff --git a/lib/ansible/modules/web_infrastructure/_letsencrypt.py b/lib/ansible/modules/web_infrastructure/_letsencrypt.py
new file mode 120000
--- /dev/null
+++ b/lib/ansible/modules/web_infrastructure/_letsencrypt.py
@@ -0,0 +1 @@
+acme_certificate.py
\ No newline at end of file
diff --git a/lib/ansible/modules/web_infrastructure/letsencrypt.py b/lib/ansible/modules/web_infrastructure/acme_certificate.py
similarity index 99%
rename from lib/ansible/modules/web_infrastructure/letsencrypt.py
rename to lib/ansible/modules/web_infrastructure/acme_certificate.py
--- a/lib/ansible/modules/web_infrastructure/letsencrypt.py
+++ b/lib/ansible/modules/web_infrastructure/acme_certificate.py
@@ -15,7 +15,7 @@
 
 DOCUMENTATION = '''
 ---
-module: letsencrypt
+module: acme_certificate
 author: "Michael Gruener (@mgruener)"
 version_added: "2.2"
 short_description: Create SSL certificates with Let's Encrypt
@@ -40,6 +40,8 @@
       the Let's Encrypt CA, the module can be used with any service using the ACME
       v1 or v2 protocol."
    - "At least one of C(dest) and C(fullchain_dest) must be specified."
+   - "Note: this module was called C(letsencrypt) before Ansible 2.6. The usage
+      did not change."
 requirements:
   - "python >= 2.6"
   - openssl
@@ -194,7 +196,7 @@
 ### Example with HTTP challenge ###
 
 - name: Create a challenge for sample.com using a account key from a variable.
-  letsencrypt:
+  acme_certificate:
     account_key_content: "{{ account_private_key }}"
     csr: /etc/pki/cert/csr/sample.com.csr
     dest: /etc/httpd/ssl/sample.com.crt
@@ -202,7 +204,7 @@
 
 # Alternative first step:
 - name: Create a challenge for sample.com using a account key from hashi vault.
-  letsencrypt:
+  acme_certificate:
     account_key_content: "{{ lookup('hashi_vault', 'secret=secret/account_private_key:value') }}"
     csr: /etc/pki/cert/csr/sample.com.csr
     fullchain_dest: /etc/httpd/ssl/sample.com-fullchain.crt
@@ -210,7 +212,7 @@
 
 # Alternative first step:
 - name: Create a challenge for sample.com using a account key file.
-  letsencrypt:
+  acme_certificate:
     account_key_src: /etc/pki/cert/private/account.key
     csr: /etc/pki/cert/csr/sample.com.csr
     dest: /etc/httpd/ssl/sample.com.crt
@@ -226,7 +228,7 @@
 #     when: sample_com_challenge is changed
 
 - name: Let the challenge be validated and retrieve the cert and intermediate certificate
-  letsencrypt:
+  acme_certificate:
     account_key_src: /etc/pki/cert/private/account.key
     csr: /etc/pki/cert/csr/sample.com.csr
     dest: /etc/httpd/ssl/sample.com.crt
@@ -237,7 +239,7 @@
 ### Example with DNS challenge against production ACME server ###
 
 - name: Create a challenge for sample.com using a account key file.
-  letsencrypt:
+  acme_certificate:
     account_key_src: /etc/pki/cert/private/account.key
     account_email: myself@sample.com
     src: /etc/pki/cert/csr/sample.com.csr
@@ -274,7 +276,7 @@
 #     when: sample_com_challenge is changed
 
 - name: Let the challenge be validated and retrieve the cert and intermediate certificate
-  letsencrypt:
+  acme_certificate:
     account_key_src: /etc/pki/cert/private/account.key
     account_email: myself@sample.com
     src: /etc/pki/cert/csr/sample.com.csr
@@ -1304,6 +1306,8 @@ def main():
         ),
         supports_check_mode=True,
     )
+    if module._name == 'letsencrypt':
+        module.deprecate("The 'letsencrypt' module is being renamed 'acme_certificate'", version=2.10)
 
     # AnsibleModule() changes the locale, so change it back to C because we rely on time.strptime() when parsing certificate dates.
     module.run_command_environ_update = dict(LANG='C', LC_ALL='C', LC_MESSAGES='C', LC_CTYPE='C')


Test patch: