VM 作成時にカスタム スクリプトを実行する - VmStartupScript (プレビュー)
はじめに
この機能はプレビューです。今日から使い始めてフィードバックをいただけます。私たちに連絡する方法については、記事の最後で説明します。プレビュー中はテクニカル サポートが限定的であることに注意してください。
これは高度な機能であり、細心の注意を払って使用する必要があります。実行中のスクリプトは、管理者 (root) 権限で仮想マシン (VM) レベルで実行されます。適切に使用しないと、実行中のゲーム サーバーの通常のフローが中断されたり、まったく実行されなくなる可能性があります。スクリプトの内容についてはエンド ユーザーが責任を負います。
VmStartupScript の使用方法
VmStartupScript 機能を使用するには、カスタム スクリプトと、インストール予定の関連するすべてのソフトウェア (任意) を用意する必要があります。スクリプトは、仮想マシンが初期化されると実行を開始します。この操作は、各 VM でゲーム サーバーが起動する前に発生します。スクリプトが正常に実行を終了すると、MPS サービスはゲーム サーバーの初期化を完了し、StandingBy 状態にします。ゲーム サーバーのさまざまな状態の詳細については、マルチプレイヤー サーバーのライフサイクル を参照してください。 この機能を実際の運用環境で使用するには、開始前に 推奨される開発者ワークフロー を参照してください。スクリプトを作成する
- Linux VM の場合は PF_StartupScript.sh、Windows VM の場合は PF_StartupScript.ps1 というファイルを作成します。
- ファイルにセットアップ/実行コマンドを追加します。必要に応じて、スクリプトで使用できる一般的な 環境変数 をいくつか使用できます。一部のアクションはサポートされていないか、VM が正常に起動せず、意図しない課金が発生する可能性があります。詳細については、サポートされていない事項 セクションを参照してください。
ZIP ファイルの作成とアップロード
- スクリプトが使用または呼び出す予定の関連ソフトウェアをすべてフォルダーに集めます。スクリプトがサード パーティ ソフトウェアをインストールする場合は、実行中にダウンロードするか、ZIP ファイルにバンドルできます。何もインストールしない場合は、この手順をスキップしてください。
- 前のセクションで作成したスクリプト (.sh または .ps1) と、必要な場合は前のステップで集めたソフトウェアを含む ZIP ファイル (.zip) を作成します。スクリプト ファイルは ZIP ファイルのルートに配置し、ディレクトリ内に置かないでください。また、スクリプト ファイルの名前が PF_StartupScript.sh (Linux) または PF_StartupScript.ps1 (Windows) でない場合、実行されずゲーム サーバーの起動に失敗します。
- 以下のいずれかの方法で ZIP ファイルをアップロードします。
- PlayFab Game Manager を使用する
- GetAssetUploadUrl API 呼び出しから返される URL に、ヘッダー {“x-ms-blob-type”: “BlockBlob”} を付けて PUT リクエストを発行する。
- PowerShell コマンドレット を使用する。
スクリプトが必要とするすべてのバイナリとアセットを ZIP ファイルに含めることをお勧めします。これにより実行が速くなり、MPS がゲーム サーバーを提供するまでの時間が短縮されます。ゲーム サーバーが実行される関連プラットフォーム用のアセットを必ず含めてください。たとえば、Linux サーバーを使用する場合は、「amd64」の Debian/Ubuntu パッケージを含める必要があります。
新しいビルドにカスタム スクリプトを適用する
.zip ファイルをアップロードした後、VmStartupScriptAssetReference プロパティを構成した上で MPS API を使用して新しいビルドを作成します。手順については、MPS API を使用したビルドの作成方法 を参照してください。- アップロードされたアセット ファイルへの参照を含む VmStartupScriptConfiguration.VmStartupScriptAssetReference プロパティを追加します。このプロパティは、CreateBuildWithCustomContainer、CreateBuildWithManagedContainer、CreateBuildWithProcessBasedServer など、すべての「CreateBuild」関連 API の一部です。
- VmStartupScriptAssetReference.FileName プロパティに有効な値を追加します。この値は、アセット ファイルの名前と同じでなければなりません (例: vmstartupscriptassets.zip)。
- VmStartupScriptAssetReference.MountPath プロパティは空である必要があります。VmStartupScript 機能ではサポートされていないためです。
MountPath プロパティに値を設定すると、ビルドの作成操作は失敗します。
特別な考慮事項
Linux では、PF_StartupScript.sh ファイルを実行可能としてマークする必要がありますか?
MPS がスクリプト ファイルを実行する前に、実行可能としてマークし、Windows の行末 (“\r\n”) を Linux のもの (“\n”) に変換します。したがって、この 2 つについて心配する必要はありません。環境変数
以下は、スタートアップ スクリプトで使用できる環境変数です。サポートされていない事項
スクリプトからは以下のアクションを行うべきではありません。VM とゲーム サーバーのライフサイクルを中断する可能性が高くなります。- スタートアップ スクリプトの実行中にブロックしないでください。ゲーム サーバーを作成するには、スクリプトが正常に終了する必要があります。バックグラウンドで実行する必要がある場合は、Linux では systemd サービスとして、Windows では Windows サービスとしてインストールできます。
- ポート 30000 以降はゲーム サーバー用に使用され、ポート 56001 は VmAgent プロセス (MPS ゲーム サーバー オーケストレーター実行可能ファイル) が使用しているため、これらのポートを使用しないでください。
- D: (Windows) または /mnt (Linux) パス上のファイルは、VmAgent の動作に必要なため、変更しないでください (
PF_SHARED_CONTENT_FOLDER_VMのような編集可能なコンテンツを含むフォルダーは除く)。 - VmStartupScript 内、またはそれによって起動されるアプリから GSDK を使用しないでください。GSDK は GameServers からのみ使用する必要があります。
- MPS Control Plane との通信に問題が発生するため、仮想マシンを手動で再起動しないでください。
ポート
VmStartupScript 機能を使用する場合、各 VM で公開するポートをいくつか要求することができます。これらのポートは、スクリプトによって起動される任意のプログラムで使用できます。MPS がゲーム サーバー用に開くポートとは異なります。使用方法
VM ごとに最大 5 個のポートを要求できます。各ポートについて、プロトコル (TCP または UDP) と名前を指定する必要があります。2 つのポートを要求する方法の例を以下に示します。
たとえば、上記のサンプル スクリプトで要求された 2 つのポートの場合、VmStartupScript で以下の環境変数が見つかると期待できます。
ゲーム サーバー用に開かれるポートと同様に、ポートに接続するクライアントを認証するのはあなたの責任です。MPS はこれらのポートに対する認証機構を提供しません。
割り当てられるポートは 20000 番から始まることに気付くでしょう。ただし、この値は将来変更される可能性があるため、スクリプトにハードコードせず、常に環境変数を使用して適切なポート情報を取得することをお勧めします。
