Ausführen eines benutzerdefinierten Skripts während der VM-Erstellung – VmStartupScript (Vorschau)

Einführung

Wichtig

Dieses Feature befindet sich in der Vorschauphase. Sie können es gerne noch heute verwenden und uns Ihr Feedback geben. Anweisungen zum Herstellen einer Verbindung mit uns finden Sie am Ende des Artikels. Beachten Sie, dass der technische Support während der Vorschau eingeschränkt ist.

Mit VmStartupScript können Sie ein benutzerdefiniertes Skript auf virtuellen Computern (VMs) ausführen, die in Azure PlayFab Multiplayer-Servern (MPS) verwendet werden. MPS ist für Das Hosten von Spieleservern optimiert, sodass Es für Ihren Titel einfach ist, dynamisch je nach Bedarf zu skalieren. Um die einfache Anpassung einer großen Anzahl von Servern während der VM-Initialisierung zu verbessern, kann das benutzerdefinierte Skript auf jeder zugrunde liegenden VM ausgeführt werden, auf der Ihre Spieleserver gehostet werden. Es kann verwendet werden, um Aufgaben wie das Installieren von benutzerdefinierter Software, das Ändern von Sicherheitseinstellungen, die Verwendung eines benutzerdefinierten Diensts zum Protokollieren von Spielserverausgaben und -metriken usw. auszuführen.

Notiz

Dies ist ein erweitertes Feature, das mit äußerster Vorsicht verwendet werden sollte. Das ausgeführte Skript wird auf der Ebene virtueller Computer (VM) mit Administratorrechten (Root) ausgeführt. Wenn sie nicht ordnungsgemäß verwendet wird, kann dies möglicherweise den regulären Fluss der ausgeführten Spieleserver stören oder sogar verhindern, dass sie überhaupt ausgeführt werden. Der Endbenutzer ist für den Inhalt des Skripts verantwortlich.

Verwenden von VmStartupScript

Um das VmStartupScript-Feature verwenden zu können, müssen Sie ein benutzerdefiniertes Skript und die gesamte relevante Software (optional) bereitstellen, die Sie installieren möchten. Das Skript beginnt mit der Ausführung, wenn der virtuelle Computer initialisiert wird. Dieser Vorgang tritt auf, bevor die Spielserver auf jedem virtuellen Computer gestartet werden. Nachdem die Ausführung des Skripts erfolgreich abgeschlossen wurde, fährt der MPS-Dienst mit der Initialisierung der Spielserver fort und übergibt sie in den Status StandingBy . Weitere Informationen zum Zustand der verschiedenen Spielserver finden Sie unter Lebenszyklus eines Multiplayerservers.

Informationen zur Verwendung dieses Features in einer tatsächlichen Produktionsumgebung finden Sie unter Empfohlener Entwicklerworkflow vor dem Starten.

Erstellen eines Skripts

• Erstellen Sie eine Datei namens PF_StartupScript.sh für Linux-VMs oder PF_StartupScript.ps1 für Windows-VMs.
• Fügen Sie der Datei Setup-/Ausführungsbefehle hinzu. Wenn Sie sie benötigen, finden Sie hier einige häufig verwendete Umgebungsvariablen , die Sie im Skript verwenden können. Einige Aktionen werden nicht unterstützt oder würden dazu führen, dass die VMs nicht erfolgreich gestartet werden, was zu unerwünschten Gebühren führt. Weitere Informationen finden Sie im Abschnitt Was wird nicht unterstützt .

Skriptbeispiele finden Sie unter VmStartupScriptGallery.

Erstellen und Hochladen der gezippten Datei

