VM을 만드는 동안 사용자 지정 스크립트 실행 - VmStartupScript(미리 보기)

아티클
07/11/2023

소개

Important

이 기능은 미리 보기 상태입니다. 오늘 사용을 시작하고 피드백을 제공해 드립니다. Microsoft와 연결하는 방법에 대한 지침은 문서의 끝에 제공됩니다. 미리 보기 중에는 기술 지원이 제한됩니다.

VmStartupScript를 사용하면 Azure PlayFab MPS(멀티 플레이어 서버)에서 사용되는 VM(가상 머신)에서 사용자 지정 스크립트를 실행할 수 있습니다. MPS는 게임 서버 호스팅에 최적화되어 있어 타이틀이 수요에 따라 동적으로 확장되기 쉽습니다. VM 초기화 중에 많은 수의 서버를 빠르게 사용자 지정하는 용이성을 개선하기 위해 사용자 지정 스크립트는 게임 서버를 호스트하는 모든 기본 VM에서 실행할 수 있습니다. 사용자 지정 소프트웨어 설치, 보안 설정 수정, 사용자 지정 서비스를 사용하여 게임 서버 출력 및 메트릭 등을 기록하는 등의 작업을 수행하는 데 사용할 수 있습니다.

참고 항목

이 기능은 매우 주의해서 사용해야 하는 고급 기능입니다. 실행 중인 스크립트는 관리자(루트) 권한으로 VM(Virtual Machine) 수준에서 실행됩니다. 제대로 사용되지 않으면 실행 중인 게임 서버의 정기적인 흐름을 방해하거나 실행되지 않을 수 있습니다. 최종 사용자는 스크립트의 콘텐츠를 담당합니다.

사용 방법

VmStartupScript 기능을 사용하려면 사용자 지정 스크립트와 설치하려는 모든 관련 소프트웨어(선택 사항)를 제공해야 합니다. 가상 머신이 초기화되면 스크립트가 실행하기 시작합니다. 이 작업은 게임 서버가 모든 VM에서 시작되기 전에 발생합니다. 스크립트 실행이 성공적으로 완료되면 MPS 서비스는 게임 서버 초기화를 완료하고 이를 StandingBy 상태로 전달합니다. 다른 게임 서버의 상태에 대한 자세한 내용은 멀티 플레이어 서버의 수명 주기를 참조하세요.

실제 프로덕션 환경에서 이 기능을 사용하려면 시작하기 전에 권장되는 개발자 워크플로 를 참조하세요.

스크립트 만들기

Linux VM용 PF_StartupScript.sh 또는 Windows VM용 PF_StartupScript.ps1 파일을 만듭니다.
파일에 설정/실행 명령을 추가합니다. 필요한 경우 스크립트에서 사용할 수 있는 몇 가지 일반적으로 사용되는 환경 변수는 다음과 같습니다. 일부 작업은 지원되지 않거나 VM이 성공적으로 시작되지 않아 원치 않는 요금이 발생합니다. 자세한 내용은 지원되지 않는 항목 섹션을 참조하세요.

스크립트 예제는 VmStartupScriptGallery를 참조하세요.

압축된 파일 만들기 및 업로드

스크립트에서 사용하거나 호출하려는 폴더에 모든 관련 소프트웨어를 수집합니다. 스크립트가 타사 소프트웨어를 설치하는 경우 스크립트는 실행 중에 다운로드하거나 압축된 파일에서 함께 묶을 수 있습니다. 아무것도 설치하지 않는 경우 이 단계를 건너뜁니다.
이전 섹션에서 만든 스크립트(.sh 또는 .ps1)와 필요한 경우 이전 단계에서 수집한 소프트웨어를 사용하여 압축된 파일(.zip)을 만듭니다. 스크립트 파일은 디렉터리 내부가 아니라 압축된 파일의 루트에 있어야 합니다. 또한 스크립트 파일의 이름이 PF_StartupScript.sh (Linux) 또는 PF_StartupScript.ps1 (Windows)가 아닌 경우 실행되지 않으며 게임 서버가 시작되지 않습니다.
다음 방법 중 하나를 사용하여 Hadoop 클러스터에 jar 파일을 업로드합니다.

PlayFab 게임 관리자 사용
GetAssetUploadUrl API 호출에서 반환된 URL에서 헤더 {"x-ms-blob-type": "BlockBlob"}을 사용하여 PUT 요청을 실행합니다.
PowerShell cmdlet을 사용합니다.

참고 항목

압축된 파일에 스크립트에 필요한 모든 이진 파일 및 자산을 포함하는 것이 좋습니다. 따라서 MPS가 게임 서버를 전달하는 데 걸리는 시간이 빨라지고 실행 시간이 단축됩니다. 게임 서버가 실행될 관련 플랫폼에 대한 자산을 포함해야 합니다. 예를 들어 Linux 서버를 사용하는 경우 "amd64" Debian/Ubuntu 패키지를 포함해야 합니다.

새 빌드에 사용자 지정 스크립트 적용

.zip 파일을 업로드한 후 MPS API를 사용하여 VmStartupScriptAssetReference 속성을 구성한 후 새 Build를 만듭니다. 지침은 MPS API를 사용하여 빌드를 만드는 방법을 참조하세요.

