acme_sh

Что такое ansible-acme-sh?

Это Ansible роль для:

• Установки acme.sh для получения, обновления или удаления SSL-сертификатов Let's Encrypt.
• Получения сертификатов для единичных, нескольких илиWildcard доменов.
• Настройки нескольких доменов через один сертификат или отдельные сертификаты.
• Проведения DNS-тестов, используя автоматизированный DNS API функционал acme.sh.
• Выполнения пользовательских команд acme.sh, если стандартные настройки вам не подходят.

Зачем использовать эту роль?

Эта роль использует acme.sh, который представляет собой самодостаточный Bash-скрипт для обработки всех сложностей получения и автоматического обновления ваших SSL-сертификатов.

Цели этой роли — быть высоко настроенной, при этом иметь разумные настройки по умолчанию, чтобы вы могли начать, указав только список доменных имен, указав своего поставщика DNS и API-ключ.

Она также идемпотентна для каждой задачи, поскольку именно так я работаю!

Почему поддерживаются только DNS-тесты?

Проведение тестов через DNS означает, что вы можете настроить свои сертификаты до того, как ваш веб-сервер или прокси будет подготовлен. Это также значит, что вашему веб-серверу не нужно знать, как работает тест ACME. Все, что вам нужно сделать, это ссылаться на финальные сертификаты, которые генерирует эта роль.

Еще одно преимущество состоит в том, что если вы запускаете веб-сервер внутри Docker, возможно, он не будет запущен до того, как ваш сервер будет настроен Ansible. Например, обычно настраивают git-развертывания для запуска развертывания приложения.

Кроме того, хорошо использовать DNS-тесты, потому что DNS-тесты — единственный способ получения wildcard сертификатов с помощью Let's Encrypt. Сосредоточение усилий на одном решении, которое работает со всеми типами сертификатов, было правильным шагом.

С учетом сказанного, я, вероятно, не буду поддерживать другие методы, такие как standalone, webroot, nginx или Apache, но ничего не окончательно.

Поддерживаемые платформы

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

Переменные роли

# Пользователь в системе, от имени которого будет выполняться acme.sh. Учтите, что этот пользователь
# должен уже существовать, эта роль не создаст его.
acme_sh_become_user: "root"

# Зависимости пакета acme.sh. Значения по умолчанию предназначены для Debian / Ubuntu.
# Для CentOS и Fedora вы можете заменить "cron" на "crond".
acme_sh_dependencies: ["cron", "git", "wget"]

# Репозиторий acme.sh для клонирования.
acme_sh_git_url: "https://github.com/acmesh-official/acme.sh"

# Ветка, тег или коммит, который будет клонирован.
acme_sh_git_version: "master"

# По умолчанию, если вы клонируете этот репозиторий сейчас, а затем через 6 месяцев снова,
# он останется на старой версии master, полученной 6 месяцев назад.
# Если вы хотите получать последнюю версию master при каждом запуске, установите это значение в True.
acme_sh_git_update: False

# Куда будет клонирован этот репозиторий?
acme_sh_git_clone_dest: "/usr/local/src/acme.sh"

# Когда включено, acme.sh будет обновлять себя до последней версии, что отличается от обновления git-репозитория.
# Это связано с тем, что acme.sh устанавливает себя с помощью инсталлятора после клонирования исходного кода.
#
# Включение этой функции может быть полезно для получения последнего релиза, который может содержать исправления,
# но имейте в виду, что если вы это сделаете, вы можете получить разные результаты при каждом запуске. Я
# рекомендую периодически ставить это значение в True, но обычно держать его отключенным.
acme_sh_upgrade: False

# Когда включено, клонированный исходный код, путь установки, файлы журнала и задания cron по обновлению
# будут удалены.
#
# Установленные сертификаты не будут удалены. Если вы хотите удалить установленные сертификаты, есть другая опция для этого,
# которую мы рассмотрим позже.
acme_sh_uninstall: False

# При создании первоначальной учетной записи Let's Encrypt вы можете опционально указать
# адрес электронной почты. По умолчанию это значение не установлено, но вы можете добавить свой адрес.
# Если вы его установите, вы получите сообщение по электронной почте, когда ваши сертификаты
# будут находиться в 20 днях от истечения срока.
#
# Я настоятельно рекомендую установить это значение, потому что, если все будет идти по плану,
# вы никогда не получите письмо, если acme.sh не сбойнет и не обновит сертификат.
acme_sh_account_email: ""

