Модуль community.crypto.acme_certificate — создание сертификатов SSL/TLS с помощью протокола ACME

Примечание

Этот модуль входит в коллекцию community.crypto (версия 3.2.1).

Возможно, эта коллекция уже установлена, если вы используете пакет ansible. Она не входит в ansible-core. Чтобы проверить, установлена ли она, выполните ansible-galaxy collection list.

Для установки используйте: ansible-galaxy collection install community.crypto. Для использования этого модуля требуются дополнительные компоненты. Подробности см. в разделе Требования.

Чтобы использовать модуль в плейбуке, укажите: community.crypto.acme_certificate.

Обзор
Требования
Параметры
Атрибуты
Примечания
См. также
Примеры
Возвращаемые значения

Обзор

Создание и обновление сертификатов SSL/TLS с помощью центра сертификации, поддерживающего протокол ACME, например Let’s Encrypt. Текущая реализация поддерживает проверки http-01, dns-01, dns-account-01, dns-persist-01 и tls-alpn-01.
Для использования этого модуля его необходимо выполнить дважды: либо в виде двух разных задач за один запуск, либо во время двух запусков. Обратите внимание: результат первого запуска необходимо сохранить и передать во второй запуск в качестве аргумента модуля data.
Между этими двумя задачами необходимо любым способом выполнить необходимые действия для выбранной проверки. Для http-01 это означает создание необходимого файла проверки на целевом веб-сервере. Для dns-01, dns-account-01 и dns-persist-01 необходимо создать соответствующие записи DNS. Для tls-alpn-01 необходимо создать и предоставить соответствующий сертификат. Выполнение этих действий не входит в обязанности этого модуля.
Чтобы узнать, как проходить эти проверки, возможно, потребуется ознакомиться с основной спецификацией ACME и спецификацией TLS-ALPN-01. Также ознакомьтесь с примерами для этого модуля.
Модуль поддерживает IP-идентификаторы в соответствии с RFC 8738.
Модуль экспериментально поддерживает тип проверки dns-account-01 в соответствии с черновиком acme-dns-account-label 02. Обратите внимание: поддерживаемая версия черновика может измениться в любое время, и изменения будут считаться несовместимыми только после того, как черновик получит статус RFC.
Модуль экспериментально поддерживает тип проверки dns-persist-01 в соответствии с черновиком acme-dns-persist 01. Обратите внимание: поддерживаемая версия черновика может измениться в любое время, и изменения будут считаться несовместимыми только после того, как черновик получит статус RFC.

Требования

Перечисленные ниже требования необходимы на узле, который выполняет этот модуль.

либо openssl
либо cryptography >= 3.3

Параметры

