nickjj.acme_sh

Qu'est-ce qu'ansible-acme-sh ?

C'est un rôle Ansible pour :

• Installer acme.sh pour délivrer, renouveler ou supprimer des certificats SSL basés sur Let's Encrypt
• Délivrer des certificats pour des domaines uniques, multiples ou génériques
• Configurer plusieurs domaines avec un certificat unique ou des certificats distincts
• Délivrer des défis basés sur DNS en utilisant la fonctionnalité API DNS automatisée d'acme.sh
• Exécuter des commandes acme.sh personnalisées si les paramètres prédéfinis ne suffisent pas

Pourquoi voudriez-vous utiliser ce rôle ?

Ce rôle utilise acme.sh, qui est un script Bash autonome pour gérer toutes les complexités de la délivrance et du renouvellement automatique de vos certificats SSL.

Les objectifs de ce rôle sont d'être très configurable tout en ayant des valeurs par défaut sensées afin que vous puissiez commencer simplement en fournissant une liste de noms de domaine, en réglant votre fournisseur DNS et en fournissant la clé API de votre fournisseur DNS.

Il est également idempotent pour chaque tâche, car c'est ma façon de faire !

Pourquoi les défis basés sur DNS sont-ils la seule méthode prise en charge ?

Les défis effectués par DNS signifient que vous pouvez configurer vos certificats avant que votre serveur web ou proxy ne soit provisionné. Cela signifie également que votre serveur web n'a pas besoin de savoir comment fonctionne le défi ACME. Tout ce que vous avez à faire est de faire référence aux certificats finaux que ce rôle génère.

Un autre avantage est que si vous exécutez un serveur web à l'intérieur de Docker, il se pourrait que cela ne soit pas opérationnel avant que votre serveur n'ait été provisionné par Ansible. Par exemple, il est courant de configurer des déploiements basés sur git pour démarrer un déploiement d'application.

De plus, il est agréable d'utiliser des défis DNS car ils sont le seul moyen de délivrer des certificats génériques avec Let's Encrypt. Se concentrer sur une solution unique qui fonctionne avec tous les types de certificats semblait être la bonne démarche.

Cela dit, je ne prévois probablement pas de prendre en charge d'autres modes tels que standalone, webroot, nginx ou Apache, mais rien n'est gravé dans la pierre.

Plates-formes prises en charge

• Ubuntu 16.04 LTS (Xenial)
• Ubuntu 18.04 LTS (Bionic)
• Debian 8 (Jessie)
• Debian 9 (Stretch)

Variables du rôle

# L'utilisateur qui exécutera acme.sh sur le système. Gardez à l'esprit que cet utilisateur
# doit déjà exister, ce rôle ne le créera pas.
acme_sh_become_user: "root"

# Dépendances du package acme.sh. Les valeurs par défaut sont pour Debian / Ubuntu.
# Pour CentOS et Fedora, vous pouvez remplacer "cron" par "crond".
acme_sh_dependencies: ["cron", "git", "wget"]

# Le dépôt acme.sh à cloner.
acme_sh_git_url: "https://github.com/acmesh-official/acme.sh"

# La branche, le tag ou le commit qui sera cloné.
acme_sh_git_version: "master"

# Par défaut, si vous cloniez ce dépôt maintenant puis que vous le cloniez à nouveau dans 6 mois,
# il conserverait l'ancienne version master d'il y a 6 mois.
# Si vous souhaitez tirer la dernière version master à chaque exécution, définissez ceci sur True.
acme_sh_git_update: False

# Où ce dépôt sera-t-il cloné ?
acme_sh_git_clone_dest: "/usr/local/src/acme.sh"

# Lorsqu'il est activé, acme.sh se mettra à jour vers la dernière version qui est
# distincte de la mise à jour du dépôt git. C'est parce qu'acme.sh s'installe
# avec un installateur après le clonage du code source.
#
# L'activer peut être bon pour obtenir la dernière version qui pourrait comporter des corrections de bogues,
# mais gardez à l'esprit que si vous le faites, vous pourriez obtenir des résultats différents à chaque exécution. Je
# recommande de le définir occasionnellement sur True mais de le laisser généralement désactivé.
acme_sh_upgrade: False

