模式验证已加入 Pulumi ESC（使用 fn::validate）

Source: Pulumi Blog

工作原理

fn::validate 函数接受一个 JSON Schema 和一个值。如果该值符合模式，则保持不变直接通过；如果不符合，ESC 会抛出验证错误。

values:
  port:
    fn::validate:
      schema: { type: number, minimum: 1, maximum: 65535 }
      value: 8080

这会验证 port 是否是 1 到 65535 之间的数字。求值结果就是 8080。

验证带必填字段的对象

对于复杂配置，你可以强制结构和必填字段：

values:
  database:
    fn::validate:
      schema:
        type: object
        properties:
          host: { type: string }
          port: { type: number }
          name: { type: string }
        required: [host, port, name]
      value:
        host: "db.example.com"
        port: 5432
        name: "myapp"

如果缺少任何必填字段或字段类型错误，环境将无法保存。

在多个环境中复用模式

一次定义模式后即可在多个环境中引用。使用environments 内置属性 可以将模式从环境输出中抽离。

模式环境 (my-project/schemas)

values:
  database-schema:
    type: object
    properties:
      host: { type: string }
      port: { type: number }
    required: [host, port]

使用该模式的环境

values:
  database:
    fn::validate:
      schema: ${environments.my-project.schemas.database-schema}
      value:
        host: "prod-db.example.com"
        port: 5432

这种模式确保团队和项目之间的验证规则保持一致。

验证失败时会发生什么

当值不符合其模式时，ESC 会返回清晰的错误信息：

values:
  port:
    fn::validate:
      schema: { type: string }
      value: 8080

这会抛出：expected string, got number。在修复值或更新模式之前，环境无法保存。

何时使用模式验证

在以下场景启用 fn::validate：

• 需要特定类型的值（数字、字符串、数组）
• 必须包含特定字段的对象
• 必须落在有效范围内的数字
• 在多个环境之间共享的配置
• 任何希望提前捕获错误以防止下游问题的值

入门指南

fn::validate 函数已在所有 Pulumi ESC 环境中可用。可以将模式验证添加到已有环境，也可以在创建新环境时使用。

更多信息，请参阅 fn::validate 文档。