SaaS 运行时的变量和变量映射

本文档介绍了变量、变量映射和依赖项在 SaaS 运行时中的运作方式。

借助 SaaS 运行时，您可以将复杂的 SaaS 应用整理为模块化单元，从而部署和管理这些应用。这些由蓝图中的 Terraform 配置定义的单元可以通过依赖关系互连，从而实现复杂的编排和自动化配置。管理这些单元及其互动的一个关键方面是通过变量和变量映射。

您可以构建复杂、模块化且可伸缩的部署，并实现自动化配置、单元间通信和灵活的配置选项。请仔细考虑变量层次结构、依赖关系和变量映射，以便在 SaaS 运行时中优化 SaaS 架构和管理工作流程。

单位和变量

SaaS 运行时的核心是单元。单元利用变量自定义其部署和行为。这些变量本质上是 Terraform 变量，您可以在蓝图的 variables.tf 文件中定义这些变量。借助它们，您可以对 Terraform 配置进行参数化，使其可在不同的环境和部署中重复使用和调整。

单元配置的必需变量

虽然您可以为单元定义自定义变量，但 SaaS 运行时也依赖于一组必需变量。即使这些变量未在您的 Terraform 配置中明确定义，SaaS 运行时也会自动识别和处理它们。

必需变量包括：

  • project_id 和 project_number（或 tenant_project_id 和 tenant_project_id）：此变量用于指定 Google Cloud 项目 ID，您的单元的资源将部署到该项目。您可以使用 project_id 和 project_number，也可以使用 tenant_id 和 tenant_project_id。此字段对于在正确的 Google Cloud 项目中创建和管理资源是必需的。

    您可以在 Google Cloud 控制台的信息中心页面上找到项目 ID。 在云概览部分内的项目信息卡片中，找到项目 ID 字段。

  • project_number 或 tenant_project_number：与 project_id 类似，此变量表示 Google Cloud 项目编号。您可以交替使用 project_number 或 tenant_project_number。

    您可以在 Google Cloud 控制台信息中心页面的 Cloud 概览部分中的项目信息卡片内找到项目编号以及项目 ID。

  • actuation_sa：此变量表示启动服务账号的电子邮件地址。此服务账号是 SaaS 运行时（通过 Infrastructure Manager）在配置、更新或取消配置单元时用于执行 Terraform 配置的用户管理的服务账号。

    我们建议您为每个租户（或单位）使用专用的促动服务账号，以实现最小权限原则。这样可以限制安全漏洞的潜在影响，并更好地隔离部署。

    如需详细了解如何配置和授予执行服务账号权限，请参阅产品概览。

单位变量层次结构

单元变量可以定义并从多个位置获取。使用 SaaS 运行时时，务必要了解在单元操作期间使用的变量值层次结构。

顺序如下（从最低优先级到最高优先级）：

SaaS 运行时按以下顺序解析变量值：

  1. 单元上的现有输入变量：如果变量已在单元资源本身上定义（例如，通过之前的操作或配置），则此值具有最低优先级。如果直接在单元上设置了变量值，则当从层次结构中更高级别的来源找到值时，该值会被覆盖。

  2. 发布默认值：如果设备上尚未设置变量，则应用发布默认值，但这些默认值会替换现有的设备变量。

  3. 单元操作：当您执行 单元操作（例如 provision 或 upgrade）时，可以明确提供输入变量作为操作请求的一部分。在单元操作中提供的变量将替换版本默认值和现有单元变量。

  4. 依赖项的输入变量映射：当某个单元依赖于其他单元时，在单元种类中定义的变量映射可以从依赖项单元的输出变量中获取变量值。这是优先级最高的来源。通过依赖关系映射获得的变量将替换来自单元操作、发布默认值和现有单元变量的值。

这种分层方法可让您灵活地控制变量管理。您可以直接在设备上建立持久配置（优先级最低），使用版本定义基准默认值，针对特定操作进行自定义，并从设备依赖项中动态获取最重要和覆盖的值（优先级最高）。

单元依赖项

借助 SaaS 运行时，您可以定义单元之间的依赖关系。这对于构建不同组件相互依赖的复杂 SaaS 应用非常重要。依赖项可确保以协调一致的方式预配和管理相关单元。

您可以在单元种类中定义依赖项。当您创建特定单元类型的单元时，SaaS 运行时会自动管理其依赖项。

单元种类中的依赖项定义

在 UnitKind 定义中，您可以指定一个依赖项列表，每个依赖项都引用另一个 UnitKind 并为其分配一个别名。此别名用于在变量映射中引用依赖项：

  message UnitKind {
    // ... other fields ...

    // List of other unit kinds that this release will depend on.
    repeated Dependency dependencies = 4
        [(.google.api.field_behavior) = OPTIONAL];
    // ...
  }

  message Dependency {
    // The unit kind of the dependency.
    string unit_kind = 1 [
      (.google.api.field_behavior) = REQUIRED,
      (.google.api.field_behavior) = IMMUTABLE,
      (.google.api.resource_reference) = {
        type: "saasservicemgmt.googleapis.com/UnitKind"
      }
    ];

    // An alias for the dependency. Used for input variable mapping.
    string alias = 2 [(.google.api.field_behavior) = REQUIRED];
  }