# Сертификаты будут обновляться через задание cron, управляемое acme.sh. По умолчанию
# acme.sh использует 60 дней для каждой попытки обновления, но я выбрал 30
# по умолчанию, чтобы дать одну дополнительную попытку на случай неожиданных ситуаций.
#
# Сертификаты, которые не нуждаются в обновлении, будут пропущены acme.sh, так что
# все в порядке. Также стоит упомянуть, что это значение не может превышать 60 дней,
# что является ограничением, установленным acme.sh, эта роль не проверяет значение.
acme_sh_renew_time_in_days: 30

# Базовый путь, куда будут скопированы сертификаты. Если вы знакомы с
# acme.sh, это путь для сертификатов, сгенерированных с помощью --install-cert.
#
# Это окончательное назначение для ваших сертификатов, и выбранный вами пользователь
# должен иметь доступ на запись в этот путь. Этот путь будет иметь
# владельца:группу, установленную на значение acme_sh_become_user.
acme_sh_copy_certs_to_path: "/etc/ssl/ansible"

# В конце выполнения команды Ansible выведет отладочное сообщение со списком
# доменов, для которых есть действительные SSL-сертификаты, а также с их
# датами истечения. Вы можете отключить это, установив значение False.
acme_sh_list_domains: True

# Когда установлено в False, будет использоваться работающий сервер Let's Encrypt,
# поэтому убедитесь, что все работает с явным значением True, иначе вы можете оказаться в ситуации,
# когда лимит превышен.
#
# Стоит упомянуть, что вам нужно будет принудительно получить новый сертификат
# при переключении между тестовой и рабочей средой.
acme_sh_default_staging: True

# Когда установлено в True, это будет генерировать новый сертификат, даже если ваш список
# доменов не изменился. Это также используется для установки нового поставщика DNS и API-ключей.
#
# Будьте осторожны с этим, так как вы можете попасть под ограничение скорости на
# рабочем сервере. Рассматривайте это только для обновления вашего DNS-поставщика. Вы должны вернуть
# это значение на False, когда закончите.
acme_sh_default_force_issue: False

# Когда установлено в True, это создаст новый сертификат для уже существующего списка
# сертификатов. Это не обновит вашего поставщика DNS или API-ключи.
#
# Это может быть полезно, если ваши сертификаты истекли. Вам следует вернуть это значение
# на False, когда закончите.
acme_sh_default_force_renew: False

# Когда установлено в True, это предоставит более подробную информацию в STDOUT. Это
# может быть полезно, если вы тестируете роль в режиме тестирования.
acme_sh_default_debug: False

# Какого поставщика DNS вы должны использовать?
# Список поддерживаемых поставщиков можно найти по ссылке:
#   https://github.com/acmesh-official/acme.sh/tree/master/dnsapi
# Что касается названия, которое нужно использовать, вы также можете найти его по указанному выше URL.
#
# По умолчанию используется DigitalOcean. Убедитесь, что вы включили части dns_ в названии,
# но пропустите расширение .sh.
acme_sh_default_dns_provider: "dns_dgon"

# Какие API-ключи вашего поставщика DNS?
# Имена ключей можно найти по адресу:
#   https://github.com/acmesh-official/acme.sh/tree/master/dnsapi
#
# API-ключ можно создать на веб-сайте вашего поставщика DNS. Некоторые поставщики
# требуют 1 ключ, в то время как другим требуется 2 и более. Просто добавьте их как пары ключ/значение здесь
# без "export ".
#
# Например, если вы используете DigitalOcean, вы бы ввели:
#    acme_sh_default_dns_provider_api_keys:
#      "DO_API_KEY": "THE_API_SECRET_TOKEN_FROM_THE_DO_DASHBOARD"
acme_sh_default_dns_provider_api_keys: {}

# Как долго должен спать acme.sh после попытки установить TXT-запись в ваших
# DNS-записях? Некоторые поставщики DNS обновляются не так быстро, как другие.
#
# 120 — это значение по умолчанию из acme.sh, но имейте в виду, что, если вы используете
# NameSilo, их DNS обновления происходят только один раз за 15 минут, так что вам нужно
# установить это значение на 900 или вы рискуете получить ошибку DNS NXDOMAIN.
#
# Я рекомендую оставлять его на уровне 120 или выше, если ваш поставщик DNS требует этого.
#
# Хотя в дополнение, я использовал 10 при тестировании этой роли на DigitalOcean
# и это сработало около 30 раз подряд. Все же, в рабочей среде я бы установил 120,
# чтобы быть в безопасности, потому что эта 2-минутная задержка повлияет на вас только при первом
# запуске Ansible. После этого это будет обновлено в фоновом режиме через задание cron.
acme_sh_default_dns_sleep: 120

