SaaS 執行階段的變數和變數對應

本文說明變數、變數對應和依附元件在 SaaS 執行階段中的運作方式。

SaaS 執行階段可將複雜的 SaaS 應用程式整理成模組化單元，方便您部署及管理。這些單元是由藍圖中的 Terraform 設定定義，可透過依附元件互連，實現精密的自動化調度管理和自動佈建。管理這些單元及其互動的重點，在於變數和變數對應。

您可以透過自動佈建、單元間通訊和彈性設定選項，建構複雜、模組化且可擴充的部署作業。請仔細考量變數階層、依附關係和變數對應，在 SaaS 執行階段中，盡可能提升 SaaS 架構和管理工作流程的效率。

單位和變數

SaaS 執行階段的核心是單元。單元會使用變數自訂部署作業和行為。這些變數基本上是 Terraform 變數，您可以在藍圖的 variables.tf 檔案中定義。您可以使用這些範本將 Terraform 設定參數化，以便在不同環境和部署作業中重複使用及調整設定。

單元佈建的必要變數

您可以為單元定義自訂變數，但 SaaS Runtime 也會依賴一組必要變數。即使這些變數未在 Terraform 設定中明確定義，SaaS 執行階段仍會自動辨識及處理。

必要變數如下：

  • project_id 和 project_number (或 tenant_project_id 和 tenant_project_id)：這個變數會指定要部署單元資源的 Google Cloud 專案 ID Google Cloud 。您可以使用 project_id 和 project_number，也可以使用 tenant_id 和 tenant_project_id。這個欄位是建立資源的必要條件，且有助於在正確的 Google Cloud 專案中管理資源。

    您可以在 Google Cloud 控制台的資訊主頁找到專案 ID。 在「Cloud overview」(雲端總覽) 區段的「Project info」(專案資訊) 資訊卡中，找出「Project ID」(專案 ID) 欄位。

  • project_number 或 tenant_project_number：與 project_id 類似，這個變數代表 Google Cloud 專案編號。您可以交替使用 project_number 或 tenant_project_number。

    您可以在 Google Cloud 控制台資訊主頁的「Cloud overview」(雲端總覽) 部分，找到「Project info」(專案資訊) 資訊卡，其中會列出專案 ID 和專案編號。

  • actuation_sa：這個變數代表啟動服務帳戶的電子郵件地址。這個服務帳戶是使用者管理的服務帳戶，SaaS 執行階段會使用這個帳戶 (透過 Infrastructure Manager) 執行 Terraform 設定，以佈建、更新或取消佈建單元。

    建議您為每個租戶 (或單位) 使用專屬的啟動服務帳戶，以落實最低權限原則。這項做法可限制安全性漏洞的潛在影響，並在部署作業之間提供更完善的隔離措施。

    如要進一步瞭解如何設定及授予啟動服務帳戶權限，請參閱產品總覽。

單元變數階層

您可以從多個位置定義及取得單元變數。使用 SaaS 執行階段時，請務必瞭解單元作業期間使用的變數值階層。

優先順序如下 (從最低到最高)：

SaaS 執行階段會依下列順序解析變數值：

  1. 單元上的現有輸入變數：如果變數已在單元資源本身上定義 (例如來自先前的作業或設定)，這個值會採用最低優先順序。如果直接在單元上設定變數值，系統會從階層中較高的來源找到值，並覆寫該值。

  2. 發布預設值：如果單元尚未設定變數，系統會套用發布預設值，但會覆寫現有的單元變數。

  3. 單元作業：執行 單元作業 (例如 provision 或 upgrade) 時，您可以明確提供輸入變數做為作業要求的一部分。單元作業中提供的變數會覆寫版本預設值和現有單元變數。

  4. 依附元件的輸入變數對應：如果單元依附於其他單元，單元種類中定義的變數對應可以從依附元件單元的輸出變數取得變數值。這是優先順序最高的來源。透過依附元件對應取得的變數會覆寫單元作業、版本預設值和現有單元變數的值。

這種階層式做法可讓您彈性控管變數管理作業。您可以直接在單元上建立持續性設定 (最低優先順序)，使用版本定義基準預設值，為特定作業自訂設定，並從單元依附元件動態取得最重要和覆寫的值 (最高優先順序)。

單元依附元件

您可以使用 SaaS 執行階段定義單元之間的依附元件。這對於建構複雜的 SaaS 應用程式非常重要，因為不同元件會相互依賴。依附元件可確保相關單元以協調一致的方式佈建及管理。

您可以在單元 kind 中定義依附元件。建立特定單元 kind 的單元時，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 Runtime 會先自動佈建依附單元，再佈建依附單元。

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];
}

    在提供的程式碼研究室範例中，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];
}

    在本程式碼研究室中，App UnitKind 會使用 ToMapping 將 tenant_project_id 和 tenant_project_number 輸入變數傳遞至 Cluster UnitKind 依附元件。這可確保 Kubernetes 叢集是在正確的專案中建立。

  • ignore_for_lookup in ToMapping：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 Runtime 變數不適合用來儲存密碼、API 金鑰或憑證等機密資訊。直接在變數中儲存密鑰會造成安全風險。變數值可能會記錄在系統輸出內容中，進而遭到公開，增加未經授權存取的風險。

為確保 SaaS Runtime 應用程式中的 Secret 管理安全無虞，我們強烈建議使用 Secret Manager。

後續步驟