Параметр	Комментарии
account_email string	Он будет использоваться для предупреждений об истечении срока действия сертификата. Обратите внимание: если `modify_account` не задано в значение `false`, а также вы использовали модуль community.crypto.acme_account, чтобы указать для учетной записи более одного контактного адреса, этот модуль обновит учетную запись и ограничит список контактов адресом электронной почты (не более одного), указанным здесь.
account_key_content string	Содержимое ключа учетной записи ACME RSA или ключа на эллиптических кривых. Для ключей на эллиптических кривых поддерживаются только следующие кривые: `secp256r1`, `secp384r1` и `secp521r1`. Взаимоисключающий параметр с `account_key_src`. Обязателен, если не используется `account_key_src`. Предупреждение: содержимое будет записано во временный файл, который Ansible удалит после завершения работы модуля. Поскольку это важный закрытый ключ — его можно использовать для смены ключа учетной записи или отзыва сертификатов без знания их закрытых ключей, — такой вариант может быть неприемлем. Если используется `cryptography`, содержимое не записывается во временный файл. Однако Ansible все еще может записать его на диск в процессе перемещения модуля вместе с его аргументом на узел, где он выполняется.
account_key_passphrase string добавлено в community.crypto 1.6.0	Парольная фраза для расшифровки ключа учетной записи. Примечание: эта возможность не поддерживается модулем `openssl`, только модулем `cryptography`.
account_key_src псевдонимы: account_key path	Путь к файлу, содержащему ключ учетной записи ACME RSA или ключ на эллиптических кривых. Для ключей на эллиптических кривых поддерживаются только следующие кривые: `secp256r1`, `secp384r1` и `secp521r1`. Закрытые ключи можно создать с помощью модулей community.crypto.openssl_privatekey или community.crypto.openssl_privatekey_pipe. Если необходимая библиотека (cryptography) недоступна, ключи также можно создать непосредственно с помощью инструмента командной строки `openssl`: ключи RSA можно создать с помощью `openssl genrsa ...`. Ключи на эллиптических кривых можно создать с помощью `openssl ecparam -genkey ...`. Можно использовать и любые другие инструменты, создающие закрытые ключи в формате PEM. Взаимоисключающий параметр с `account_key_content`. Обязателен, если не используется `account_key_content`.
account_uri string	Если задано, предполагается, что URI учетной записи соответствует указанному значению. Если ключ учетной записи не соответствует этой учетной записи или учетная запись с таким URI не существует, выполнение модуля завершится ошибкой.
acme_directory string / обязательный	Каталог ACME, который следует использовать. Это URL-адрес точки входа для доступа к API сервера центра сертификации ACME. В целях безопасности по умолчанию используется тестовый сервер Let’s Encrypt (для протокола ACME v1). Он создает технически корректные, но недоверенные сертификаты. Все тестовые конечные точки Let’s Encrypt перечислены здесь: https://letsencrypt.org/docs/staging-environment/. Для Let’s Encrypt URL-адрес производственного каталога ACME v2: https://acme-v02.api.letsencrypt.org/directory. Для ZeroSSL URL-адрес производственного каталога ACME v2: https://acme.zerossl.com/v2/DV90. Для Sectigo URL-адрес производственного каталога ACME v2: https://acme-qa.secure.trust-provider.com/v2/DV. Для HARICA URL-адрес производственного каталога ACME v2: https://acme.harica.gr/XXX/directory, где XXX — значение, зависящее от учетной записи. В примечаниях к этому модулю приведен список служб ACME, с которыми он прошел тестирование.
acme_version integer	Версия ACME конечной точки. Для стандартизированных конечных точек ACME v2 должна быть указана `2`. Значение `1` больше не поддерживается начиная с community.crypto 3.0.0. Варианты: `2` ← (по умолчанию)
agreement string	URI документа с условиями предоставления услуг, с которыми вы соглашаетесь при использовании службы ACME v1 на `acme_directory`. По умолчанию используется последняя версия, полученная с URL-адреса `acme_directory`. Этот параметр больше не действует. Он устарел и будет удален из community.crypto 4.0.0.
chain_dest псевдонимы: chain path	Если задано, промежуточный сертификат будет записан в этот файл.
challenge string	Проверка, которую необходимо выполнить. Если задано значение `no challenge`, проверка выполняться не будет. Это необходимо для некоторых частных центров сертификации, использующих External Account Binding и другие способы проверки надежности сертификата. Например, учетной записи может быть разрешено выпускать сертификаты для `foo.example.com` без дополнительной проверки в течение определенного периода времени. Поддержка `dns-account-01` и `dns-persist-01` добавлена в community.crypto 3.2.0. Варианты: `"http-01"` ← (по умолчанию) `"dns-01"` `"dns-account-01"` `"dns-persist-01"` `"tls-alpn-01"` `"no challenge"`
csr псевдонимы: src path	Файл, содержащий запрос на сертификат (CSR) для нового сертификата. Его можно создать с помощью community.crypto.openssl_csr. CSR может содержать несколько альтернативных имен субъекта, но для каждого из них потребуется отдельная проверка, которую необходимо пройти, чтобы CSR был подписан. Примечание: закрытый ключ, использованный для создания CSR, не должен быть ключом учетной записи. С точки зрения безопасности это плохая идея, и центр сертификации не должен принимать CSR. В этом случае сервер ACME должен вернуть ошибку. Необходимо указать ровно один из параметров `csr` или `csr_content`.
csr_content string добавлено в community.crypto 1.2.0	Содержимое запроса на сертификат (CSR) для нового сертификата. Его можно создать с помощью community.crypto.openssl_csr_pipe. CSR может содержать несколько альтернативных имен субъекта, но для каждого из них потребуется отдельная проверка, которую необходимо пройти, чтобы CSR был подписан. Примечание: закрытый ключ, использованный для создания CSR, не должен быть ключом учетной записи. С точки зрения безопасности это плохая идея, и центр сертификации не должен принимать CSR. В этом случае сервер ACME должен вернуть ошибку. Необходимо указать ровно один из параметров `csr` или `csr_content`.
data dictionary	Данные для проверки выполняемых проверок. Их необходимо указать только при втором запуске модуля. Значение, которое следует использовать здесь, будет предоставлено при предыдущем использовании этого модуля. Дополнительные сведения см. в примерах. Обратите внимание: для ACME v2 будет использоваться только запись `order_uri` из `data`. Для ACME v1 параметр `data` должен быть непустым, чтобы указать на активность второго этапа; все необходимые данные будут взяты из CSR. Примечание: до Ansible 2.5 параметр `data` имел пометку `no_log`. Начиная с Ansible 2.6 эта пометка больше не используется, поскольку из-за нее сообщения об ошибках становились непригодными, а `data` не содержит информации, которую можно использовать без доступа к ключу учетной записи или которая в любом случае не является общедоступной.
deactivate_authzs boolean	Деактивировать объекты аутентификации (authz) после выдачи сертификата или в случае неудачной выдачи сертификата. Объекты аутентификации связаны с ключом учетной записи, остаются действительными в течение определенного времени и могут использоваться для выдачи сертификатов без повторной аутентификации домена. Это может представлять угрозу безопасности. Варианты: `false` ← (по умолчанию) `true`
dest псевдонимы: cert path	Файл назначения для сертификата. Обязателен, если не задан параметр `fullchain_dest`.
force boolean	Принудительно выполняет проверку и валидацию, даже если срок действия существующего сертификата истекает более чем через `remaining_days`. Это особенно полезно при обновлении CSR, например при добавлении доменов, для которых требуется новый сертификат. Варианты: `false` ← (по умолчанию) `true`
fullchain_dest псевдонимы: fullchain path	Файл назначения для полной цепочки (то есть сертификата, за которым следует цепочка промежуточных сертификатов). Обязателен, если не задан параметр `dest`.
include_renewal_cert_id string добавлено в community.crypto 2.20.0	Определяет, следует ли запрашивать продление существующего сертификата в соответствии с разделом 5 RFC 9773. Используется только в том случае, если сертификат, указанный в `dest` или `fullchain_dest`, уже существует. Как правило, следует использовать `when_ari_supported`, если известно, что служба ACME поддерживает совместимый черновик (или окончательную версию после ее публикации) расширения ARI. `always` не должно требоваться. Если вы не уверены или получаете странные ошибки из-за недопустимых значений `replaces` в объектах order, используйте `never` — это также значение по умолчанию. Серверы ACME могут отказаться создавать новые заказы с `replaces` для сертификатов, для которых уже существует заказ. Это может произойти, если этот модуль используется для создания заказа, а затем выполнение playbook/роли завершается ошибкой из-за невозможности настроить проверки. Если playbook/роль не сохраняет данные заказа для продолжения работы с существующим заказом, а при следующем запуске пытается создать новый, его создание может завершиться ошибкой. Если задано `order_creation_error_strategy=fail`, это приведет к сбою модуля. `order_creation_error_strategy=auto` и `order_creation_error_strategy=retry_without_replaces_cert_id` позволят избежать этого, не передавая `replaces` при повторных попытках. Если задано `order_creation_error_strategy=fail`, по вышеуказанной причине этому параметру следует присваивать значение, отличное от `never`, только в том случае, если использующая его роль/playbook отслеживает данные заказа между перезапусками или деактивирует заказы, обработка которых была прервана. Заказы можно деактивировать с помощью модуля community.crypto.acme_certificate_deactivate_authz. Варианты: `"always"`: всегда отправлять идентификатор сертификата, который нужно продлить. `"never"` (по умолчанию): никогда не отправлять идентификатор сертификата, который нужно продлить. `"when_ari_supported"`: отправлять идентификатор сертификата, только если в каталоге ACME обнаружена конечная точка ARI.
modify_account boolean	Логическое значение, определяющее, должен ли модуль при необходимости создавать учетную запись и обновлять ее контактные данные. Установите значение `false`, если вы хотите управлять учетной записью с помощью модуля community.crypto.acme_account и избежать случайного создания новой учетной записи со старым ключом, если ключ учетной записи был изменен с помощью community.crypto.acme_account. Если задано значение `false`, параметры `terms_agreed` и `account_email` игнорируются. Текущее значение по умолчанию `true` устарело и будет изменено на `false` в community.crypto 4.0.0. Варианты: `false` `true`
order_creation_error_strategy string добавлено в community.crypto 2.24.0	Выбирает стратегию обработки ошибок протокола ACME в случае сбоя при создании нового заказа ACME. Варианты: `"always"`: всегда повторять попытки, пока не будет достигнут предел, заданный в `order_creation_max_retries`. `"auto"` (по умолчанию): неуказанный алгоритм, который пытается действовать разумно. В настоящее время работает так же, как `retry_without_replaces_cert_id`. `"fail"`: просто завершать работу с ошибкой при возникновении ошибок. Не пытаться повторить запрос. До community.crypto 2.24.0 этот вариант использовался по умолчанию. `"retry_without_replaces_cert_id"`: если присутствует `include_renewal_cert_id`, будет предпринята повторная попытка создать заказ без `replaces`. Единственное исключение — ошибка типа `urn:ietf:params:acme:error:alreadyReplaced`, означающая, что сертификат уже заменен. Обычно это свидетельствует о проблеме, которую пользователю следует изучить.
order_creation_max_retries integer добавлено в community.crypto 2.24.0	В зависимости от стратегии, выбранной в `order_creation_error_strategy`, создание новых заказов будет повторяться не более указанного числа раз. По умолчанию: `3`
profile string добавлено в community.crypto 2.24.0	Выберите профиль для сертификата. Доступные профили зависят от центра сертификации. Дополнительные сведения см. в публикации в блоге Let’s Encrypt и в документе draft-aaron-acme-profiles-01.
remaining_days integer	Количество дней, в течение которых сертификат должен оставаться действительным. Если `cert_days` < `remaining_days`, сертификат будет продлен. Если сертификат не продлевается, возвращаемые модулем значения не будут содержать `challenge_data`. Чтобы гарантировать продление сертификата в любом случае, можно использовать параметр `force`. По умолчанию: `10`
request_timeout integer добавлено в community.crypto 2.3.0	Время, в течение которого Ansible должен ожидать ответа от API ACME. Это время ожидания применяется ко всем HTTP(S)-запросам (HEAD, GET, POST). По умолчанию: `10`
retrieve_all_alternates boolean	Если задано значение `true`, будут получены все альтернативные цепочки доверия, предлагаемые центром сертификации ACME. Они не будут записаны на диск, но будут возвращены вместе с основной цепочкой в качестве `all_chains`. Подробности см. в документации по возвращаемому значению `all_chains`. Варианты: `false` ← (по умолчанию) `true`
select_chain list / элементы=dictionary добавлено в community.crypto 1.0.0	Позволяет указать критерии выбора цепочки доверия (альтернативной или основной). Список критериев проверяется по очереди, пока не будет найдена цепочка, соответствующая одному из них. Если такая цепочка найдена, модуль использует ее вместо цепочки по умолчанию. Если критерию соответствуют несколько цепочек, будет возвращена первая подходящая. Порядок определяется последовательностью заголовков `Link`, возвращаемых сервером ACME, и может быть недетерминированным. Каждый критерий может состоять из нескольких разных условий, таких как `select_chain[].issuer` и `select_chain[].subject`. Чтобы цепочка соответствовала критерию, все условия должны выполняться для одного и того же сертификата в цепочке. Этот параметр можно использовать только с модулем `cryptography`.
authority_key_identifier string	Проверяет наличие расширения AuthorityKeyIdentifier. Это идентификатор, основанный на закрытом ключе издателя промежуточного сертификата. Идентификатор должен иметь формат `C4:A7:B1:A4:7B:2C:71:FA:DB:E1:4B:90:75:FF:C4:15:60:85:89:10`.
issuer dictionary	Позволяет указать части данных об издателе сертификата в цепочке, которым он должен соответствовать для выбора. Если `select_chain[].issuer` пуст, подойдет любой сертификат. Пример значения: `{"commonName": "My Preferred CA Root"}`.
subject dictionary	Позволяет указать части данных о субъекте сертификата в цепочке, которым он должен соответствовать для выбора. Если `select_chain[].subject` пуст, подойдет любой сертификат. Пример значения: `{"CN": "My Preferred CA Intermediate"}`.
subject_key_identifier string	Проверяет наличие расширения SubjectKeyIdentifier. Это идентификатор, основанный на закрытом ключе промежуточного сертификата. Идентификатор должен иметь формат `A8:4A:6A:63:04:7D:DD:BA:E6:D1:39:B7:A6:45:65:EF:F3:A8:EC:A1`.