# Lorsqu'il est activé, le code source cloné, le chemin d'installation, les fichiers journaux et les tâches cron de renouvellement
# seront supprimés.
#
# Les certificats installés ne seront pas supprimés. Si vous souhaitez supprimer les certificats installés, il existe une autre option à cet effet que nous aborderons plus tard.
acme_sh_uninstall: False

# Lors de la création d'un compte Let's Encrypt initial, vous pouvez optionnellement fournir une
# adresse e-mail. Par défaut, cela n'est pas défini, mais n'hésitez pas à ajouter votre adresse e-mail
# si vous le souhaitez. Si vous le définissez, vous recevrez un e-mail lorsque vos
# certificats seront dans les 20 jours de leur expiration.
#
# Je recommande vivement de le définir car si tout se passe comme prévu, vous ne
# recevrez jamais d'e-mail à moins qu'acme.sh ne fonctionne pas correctement et échoue à renouveler un certificat.
acme_sh_account_email: ""

# Les certificats seront renouvelés par un job cron géré par acme.sh. Par défaut
# acme.sh utilise 60 jours pour chaque tentative de renouvellement, mais j'ai choisi d'utiliser 30
# par défaut pour donner une tentative supplémentaire au cas où quelque chose d'inattendu se produirait.
#
# Les certificats qui n'ont pas besoin d'être renouvelés seront ignorés par acme.sh, donc
# tout est en ordre. Il est également bon de mentionner que cette valeur ne peut pas dépasser 60 jours, ce qui
# est une limitation imposée par acme.sh, ce rôle ne vérifie pas la valeur.
acme_sh_renew_time_in_days: 30

# Le chemin de base où les certificats seront copiés. Si vous êtes familier avec
# acme.sh, cela concerne les certificats générés avec --install-cert.
#
# C'est la destination finale pour vos certificats et l'utilisateur que vous avez choisi
# devra avoir un accès en écriture à ce chemin. Ce chemin finira par avoir son
# propriétaire:groupe défini sur la valeur de acme_sh_become_user.
acme_sh_copy_certs_to_path: "/etc/ssl/ansible"

# À la fin de l'exécution, un message de débogage Ansible affichera une liste de
# domaines qui ont des certificats SSL valides avec leurs dates d'expiration.
# Vous pouvez désactiver cela en le définissant sur False.
acme_sh_list_domains: True

# Lorsqu'il est défini sur False, il utilisera les serveurs Let's Encrypt en direct, assurez-vous donc
# que tout fonctionne avec le mode staging activé ou vous risquez d'être limité en fréquence.
#
# Il convient de mentionner que vous devrez forcer la délivrance d'un nouveau certificat lors
# de la transition entre staging et live ou vice versa.
acme_sh_default_staging: True

# Lorsqu'il est défini sur True, cela régénérera un nouveau certificat même si votre liste de
# domaines n'a pas changé. Il est également utilisé pour définir un nouveau fournisseur DNS et des clés API.
#
# Soyez prudent avec cela car vous pourriez être limité en fréquence sur le serveur en direct.
# N'envisagez d'utiliser cela que pour mettre à jour votre fournisseur DNS. Vous devriez
# le remettre à False lorsque vous avez terminé.
acme_sh_default_force_issue: False

# Lorsqu'il est défini sur True, cela régénérera un nouveau certificat pour une liste
# de certificats existants. Cela ne mettra pas à jour votre fournisseur DNS ni vos clés API.
#
# Cela pourrait être utile si vos certificats ont expiré. Vous devriez
# le remettre à False lorsque vous avez terminé.
acme_sh_default_force_renew: False

# Lorsqu'il est défini sur True, cela fournira plus d'informations détaillées à STDOUT. Cela
# pourrait être utile si vous testez le rôle en mode staging.
acme_sh_default_debug: False

