nickjj.acme_sh

Czym jest ansible-acme-sh?

To rola Ansible, która:

• Instaluje acme.sh do wydawania, odnawiania lub usuwania certyfikatów SSL opartych na Let's Encrypt
• Wydaje certyfikaty dla pojedynczych, wielu lub dzikich domen
• Umożliwia skonfigurowanie wielu domen za pomocą jednego certyfikatu lub osobnych certyfikatów
• Używa wyzwań DNS przy pomocy zautomatyzowanej funkcji API DNS w acme.sh
• Uruchamia niestandardowe komendy acme.sh, jeśli preset nie jest wystarczający

Dlaczego chcesz używać tej roli?

Ta rola wykorzystuje acme.sh, co jest samodzielnym skryptem Bash do obsługi wszystkich złożoności związanych z wydawaniem oraz automatycznym odnawianiem certyfikatów SSL.

Cele tej roli to bycie bardzo konfigurowalnym, ale z rozsądnymi wartościami domyślnymi, abyś mógł zacząć, podając jedynie listę nazw domen, ustawiając swojego dostawcę DNS i klucz API dostawcy DNS.

Jest również idempotentna dla każdego zadania, ponieważ tak działam!

Dlaczego jedyną wspieraną metodą są wyzwania DNS?

Przeprowadzanie wyzwań przez DNS oznacza, że możesz ustawić swoje certyfikaty, zanim twój serwer WWW lub proxy zostaną skonfigurowane. Oznacza to również, że twój serwer WWW nie musi wiedzieć nic o tym, jak działa wyzwanie ACME. Wszystko, co musisz zrobić, to odwołać się do finalnych certyfikatów, które generuje ta rola.

Kolejną zaletą jest to, że jeśli uruchamiasz serwer WWW w Dockerze, możesz go nie mieć w działaniu, zanim twój serwer zostanie skonfigurowany przez Ansible. Na przykład, często ustawia się wdrażanie oparte na gicie, aby uruchomić wydanie aplikacji.

Ponadto, używanie wyzwań DNS jest dobre, ponieważ są one jedynym sposobem na wydawanie wildcard certyfikatów przy użyciu Let's Encrypt. Skupienie się na jednym rozwiązaniu, które działa ze wszystkimi typami certyfikatów, wydawało się właściwym krokiem.

Mówiąc to, prawdopodobnie nie będę wspierać innych trybów, takich jak standalone, webroot, nginx czy Apache, ale nic nie jest pewne.

Wspierane platformy

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

Zmienne roli

# Użytkownik w systemie, na którym będzie działać acme.sh. Pamiętaj, że użytkownik
# musi już istnieć, ta rola go nie stworzy.
acme_sh_become_user: "root"

# Zależności pakietów acme.sh. Wartości domyślne są dla Debiana / Ubuntu.
# Dla CentOS i Fedory możesz zastąpić "cron" "crond".
acme_sh_dependencies: ["cron", "git", "wget"]

# Repozytorium acme.sh do sklonowania.
acme_sh_git_url: "https://github.com/acmesh-official/acme.sh"

# Gałąź, tag lub commit, który będzie sklonowany.
acme_sh_git_version: "master"

# Domyślnie, jeśli sklonujesz to repo teraz, a potem za 6 miesięcy znowu,
# pozostanie na starej wersji master sprzed 6 miesięcy.
# Jeśli chcesz pobierać najnowszą wersję master przy każdym uruchomieniu, ustaw to na True.
acme_sh_git_update: False

# Gdzie to repo zostanie sklonowane?
acme_sh_git_clone_dest: "/usr/local/src/acme.sh"

# Kiedy włączone, acme.sh zaktualizuje się do najnowszej wersji, co jest
# oddzielne od aktualizacji repozytorium git. Ponieważ acme.sh instaluje
# się samo przy użyciu instalatora po sklonowaniu źródła.
#
# Włączenie tego może być dobre do uzyskania najnowszej wersji, która może
# zawierać poprawki, ale pamiętaj, że możesz uzyskać różne wyniki przy
# każdorazowym uruchomieniu. Zalecam okazjonalnie ustawienie tego na True,
# ale zazwyczaj pozostawiać wyłączone.
acme_sh_upgrade: False