test_certificates string	Определяет, какие сертификаты в цепочке будут проверяться. `all` проверяет все сертификаты в цепочке (за исключением конечного сертификата, который одинаков во всех цепочках). `first` проверяет только первый сертификат в цепочке, то есть сертификат, подписавший конечный сертификат. `last` проверяет только последний сертификат в цепочке, то есть сертификат, наиболее удалённый от конечного. Его издатель — корневой сертификат этой цепочки. Варианты: `"first"` `"last"` `"all"` ← (по умолчанию)
select_crypto_backend string	Определяет, какой криптографический движок использовать. По умолчанию выбирается `auto`: сначала модуль пытается использовать `cryptography`, если он доступен, а в противном случае использует `openssl`. Если задано значение `openssl`, модуль попытается использовать исполняемый файл `openssl`. Если задано значение `cryptography`, модуль попытается использовать библиотеку cryptography. Варианты: `"auto"` ← (по умолчанию) `"cryptography"` `"openssl"`
terms_agreed boolean	Логическое значение, указывающее, согласны ли вы с условиями предоставления услуг. Серверы ACME могут требовать, чтобы это значение было равно true. Варианты: `false` ← (по умолчанию) `true`
validate_certs boolean	Следует ли проверять TLS-сертификаты при обращении к каталогу ACME. Предупреждение: Значение `false` следует задавать только для тестирования, например при проверке на локальном сервере Pebble. Варианты: `false` `true` ← (по умолчанию)