1. Sammeln Sie alle relevanten Software in einem Ordner, den Ihr Skript verwenden oder aufrufen möchte. Wenn Ihr Skript Software von Drittanbietern installiert, kann Ihr Skript diese während der Ausführung herunterladen oder in der ZIP-Datei gebündelt werden. Überspringen Sie diesen Schritt, wenn Sie nichts installieren.
2. Erstellen Sie eine ZIP-Datei (.zip) mit dem Skript (.sh oder .ps1), das Sie im vorherigen Abschnitt erstellt haben, und der Software, die Sie im vorherigen Schritt gesammelt haben, falls erforderlich. Die Skriptdatei sollte sich im Stammverzeichnis der ZIP-Datei und nicht in einem Verzeichnis befinden. Wenn Ihre Skriptdatei nicht PF_StartupScript.sh (Linux) oder PF_StartupScript.ps1 (Windows) benannt ist, wird sie nicht ausgeführt, und die Spielserver können nicht gestartet werden.
3. Laden Sie die ZIP-Datei mit einer der folgenden Methoden hoch:

• Verwenden des PlayFab-Spiel-Managers
• Stellen Sie eine PUT-Anforderung mit dem Header {"x-ms-blob-type": "BlockBlob"} für die URL aus, die vom GetAssetUploadUrl-API-Aufruf zurückgegeben wird.
• Verwenden Sie die PowerShell-Cmdlets.

Notiz

Es wird empfohlen, alle Binärdateien und Ressourcen, die von Ihrem Skript benötigt werden, in die ZIP-Datei einzuschließen, da dies zu einer schnelleren Ausführung und kürzerer Zeit für MPS für die Bereitstellung Ihrer Spieleserver führt. Stellen Sie sicher, dass Sie die Ressourcen für die relevante Plattform einschließen, auf der Ihre Spieleserver ausgeführt werden. Wenn Sie beispielsweise Linux-Server verwenden, sollten Sie Debian-/Ubuntu-Pakete vom Typ "amd64" einschließen.

Anwenden des benutzerdefinierten Skripts auf neue Builds

Verwenden Sie nach dem Hochladen der .zip-Datei die MPS-API, um nach dem Konfigurieren der VmStartupScriptAssetReference-Eigenschaft einen neuen Build zu erstellen. Anweisungen finden Sie unter Erstellen von Builds mithilfe der MPS-API.

• Fügen Sie die VmStartupScriptConfiguration.VmStartupScriptAssetReference-Eigenschaft hinzu, die einen Verweis auf die hochgeladene Ressourcendatei enthält. Diese Eigenschaft ist Teil aller "CreateBuild"-APIs, z. B . CreateBuildWithCustomContainer, CreateBuildWithManagedContainer und CreateBuildWithProcessBasedServer.
• Fügen Sie einen gültigen Wert für die VmStartupScriptAssetReference.FileName-Eigenschaft hinzu. Dieser Wert muss mit dem Namen Ihrer Ressourcendatei identisch sein, z. B. vmstartupscriptassets.zip.
• Die VmStartupScriptAssetReference.MountPath-Eigenschaft muss leer sein, da für das VmStartupScript-Feature nicht unterstützt wird.

Notiz

Wenn Sie einen Wert für die MountPath-Eigenschaft einrichten, schlägt der Builderstellungsvorgang fehl.

Im folgenden Codebeispiel wird ein Build mit Linux-Containern erstellt und dann das Skript in vmstartupscriptassets.zip verwendet, um die VMs anzupassen:

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 wird während der Propping-Phase des virtuellen Computers ausgeführt und muss erfolgreich beendet werden, damit die Spielserver gestartet werden können. Wenn ein Fehler auftritt (anderer Exitcode als 0), wechselt der virtuelle Computer nicht in den Zustand "Wird ausgeführt", und Sie müssen zum Debuggen RDP/SSH mit dem virtuellen Computer herstellen. Weitere Informationen finden Sie unter Empfohlener Entwicklerworkflow. Der virtuelle Computer versucht weiterhin, vmStartupScript auszuführen.

Besondere Überlegungen

