> For the complete documentation index, see [llms.txt](/llms.txt)

# GS2-Deploy

マスターデータCI/CD機能




GS2-Deploy は、GS2 の各マイクロサービスのネームスペースやマスターデータをコードとして管理し、宣言的にプロビジョニングするための機能を提供します。<br>
AWS の CloudFormation に近い思想で設計されており、テンプレートファイルに記述したリソース定義を元に、複数のマイクロサービスをまたいだ環境構築・更新・削除をひとつのまとまり（スタック）として扱えます。

ゲーム開発においては、マスターデータの調整やネームスペース構成の変更が頻繁に発生します。<br>
GS2-Deploy を活用することで、これらの変更を Git で管理し、GitHub などのリポジトリと連携した CI/CD パイプラインから自動的にデプロイする運用が可能になります。

## スタック (Stack)

スタックは、GS2 のリソースをまとめて管理する単位です。

スタックは YAML 形式で記述されたテンプレートを元に作成され、テンプレートに記述されたリソース定義に従って、ネームスペースやマスターデータなどを自動的に作成・更新・削除します。<br>
1つのスタックには複数のマイクロサービスにまたがるリソースを含めることができ、ゲームを構成する一連の設定をひとまとまりとして扱えます。

```mermaid
graph LR
  Template["テンプレート(YAML)"] --> Stack["スタック"]
  Stack --> R1["GS2-Account ネームスペース"]
  Stack --> R2["GS2-Inventory マスターデータ"]
  Stack --> R3["GS2-Mission マスターデータ"]
  Stack --> R4["GS2-Showcase マスターデータ"]
```

スタックは内部的に以下の状態を持ちます。

- `CREATE_PROCESSING`: 作成処理中
- `CREATE_COMPLETE`: 作成が完了し、リソースが利用可能
- `UPDATE_PROCESSING`: 更新処理中
- `UPDATE_COMPLETE`: 更新完了
- `ROLLBACK_PROCESSING`: 失敗時のロールバック処理中
- `ROLLBACK_COMPLETE`: ロールバック完了
- `DELETE_PROCESSING`: 削除処理中
- `DELETE_COMPLETE`: 削除完了

スタックの更新時に途中で失敗した場合は、自動的に変更前の状態に戻す《ロールバック》処理が行われます。

## テンプレート

テンプレートは YAML 形式で記述します。記述するセクションは以下です。

- `GS2TemplateFormatVersion`: テンプレートのフォーマットバージョン
- `Description`: スタックの説明
- `Resources`: 作成するリソースの定義
- `Outputs`: スタック作成後に他システムから参照できる値の定義

以下はテンプレートの記述例です。

```yaml
GS2TemplateFormatVersion: "2019-05-01"
Description: |
  GS2-Account namespace

Resources:
  Namespace:
    Type: GS2::Account::Namespace
    Properties:
      Name: namespace-0001
      Description: anonymous account
      ChangePasswordIfTakeOver: true

Outputs:
  NamespaceId: !GetAttr Namespace.Item.NamespaceId
```

`Type` には作成対象となる GS2 リソースの種別を、`Properties` には各リソース固有の設定値を指定します。<br>
`!GetAttr` 関数を使用することで、他のリソースの出力値を参照しながら依存関係のあるリソースを連鎖的に構築できます。

## リソース (Resource)

スタック内に作成される個々の GS2 リソースを《リソース》と呼びます。<br>
リソースには以下のような情報が保持されます。

- `type`: リソースの種別 (`GS2::Account::Namespace` など)
- `name`: テンプレート内で割り当てられた論理名
- `request`: リソース作成時に GS2 API へ送信されたリクエスト内容
- `response`: GS2 API からの応答内容
- `rollbackContext`: ロールバック実行時に使用される情報

スタックを参照することで、スタックに含まれる全てのリソースの作成状況を一覧で確認できます。

## 出力 (Output)

テンプレートの `Outputs` セクションで宣言された値は、スタック作成完了後に他の場所から参照できる出力値として保存されます。

出力は、外部システム連携や、別のスタックでの値の参照、運用ツールが GS2 リソースの GRN を取得する用途などに利用できます。

## イベント (Event)

スタックの作成・更新・削除の処理中に発生する個々の操作は《イベント》として記録されます。<br>
スタック処理が失敗した場合は、イベント履歴を確認することで、どのリソースのどの段階で失敗したのかを特定できます。

## GitHub 連携

テンプレートファイルは GS2 のマネージメントコンソールから直接アップロードする他、GitHub リポジトリと連携して取得することも可能です。

GitHub 連携を利用すると、以下のような運用が可能になります。

- マスターデータの設定を Pull Request ベースでレビュー・マージするワークフロー
- main ブランチへのマージをトリガーに、CI から GS2-Deploy を呼び出してリソースを更新するパイプライン
- 環境ごと (開発・ステージング・本番) に異なるブランチ・スタックを割り当てる多環境運用

GitHub からのテンプレート取得には GitHub API のアクセストークンを使用します。プライベートリポジトリでも利用可能です。

## マスターデータをコードで管理する

GS2-Deploy の主要なユースケースの1つは、各マイクロサービスのマスターデータを GS2-Deploy のテンプレート経由で登録することです。

ネームスペース定義と同じテンプレート内にマスターデータの内容を記述しておくことで、ネームスペース作成からマスターデータ登録までを1スタックで一括管理できます。<br>
これにより、マスターデータの変更履歴を Git で追跡でき、過去バージョンへのロールバックや、レビュー前の変更内容の事前確認なども容易になります。

## 操作対象について

GS2-Deploy はプロジェクトの構築を担う管理 API のため、原則としてゲームエンジン側のクライアント (Unity / Unreal Engine 等) から呼び出すサービスではありません。<br>
実運用では、マネージメントコンソール経由での操作 と、CI/CD パイプラインから GS2 SDK を介して操作するワークフロー が中心になります。

## 実装例

GS2-Deploy は管理API中心のマイクロサービスです。ゲームエンジン用 SDK (Unity/Unreal Engine) には専用の Domain クラスが提供されていません。

そのため、ゲームクライアントから直接呼び出すのではなく、以下のいずれかの手段で操作することを推奨します。

- マネジメントコンソール
- GS2 CLI
- 各種言語向け一般SDK (C# / Go / Python / TypeScript / PHP / Java)
- GS2-Deploy 自身のテンプレートによる宣言的な管理

各種SDKの詳細は対応するリファレンスページを参照してください。

## 詳細なリファレンス

[GS2-Deploy API リファレンス](../../api_reference/deploy)