App Lifecycle Manager の変数と変数マッピング

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

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

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

ユニットと変数

App Lifecycle Manager の中心となるのはユニットです。ユニットは変数を使用して、デプロイと動作をカスタマイズします。これらの変数は、ブループリントの variables.tf ファイルで定義できる Terraform 変数です。これにより、Terraform 構成をパラメータ化して、さまざまな環境やデプロイで再利用および適応させることができます。

ユニットプロビジョニングの必須変数

ユニットのカスタム変数を定義できますが、App Lifecycle Manager は一連の必須変数にも依存しています。これらの変数は、Terraform 構成で明示的に定義されていない場合でも、App Lifecycle Manager によって自動的に認識され、処理されます。

必須の変数は次のとおりです。

project_id と project_number（または tenant_project_id と tenant_project_number）: この変数は、 Google Cloud プロジェクト ID で、ユニットのリソースがデプロイされる場所を指定します。と project_id、または tenant_id と tenant_project_number のいずれかを使用できます。project_numberこのフィールドは、正しい Google Cloud プロジェクト内でリソースを作成して管理するために必要です。

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

プロジェクト番号は、 Google Cloud コンソール [Dashboard page]の [Cloud overview]セクションにある [Project info] カードで、プロジェクト ID とともに確認できます。

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

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

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

ユニット変数の階層

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

順序は次のとおりです（優先度が低い順から高い順）。

App Lifecycle Manager は、次の順序で変数値を解決します。

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

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

ユニットの依存関係

App Lifecycle Manager を使用すると、ユニット間の依存関係を定義できます。これは、さまざまなコンポーネントが相互に依存する複雑な SaaS アプリケーションを構築する場合に重要です。依存関係により、関連するユニットが連携してプロビジョニングおよび管理されます。

依存関係はユニットの種類内で定義します。特定のユニット種類のユニットを作成すると、App Lifecycle Manager がその依存関係を自動的に管理します。

ユニットの種類での依存関係の定義

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 で定義された依存関係を持つユニットのプロビジョニングをリクエストすると、App Lifecycle Manager はこれらの依存関係ユニットが存在するかどうかを自動的に確認します。

依存関係ユニットが見つからない場合、App Lifecycle Manager は依存ユニットをプロビジョニングする前に自動的にプロビジョニングします。

App Lifecycle Manager は、依存関係ユニットが依存ユニットの前にプロビジョニングされるようにして、オペレーションの正しい順序を維持します。

変数マッピング

変数マッピングは、依存関係ユニットとその依存関係の間でデータ（変数値）を渡すメカニズムです。これは、依存関係の出力に基づいて依存関係ユニットを構成するために不可欠です。

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

例: 共有 Kubernetes クラスタ

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

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

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

シークレットを管理する

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

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

次のステップ

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