Ошибка «configuration requires vault but no vault provided» возникает в Ansible, когда плейбук или роль содержит зашифрованные через Ansible Vault данные, но при запуске не передан ни пароль, ни файл с ключом для их расшифровки. Ansible видит блок, начинающийся с заголовка $ANSIBLE_VAULT, пытается его расшифровать и останавливается, поскольку секрет недоступен.
Проблема типична для двух сценариев: либо в проекте действительно есть зашифрованные переменные, а разработчик забыл указать способ их расшифровки, либо файл был случайно зашифрован (или скопирован из другого проекта), и конфигурация «тянет» его за собой. Ниже разберём, как определить источник ошибки и устранить её без риска для секретов.
Что означает эта ошибка
Ansible Vault — встроенный механизм шифрования чувствительных данных: паролей, токенов, ключей API. Зашифрованный файл или переменная хранятся в репозитории в безопасном виде, а расшифровка происходит только в момент выполнения плейбука.
Когда Ansible встречает зашифрованный контент, ему нужен секрет: пароль, введённый интерактивно, или путь к файлу с паролем. Если ни то ни другое не предоставлено, выполнение прерывается с сообщением о том, что конфигурация требует vault, но vault не предоставлен.
- 🔐 Файл переменных зашифрован целиком через
ansible-vault encrypt - 🧩 Отдельная переменная зашифрована через
ansible-vault encrypt_string - 📁 Плейбук подключает чужой inventory или group_vars с vault-данными
- ⚙️ В
ansible.cfgотсутствует ссылка на password-файл
Как найти зашифрованные файлы в проекте
Первый шаг диагностики — определить, какие именно файлы требуют расшифровки. Зашифрованный vault-файл легко распознать: он начинается со строки $ANSIBLE_VAULT;1.1;AES256 (версия формата может отличаться). Откройте подозрительные файлы в group_vars, host_vars и каталоге ролей.
Быстрый поиск по всему проекту выполняется одной командой:
grep -rl "ANSIBLE_VAULT" .Команда выведет список всех файлов, содержащих зашифрованные блоки. Если среди них есть файлы, которые вы не шифровали, — возможно, они попали в проект при копировании чужой роли или шаблона из репозитория.
Способы передать пароль vault при запуске
Существует несколько штатных способов сообщить Ansible секрет для расшифровки. Выбор зависит от того, запускаете ли вы плейбук вручную или в автоматизированном конвейере.
| Способ | Команда / параметр | Когда использовать |
|---|---|---|
| Интерактивный ввод | --ask-vault-pass | Ручной запуск, пароль вводится с клавиатуры |
| Файл с паролем | --vault-password-file путь | CI/CD и скрипты, файл защищён правами доступа |
| Скрипт-клиент | --vault-id метка@скрипт | Интеграция с внешними хранилищами секретов |
| Настройка в конфиге | vault_password_file в ansible.cfg | Постоянная привязка для локального проекта |
Пример запуска плейбука с интерактивным вводом пароля:
ansible-playbook site.yml --ask-vault-passДля автоматизации удобнее файл с паролем. Создайте текстовый файл, запишите в него пароль одной строкой, ограничьте права (chmod 600) и обязательно добавьте имя файла в .gitignore.
Пошаговое исправление ошибки
Действуйте последовательно: сначала диагностика, затем минимальное исправление. Не спешите расшифровывать файлы насовсем — часто достаточно правильно передать секрет.
☑️ Проверка и устранение ошибки vault
Если пароль от vault утерян, восстановить зашифрованные данные невозможно — шифрование стойкое. В этом случае единственный путь — заменить секреты: сгенерировать новые пароли и токены в исходных системах, зашифровать их заново через ansible-vault encrypt_string и обновить переменные.
⚠️ Внимание: не пытайтесь «обойти» ошибку, удаляя зашифрованные блоки вслепую. Если плейбук ссылается на эти переменные, вы получите новые ошибки об undefined-переменных, а в худшем случае — развёрнутую систему с пустыми паролями.
Если файл зашифрован случайно
Иногда ошибка появляется после того, как файл был зашифрован по ошибке — например, команду ansible-vault encrypt выполнили не в том каталоге. Если вы знаете пароль, вернуть файл в открытый вид просто:
ansible-vault decrypt путь/к/файлу.ymlПосле расшифровки проверьте содержимое и при необходимости зашифруйте заново — уже осознанно. Просмотреть зашифрованный файл без изменения можно командой ansible-vault view, а отредактировать — ansible-vault edit: обе попросят пароль.
Несколько vault-паролей в одном проекте
Ansible поддерживает несколько vault ID. Например: --vault-id dev@prompt --vault-id prod@/secure/prod.pass. Каждый зашифрованный блок помечается меткой, и Ansible подбирает нужный секрет автоматически. Это удобно, когда dev- и prod-секреты разделены.
Настройка ansible.cfg для постоянной работы
Чтобы не указывать параметры при каждом запуске, зафиксируйте способ расшифровки в конфигурации проекта. Откройте или создайте файл ansible.cfg в корне проекта и добавьте секцию:
[defaults]
vault_password_file = ~/.vault_pass
Путь указывайте на файл вне репозитория — например, в домашнем каталоге. Тогда любой член команды сможет настроить свой локальный секрет, не меняя общий конфиг и не рискуя закоммитить пароль.
⚠️ Внимание: файл, указанный в vault_password_file, должен содержать только пароль и иметь права, запрещающие чтение другим пользователям. Ansible может отказаться использовать файл, если он исполняемый без надобности или доступен всем.
Профилактика: как избежать ошибки в будущем
Большинство подобных сбоев — следствие незафиксированных договорённостей в команде. Опишите в README проекта, какие файлы зашифрованы и как получить доступ к секретам. Новый участник не должен гадать, почему плейбук падает на первом же запуске.
Для конвейеров CI/CD используйте встроенные механизмы хранения секретов вашей системы сборки: пароль vault передаётся в защищённую переменную окружения, а файл с паролем создаётся на лету и удаляется после выполнения. Так вы избежите и ошибки запуска, и утечки секрета в логи.
- 📋 Документируйте состав vault-файлов и владельцев паролей
- 🚫 Держите файлы паролей в
.gitignoreи вне репозитория - 🔁 Периодически меняйте пароль через
ansible-vault rekey - 🧪 Проверяйте запуск плейбука на чистом окружении перед выкладкой
Частые вопросы
Можно ли восстановить пароль Ansible Vault, если он утерян?
Нет. Шифрование Vault не предусматривает восстановления: без пароля данные расшифровать невозможно. Нужно сгенерировать новые секреты в исходных системах и зашифровать их заново.
Почему ошибка появилась после клонирования чужого репозитория?
В проекте есть зашифрованные файлы, а у вас нет пароля автора. Либо запросите секрет у владельца проекта, либо замените зашифрованные переменные собственными значениями.
Чем --vault-id отличается от --vault-password-file?
--vault-password-file задаёт один файл с паролем. --vault-id позволяет указать несколько секретов с метками (например, dev и prod) и подключать внешние скрипты получения паролей.
Ansible не принимает мой файл пароля — в чём причина?
Проверьте, что файл содержит только пароль без лишних строк, не является исполняемым и имеет строгие права доступа. Также убедитесь, что путь в ansible.cfg указан корректно.
Можно ли зашифровать не весь файл, а одну переменную?
Да, для этого служит команда ansible-vault encrypt_string. Она выдаёт зашифрованный блок, который вставляется как значение переменной в обычный YAML-файл.