VM 作成中のカスタムスクリプトの実行 - VmStartupScript (プレビュー)

[アーティクル]
07/13/2023

概要

Important

この機能はプレビュー段階にあります。今すぐ使用を開始して、フィードバックをお寄せください。 Microsoft に接続する方法については、記事の最後に記載されています。プレビュー期間中はテクニカルサポートが制限されていることに注意してください。

VmStartupScript を使用すると、Azure PlayFab マルチプレイヤーサーバー (MPS) で使用される仮想マシン (VM) でカスタムスクリプトを実行できます。 MPS は、ゲームサーバーのホスティングに最適化されており、タイトルは需要に応じて動的に拡大縮小しやすくなります。 VM の初期化中に多数のサーバーをすばやくカスタマイズしやすくするために、ゲームサーバーをホストするすべての基になる VM でカスタムスクリプトを実行できます。これは、カスタムソフトウェアのインストール、セキュリティ設定の変更、カスタムサービスを使用したゲームサーバーの出力とメトリックスのログ記録などのタスクを実行するために使用できます。

注意

これは高度な機能であり、細心の注意を払って使用する必要があります。実行中のスクリプトは、管理者 (ルート) 特権を持つ仮想マシン (VM) レベルで実行されます。適切に使用しないと、実行中のゲームサーバーの通常のフローが中断されたり、まったく実行されなくなる可能性があります。エンドユーザーはスクリプトの内容に対して責任を負います。

VmStartupScript の使用方法

VmStartupScript 機能を使用するには、カスタムスクリプトと、インストールする予定のすべての関連ソフトウェア (オプション) を指定する必要があります。仮想マシンが初期化されると、スクリプトの実行が開始されます。この操作は、すべての VM でゲームサーバーが起動する前に発生します。スクリプトの実行が正常に完了すると、MPS サービスはゲームサーバーの初期化を完了し、StandingBy 状態に移行します。さまざまなゲームサーバーの状態の詳細については、「マルチプレイヤーサーバーのライフサイクル」を参照してください。

実際の運用環境でこの機能を使用するには、開始する前に、「推奨される開発者ワークフロー」を参照してください。

台本を作成する

Linux VM の場合は PF_StartupScript.sh、Windows VM の場合は PF_StartupScript.ps1 という名前のファイルを作成します。
セットアップ/実行コマンドをファイルに追加します。必要に応じて、スクリプトで使用できる一般的に使用される環境変数を次にいくつか示します。一部のアクションはサポートされていないか、VM が正常に起動せず、不要な料金が発生する可能性があります。詳細については、「サポートされていないもの」セクションを参照してください。

スクリプトの例については、「VmStartupScriptGallery」を参照してください。

ZIP ファイルを作成してアップロードする

スクリプトが使用または呼び出す予定のフォルダーに、関連するすべてのソフトウェアを集めます。スクリプトがサードパーティ製ソフトウェアをインストールする場合、スクリプトは実行中にダウンロードすることも、ZIP ファイルにバンドルすることもできます。何もインストールしていない場合は、この手順をスキップします。
前のセクションで作成したスクリプト (.sh または .ps1) と、必要に応じて前の手順で収集したソフトウェアを含む ZIP ファイル (.zip) を作成します。スクリプトファイルは、ディレクトリ内ではなく ZIP ファイルのルートにある必要があります。また、スクリプトファイルの名前が PF_StartupScript.sh (Linux) または PF_StartupScript.ps1 (Windows) でない場合、スクリプトファイルは実行されず、ゲームサーバーの起動に失敗します。
次のいずれかの方法を使って、ZIP ファイルをアップロードします。

PlayFab ゲームマネージャーを使用する
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 コンテナーを使用してビルドを作成し、vmstartupscriptassets.zip 内のスクリプトを使用して VM をカスタマイズします。

var request = new CreateBuildWithCustomContainerRequest()
{ 
    ContainerImageReference = new ContainerImageReference()
    {
         ImageName= "testimagename",
         Tag= "0.1"
    },
    ContainerFlavor = ContainerFlavor.CustomLinux,
    BuildName = "testbuildwithvmstartupscript",
    VmSize = AzureVmSize.Standard_D2as_v4,
    MultiplayerServerCountPerVm = 3,
    Ports= new List<Port>
    {
        new Port()
        {
            Name= "port",
            Num= 123,
            Protocol = ProtocolType.TCP   
        }
    },
    RegionConfigurations = new List<BuildRegionParams> { new BuildRegionParams()
    {
        Region = "EastUs",
        StandbyServers = 3,
        MaxServers = 6

    } 
    },
    VmStartupScriptConfiguration = new VmStartupScriptParams()
    {
        VmStartupScriptAssetReference = new AssetReferenceParams()
        {
            FileName = "vmstartupscriptassets.zip"
        }
    }
};
var result = await PlayFabMultiplayerAPI.CreateBuildWithCustomContainerAsync(request);