# Gdy włączone, sklonowany kod źródłowy, ścieżka instalacji, pliki dzienników i zadania cron
# do odnawiania zostaną usunięte.
#
# Zainstalowane certyfikaty nie zostaną usunięte. Jeśli chcesz usunąć zainstalowane
# certyfikaty, mamy inną opcję na to, którą omówimy później.
acme_sh_uninstall: False

# Przy tworzeniu początkowego konta Let's Encrypt, opcjonalnie możesz podać
# adres e-mail. Domyślnie nie jest to ustawione, ale możesz dodać swój adres
# e-mail, jeśli chcesz. Jeśli go ustawisz, otrzymasz wiadomość e-mail, gdy
# twoje certyfikaty będą miały 20 dni do wygaśnięcia.
#
# Zdecydowanie zalecam ustawienie tego, ponieważ jeśli wszystko pójdzie zgodnie
# z planem, nigdy nie otrzymasz wiadomości e-mail, chyba że acme.sh nie zadziała
# i nie odnowi certyfikatu.
acme_sh_account_email: ""

# Certyfikaty będą odnawiane przez zarządzany przez acme.sh cron job. Domyślnie
# acme.sh używa 60 dni na każdą próbę odnawiania, ale postanowiłem użyć 30
# dni domyślnie, aby dać sobie jedną dodatkową próbę w razie nieoczekiwanych
# sytuacji.
#
# Certyfikaty, które nie muszą być odnawiane, będą pomijane przez acme.sh, więc
# wszystko jest w porządku. Warto również wspomnieć, że ta wartość nie
# może być większa niż 60 dni, co jest limitem narzuconym przez acme.sh; ta rola
# nie sprawdza podwójnie tej wartości.
acme_sh_renew_time_in_days: 30

# Podstawowa ścieżka, gdzie certyfikaty będą kopiowane. Jeśli znasz
# acme.sh, to dotyczy certyfikatów generowanych z użyciem --install-cert.
#
# To jest ostateczne miejsce przeznaczenia dla twoich certyfikatów, a wybrany
# przez ciebie użytkownik będzie musiał mieć dostęp do zapisu w tej ścieżce.
# Ta ścieżka będzie miała ustawionego właściciela i grupę według wartości
# acme_sh_become_user.
acme_sh_copy_certs_to_path: "/etc/ssl/ansible"

# Na koniec uruchomienia, komunikat debugujący Ansible wyświetli listę
# domen, które mają ważne certyfikaty SSL oraz ich daty wygaśnięcia.
# Możesz to wyłączyć, ustawiając to na False.
acme_sh_list_domains: True

# Jeśli ustawione na False, zostaną użyte na żywo serwery Let's Encrypt, więc upewnij
# się, że wszystko działa z staging na True, inaczej możesz napotkać ograniczenia
# w ilości żądań.
#
# Warto wspomnieć, że będziesz musiał wymusić wydanie nowego certyfikatu przy
# przełączaniu się między staging a live lub vice versa.
acme_sh_default_staging: True

# Jeśli ustawione na True, to wygeneruje nowy certyfikat, nawet jeśli
# twoja lista domen się nie zmieniła. Jest to także używane, aby ustawić nowego
# dostawcę DNS i klucze API.
#
# Bądź ostrożny w tym, ponieważ możesz zostać ograniczony, jeśli jesteś na
# serwerze produkcyjnym. Używaj tego tylko do aktualizacji dostawcy DNS.
# Powinieneś wrócić do False, gdy skończysz.
acme_sh_default_force_issue: False

# Jeśli ustawione na True, to wygeneruje nowy certyfikat dla istniejącej
# listy certyfikatów. To nie zaktualizuje twojego dostawcy DNS ani kluczy API.
#
# Może być przydatne, jeśli twoje certyfikaty wygasły. Powinieneś zmienić
# to z powrotem na False, gdy skończysz.
acme_sh_default_force_renew: False

# Jeśli ustawione na True, to dostarczy więcej szczegółowych informacji na STDOUT. To
# może być przydatne, jeśli testujesz rolę w trybie staging.
acme_sh_default_debug: False

