SaaS ランタイムの変数と変数マッピング

このドキュメントでは、SaaS ランタイム内での変数、変数マッピング、依存関係の仕組みについて説明します。

SaaS ランタイムを使用すると、複雑な SaaS アプリケーションをモジュール式のユニットに整理して、デプロイと管理を行うことができます。これらのユニットは、ブループリント内の Terraform 構成で定義され、依存関係を通じて相互接続できるため、高度なオーケストレーションと自動プロビジョニングが可能になります。これらのユニットとそのインタラクションを管理するうえで重要なのは、変数と変数マッピングです。

自動プロビジョニング、ユニット間の通信、柔軟な構成オプションを使用して、複雑でモジュール式のスケーラブルなデプロイを構築できます。変数階層、依存関係、変数マッピングを慎重に検討して、SaaS ランタイム内の SaaS アーキテクチャと管理ワークフローを最適化します。

単位と変数

SaaS ランタイムの中核となるのはユニットです。ユニットは変数を使用して、デプロイと動作をカスタマイズします。これらの変数は、ブループリントの variables.tf ファイルで定義できる Terraform 変数です。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 プロジェクト内のリソースの作成と管理に必要です。

プロジェクト ID は、 Google Cloud コンソールの [ダッシュボード] ページで確認できます。[Cloud の概要] セクションの [プロジェクト情報] カードで、[プロジェクト ID] フィールドを探します。
project_number または tenant_project_number: project_id と同様に、この変数は Google Cloud プロジェクト番号を表します。project_number と tenant_project_number は相互に使用できます。

プロジェクト番号は、 Google Cloud コンソールの [ダッシュボード] ページの [Cloud の概要] セクションにある [プロジェクト情報] カードで、プロジェクト ID とともに確認できます。

注意: project_id と project_number、または tenant_project_id と tenant_project_number のいずれかを使用する必要があります。project_id と tenant_project_number などの組み合わせはサポートされておらず、エラーが発生する可能性があります。
actuation_sa: この変数は、アクチュエーションサービスアカウントのメールアドレスを表します。このサービスアカウントは、SaaS ランタイムが（Infrastructure Manager を介して）ユニットのプロビジョニング、更新、プロビジョニング解除時に Terraform 構成を実行するために使用するユーザー管理のサービスアカウントです。

最小権限の原則を実装するには、テナント（またはユニット）ごとに専用のアクチュエーションサービスアカウントを使用することをおすすめします。これにより、セキュリティ侵害の影響を抑え、デプロイ間の分離を強化できます。

アクチュエーションサービスアカウントの権限の構成と付与の詳細については、プロダクトの概要をご覧ください。

ユニット変数の階層

ユニット変数は複数の場所で定義して取得できます。SaaS Runtime を使用する場合は、ユニットオペレーションで使用される変数階層を理解することが重要です。

優先順位は、低い順から高い順に次のようになります。

SaaS ランタイムは、次の順序で変数値を解決します。

ユニットの既存の入力変数: 変数がユニットリソース自体にすでに定義されている場合（以前のオペレーションや構成など）、この値の優先順位は最も低くなります。変数値がユニットに直接設定されている場合、階層の上位のソースから値が見つかると、その値はオーバーライドされます。
リリースデフォルト: 変数がユニットにまだ設定されていない場合は、リリースデフォルト値が適用されますが、既存のユニット変数はオーバーライドされます。
ユニットオペレーション: provision や upgrade などのユニットオペレーションを実行するときに、オペレーションリクエストの一部として入力変数を明示的に指定できます。ユニットオペレーションで指定された変数は、リリースのデフォルトと既存のユニット変数をオーバーライドします。
依存関係の入力変数のマッピング: ユニットが他のユニットに依存している場合、ユニットの種類で定義された変数のマッピングは、依存関係のユニットの出力変数から変数値を取得できます。これは優先順位が最も高いソースです。依存関係マッピングで取得した変数は、ユニットオペレーション、リリースデフォルト、既存のユニット変数から取得した値をオーバーライドします。

この階層型のアプローチにより、変数の管理を柔軟に制御できます。永続的な構成をユニットで直接確立（優先度最低）、リリースを使用してベースラインのデフォルトを定義、特定のオペレーションに合わせてカスタマイズ、ユニットの依存関係から最も重要でオーバーライドする値を動的に取得（優先度最高）できます。

ユニットの依存関係

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 Runtime は ToMapping で指定された入力変数をルックアップキーとして使用して、既存の依存関係ユニットを検索します。一致する入力変数を持つユニットが見つかった場合、そのユニットは依存関係として再利用されます。一致するユニットが見つからない場合は、新しい依存関係ユニットがプロビジョニングされます。これは、クラスタなどの共有リソースを再利用する場合に便利です。
- true: true に設定すると、ToMapping の入力変数は依存関係のルックアップに使用されません。つまり、同じ入力変数を持つユニットがすでに存在する場合でも、新しい依存関係ユニットが常にプロビジョニングされます。これは、依存ユニットごとに専用の共有されない依存関係が必要な場合に便利です。

例: 共有 Kubernetes クラスタ

同じプロジェクト内の複数のアプリケーションユニットで Kubernetes クラスタを再利用する場合は、ignore_for_lookup を false に設定した ToMapping を使用し、tenant_project_id や region などの変数をクラスタユニットの種類にマッピングします。同じプロジェクトとリージョンのユニットは、同じクラスタを再利用します。

例: アプリケーションごとに専用の Kubernetes クラスタ

アプリケーションユニットごとに専用の Kubernetes クラスタが必要な場合は、ignore_for_lookup を true に設定して ToMapping を使用するか、ToMapping ルックアップ変数を使用しないようにします。各アプリケーションユニットは、新しい分離された Kubernetes クラスタのプロビジョニングをトリガーします。

シークレットを管理する

SaaS Runtime 変数は、パスワード、API キー、証明書などの機密情報を保存することを目的としていません。シークレットを変数に直接保存すると、セキュリティリスクが生じます。変数の値がログに記録され、システム出力を通じて公開される可能性があり、不正アクセスのリスクが高まります。

SaaS ランタイムアプリケーションでシークレットを安全に管理するには、Secret Manager を使用することを強くおすすめします。

次のステップ

SaaS ランタイムの詳細については、SaaS ランタイムの概要をご覧ください。
チュートリアルを試すには、SaaS ランタイムを使用して VM をデプロイするをご覧ください。
Terraform 構成を使用した SaaS サービスの定義の詳細については、SaaS ランタイムのブループリントをご覧ください。