Атрибуты

Атрибут	Поддержка	Описание
action_group	Группы действий: community.crypto.acme, acme	Используйте `group/acme` или `group/community.crypto.acme` в `module_defaults`, чтобы задать значения по умолчанию для этого модуля.
check_mode	Поддержка: полная	Может работать в режиме `check_mode` и возвращать прогноз изменения состояния, не изменяя целевой объект.
diff_mode	Поддержка: отсутствует	В режиме diff будут возвращены сведения об изменениях (или о возможных изменениях в `check_mode`).
idempotent	Поддержка: частичная Если `force=true`, модуль не является идемпотентным. Если `force=false`, это зависит от срока действия сертификата и значения `remaining_days`. Повторный вызов модуля на втором этапе всегда идемпотентен, если не возникает ошибок.	При двух последовательных запусках вне режима проверки с одинаковыми аргументами второй вызов не сообщает об изменениях. Предполагается, что система, которой управляет модуль или к которой он обращается, не изменилась существенным образом.
safe_file_operations	Поддержка: полная	Использует строгие функции Ansible для работы с файлами, чтобы обеспечить правильные разрешения и избежать повреждения данных.

Примечания

Примечание

Необходимо указать как минимум один из параметров dest и fullchain_dest.
Этот модуль включает базовые функции управления учётной записью. Чтобы управлять учётной записью ACME более гибко, используйте модуль community.crypto.acme_account и отключите управление учётной записью для этого модуля с помощью параметра modify_account.
До Ansible 2.6 этот модуль назывался letsencrypt. Способ его использования не изменился.
Хотя значения по умолчанию подобраны так, чтобы модуль можно было использовать с CA Let’s Encrypt, в принципе его можно использовать с любым центром сертификации, предоставляющим конечную точку ACME.
На данный момент разработчики тестировали модули ACME только с Let’s Encrypt (тестовая и рабочая среды), ZeroSSL (рабочая среда) и тестовым сервером Pebble. Сообщество также сообщало, что модули работают с Sectigo ACME Service для InCommon и с HARICA. Если у вас возникли проблемы с другим сервером ACME, пожалуйста, создайте задачу, чтобы помочь нам обеспечить его поддержку. Мы также будем благодарны за сообщения о том, что сервер ACME, не упомянутый здесь, работает.
Если доступна достаточно новая версия библиотеки cryptography (подробности см. в разделе «Требования»), вместо исполняемого файла openssl будет использоваться эта библиотека. Это можно явно отключить или включить с помощью параметра select_crypto_backend. Обратите внимание: использование исполняемого файла openssl будет медленнее и менее безопасно, так как закрытый ключ всегда приходится хранить на диске (см. account_key_content).

