​

Running custom script during VM creation - VmStartupScript (preview)

​

Introduction

​

How to use VmStartupScript

​

Create a script

• Create a file called PF_StartupScript.sh for Linux VMs or PF_StartupScript.ps1 for Windows VMs.
• Add set-up/execution commands in the file. If you need them, here are some commonly used environment variables that you can use in the script. Some actions aren’t supported or would cause the VMs to not start successfully, incurring unwanted charges. For details, see the What is not supported section.

​

Create and upload the zipped file

1. Gather all the relevant software in a folder that your script is planning to use or call. If your script installs third party software, your script can download it during execution, or it can be bundled with it in the zipped file. Skip this step if you aren’t installing anything.
2. Create a zipped file (.zip) with the script (.sh or .ps1) you created in the earlier section and the software you gathered in the earlier step, if needed. The script file should be at the root of the zipped file and not inside a directory. Additionally, if your script file isn’t named PF_StartupScript.sh (Linux) or PF_StartupScript.ps1 (Windows), it will not be executed and the game servers will fail to start.
3. Upload the zipped file using one of the following methods:

• Use PlayFab Game Manager
• Issue a PUT request with the header {“x-ms-blob-type”: “BlockBlob”} on the URL returned from the GetAssetUploadUrl API call.
• Use the PowerShell cmdlets.

​

Apply the custom script to new builds

• Add the VmStartupScriptConfiguration.VmStartupScriptAssetReference property that includes a reference to the uploaded assets file. This property is part of all the “CreateBuild” related APIs, like CreateBuildWithCustomContainer, CreateBuildWithManagedContainer and CreateBuildWithProcessBasedServer.
• Add a valid value for the VmStartupScriptAssetReference.FileName property. This value must be the same as the name of your assets file, for example vmstartupscriptassets.zip.
• The VmStartupScriptAssetReference.MountPath property must be empty, since isn’t supported for the VmStartupScript feature.

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);

​

Special considerations

​

On Linux, do I need to have the PF_StartupScript.sh file marked as executable?

​

Environment variables

​

What is not supported

• Don’t block during the execution of the startup script. The script must end successfully for the game servers to be created. If you need something to run in the background, you can install it either as a systemd service on Linux or a Windows service.
• Don’t use ports starting from 30000 since they’re used for the game servers or port 56001 as it’s used by VmAgent process (the MPS game server orchestrator executable).
• Don’t modify any of the files on the D: (Windows) or /mnt (Linux) paths as these files are necessary for VmAgent operation (apart from folders that contain editable content, like the PF_SHARED_CONTENT_FOLDER_VM).
• You shouldn’t use GSDK from within the VmStartupScript or an app that is launched by it. GSDK should only be used from GameServers.
• You shouldn’t manually reboot the Virtual Machine as this operation will create challenges in the communication with the MPS Control Plane.

​

Ports

​

Usage

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

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

​

Development/Debugging

​

Recommended development workflow

​

Support