# Quel fournisseur DNS devriez-vous utiliser ?
# Une liste de fournisseurs pris en charge peut être trouvée à :
#   https://github.com/acmesh-official/acme.sh/tree/master/dnsapi
# Quant à obtenir le nom à utiliser, vous pouvez également le trouver à l'URL ci-dessus.
#
# Par défaut, c'est DigitalOcean. Assurez-vous d'inclure le préfixe dns_ du nom,
# mais omettez l'extension .sh.
acme_sh_default_dns_provider: "dns_dgon"

# Quelles sont les clés API de votre fournisseur DNS ?
# Les noms de clé à utiliser peuvent être trouvés à :
#   https://github.com/acmesh-official/acme.sh/tree/master/dnsapi
#
# La clé API peut être créée sur le site Web de votre fournisseur DNS. Certains fournisseurs
# nécessitent 1 clé, tandis que d'autres nécessitent 2+. Ajoutez-les simplement en tant que paires clé / valeur ici
# sans le "export ".
#
# Par exemple, si vous utilisez DigitalOcean, vous entreriez :
#    acme_sh_default_dns_provider_api_keys:
#      "DO_API_KEY": "LE_TOKEN_SECRETC_API_DU_TABLEAU_DE_BORD_DO"
acme_sh_default_dns_provider_api_keys: {}

# Combien de temps acme.sh doit-il dormir après avoir tenté de définir l'enregistrement TXT dans vos
# enregistrements DNS ? Certains fournisseurs DNS ne mettent pas à jour aussi rapidement que d'autres.
#
# 120 est la valeur par défaut d'acme.sh lui-même, mais gardez à l'esprit que si vous utilisez
# NameSilo, leurs mises à jour DNS ne se propagent qu'une fois toutes les 15 minutes, donc vous devrez définir
# cette valeur sur 900, sinon vous risquez de rencontrer une erreur DNS NXDOMAIN.
#
# Je recommande de garder cela défini sur 120 ou plus si votre fournisseur DNS l'exige.
#
# Bien qu'à titre d'exemple, j'ai utilisé 10 lors du test de ce rôle contre DigitalOcean
# et cela a fonctionné environ 30 fois de suite. Néanmoins, en production, j'utiliserais 120
# juste pour être sûr car ce délai de 2 minutes ne vous affectera que lors de la première
# exécution d'Ansible. Par la suite, il sera mis à jour en arrière-plan via un job cron.
acme_sh_default_dns_sleep: 120

# Lors de la délivrance de nouveaux certificats, vous pouvez choisir d'ajouter des drapeaux supplémentaires qui
# ne sont pas présents par défaut ici. Fournissez-les comme sur la ligne de commande, comme "--help".
acme_sh_default_extra_flags_issue: ""

# Lors du renouvellement des certificats, vous pouvez choisir d'ajouter des drapeaux supplémentaires qui
# ne sont pas présents par défaut ici. Fournissez-les comme sur la ligne de commande, comme "--help".
acme_sh_default_extra_flags_renew: ""

# Lors de l'installation des certificats, vous pouvez choisir d'ajouter des drapeaux supplémentaires qui
# ne sont pas présents par défaut ici. Fournissez-les comme sur la ligne de commande, comme "--help".
#
# L'installation est différente de la délivrance et nous aborderons cela plus tard.
acme_sh_default_extra_flags_install_cert: ""

# Lorsqu'un certificat est délivré ou renouvelé, acme.sh tentera d'exécuter une commande
# de votre choix. Cela peut être pour redémarrer ou recharger votre serveur web ou proxy.
#
# Gardez à l'esprit que l'utilisateur que vous avez défini dans acme_sh_become_user doit avoir les droits d'accès à
# sudo si vous l'utilisez ici, sinon, il doit avoir les droits d'accès pour recharger votre
# serveur web/proxy.
#
# Pour un exemple avec Docker, consultez la section d'exemple de ce README.
acme_sh_default_install_cert_reloadcmd: "sudo systemctl reload nginx"