См. также

Документация Let’s Encrypt: Документация центра сертификации Let’s Encrypt. Содержит полезные сведения, например об ограничениях частоты запросов.
Среда автоматического управления сертификатами (ACME): Спецификация протокола ACME (RFC 8555).
Расширение ACME TLS ALPN Challenge: Спецификация проверки tls-alpn-01 (RFC 8737).
community.crypto.acme_challenge_cert_helper: Помогает подготовить проверки tls-alpn-01.
community.crypto.openssl_privatekey: Можно использовать для создания закрытых ключей (как для сертификатов, так и для учётных записей).
community.crypto.openssl_privatekey_pipe: Можно использовать для создания закрытых ключей без записи на диск (как для сертификатов, так и для учётных записей).
community.crypto.openssl_csr: Можно использовать для создания запроса на подпись сертификата (CSR).
community.crypto.openssl_csr_pipe: Можно использовать для создания запроса на подпись сертификата (CSR) без записи на диск.
community.crypto.certificate_complete_chain: Позволяет найти корневой сертификат для возвращённой полной цепочки.
community.crypto.acme_certificate_revoke: Позволяет отзывать сертификаты.
community.crypto.acme_account: Позволяет создавать, изменять и удалять учётную запись ACME.
community.crypto.acme_inspect: Позволяет отлаживать проблемы.
community.crypto.acme_certificate_deactivate_authz: Позволяет деактивировать (аннулировать) заказы ACME v2.