VmStartupScript は VM の "Propping" ステージ中に実行され、ゲームサーバーを起動するには正常に終了する必要があります。失敗した場合 (0 以外の終了コード)、VM は "Running" 状態に移行しないため、デバッグするには VM に RDP/SSH を実行する必要があります。詳細については、「推奨される開発者ワークフロー」を参照してください。 VM は VmStartupScript の実行を再試行し続けます。

特別な考慮事項

Linux では、PF_StartupScript.sh ファイルを実行可能ファイルとしてマークする必要がありますか?

MPS がスクリプトファイルを実行する前に、スクリプトファイルを実行可能ファイルとしてマークし、Windows の行末 ("\r\n") を Linux の行末 ("\n") に変換します。そのため、これら 2 つのことを心配する必要はありません。

環境変数

スタートアップスクリプトで使用できる環境変数を次に示します。

名前	説明
PF_TITLE_ID	PlayFab タイトル ID
PF_BUILD_ID	PlayFab MPS ビルド ID
PF_VM_ID	MPS 仮想マシン ID
PF_REGION	VM がホストされる Azure リージョン
PF_PUBLIC_IPV4_ADDRESS	VM のパブリック IP アドレス
PF_FQDN	VM のパブリック IP に対応する完全修飾ドメイン名
PF_SHARED_CONTENT_FOLDER_VM	VM 全体の共有コンテンツを含むフォルダー

サポートされていないもの

VM とゲームサーバーのライフサイクルを中断する可能性が高いため、スクリプトからこれらのアクションを実行しないでください。

スタートアップスクリプトの実行中はブロックしないでください。ゲームサーバーを作成するには、スクリプトが正常に終了する必要があります。バックグラウンドで実行するものが必要な場合、Linux 上の systemd サービスまたは Windows サービスとしてインストールできます。
30000 から始まるポートはゲームサーバーに使用されるため使用しないでください。ポート 56001 は VmAgent プロセス (MPS ゲームサーバーオーケストレーター実行可能ファイル) によって使用されるため、使用しないでください。
D: (Windows) または /mnt (Linux) パス上のファイルは、VmAgent 操作に必要なので変更しないでください (PF_SHARED_CONTENT_FOLDER_VM などの編集可能なコンテンツを含むフォルダーは除きます)。
VmStartupScript またはそれによって起動されるアプリ内から GSDK を使用しないでください。 GSDK は GameServers からのみ使用する必要があります。
MPS コントロールプレーンとの通信で問題が発生する可能性があるため、仮想マシンを手動で再起動しないでください。

Port

VmStartupScript 機能を使用すると、各 VM で多数のポートを公開するように要求できます。これらのポートは、スクリプトによって起動される任意のプログラムで使用でき、MPS がゲームサーバー用に開くポートとは異なります。

使用法

VM ごとに最大 5 つのポートを要求できます。ポートごとに、プロトコル (TCP または UDP) と名前を指定する必要があります。以下は、2 つのポートを要求する方法の例です。

VmStartupScriptConfiguration = new VmStartupScriptParams()
{
    VmStartupScriptAssetReference = new AssetReferenceParams()
    {
        FileName = "vmstartupscriptassets.zip"
    },
    PortRequests = new List<VmStartupScriptPortRequest>()
        {
            new VmStartupScriptPortRequest()
            {
                Name = "port0",
                Protocol = ProtocolType.TCP
            },
            new VmStartupScriptPortRequest()
            {
                Name = "port1",
                Protocol = ProtocolType.UDP
            }
        }
}

任意のポートを要求する場合、スクリプトで次の環境変数を使用して、ポートに関する情報を取得できます。

名前	説明
PF_STARTUP_SCRIPT_PORT_COUNT	VmStartupScript ポートの数
PF_STARTUP_SCRIPT_PORT_NAME_(index)	要求に記載されているポートの名前
PF_STARTUP_SCRIPT_PORT_PROTOCOL_(index)	要求に記載されているポートのプロトコル
PF_STARTUP_SCRIPT_PORT_INTERNAL_(index)	VM でプログラムがバインドするポート
PF_STARTUP_SCRIPT_PORT_EXTERNAL_(index)	外部エンドポイントで開くポート。外部クライアントは、このポートを使用して、INTERNAL ポートにバインドするプログラムに接続する必要があります