自动依赖项配置

当您请求预配在 UnitKind 中定义了依赖项的单元时，SaaS 运行时会自动检查这些依赖单元是否存在。

如果找不到依赖单元，SaaS 运行时会在预配依赖单元之前自动预配该依赖单元。

SaaS 运行时可确保在依赖单元之前预配依赖项单元，从而保持正确的操作顺序。

变量映射

变量映射是一种在相关单元及其依赖项之间传递数据（变量值）的机制。这对于根据相关单元的输出配置相关单元至关重要。

变量映射在相关单元种类中定义，并使用 FromMapping 和 ToMapping：

  • FromMapping：FromMapping 用于从依赖单元检索输出变量，并将它们映射到依赖单元的输入变量。相关单元就是通过这种方式从其依赖项（例如连接端点或资源 ID）获取信息。

    message VariableMapping {
  // ...
  oneof mapping_type {
    // Output variables which will get their values from dependencies
    FromMapping from = 2 [(.google.api.field_behavior) = OPTIONAL];
    // ...
  }
}

message FromMapping {
  // Alias of the dependency that the outputVariable will pass its value to
  string dependency = 1 [(.google.api.field_behavior) = REQUIRED];

  // Name of the outputVariable on the dependency
  string output_variable = 2 [(.google.api.field_behavior) = REQUIRED];
}

    在提供的 Codelab 示例中，App UnitKind 具有 FromMapping，用于从 Cluster UnitKind 依赖项中检索 cluster_endpoint 输出变量。这样一来，应用便可连接到新配置的 Kubernetes 集群。

  • ToMapping：ToMapping 用于将相关单元的输入变量传递给依赖单元的输入变量。这样一来，您就可以根据为依赖单元提供的参数来配置依赖单元。

    message VariableMapping {
  // ...
  oneof mapping_type {
    // ...
    // Input variables whose values will be passed on to dependencies.
    ToMapping to = 3 [(.google.api.field_behavior) = OPTIONAL];
  }
}

message ToMapping {
  // Alias of the dependency that the inputVariable will pass its value to
  string dependency = 1 [(.google.api.field_behavior) = REQUIRED];

  // Name of the inputVariable on the dependency
  string input_variable = 2 [(.google.api.field_behavior) = REQUIRED];

  // Tells EasySaaS if this mapping should be used during lookup or not
  bool ignore_for_lookup = 3 [(.google.api.field_behavior) = OPTIONAL];
}

    在此 Codelab 中，App UnitKind 使用 ToMapping 将 tenant_project_id 和 tenant_project_number 输入变量传递给 Cluster UnitKind 依赖项。这可确保在正确的项目中创建 Kubernetes 集群。

  • ToMapping 中的 ignore_for_lookup：ToMapping 中的 ignore_for_lookup 字段用于控制依赖项查找行为。这是一个布尔值：

    • false（或未指定）：如果设置为 false，SaaS 运行时会将 ToMapping 中指定的输入变量用作查找键来查找现有的依赖单元。如果找到具有匹配输入变量的单元，则会将其重新用作依赖项。如果未找到匹配的单元，系统将预配新的依赖项单元。这有助于重用集群等共享资源。
    • true：设置为 true 时，ToMapping 中的输入变量将不会用于依赖项查找。这意味着，即使已存在具有相同输入变量的单元，系统也始终会预配新的依赖单元。如果您需要为每个依赖单元提供专用且非共享的依赖项，此功能非常有用。

示例：共享 Kubernetes 集群

如果您想在同一项目内将 Kubernetes 集群重复用于多个应用单元，则可以使用 ToMapping，并将 ignore_for_lookup 设置为 false，然后将 tenant_project_id 和 region 等变量映射到集群单元类型。同一项目和区域中的单元随后会重复使用同一集群。

示例：每个应用对应一个专用 Kubernetes 集群

如果您需要为每个应用单元提供专用 Kubernetes 集群，则可以使用 ToMapping 并将 ignore_for_lookup 设置为 true，或者完全避免使用 ToMapping 查找变量。然后，每个应用单元都会触发新隔离的 Kubernetes 集群的配置。

管理密文

SaaS 运行时变量不适合用于存储密码、API 密钥或证书等敏感信息。直接在变量中存储密文会带来安全风险。变量值可能会被记录下来，并通过系统输出公开，从而增加未经授权的访问风险。

为了在 SaaS 运行时应用中安全地管理 Secret，我们强烈建议使用 Secret Manager。

后续步骤