Примеры

---
### Example with HTTP challenge ###

- name: Create a challenge for sample.com using a account key from a variable.
  community.crypto.acme_certificate:
    account_key_content: "{{ account_private_key }}"
    csr: /etc/pki/cert/csr/sample.com.csr
    dest: /etc/httpd/ssl/sample.com.crt
    modify_account: false
  register: sample_com_challenge

# Alternative first step:
- name: Create a challenge for sample.com using a account key from Hashi Vault.
  community.crypto.acme_certificate:
    account_key_content: >-
      {{ lookup('community.hashi_vault.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
    modify_account: false
  register: sample_com_challenge

# Alternative first step:
- name: Create a challenge for sample.com using a account key file.
  community.crypto.acme_certificate:
    account_key_src: /etc/pki/cert/private/account.key
    csr_content: "{{ lookup('file', '/etc/pki/cert/csr/sample.com.csr') }}"
    dest: /etc/httpd/ssl/sample.com.crt
    fullchain_dest: /etc/httpd/ssl/sample.com-fullchain.crt
    modify_account: false
  register: sample_com_challenge

# perform the necessary steps to fulfill the challenge
# for example:
#
# - name: Copy http-01 challenge for sample.com
#   ansible.builtin.copy:
#     dest: /var/www/html/{{ sample_com_challenge['challenge_data']['sample.com']['http-01']['resource'] }}
#     content: "{{ sample_com_challenge['challenge_data']['sample.com']['http-01']['resource_value'] }}"
#   when: sample_com_challenge is changed and 'sample.com' in sample_com_challenge['challenge_data']
#
# Alternative way:
#
# - name: Copy http-01 challenges
#   ansible.builtin.copy:
#     dest: /var/www/{{ item.key }}/{{ item.value['http-01']['resource'] }}
#     content: "{{ item.value['http-01']['resource_value'] }}"
#   loop: "{{ sample_com_challenge.challenge_data | dict2items }}"
#   when: sample_com_challenge is changed

- name: Let the challenge be validated and retrieve the cert and intermediate certificate
  community.crypto.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
    fullchain_dest: /etc/httpd/ssl/sample.com-fullchain.crt
    chain_dest: /etc/httpd/ssl/sample.com-intermediate.crt
    data: "{{ sample_com_challenge }}"
    modify_account: false

---
### Example with DNS challenge against production ACME server ###

- name: Create a challenge for sample.com using a account key file.
  community.crypto.acme_certificate:
    account_key_src: /etc/pki/cert/private/account.key
    account_email: myself@sample.com
    src: /etc/pki/cert/csr/sample.com.csr
    cert: /etc/httpd/ssl/sample.com.crt
    challenge: dns-01
    acme_directory: https://acme-v01.api.letsencrypt.org/directory
    # Renew if the certificate is at least 30 days old
    remaining_days: 60
    modify_account: false
  register: sample_com_challenge

# perform the necessary steps to fulfill the challenge
# for example:
#
# - name: Create DNS record for sample.com dns-01 challenge
#   community.aws.route53:
#     zone: sample.com
#     record: "{{ sample_com_challenge.challenge_data['sample.com']['dns-01'].record }}"
#     type: TXT
#     ttl: 60
#     state: present
#     wait: true
#     # Note: route53 requires TXT entries to be enclosed in quotes
#     value: "{{ sample_com_challenge.challenge_data['sample.com']['dns-01'].resource_value | community.dns.quote_txt(always_quote=true) }}"
#   when: sample_com_challenge is changed and 'sample.com' in sample_com_challenge.challenge_data
#
# Alternative way:
#
# - name: Create DNS records for dns-01 challenges
#   community.aws.route53:
#     zone: sample.com
#     record: "{{ item.key }}"
#     type: TXT
#     ttl: 60
#     state: present
#     wait: true
#     # Note: item.value is a list of TXT entries, and route53
#     # requires every entry to be enclosed in quotes
#     value: "{{ item.value | map('community.dns.quote_txt', always_quote=true) | list }}"
#   loop: "{{ sample_com_challenge.challenge_data_dns | dict2items }}"
#   when: sample_com_challenge is changed

- name: Let the challenge be validated and retrieve the cert and intermediate certificate
  community.crypto.acme_certificate:
    account_key_src: /etc/pki/cert/private/account.key
    account_email: myself@sample.com
    src: /etc/pki/cert/csr/sample.com.csr
    cert: /etc/httpd/ssl/sample.com.crt
    fullchain: /etc/httpd/ssl/sample.com-fullchain.crt
    chain: /etc/httpd/ssl/sample.com-intermediate.crt
    challenge: dns-01
    acme_directory: https://acme-v01.api.letsencrypt.org/directory
    remaining_days: 60
    data: "{{ sample_com_challenge }}"
    modify_account: false
  when: sample_com_challenge is changed

# Alternative second step:
- name: Let the challenge be validated and retrieve the cert and intermediate certificate
  community.crypto.acme_certificate:
    account_key_src: /etc/pki/cert/private/account.key
    account_email: myself@sample.com
    src: /etc/pki/cert/csr/sample.com.csr
    cert: /etc/httpd/ssl/sample.com.crt
    fullchain: /etc/httpd/ssl/sample.com-fullchain.crt
    chain: /etc/httpd/ssl/sample.com-intermediate.crt
    challenge: tls-alpn-01
    remaining_days: 60
    data: "{{ sample_com_challenge }}"
    # We use Let's Encrypt's ACME v2 endpoint
    acme_directory: https://acme-v02.api.letsencrypt.org/directory
    # The following makes sure that if a chain with /CN=DST Root CA X3 in its issuer is provided
    # as an alternative, it will be selected. These are the roots cross-signed by IdenTrust.
    # As long as Let's Encrypt provides alternate chains with the cross-signed root(s) when
    # switching to their own ISRG Root X1 root, this will use the chain ending with a cross-signed
    # root. This chain is more compatible with older TLS clients.
    select_chain:
      - test_certificates: last
        issuer:
          CN: DST Root CA X3
          O: Digital Signature Trust Co.
    modify_account: false
  when: sample_com_challenge is changed

Возвращаемые значения

Общие возвращаемые значения описаны здесь; ниже перечислены поля, относящиеся только к этому модулю:

Ключ	Описание
account_uri string	URI учётной записи ACME. Возвращается: changed
all_chains list / elements=dictionary	Если для `retrieve_all_alternates` задано значение `true`, модуль запросит у сервера ACME альтернативные цепочки. Это возвращаемое значение содержит список всех полученных цепочек; первая запись — основная цепочка, возвращённая сервером. Подробнее см. раздел 7.4.2 RFC 8555. Возвращается: если сертификат получен и для `retrieve_all_alternates` задано значение `true`
cert string	Сам конечный сертификат в формате PEM. Возвращается: всегда
chain string	Цепочка сертификатов без корневого сертификата, представленная объединёнными сертификатами PEM. Возвращается: всегда
full_chain string	Цепочка сертификатов без корневого сертификата, но с конечным сертификатом, представленная объединёнными сертификатами PEM. Возвращается: всегда
authorizations dictionary	Данные авторизации ACME. Сопоставляет идентификатор с объектами авторизации ACME. См. https://tools.ietf.org/html/rfc8555#section-7.1.4. Возвращается: changed Пример: `{"example.com": {"challenges": [{"status": "valid", "token": "A5b1C3d2E9f8G7h6", "type": "http-01", "url": "https://example.org/acme/challenge/12345", "validated": "2022-08-01T01:01:02.34Z"}], "expires": "2022-08-04T01:02:03.45Z", "identifier": {"type": "dns", "value": "example.com"}, "status": "valid", "wildcard": false}}`
cert_days integer	Количество дней, в течение которых сертификат остаётся действительным. Возвращается: при успешном выполнении
challenge_data dictionary	Данные проверки для каждой пары «идентификатор / тип проверки». Начиная с Ansible 2.8.5 возвращаются только проверки, которые ещё не действительны. Возвращается: changed
identifier dictionary	Для каждого идентификатора предоставляет словарь типов проверок, сопоставленных с данными проверок. Ключами этого словаря являются идентификаторы. `identifier` — заполнитель, используемый в документации. Обратите внимание, что эти ключи не являются допустимыми идентификаторами Jinja2. Возвращается: changed
challenge-type dictionary	Данные для каждого типа проверки. Ключами этого словаря являются типы проверок. `challenge-type` — заполнитель, используемый в документации. Возможные ключи: `http-01`, `dns-01`, `dns-account-01`, `dns-persist-01` и `tls-alpn-01`. Обратите внимание, что эти ключи не являются допустимыми идентификаторами Jinja2. Обратите внимание: это возвращаемое значение для проверок `dns-account-01` и `dns-persist-01` является экспериментальным и может измениться с нарушением обратной совместимости даже в минорных выпусках, пока черновики acme-dns-account-label и acme-dns-persist соответственно не перейдут в более стабильное состояние. Возвращается: changed
account_uri string	URI учётной записи, который необходимо указать в записи DNS TXT. Обратите внимание: тип этого возвращаемого значения может измениться с нарушением обратной совместимости даже в минорных выпусках, пока черновик acme-dns-persist не перейдёт в более стабильное состояние. Это поле проверки в настоящее время обсуждается в рабочей группе ACME. Возвращается: при изменении, если проверка — `dns-persist-01` Пример: `"https://ca.example/acct/123"`
issuer_domain_names list / elements=string	Одно из доменных имён издателя необходимо указать в записи DNS TXT. Возвращается: при изменении, если проверка — `dns-persist-01` Пример: `["letsencrypt.org"]`
record string	Полное имя DNS-записи для проверки. Возвращается: при изменении, если тип проверки — `dns-01` или `dns-account-01` Пример: `"_acme-challenge.example.com"`
resource string	Ресурс проверки, который необходимо создать для проверки подлинности. Возвращается: при изменении, если тип проверки не `dns-persist-01` Пример: `".well-known/acme-challenge/evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA"`
resource_original string	Исходный ресурс проверки, включая идентификатор типа для проверок `tls-alpn-01`. Возвращается: при изменении, если `challenge` — `tls-alpn-01` Пример: `"DNS:example.com"`
resource_value string	Значение, которое должен выдавать ресурс для прохождения проверки. Для проверок `http-01`, `dns-01` и `dns-account-01` это значение можно использовать без изменений. Для проверок `tls-alpn-01` обратите внимание, что это возвращаемое значение содержит закодированную в Base64 версию правильного двоичного блока, который необходимо поместить в расширение acmeValidation x509; подробности см. на странице https://www.rfc-editor.org/rfc/rfc8737.html#section-3. Для этого может понадобиться фильтр Jinja ansible.builtin.b64decode, чтобы извлечь двоичный блок из этого возвращаемого значения. Возвращается: при изменении, если тип проверки не `dns-persist-01` Пример: `"IlirfxKKXA...17Dt3juxGJ-PCt92wr-oA"`
challenge_data_dns dictionary	Список значений TXT для каждой записи DNS, если тип проверки — `dns-01` или `dns-account-01`. Начиная с Ansible 2.8.5 возвращаются только проверки, которые ещё не действительны. Возвращается: changed
finalization_uri string	URI финализации ACME. Возвращается: changed
order_uri string	URI заказа ACME. Возвращается: changed

Авторы

Michael Gruener (@mgruener)

Ссылки на коллекцию

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/community/crypto/acme_certificate_module.html