Muss die PF_StartupScript.sh Datei unter Linux als ausführbare Datei gekennzeichnet sein?

Bevor MPS die Skriptdatei ausführt, markiert es sie als ausführbar und konvertiert dann alle Windows-Zeilenenden ("\r\n") in Linux-Dateien ("\n"). Sie müssen sich also keine Gedanken über diese beiden Dinge machen.

Umgebungsvariablen

Im Folgenden finden Sie Umgebungsvariablen, die Sie in Ihrem Startskript verwenden können.

Name	Beschreibung
PF_TITLE_ID	PlayFab-Titel-ID
PF_BUILD_ID	PlayFab MPS-Build-ID
PF_VM_ID	MPS-VM-ID
PF_REGION	Azure-Region, in der der virtuelle Computer gehostet wird
PF_PUBLIC_IPV4_ADDRESS	Öffentliche IP-Adresse des virtuellen Computers
PF_FQDN	Vollqualifizierter Domänenname, der der öffentlichen IP-Adresse des virtuellen Computers entspricht
PF_SHARED_CONTENT_FOLDER_VM	Ordner mit VM-weiten freigegebenen Inhalten

Was nicht unterstützt wird

Sie sollten diese Aktionen nicht über Ihr Skript ausführen, da die Wahrscheinlichkeit hoch ist, dass der Lebenszyklus von VM- und Spielservern unterbrochen wird:

• Blockieren Sie nicht während der Ausführung des Startskripts. Das Skript muss erfolgreich beendet werden, damit die Spielserver erstellt werden. Wenn Sie etwas benötigen, das im Hintergrund ausgeführt werden soll, können Sie es entweder als systemd-Dienst unter Linux oder als Windows-Dienst installieren.
• Verwenden Sie keine Ports ab 30000, da sie für die Spielserver oder Port 56001 verwendet werden, da er vom VmAgent-Prozess (der ausführbaren Datei des MPS-Spielserver-Orchestrators) verwendet wird.
• Ändern Sie keine der Dateien in den Pfaden D: (Windows) oder /mnt (Linux), da diese Dateien für den VmAgent-Vorgang erforderlich sind (mit Ausnahme von Ordnern, die bearbeitbare Inhalte enthalten, z. B PF_SHARED_CONTENT_FOLDER_VM. ).
• Sie sollten GSDK nicht aus dem VmStartupScript oder einer App verwenden, die von diesem gestartet wird. GSDK sollte nur von GameServern verwendet werden.
• Sie sollten den virtuellen Computer nicht manuell neu starten, da dieser Vorgang zu Herausforderungen bei der Kommunikation mit der MPS-Steuerungsebene führt.

Ports

Wenn Sie das VmStartupScript-Feature verwenden, ist es möglich, eine Reihe von Ports anzufordern, die auf jedem virtuellen Computer verfügbar gemacht werden sollen. Diese Ports können von allen Programmen verwendet werden, die von Ihrem Skript gestartet werden und unterscheiden sich von den Ports, die MPS für Ihre Spieleserver öffnet.

Nutzung

Sie können bis zu fünf Ports für jede VM anfordern. Für jeden Port müssen Sie das Protokoll (TCP oder UDP) und einen Namen angeben. Im Folgenden finden Sie ein Beispiel für die Anforderung von zwei Ports:

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
            }
        }
}

Sofern Sie nach Ports fragen, stehen Ihrem Skript die folgenden Umgebungsvariablen zur Verfügung, um Informationen zu den Ports zu erhalten:

