Команда: validate

Команда tofu validate проверяет файлы конфигурации в каталоге, учитывая только конфигурацию и не обращаясь к удалённым службам, таким как удалённое состояние, API провайдеров и т. д.

Команда validate выполняет проверки, чтобы определить, является ли конфигурация синтаксически корректной и внутренне согласованной, независимо от существующего состояния. Поэтому она в первую очередь полезна для общей проверки повторно используемых модулей, включая правильность имён атрибутов и типов значений.

Эту команду безопасно запускать автоматически, например в качестве проверки после сохранения в текстовом редакторе или в качестве этапа тестирования повторно используемого модуля в системе CI.

Для проверки требуется инициализированный рабочий каталог со всеми установленными подключаемыми модулями и модулями, на которые есть ссылки. Чтобы инициализировать рабочий каталог для проверки, не обращаясь к настроенному серверу состояния, используйте:

$ tofu init -backend=false

Чтобы проверить конфигурацию в контексте конкретного запуска (определённого целевого рабочего пространства, значений входных переменных и т. д.), используйте вместо этого команду tofu plan, которая автоматически включает проверку.

Использование​

Использование: tofu validate [options]

Команда принимает следующие параметры:

• -json — выводит результат в машиночитаемом формате JSON, подходящем для интеграции с текстовыми редакторами и другими автоматизированными системами. Всегда отключает цветной вывод.

• -json-into=out.json — выводит те же данные, что и -json, но перенаправляет их в файл. Это позволяет одновременно сохранять журналы в удобочитаемом и машиночитаемом форматах.

• -no-color — при указании отключает цветной вывод.

• -var 'NAME=VALUE' — задаёт значение для одной входной переменной, объявленной в корневом модуле конфигурации. Используйте этот параметр несколько раз, чтобы задать значения для нескольких переменных. Подробнее см. в разделе Входные переменные в командной строке.

• -var-file=FILENAME — задаёт значения для нескольких входных переменных, объявленных в корневом модуле конфигурации, используя определения из файла «tfvars». Используйте этот параметр несколько раз, чтобы включить значения из нескольких файлов.

Существует несколько других способов задать значения входных переменных в корневом модуле помимо параметров -var и -var-file. Подробнее см. в разделе Назначение значений переменным корневого модуля.

Формат вывода JSON​

При использовании параметра -json OpenTofu выводит результаты проверки в формате JSON, чтобы их можно было использовать в интеграциях с другими инструментами, например для подсветки ошибок в текстовом редакторе.

Как и при использовании всех параметров вывода JSON, OpenTofu может столкнуться с ошибкой до начала проверки, и тогда на неё не будет распространяться настройка вывода JSON. Поэтому внешнее программное обеспечение, обрабатывающее вывод OpenTofu, должно быть готово к тому, что в stdout могут оказаться данные, которые не являются корректным JSON. В таком случае их следует рассматривать как обычную ошибку.

Вывод содержит ключ format_version со значением "1.0". Семантика этой версии следующая:

• Мы будем увеличивать младшую версию, например "1.1", при обратно совместимых изменениях или дополнениях. Чтобы сохранить прямую совместимость с будущими младшими версиями, игнорируйте свойства объектов с неизвестными именами.
• Мы будем увеличивать основную версию, например "2.0", при несовместимых изменениях. Отклоняйте любые входные данные, в которых указана неподдерживаемая основная версия.

Мы будем вводить новые основные версии только в рамках обещаний совместимости OpenTofu 1.0.

В обычном случае OpenTofu выводит объект JSON в стандартный поток вывода. Объект JSON верхнего уровня содержит следующие свойства:

• valid (логическое значение): сводный результат проверки, который показывает true, если OpenTofu считает текущую конфигурацию корректной, или false, если обнаружены ошибки.

• error_count (число): целое неотрицательное число, указывающее количество ошибок, обнаруженных OpenTofu. Если valid равно true, то error_count всегда будет равно нулю, поскольку именно наличие ошибок означает, что конфигурация некорректна.

• warning_count (число): целое неотрицательное число, указывающее количество предупреждений, обнаруженных OpenTofu. Предупреждения не приводят к тому, что OpenTofu считает конфигурацию некорректной, но указывают на возможные ограничения, которые пользователю следует учитывать и, возможно, устранить.

• diagnostics (массив объектов): массив JSON с вложенными объектами, каждый из которых описывает ошибку или предупреждение OpenTofu.

Вложенные объекты в diagnostics имеют следующие свойства:

• severity (строка): строковое ключевое слово — "error" или "warning", указывающее серьёзность диагностического сообщения.

  Наличие ошибок приводит к тому, что OpenTofu считает конфигурацию некорректной, тогда как предупреждения — это лишь рекомендации или примечания для пользователя, которые не препятствуют работе с конфигурацией. В будущих версиях OpenTofu могут появиться новые ключевые слова, обозначающие серьёзность, поэтому клиентские приложения должны быть готовы принимать и игнорировать неизвестные им значения.

