跳至主要内容

命令：validate

tofu validate 命令验证目录中的配置文件，仅参考配置，不访问任何远程服务，例如远程状态、提供程序 API 等。

Validate 运行检查以验证配置是否在语法上有效且在内部一致，而不管现有状态如何。因此，它主要用于对可重用模块进行一般验证，包括属性名称和值类型的正确性。

可以安全地自动运行此命令，例如在文本编辑器中作为保存后检查，或在 CI 系统中作为可重用模块的测试步骤。

验证需要一个已初始化的工作目录，并安装任何引用的插件和模块。要初始化一个用于验证的工作目录而不访问任何已配置的后端，请使用

代码块
$ tofu init -backend=false

要验证特定运行环境下的配置（特定目标工作区、输入变量值等），请改用 tofu plan 命令，其中包含隐式验证检查。

用法​

用法：tofu validate [选项]

此命令接受以下选项

  • -json - 以机器可读的 JSON 格式生成输出，适合在文本编辑器集成和其他自动化系统中使用。始终禁用颜色。

  • -no-color - 如果指定，输出将不包含任何颜色。

  • -var 'NAME=VALUE' - 为配置根模块中声明的单个 输入变量 设置值。使用此选项多次可设置多个变量。有关更多信息，请参阅 命令行上的输入变量。

  • -var-file=FILENAME - 使用来自 "tfvars" 文件 的定义，为配置根模块中声明的可能多个 输入变量 设置值。使用此选项多次可包含来自多个文件的值。

除了 -var 和 -var-file 选项外，还有几种其他方法可以在根模块中为输入变量设置值。有关更多信息，请参阅 为根模块变量赋值。

JSON 输出格式​

当您使用 -json 选项时，OpenTofu 将以 JSON 格式生成验证结果，以便将验证结果用于工具集成，例如在文本编辑器中突出显示错误。

与所有 JSON 输出选项一样，OpenTofu 可能会在开始验证任务之前遇到错误，因此该错误不会受 JSON 输出设置的影响。因此，使用 OpenTofu 输出的外部软件应准备好查找 不是 有效 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（数字）：一个基于 1 的行数，表示 code 代码段开始时源文件中的位置。这并不一定与 range.start.line 的值相同，因为 code 可以在诊断源之前包含一行或多行上下文。

    • highlight_start_offset（数字）：一个基于 0 的字符偏移量，位于 code 字符串中，指向触发诊断的表达式的开头。

    • highlight_end_offset（数字）：一个基于 0 的字符偏移量，位于 code 字符串中，指向触发诊断的表达式的结尾。

    • values（对象数组）：包含零个或多个表达式值，这些值可能有助于理解复杂表达式中诊断的来源。这些表达式值对象在下面描述。

源位置​

诊断对象 range 属性中使用的源位置对象具有以下属性

  • byte（数字）：一个基于 0 的字节偏移量，位于指示的文件中。

  • line（数字）：指示文件中包含相关位置的行的一个基于 1 的行数。

  • column（数字）：从 line 中指示的行开始的一个基于 1 的Unicode 字符计数。

start 位置是包含的，而 end 位置是不包含的。用于特定错误消息的确切位置仅供人类解释。

表达式值​

表达式值对象提供了有关触发诊断的表达式一部分的值的附加信息。这在使用 for_each 或类似构造时特别有用，以便准确识别导致错误的值。该对象有两个属性

  • traversal（字符串）：一个类似 HCL 的遍历字符串，例如 var.instance_count。复杂的索引键值可能会被省略，因此这并不总是有效的、可解析的 HCL。此字符串的内容旨在供人类阅读。

  • statement（字符串）：描述触发诊断时表达式值的简短英文片段。此字符串的内容旨在供人类阅读，并且在 OpenTofu 的未来版本中可能会发生变化。