# Si vous avez besoin de plus de contrôle granulaire que le reloadcmd, vous pouvez vous intégrer dans le
# cycle de vie de la délivrance ou du renouvellement d'un certificat. Par défaut, les 3
# options suivantes ne font rien sauf si vous les complétez. Elles ne sont pas nécessaires pour que tout
# fonctionne tant que votre reloadcmd fonctionne.
#
# Lorsqu'un certificat est délivré ou renouvelé, acme.sh tentera d'exécuter une commande
# avant de tenter de délivrer un certificat. Cela ne peut être appliqué qu'au moment de la délivrance d'un
# certificat, mais il sera enregistré et utilisé pour le renouvellement également.
#
# Cela s'exécutera même si le certificat n'a pas été délivré / renouvelé avec succès.
acme_sh_default_issue_pre_hook: ""

# Lorsqu'un certificat est délivré ou renouvelé, acme.sh tentera d'exécuter une commande
# après avoir tenté de délivrer un certificat. Cela ne peut être appliqué qu'au moment de la délivrance d'un
# certificat, mais il sera enregistré et utilisé pour le renouvellement également.
#
# Cela s'exécutera même si le certificat n'a pas été délivré / renouvelé avec succès.
acme_sh_default_issue_post_hook: ""

# Lorsqu'un certificat est délivré ou renouvelé, acme.sh tentera d'exécuter une commande
# après qu'un certificat ait été renouvelé avec succès. Cela ne peut être appliqué qu'au moment de la délivrance d'un
# certificat, mais il sera enregistré et utilisé pour le renouvellement également.
#
# Cela ne s'exécutera que si le certificat a été délivré / renouvelé avec succès.
acme_sh_default_issue_renew_hook: ""

# Lorsqu'il est défini sur True, les certificats seront supprimés et désactivés au lieu d'être créés et définis pour renouvellement. Cela n'installera pas acme.sh.
acme_sh_default_remove: False

# Cette liste contient une liste de domaines, ainsi que des paires clé / valeur pour
# configurer chaque ensemble de domaines individuellement.
#
# Voici un exemple avec chaque option disponible documentée, et quelques exemples réels
# seront également inclus dans la section d'exemple de ce README :
acme_sh_domains:
#  Une liste de 1 ou plusieurs domaines, vous pouvez utiliser ["example.com", "*.example.com"] ou
#  ["*.example.com", "example.com"] pour définir un certificat générique avec le certificat de domaine racine dans le même fichier. Le premier domaine de la liste
#  sera utilisé comme nom de base pour le nom du certificat.
#
#  Si vous souhaitez avoir des fichiers séparés, créez un nouvel élément "domains:" dans la liste.
#  - domains: ["example.com", "www.example.com", "admin.example.com"]
#    # Optionnellement remplacer la variable de staging par défaut. Ce modèle général vous permet
#    # de remplacer situationnellement les valeurs par défaut listées ci-dessus pour chaque liste de domaines.
#    staging: False
#    # Optionnellement forcer la délivrance de nouveaux certificats.
#    force_issue: False
#    # Optionnellement forcer le renouvellement des certificats.
#    force_renew: False
#    # Optionnellement activer le mode débogage.
#    debug: True
#    # Optionnellement remplacer le fournisseur DNS par défaut.
#    dns_provider: "dns_namesilo"
#    # Optionnellement remplacer les clés API DNS par défaut.
#    dns_provider_api_keys:
#     "Namesilo_Key": "LE_TOKEN_SECRET_API_DU_TABLEAU_DE_BORD_NAMESILO"
#    # Optionnellement remplacer le temps de sommeil DNS par défaut.
#    dns_sleep: 900
#    # Optionnellement ajouter des drapeaux supplémentaires à chacune de ces 3 actions :
#    extra_flags_issue: ""
#    extra_flags_renew: ""
#    extra_flags_install_cert: ""
#    # Optionnellement définir une commande de rechargement différente.
#    install_cert_reloadcmd: "whoami"
#    # Optionnellement exécuter des commandes à différents moments du processus de délivrance du certificat :
#    extra_issue_pre_hook: ""
#    extra_issue_post_hook: ""
#    extra_issue_renew_hook: ""
#    # Optionnellement supprimer et désactiver le certificat.
#    remove: True

Exemple d'utilisation