# Którego dostawcę DNS chcesz używać?
# Listę wspieranych dostawców znajdziesz pod adresem:
#   https://github.com/acmesh-official/acme.sh/tree/master/dnsapi
# Nazwę do użycia znajdziesz pod tym samym adresem.
#
# Domyślnie ustawia się na DigitalOcean. Upewnij się, że uwzględniasz prefiks dns_,
# ale pomiń .sh w rozszerzeniu.
acme_sh_default_dns_provider: "dns_dgon"

# Jakie są klucze API twojego dostawcy DNS?
# Nazwy kluczy do użycia znajdziesz pod adresem:
#   https://github.com/acmesh-official/acme.sh/tree/master/dnsapi
#
# Klucz API można stworzyć na stronie dostawcy DNS. Niektórzy dostawcy
# wymagają 1 klucza, inni 2+. Dodaj je jako pary klucz/wartość tutaj,
# bez "export ".
#
# Na przykład, jeśli korzystasz z DigitalOcean, wpisałbyś:
#    acme_sh_default_dns_provider_api_keys:
#      "DO_API_KEY": "TWÓJ_SEKRETNY_TOKEN_Z_DASHBOARDU_DO"
acme_sh_default_dns_provider_api_keys: {}

# Jak długo acme.sh ma czekać po próbie ustawienia rekordu TXT w twoich
# rekordach DNS? Niektórzy dostawcy DNS nie aktualizują tak szybko jak inni.
#
# 120 to domyślna wartość z acme.sh, ale pamiętaj, że jeśli używasz NameSilo,
# ich aktualizacje DNS propagują tylko raz na 15 minut, więc musisz ustawić
# tę wartość na 900 lub ryzykujesz uzyskanie błędu DNS NXDOMAIN.
#
# Zalecam trzymanie tego ustawienia na 120 lub wyżej, jeśli Twój dostawca DNS
# tego wymaga.
#
# Przy okazji, używałem 10 podczas testowania tej roli z DigitalOcean
# i działało to około 30 razy z rzędu. Mimo to, w produkcji użyłbym 120
# dla bezpieczeństwa, ponieważ ta 2-minutowa zwłoka wpłynie tylko na pierwsze
# uruchomienie Ansible. Po tym zostanie zaktualizowane w tle za pomocą zadania cron.
acme_sh_default_dns_sleep: 120

# Przy wydawaniu nowych certyfikatów możesz wybrać, aby dodać dodatkowe flagi, które
# nie są tutaj domyślnie obecne. Podaj je tak, jak na linii poleceń, np. "--help".
acme_sh_default_extra_flags_issue: ""

# Przy odnawianiu certyfikatów możesz wybrać, aby dodać dodatkowe flagi, które
# nie są tutaj domyślnie obecne. Podaj je tak, jak na linii poleceń, np. "--help".
acme_sh_default_extra_flags_renew: ""

# Przy instalacji certyfikatów możesz wybrać, aby dodać dodatkowe flagi, które
# nie są tutaj domyślnie obecne. Podaj je tak, jak na linii poleceń, np. "--help".
#
# Instalacja różni się od wydania i omówimy to później.
acme_sh_default_extra_flags_install_cert: ""

# Gdy certyfikat jest wydawany lub odnawiany, acme.sh spróbuje uruchomić
# komendę, którą wybierzesz. Może to być na przykład restart lub przeładowanie
# twojego serwera WWW lub proxy.
#
# Pamiętaj, że użytkownik ustawiony w acme_sh_become_user musi mieć prawa 
# dostępu do sudo, jeśli używasz sudo tutaj, lub nie, musi mieć prawa
# dostępu do przeładowania twojego serwera WWW/proxy.
#
# Dla przykładu dotyczącego Dockera, sprawdź sekcję z przykładami w tym README.
acme_sh_default_install_cert_reloadcmd: "sudo systemctl reload nginx"