• summary (строка): краткое описание проблемы, о которой сообщает диагностическое сообщение.

  В обычных диагностических сообщениях OpenTofu, предназначенных для пользователя, сводка выполняет роль своего рода «заголовка» и выводится после пометки «Error:» или «Warning:».

  Сводки обычно представляют собой короткие предложения, но иногда могут быть длиннее, если возвращаются ошибки из подсистем, не предназначенных для выдачи полных диагностических сообщений. В таких случаях всё сообщение об ошибке становится сводкой. Она может содержать символы перевода строки, которые средство отображения должно учитывать при показе сообщения пользователю.

• detail (строка): необязательное дополнительное сообщение с более подробной информацией о проблеме.

  В обычных диагностических сообщениях OpenTofu, предназначенных для пользователя, подробное описание содержит абзацы текста, которые следуют за заголовком и ссылкой на исходный код.

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

  Некоторые подробные сообщения OpenTofu содержат приближённые маркированные списки, в которых маркеры обозначаются символами ASCII. Это не является обязательным соглашением о форматировании, поэтому средства отображения не должны полагаться на него и должны рассматривать такие строки как абзацы или предварительно отформатированный текст. В будущих версиях этого формата могут быть определены дополнительные правила для других текстовых соглашений, но будет сохранена обратная совместимость.

• range (объект): необязательный объект, указывающий на часть исходного кода конфигурации, к которой относится диагностическое сообщение. Для ошибок он обычно обозначает границы заголовка конкретного блока, атрибута или выражения, признанного некорректным.

  Диапазон исходного кода — это объект со свойством filename, которое содержит имя файла в виде относительного пути от текущего рабочего каталога, и свойствами start и end, каждое из которых является объектом, описывающим позицию в исходном коде, как описано ниже.

  Не все диагностические сообщения связаны с конкретными частями конфигурации, поэтому для сообщений, к которым это не относится, range будет отсутствовать или иметь значение null.

• snippet (объект): необязательный объект с фрагментом исходного кода конфигурации, к которому относится диагностическое сообщение.

  Информация о фрагменте включает:

  • context (строка): необязательная сводка корневого контекста диагностического сообщения. Например, это может быть блок ресурса, содержащий выражение, вызвавшее сообщение. Для некоторых диагностических сообщений эта информация недоступна; в таком случае свойство будет иметь значение null.

  • code (строка): фрагмент конфигурации OpenTofu, содержащий исходный код, к которому относится диагностическое сообщение. Он может состоять из нескольких строк и включать дополнительный исходный код конфигурации вокруг выражения, вызвавшего сообщение.

  • start_line (число): номер строки, начиная с единицы, в исходном файле, с которой начинается фрагмент code. Он не обязательно совпадает со значением range.start.line, поскольку code может включать одну или несколько контекстных строк перед исходным кодом, к которому относится диагностическое сообщение.

  • highlight_start_offset (число): смещение, отсчитываемое от нуля, в строке code, указывающее на начало выражения, вызвавшего диагностическое сообщение.

  • highlight_end_offset (число): смещение, отсчитываемое от нуля, в строке code, указывающее на конец выражения, вызвавшего диагностическое сообщение.

  • values (массив объектов): содержит ноль или более значений выражений, которые могут помочь понять источник диагностического сообщения в сложном выражении. Эти объекты значений выражений описаны ниже.

Позиция в исходном коде​

Объект позиции в исходном коде, используемый в свойстве range объекта диагностического сообщения, имеет следующие свойства:

• byte (число): смещение в байтах, отсчитываемое от нуля, в указанном файле.

• line (число): номер строки, начиная с единицы, содержащей соответствующую позицию в указанном файле.

• column (число): количество символов Unicode, отсчитываемое от начала строки, указанной в line, начиная с единицы.

Позиция start включается в диапазон, а позиция end не включается. Точные позиции, указанные для конкретных сообщений об ошибках, предназначены только для интерпретации человеком.

Значение выражения​

Объект значения выражения содержит дополнительную информацию о значении, являющемся частью выражения, которое вызвало диагностическое сообщение. Это особенно полезно при использовании for_each или аналогичных конструкций, поскольку позволяет точно определить, какие значения привели к ошибке. Объект имеет два свойства:

• traversal (строка): строка обхода, похожая на HCL, например var.instance_count. Сложные значения ключей индексов могут быть опущены, поэтому эта строка не всегда будет корректным и разбираемым кодом HCL. Содержимое этой строки предназначено для чтения человеком.

• statement (строка): краткий фрагмент на английском языке, описывающий значение выражения на момент возникновения диагностического сообщения. Содержимое этой строки предназначено для чтения человеком и может измениться в будущих версиях OpenTofu.