Name	Beschreibung
PF_STARTUP_SCRIPT_PORT_COUNT	Anzahl der VmStartupScript-Ports
PF_STARTUP_SCRIPT_PORT_NAME_(index)	Der Name für den Port, wie in der Anforderung beschrieben.
PF_STARTUP_SCRIPT_PORT_PROTOCOL_(index)	Das Protokoll für den Port, wie in der Anforderung beschrieben
PF_STARTUP_SCRIPT_PORT_INTERNAL_(index)	Der Port, an den das Programm auf dem virtuellen Computer gebunden werden soll
PF_STARTUP_SCRIPT_PORT_EXTERNAL_(index)	Der Port, der im externen Endpunkt geöffnet wird. Externe Clients sollten diesen Port verwenden, um eine Verbindung mit dem Programm herzustellen, das an den INTERNEN Port gebunden ist.

Für die beiden ports, die im obigen Beispielskript angefordert wurden, sollten Sie z. B. die folgenden Umgebungsvariablen in Ihrer VmStartupScript-Datei erwarten:

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

Wichtig

Ähnlich wie bei den Ports, die wir für Spieleserver öffnen, liegt es an Ihnen, Clients zu authentifizieren, die eine Verbindung mit Ihren Ports herstellen. MPS bietet keinen Authentifizierungsmechanismus für diese Ports.

Notiz

Kunden werden feststellen, dass zugeordnete Ports ab Nummer 20000 beginnen. Es wird jedoch empfohlen, dass Sie diesen Wert nicht in Ihren Skripts hartcodieren, da er sich in Zukunft ändern kann, und immer die Umgebungsvariablen verwenden, um die richtigen Portinformationen zu erhalten.

Entwicklung/Debuggen

Bevor Sie das VmStartupScript-Feature verwenden, sollten Sie sich diese Beispielskripts in unserem Open-Source-Repository auf GitHub (VmStartupScriptGallery) ansehen. Beiträge sind willkommen!

Empfohlener Entwicklungsworkflow

Zunächst sollten Sie einen Testbuild mit einer einzelnen VM erstellen. Diese VM sollte über ähnliche Spezifikationen verfügen wie die, auf der Sie ihre Produktionsumgebung bereitstellen möchten. Wenn diese einzelne VM bereitgestellt wird, können Sie RDP/SSH verwenden, die erforderlichen Dateien kopieren und versuchen, das Skript zu bearbeiten/auszuführen, bis es erfolgreich ist.

Sobald diese VM ausgeführt wird und Sie sich vergewissern, dass sich Ihr Skript wie erwartet verhält, können Sie das Skript und die Ressourcen in einer .zip-Datei platzieren. Anschließend können Sie es hochladen und versuchen, einen Build damit zu erstellen. Versuchen Sie erneut, einen einzelnen VM-Build zu erstellen, um Kosten zu sparen und hochzuskalieren, sobald Sie sicher sind, dass Ihr Skript funktioniert.

Wenn bei der Ausführung Ihres Skripts Probleme auftreten, können Sie debuggen, indem Sie sich über RDP/SSH bei der VM anmelden und die Dateien PF_StartupScriptStdOut.txt und PF_StartupScriptStdErr.txt auf die Standardausgabe- bzw. Standardfehlerstreams des Skripts überprüfen. Diese Dateien befinden sich entweder auf Laufwerk D: unter Windows oder auf /mnt unter Linux.

Das Skript sollte idempotent sein, da die Wahrscheinlichkeit besteht, dass es mehrmals ausgeführt wird. Wenn das Skript beispielsweise versucht, eine externe Ressource herunterzuladen, und es aufgrund eines Netzwerkproblems fehlschlägt, wiederholt MPS die gesamte Skriptausführung.

Support

Der MPS-Dienst führt alles aus, was Sie auf Ihrem VmStartupScript haben. Das Team bietet jedoch keine Unterstützung für die einzelnen Aktionen und ausführbaren Dateien, die als Teil des Skripts installiert/ausgeführt werden.

Während der Vorschauphase erhalten Sie Support und Feedback über PlayFab-Communityforen und Discord. Wenn Sie Probleme mit einem Skript im Repository VmStartupScriptGallery haben oder ein neues Skript anfordern möchten, verwenden Sie "Problem auf GitHub öffnen".