# Jeśli potrzebujesz większej kontroli niż reloadcmd, możesz włączyć
# cykl życia wydawania lub odnawiania certyfikatu. Domyślnie poniższe 3
# opcje nie robią nic, chyba że je wypełnisz. Nie są one potrzebne do
# działania, o ile twój reloadcmd działa.
#
# Gdy certyfikat jest wydawany lub odnawiany, acme.sh spróbuje uruchomić
# komendę przed próbą wydania certyfikatu. To można zastosować tylko przy
# wydawaniu certyfikatu, ale będzie zapisane i używane przy odnawianiu również.
#
# To zostanie wykonane, nawet jeśli certyfikat nie został pomyślnie wydany / odnowiony.
acme_sh_default_issue_pre_hook: ""

# Gdy certyfikat jest wydawany lub odnawiany, acme.sh spróbuje uruchomić
# komendę po próbie wydania certyfikatu. To można zastosować tylko przy
# wydawaniu certyfikatu, ale będzie zapisane i używane przy odnawianiu również.
#
# To zostanie wykonane, nawet jeśli certyfikat nie został pomyślnie wydany / odnowiony.
acme_sh_default_issue_post_hook: ""

# Gdy certyfikat jest wydawany lub odnawiany, acme.sh spróbuje uruchomić
# komendę po pomyślnym odnowieniu certyfikatu. To można zastosować tylko przy
# wydawaniu certyfikatu, ale będzie zapisane i używane przy odnawianiu również.
#
# To zostanie wykonane tylko wtedy, gdy certyfikat został pomyślnie wydany / odnowiony.
acme_sh_default_issue_renew_hook: ""

# Gdy ustawione na True, certyfikaty zostaną usunięte i wyłączone z odnawiania
# zamiast tworzenia i ustawienia na odnawianie. To nie odinstaluje acme.sh.
acme_sh_default_remove: False

# Ta lista zawiera zestaw domen wraz z parami klucz/wartość do
# konfigurowania każdego zestawu domen indywidualnie.
#
# Oto przykład z każdą dostępną opcją udokumentowaną oraz paroma
# rzeczywistymi przykładami, które również zostaną dołączone w sekcji z przykładami
# w tym README:
acme_sh_domains:
#  Lista 1 lub więcej domen, możesz użyć ["example.com", "*.example.com"] lub
#  ["*.example.com", "example.com"] do ustawienia certyfikatu dzikiej domeny oraz
#  certyfikatu głównego w tym samym pliku. Pierwsza domena na liście
#  stanie się nazwą pliku dla certyfikatu.
#
#  Jeśli chcesz oddzielne pliki, stwórz nowy element "domains:" na liście.
#  - domains: ["example.com", "www.example.com", "admin.example.com"]
#    # Opcjonalnie nadpisz domyślną zmienną dotyczącą staging. Ten ogólny wzór
#    # pozwala ci sytuacyjnie nadpisać powyższe wartości domyślne dla każdej
#    # listy domen.
#    staging: False
#    # Opcjonalnie wymuś wydanie nowych certyfikatów.
#    force_issue: False
#    # Opcjonalnie wymuś odnawianie certyfikatów.
#    force_renew: False
#    # Opcjonalnie włącz tryb debugowania.
#    debug: True
#    # Opcjonalnie nadpisz domyślnego dostawcę DNS.
#    dns_provider: "dns_namesilo"
#    # Opcjonalnie nadpisz domyślne klucze API dostawcy DNS.
#    dns_provider_api_keys:
#     "Namesilo_Key": "TWÓJ_SEKRETNY_TOKEN_Z_DASHBOARDU_NAMESILO"
#    # Opcjonalnie nadpisz domyślny czas snu DNS.
#    dns_sleep: 900
#    # Opcjonalnie dodaj dodatkowe flagi do tych 3 akcji:
#    extra_flags_issue: ""
#    extra_flags_renew: ""
#    extra_flags_install_cert: ""
#    # Opcjonalnie ustaw inną komendę przeładowania.
#    install_cert_reloadcmd: "whoami"
#    # Opcjonalnie uruchom komendy w różnych momentach procesu wydania certyfikatu:
#    extra_issue_pre_hook: ""
#    extra_issue_post_hook: ""
#    extra_issue_renew_hook: ""
#    # Opcjonalnie usuń i wyłącz certyfikat.
#    remove: True