업로드된 자산 파일에 대한 참조를 포함하는 VmStartupScriptConfiguration.VmStartupScriptAssetReference 속성을 추가합니다. 이 속성은 CreateBuildWithCustomContainer, CreateBuildWithManagedContainer 및 CreateBuildWithProcessBasedServer와 같은 모든 "CreateBuild" 관련 API의 일부입니다.
VmStartupScriptAssetReference.FileName 속성에 유효한 값을 추가합니다. 이 값은 자산 파일의 이름과 동일해야 합니다(예: vmstartupscriptassets.zip).
VmStartupScript 기능에서는 지원되지 않으므로 VmStartupScriptAssetReference.MountPath 속성은 비어 있어야 합니다.

참고 항목

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은 "실행 중" 상태로 전환되지 않으며 디버그하려면 VM에 RDP/SSH를 수행해야 합니다. 자세한 내용은 권장 개발자 워크플로를 참조하세요. VM은 VmStartupScript를 실행하기 위해 계속 다시 시도합니다.

특별 고려 사항

Linux에서 PF_StartupScript.sh 파일을 실행 파일로 표시해야 하나요?

MPS는 스크립트 파일을 실행 파일로 표시한 다음 모든 Windows 줄 끝("\r\n")을 Linux 항목("\n")으로 변환합니다. 따라서 이 두 가지에 대해 걱정할 필요가 없습니다.

환경 변수

다음은 시작 스크립트에서 사용할 수 있는 환경 변수입니다.

이름	설명
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 또는 Windows 서비스에서 시스템 서비스로 설치할 수 있습니다.
30000부터 시작하는 포트는 VmAgent 프로세스(MPS 게임 서버 오케스트레이터 실행 파일)에서 사용되므로 게임 서버 또는 포트 56001에 사용되므로 사용하지 마세요.
D: (Windows) 또는 /mnt(Linux) 경로의 파일은 VmAgent 작업에 필요하므로 수정하지 마세요(예 PF_SHARED_CONTENT_FOLDER_VM: 편집 가능한 콘텐츠가 포함된 폴더 제외).
VmStartupScript 또는 VmStartupScript에서 시작된 앱 내에서 GSDK 를 사용하면 안 됩니다. GSDK는 GameServers에서만 사용해야 합니다.
이 작업을 수행하면 MPS 컨트롤 플레인과의 통신에 문제가 발생하기 때문에 Virtual Machine을 수동으로 다시 부팅하면 안 됩니다.

포트

VmStartupScript 기능을 사용하는 경우 각 VM에 여러 포트를 노출하도록 요청할 수 있습니다. 이러한 포트는 스크립트에서 시작한 모든 프로그램에서 사용할 수 있으며 게임 서버에 대해 MPS가 열리는 포트와 다릅니다.

사용법

모든 VM에 대해 최대 5개의 포트를 요청할 수 있습니다. 각 포트에 대해 프로토콜(TCP 또는 UDP) 및 이름을 지정해야 합니다. 다음은 두 개의 포트를 요청하는 방법의 예입니다.

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)	외부 엔드포인트에서 열리는 포트입니다. 외부 클라이언트는 이 포트를 사용하여 내부 포트에 바인딩하는 프로그램에 연결해야 합니다.

예를 들어 위의 샘플 스크립트에서 요청된 두 포트의 경우 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이 배포되면 RDP/SSH를 수행하고, 필요한 파일을 복사하고, 스크립트가 성공할 때까지 편집/실행해 볼 수 있습니다.

이 VM이 실행되고 스크립트가 예상대로 작동하는지 확인하면 스크립트와 자산을 .zip 파일에 배치할 수 있습니다. 나중에 업로드하고 빌드를 만들어 볼 수 있습니다. 단일 VM 빌드를 다시 만들어 비용을 절감하고 스크립트가 작동하는지 확신하면 강화해 보세요.

스크립트를 실행할 때 문제가 발생하면 RDP/SSH를 통해 VM에 로그인하여 디버깅하고 스크립트의 표준 출력 및 표준 오류 스트림에 대해 각각 PF_StartupScriptStdOut.txt 및 PF_StartupScriptStdErr.txt 파일을 확인할 수 있습니다. 이러한 파일은 D: Windows의 드라이브 또는 Linux의 /mnt에 있습니다.

스크립트가 두 번 이상 실행될 가능성이 있으므로 스크립트는 idempotent여야 합니다. 예를 들어 스크립트가 외부 리소스를 다운로드하려고 시도하고 네트워크 문제로 인해 실패하는 경우 MPS는 전체 스크립트 실행을 다시 시도합니다.

지원

MPS 서비스는 VmStartupScript에 있는 모든 항목을 실행합니다. 그러나 팀은 스크립트의 일부로 설치/실행되는 개별 작업 및 실행 파일에 대한 지원을 제공하지 않습니다.

미리 보기 중에 PlayFab 커뮤니티 포럼 및 Discord를 사용하여 지원을 받고 피드백을 제공합니다. VmStartupScriptGallery 리포지토리에서 스크립트에 문제가 있거나 새 스크립트를 요청하려면 GitHub에서 문제 열기를 사용합니다.

Share via

VM을 만드는 동안 사용자 지정 스크립트 실행 - VmStartupScript(미리 보기)

소개

사용 방법

스크립트 만들기

압축된 파일 만들기 및 업로드

새 빌드에 사용자 지정 스크립트 적용

특별 고려 사항

Linux에서 PF_StartupScript.sh 파일을 실행 파일로 표시해야 하나요?

환경 변수

지원되지 않는 사항

포트

사용법

개발/디버깅

권장 개발 워크플로

지원

추가 리소스