Команда: validate

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

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

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

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

$ tofu init -backend=false

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

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

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

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

• -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, предназначенных для пользователей, сводка служит своего рода «заголовком» диагностического сообщения и выводится после пометки «Ошибка:» или «Предупреждение:».

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

• 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.