# При выдаче новых сертификатов вы можете выбрать добавление дополнительных флагов,
# которые по умолчанию не присутствуют здесь. Укажите их так же, как на командной
# строке, например, "--help".
acme_sh_default_extra_flags_issue: ""

# При обновлении сертификатов вы можете выбрать добавление дополнительных флагов,
# которые по умолчанию не присутствуют здесь. Укажите их так же, как на командной
# строке, например, "--help".
acme_sh_default_extra_flags_renew: ""

# При установке сертификатов вы можете выбрать добавление дополнительных флагов,
# которые по умолчанию не присутствуют здесь. Укажите их так же, как на командной
# строке, например, "--help".
#
# Установка отличается от выдачи, и мы обсудим это позже.
acme_sh_default_extra_flags_install_cert: ""

# Когда сертификат выдан или обновлен, acme.sh попытается выполнить команду
# по вашему выбору. Это может быть перезапуск или перезагрузка вашего веб-сервера или прокси.
#
# Имейте в виду, что пользователь, которого вы установили в acme_sh_become_user, должен иметь права доступа к
# sudo, если вы используете sudo здесь, или, если нет, он должен иметь права на перезагрузку вашего
# веб-сервера / прокси.
#
# Для примера с Docker, смотрите раздел примеров в этом README.
acme_sh_default_install_cert_reloadcmd: "sudo systemctl reload nginx"

# Если вам требуется более детальный контроль, чем reloadcmd, вы можете подключиться к
# жизненному циклу выдачи или обновления сертификата. По умолчанию следующие 3
# опции ничего не делают, если вы их не заполните. Они не необходимы для
# функционирования, пока работает ваш reloadcmd.
#
# Когда сертификат выдан или обновлен, acme.sh попытается выполнить команду
# перед попыткой выдать сертификат. Это может быть применимо только во время
# выдачи сертификата, но оно будет сохранено и использовано для обновления также.
#
# Эта команда будет выполнена, даже если сертификат не был успешно выдан / обновлен.
acme_sh_default_issue_pre_hook: ""

# Когда сертификат выдан или обновлен, acme.sh попытается выполнить команду
# после попытки выдать сертификат. Это может быть применимо только во время
# выдачи сертификата, но оно будет сохранено и использовано для обновления также.
#
# Эта команда будет выполнена, даже если сертификат не был успешно выдан / обновлен.
acme_sh_default_issue_post_hook: ""

# Когда сертификат выдан или обновлен, acme.sh попытается выполнить команду
# после успешного обновления сертификата. Это может быть применимо только во время
# выдачи сертификата, но оно будет сохранено и использовано для обновления также.
#
# Эта команда будет выполнена только в случае успешной выдачи / обновления сертификата.
acme_sh_default_issue_renew_hook: ""

# Когда установлено в True, сертификаты будут удалены и отменены для обновления
# вместо создания и установки для обновления. Это не удалит acme.sh.
acme_sh_default_remove: False

# Этот список содержит домены, а также ключи / значения для
# индивидуальной настройки каждого набора доменов.
#
# Вот пример со всеми доступными опциями, задокументированными, а также несколько
# реальных примеров будут также включены в раздел примеров этого README:
acme_sh_domains:
#  Список из 1 или более доменов, вы можете использовать ["example.com", "*.example.com"] или
#  ["*.example.com", "example.com"] для настройки wildcard сертификата вместе
#  с корневым доменом в одном файле. Первый домен в списке
#  будет использован в качестве базового имени файла для имени сертификата.
#
#  Если вы хотите отдельные файлы, создайте новый элемент "domains:" в списке.
#  - domains: ["example.com", "www.example.com", "admin.example.com"]
#    # Опционально переопределить переменную staging по умолчанию. Этот общий шаблон позволяет
#    # вам по ситуации переопределять умолчания, указанные выше, для каждого списка доменов.
#    staging: False
#    # Опционально принудительно выдать новые сертификаты.
#    force_issue: False
#    # Опционально принудительно обновить сертификаты.
#    force_renew: False
#    # Опционально включить режим отладки.
#    debug: True
#    # Опционально переопределить поставщика DNS по умолчанию.
#    dns_provider: "dns_namesilo"
#    # Опционально переопределить ключи API DNS по умолчанию.
#    dns_provider_api_keys:
#     "Namesilo_Key": "THE_API_SECRET_TOKEN_FROM_THE_NAMESILO_DASHBOARD"
#    # Опционально переопределить время ожидания DNS по умолчанию.
#    dns_sleep: 900
#    # Опционально добавить дополнительные флаги к любому из этих 3 действий:
#    extra_flags_issue: ""
#    extra_flags_renew: ""
#    extra_flags_install_cert: ""
#    # Опционально установить другую команду перезагрузки.
#    install_cert_reloadcmd: "whoami"
#    # Опционально запустить команды в разные моменты процесса выдачи сертификата:
#    extra_issue_pre_hook: ""
#    extra_issue_post_hook: ""
#    extra_issue_renew_hook: ""
#    # Опционально удалить и отключить сертификат.
#    remove: True