Pour cet exemple, supposons que vous avez un groupe appelé app et vous avez un fichier site.yml typique.

Pour utiliser ce rôle, modifiez votre fichier site.yml pour qu'il ressemble à ceci :

---

- name: Configurer le(s) serveur(s) d'applications
  hosts: "app"
  become: True

  roles:
    - { role: "nickjj.acme_sh", tags: ["acme_sh"] }

Voici quelques exemples. Vous pouvez recréer cet exemple de votre côté en ouvrant ou en créant group_vars/app.yml qui est situé par rapport à votre répertoire inventory et en le faisant ressembler à ceci :

---

acme_sh_account_email: "[email protected]"

# Un exemple où un fournisseur DNS a 2 clés pour l'accès API :
acme_sh_default_dns_provider: "dns_cf"
acme_sh_default_dns_provider_api_keys:
  "CF_Key": "LE_TOKEN_SECRET_API_DU_TABLEAU_DE_BORD_CLOUDFLARE"
  "CF_Email": "[email protected]"

# Rechargement de nginx à l'intérieur d'un conteneur Docker nommé "nginx".
# Si vous exécutez nginx dans un conteneur Docker, vous devrez également monter vos certificats en volume,
# mais je suis sûr que vous le saviez déjà !
acme_sh_default_install_cert_reloadcmd: "docker exec nginx nginx -s reload"

# --- Voici quelques différents exemples d'acme_sh_domains --------------------------
# Vous n'aurez besoin de fournir qu'un seul de ces exemples selon ce que vous souhaitez faire !
# ------------------------------------------------------------------------------

# 1 fichier certificat pour tous les domaines.
acme_sh_domains:
  - domains: ["example.com", "www.example.com", "admin.example.com"]

# Produit ceci sur votre serveur :
#   /etc/ssl/ansible/example.com.key (la clé privée)
#   /etc/ssl/ansible/example.com.pem (le certificat complet)

# ------------------------------------------------------------------------------

# 2 fichiers certificat utilisant les mêmes domaines que ci-dessus.
acme_sh_domains:
  - domains: ["example.com", "www.example.com"]
  - domains: ["admin.example.com"]

# Produit ceci sur votre serveur :
#   /etc/ssl/ansible/example.com.key (la clé privée)
#   /etc/ssl/ansible/example.com.pem (le certificat complet)
#   /etc/ssl/ansible/admin.example.com.key (la clé privée)
#   /etc/ssl/ansible/admin.example.com.pem (le certificat complet)

# ------------------------------------------------------------------------------

# 2 fichiers certificat utilisant le même exemple mais le certificat admin sera supprimé et désactivé.
acme_sh_domains:
  - domains: ["example.com", "www.example.com"]
  - domains: ["admin.example.com"]
    remove: True

# Produit ceci sur votre serveur :
#   /etc/ssl/ansible/example.com.key (la clé privée)
#   /etc/ssl/ansible/example.com.pem (le certificat complet)

# ------------------------------------------------------------------------------

# 2 fichiers certificat utilisant le même exemple mais passant de staging à live
# sur admin.example.com (mais n'oubliez pas de retirer force_issue après son exécution une fois).
acme_sh_domains:
  - domains: ["example.com", "www.example.com"]
  - domains: ["admin.example.com"]
    staging: False
    force_issue: True

# ------------------------------------------------------------------------------

# 2 fichiers certificat utilisant le même exemple mais forçant un renouvellement sur
# admin.example.com (disons qu'une erreur catastrophique s'est produite et que le certificat a expiré).
acme_sh_domains:
  - domains: ["example.com", "www.example.com"]
  - domains: ["admin.example.com"]
    force_renew: True

Si vous cherchez un rôle Ansible pour créer des utilisateurs, consultez mon rôle utilisateur.

Maintenant, vous exécuteriez ansible-playbook -i inventory/hosts site.yml -t acme_sh.

Installation

$ ansible-galaxy install nickjj.acme_sh

Ansible Galaxy

Vous pouvez le trouver sur le site officiel Ansible Galaxy si vous souhaitez le noter.

Licence

MIT