たとえば、上記のサンプルスクリプトで要求された 2 つのポートの場合、VmStartupScript でこれらの環境変数が見つかるはずです。

PF_STARTUP_SCRIPT_PORT_COUNT

PF_STARTUP_SCRIPT_PORT_INTERNAL_0
PF_STARTUP_SCRIPT_PORT_EXTERNAL_0
PF_STARTUP_SCRIPT_PORT_NAME_0
PF_STARTUP_SCRIPT_PORT_PROTOCOL_0

PF_STARTUP_SCRIPT_PORT_INTERNAL_1
PF_STARTUP_SCRIPT_PORT_EXTERNAL_1
PF_STARTUP_SCRIPT_PORT_NAME_1
PF_STARTUP_SCRIPT_PORT_PROTOCOL_1

Important

ゲームサーバー用に開いているポートと同様に、ポートに接続するクライアントを認証するのはユーザーの責任です。 MPS では、これらのポートの認証メカニズムは提供されません。

注意

顧客は、割り当てられたポートが 20000 以降から始まることがわかります。ただし、今後変更される可能性があるため、スクリプトではこの値をハードコードせず、常に環境変数を使用して適切なポート情報を取得することをお勧めします。

開発/デバッグ

VmStartupScript 機能を使用する前に、GitHub (VmStartupScriptGallery) のオープンソースリポジトリでこれらのサンプルスクリプトを確認することをお勧めします。貢献は大歓迎です。

推奨される開発ワークフロー

最初に、単一の VM でテストビルドを作成する必要があります。この VM には、運用環境のビルドを展開する予定の VM と同様の仕様が必要です。この単一の VM が展開されたら、RDP/SSH を実行し、必要なファイルをコピーして、正常に実行されるまでスクリプトの編集/実行を試みることができます。

この VM が起動して実行され、スクリプトが期待どおりに動作することを確認したら、スクリプトとアセットを .zip ファイルに配置できます。その後、アップロードして、ビルドを作成してみることができます。コストを節約するために単一の VM ビルドを再度作成し、スクリプトが機能することを確認したら拡大してみます。

スクリプトの実行中に問題が発生した場合は、RDP/SSH 経由で VM にログインしてデバッグし、ファイル PF_StartupScriptStdOut.txt と PF_StartupScriptStdErr.txt でスクリプトの標準出力ストリームと標準エラーストリームをそれぞれ確認できます。これらのファイルは、Windows では D: ドライブ、Linux では /mnt 上にあります。

スクリプトは、複数回実行される可能性があるため、べき等である必要があります。たとえば、スクリプトが外部リソースをダウンロードしようとして、ネットワークの問題が原因で失敗した場合、MPS はスクリプトの実行全体を再試行します。

サポート

MPS サービスは、VmStartupScript 上にあるものをすべて実行します。ただし、チームは、スクリプトの一部としてインストール/実行される個々のアクションと実行可能ファイルについてはサポートを提供しません。

プレビュー中は、PlayFab コミュニティフォーラムと Discord を使用してサポートを受け、フィードバックを提供します。 VmStartupScriptGallery リポジトリ内のスクリプトに問題がある場合、または新しいスクリプトを要求する場合は、GitHub で問題を開きます。

次の方法で共有

VM 作成中のカスタムスクリプトの実行 - VmStartupScript (プレビュー)

概要

VmStartupScript の使用方法

台本を作成する

ZIP ファイルを作成してアップロードする

新しいビルドにカスタムスクリプトを適用する

特別な考慮事項

Linux では、PF_StartupScript.sh ファイルを実行可能ファイルとしてマークする必要がありますか?

環境変数

サポートされていないもの

Port

使用法

開発/デバッグ

推奨される開発ワークフロー

サポート

フィードバック

その他のリソース

次の方法で共有

VM 作成中のカスタム スクリプトの実行 - VmStartupScript (プレビュー)

概要

VmStartupScript の使用方法

台本を作成する

ZIP ファイルを作成してアップロードする

新しいビルドにカスタム スクリプトを適用する

特別な考慮事項

Linux では、PF_StartupScript.sh ファイルを実行可能ファイルとしてマークする必要がありますか?

環境変数

サポートされていないもの

Port

使用法

開発/デバッグ

推奨される開発ワークフロー

サポート

フィードバック

その他のリソース

VM 作成中のカスタムスクリプトの実行 - VmStartupScript (プレビュー)

新しいビルドにカスタムスクリプトを適用する