Пример использования

Для этого примера давайте предположим, что у вас есть группа под названием app и у вас есть типичный файл site.yml.

Чтобы использовать эту роль, отредактируйте ваш файл site.yml, чтобы он выглядел примерно так:

---

- name: Настроить сервер(ы) приложения
  hosts: "app"
  become: True

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

Вот несколько примеров. Вы можете воспроизвести этот пример на своей стороне, открыв или создав group_vars/app.yml, который находится относительно вашего каталога inventory и сделав его таким:

---

acme_sh_account_email: "[email protected]"

# Пример, где у поставщика DNS есть 2 ключа для доступа к API:
acme_sh_default_dns_provider: "dns_cf"
acme_sh_default_dns_provider_api_keys:
  "CF_Key": "THE_API_SECRET_TOKEN_FROM_THE_CLOUDFLARE_DASHBOARD"
  "CF_Email": "[email protected]"

# Перезагрузка nginx внутри контейнера Docker с именем "nginx".
# Если вы запускаете nginx в контейнере Docker, вам также потребуется подключить
# ваши сертификаты, но я уверен, что вы это уже знали!
acme_sh_default_install_cert_reloadcmd: "docker exec nginx nginx -s reload"

# --- Вот несколько примеров acme_sh_domains -----------------------------
# Вам нужно будет предоставить только один из этих вариантов, в зависимости от того, что вы хотите сделать!
# -----------------------------------------------------------------------

# 1 файл сертификата для всех доменов.
acme_sh_domains:
  - domains: ["example.com", "www.example.com", "admin.example.com"]

# Создает это на вашем сервере:
#   /etc/ssl/ansible/example.com.key (закрытый ключ)
#   /etc/ssl/ansible/example.com.pem (полный сертификат)

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

# 2 файла сертификата, используя те же домены, что и выше.
acme_sh_domains:
  - domains: ["example.com", "www.example.com"]
  - domains: ["admin.example.com"]

# Создает это на вашем сервере:
#   /etc/ssl/ansible/example.com.key (закрытый ключ)
#   /etc/ssl/ansible/example.com.pem (полный сертификат)
#   /etc/ssl/ansible/admin.example.com.key (закрытый ключ)
#   /etc/ssl/ansible/admin.example.com.pem (полный сертификат)

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

# 2 файла сертификата, используя тот же пример, но сертификат admin будет удален и отключен.
acme_sh_domains:
  - domains: ["example.com", "www.example.com"]
  - domains: ["admin.example.com"]
    remove: True

# Создает это на вашем сервере:
#   /etc/ssl/ansible/example.com.key (закрытый ключ)
#   /etc/ssl/ansible/example.com.pem (полный сертификат)

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

# 2 файла сертификата, используя тот же пример, но переключаясь с тестовой на рабочую среду
# на admin.example.com (но не забудьте удалить force_issue после одного запуска).
acme_sh_domains:
  - domains: ["example.com", "www.example.com"]
  - domains: ["admin.example.com"]
    staging: False
    force_issue: True

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

# 2 файла сертификата, используя тот же пример, но принудительно обновляя на
# admin.example.com (скажем, произошла катастрофическая ошибка, и сертификат истек).
acme_sh_domains:
  - domains: ["example.com", "www.example.com"]
  - domains: ["admin.example.com"]
    force_renew: True

Если вы ищете роль Ansible для создания пользователей, то посмотрите на мою роль пользователя.

Теперь вы можете запустить ansible-playbook -i inventory/hosts site.yml -t acme_sh.

Установка

$ ansible-galaxy install nickjj.acme_sh

Ansible Galaxy

Вы можете найти ее на официальном Ansible Galaxy, если хотите оценить ее.

Лицензия

MIT