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