Команда: 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.