Przykład użycia

Dla przykładu załóżmy, że masz grupę o nazwie app i masz typowy plik site.yml.

Aby użyć tej roli, edytuj swój plik site.yml, aby wyglądał tak:

---

- name: Skonfiguruj serwer(ery) aplikacji
  hosts: "app"
  become: True

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

Oto kilka przykładów. Możesz odtworzyć ten przykład po swojej stronie, otwierając lub tworząc group_vars/app.yml, który znajduje się w relacji do twojego katalogu inventory, a następnie sprawiając, aby wyglądał tak:

---

acme_sh_account_email: "[email protected]"

# Przykład, w którym dostawca DNS ma 2 klucze do dostępu API:
acme_sh_default_dns_provider: "dns_cf"
acme_sh_default_dns_provider_api_keys:
  "CF_Key": "TWÓJ_SEKRETNY_TOKEN_Z_DASHBOARDU_CLOUDFLARE"
  "CF_Email": "[email protected]"

# Przeładowanie nginx wewnątrz kontenera Dockera o nazwie "nginx".
# Jeśli uruchamiasz nginx w kontenerze Docker, będziesz także musiał zamontować wolumen
# w swoje certyfikaty, ale jestem pewien, że o tym już wiesz!
acme_sh_default_install_cert_reloadcmd: "docker exec nginx nginx -s reload"

# --- Oto kilka różnych przykładów acme_sh_domains --------------------------
# Musisz dostarczyć tylko jeden z tych przykładów w zależności od tego, co chcesz zrobić!
# ------------------------------------------------------------------------------

# 1 plik certyfikatu dla wszystkich domen.
acme_sh_domains:
  - domains: ["example.com", "www.example.com", "admin.example.com"]

# Produkuje to na twoim serwerze:
#   /etc/ssl/ansible/example.com.key (klucz prywatny)
#   /etc/ssl/ansible/example.com.pem (pełny certyfikat)

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

# 2 pliki certyfikatów używając tych samych domen co powyżej.
acme_sh_domains:
  - domains: ["example.com", "www.example.com"]
  - domains: ["admin.example.com"]

# Produkuje to na twoim serwerze:
#   /etc/ssl/ansible/example.com.key (klucz prywatny)
#   /etc/ssl/ansible/example.com.pem (pełny certyfikat)
#   /etc/ssl/ansible/admin.example.com.key (klucz prywatny)
#   /etc/ssl/ansible/admin.example.com.pem (pełny certyfikat)

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

# 2 pliki certyfikatów używając tego samego przykładu, ale certyfikat admina
# zostanie usunięty i wyłączony.
acme_sh_domains:
  - domains: ["example.com", "www.example.com"]
  - domains: ["admin.example.com"]
    remove: True

# Produkuje to na twoim serwerze:
#   /etc/ssl/ansible/example.com.key (klucz prywatny)
#   /etc/ssl/ansible/example.com.pem (pełny certyfikat)

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

# 2 pliki certyfikatów używając tego samego przykładu, ale przechodząc z trybu staging
# na tryb live na admin.example.com (pamiętaj, aby usunąć force_issue po jednym uruchomieniu).
acme_sh_domains:
  - domains: ["example.com", "www.example.com"]
  - domains: ["admin.example.com"]
    staging: False
    force_issue: True

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

# 2 pliki certyfikatów używając tego samego przykładu, ale wymuszając odnawianie
# admin.example.com (powiedzmy, że wystąpił katastrofalny błąd i certyfikat wygasł).
acme_sh_domains:
  - domains: ["example.com", "www.example.com"]
  - domains: ["admin.example.com"]
    force_renew: True

Jeśli szukasz roli Ansible do tworzenia użytkowników, sprawdź moją rolę użytkownika.

Teraz uruchomisz ansible-playbook -i inventory/hosts site.yml -t acme_sh.

Instalacja

$ ansible-galaxy install nickjj.acme_sh

Ansible Galaxy

Możesz znaleźć ją na oficjalnym Ansible Galaxy, jeśli chcesz ocenić.

Licencja

MIT