VM 생성 중에 사용자 지정 스크립트 실행 - VmStartupScript(미리 보기)
소개
이 기능은 미리 보기 상태입니다. 지금부터 사용하고 피드백을 보내주시기 바랍니다. 저희에게 연락하는 방법에 대한 지침은 문서 끝에 나와 있습니다. 미리 보기 중에는 기술 지원이 제한됩니다.
이 기능은 매우 신중하게 사용해야 하는 고급 기능입니다. 실행 중인 스크립트는 관리자(root) 권한으로 가상 머신(VM) 수준에서 실행됩니다. 제대로 사용하지 않으면 실행 중인 게임 서버의 정상적인 흐름을 방해하거나 실행 자체를 방지할 수도 있습니다. 최종 사용자는 스크립트의 내용에 대해 책임을 집니다.
VmStartupScript 사용 방법
VmStartupScript 기능을 사용하려면 사용자 지정 스크립트와 설치하려는 모든 관련 소프트웨어(선택 사항)를 제공해야 합니다. 이 스크립트는 가상 머신이 초기화될 때 실행되기 시작합니다. 이 작업은 모든 VM에서 게임 서버가 시작되기 전에 발생합니다. 스크립트가 성공적으로 실행을 완료하면 MPS 서비스는 게임 서버 초기화를 완료하고 이를 StandingBy 상태로 전달합니다. 다양한 게임 서버의 상태에 대해 자세히 알아보려면 멀티플레이어 서버의 수명 주기를 참조하세요. 실제 프로덕션 환경에서 이 기능을 사용하려면 시작하기 전에 권장 개발자 워크플로를 참조하세요.스크립트 만들기
- Linux VM용 PF_StartupScript.sh 또는 Windows VM용 PF_StartupScript.ps1 파일을 만듭니다.
- 파일에 설정/실행 명령을 추가합니다. 필요한 경우 스크립트에서 사용할 수 있는 일반적으로 사용되는 환경 변수 중 일부가 있습니다. 일부 작업은 지원되지 않거나 VM이 성공적으로 시작되지 않아 원치 않는 비용이 발생할 수 있습니다. 자세한 내용은 지원되지 않는 항목 섹션을 참조하세요.
압축 파일 생성 및 업로드
- 스크립트가 사용하거나 호출할 계획인 모든 관련 소프트웨어를 폴더에 수집합니다. 스크립트가 타사 소프트웨어를 설치하는 경우 스크립트가 실행 중에 다운로드하거나 압축 파일에 함께 번들로 제공할 수 있습니다. 아무것도 설치하지 않는 경우 이 단계를 건너뛰세요.
- 이전 섹션에서 만든 스크립트(.sh 또는 .ps1)와 이전 단계에서 필요한 경우 수집한 소프트웨어가 포함된 압축 파일(.zip)을 만듭니다. 스크립트 파일은 디렉터리 내부가 아닌 압축 파일의 루트에 있어야 합니다. 또한 스크립트 파일 이름이 PF_StartupScript.sh(Linux) 또는 PF_StartupScript.ps1(Windows)이 아닌 경우 실행되지 않으며 게임 서버가 시작되지 않습니다.
- 다음 방법 중 하나를 사용하여 압축 파일을 업로드합니다.
- PlayFab Game Manager 사용
- GetAssetUploadUrl API 호출에서 반환된 URL에 대해 헤더 {“x-ms-blob-type”: “BlockBlob”}를 사용하여 PUT 요청을 발행합니다.
- PowerShell cmdlet을 사용합니다.
스크립트에 필요한 모든 이진 파일과 자산을 압축 파일에 포함하는 것이 좋습니다. 이렇게 하면 실행 속도가 빨라지고 MPS가 게임 서버를 전달하는 시간이 단축됩니다. 게임 서버가 실행될 관련 플랫폼에 대한 자산을 포함해야 합니다. 예를 들어 Linux 서버를 사용하는 경우 “amd64” Debian/Ubuntu 패키지를 포함해야 합니다.
새 빌드에 사용자 지정 스크립트 적용
.zip 파일을 업로드한 후, MPS API를 사용하여 VmStartupScriptAssetReference 속성을 구성한 후 새 빌드를 만듭니다. 자세한 내용은 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”)으로 변환합니다. 따라서 이 두 가지에 대해 걱정할 필요가 없습니다.환경 변수
시작 스크립트에서 사용할 수 있는 환경 변수는 다음과 같습니다.지원되지 않는 항목
VM 및 게임 서버의 수명 주기를 방해할 가능성이 크므로 스크립트에서 다음 작업을 수행해서는 안 됩니다.- 시작 스크립트 실행 중에 차단하지 마세요. 게임 서버가 만들어지려면 스크립트가 성공적으로 종료되어야 합니다. 백그라운드에서 실행할 항목이 필요한 경우 Linux의 경우 systemd 서비스로, Windows의 경우 Windows 서비스로 설치할 수 있습니다.
- 게임 서버에 사용되므로 30000부터 시작하는 포트나 VmAgent 프로세스(MPS 게임 서버 오케스트레이터 실행 파일)에서 사용하므로 포트 56001을 사용하지 마세요.
- 이 파일은 VmAgent 작동에 필요하므로 D:(Windows) 또는 /mnt(Linux) 경로의 파일을 수정하지 마세요(
PF_SHARED_CONTENT_FOLDER_VM와 같이 편집 가능한 콘텐츠를 포함하는 폴더 제외). - VmStartupScript 내부에서 또는 이 스크립트에 의해 시작된 앱에서 GSDK를 사용해서는 안 됩니다. GSDK는 GameServer에서만 사용해야 합니다.
- 이 작업은 MPS 컨트롤 플레인과의 통신에 문제를 일으키므로 가상 머신을 수동으로 다시 부팅해서는 안 됩니다.
포트
VmStartupScript 기능을 사용하는 경우 각 VM에 노출할 수 있는 포트 수를 요청할 수 있습니다. 이러한 포트는 스크립트에 의해 시작되는 프로그램에서 사용할 수 있으며 MPS가 게임 서버용으로 여는 포트와 다릅니다.사용
각 VM에 대해 최대 5개의 포트를 요청할 수 있습니다. 각 포트에 대해 프로토콜(TCP 또는 UDP)과 이름을 지정해야 합니다. 다음은 두 개의 포트를 요청하는 방법의 예입니다.
예를 들어 위의 샘플 스크립트에서 요청된 두 포트의 경우 VmStartupScript에서 다음 환경 변수를 찾을 것으로 예상해야 합니다.
게임 서버에 대해 여는 포트와 유사하게 사용자의 포트에 연결하는 클라이언트를 인증하는 것은 사용자의 책임입니다. MPS는 이러한 포트에 대한 어떠한 인증 메커니즘도 제공하지 않습니다.
고객은 할당된 포트가 20000번 이상부터 시작한다는 것을 알게 될 것입니다. 그러나 향후 변경될 수 있으므로 스크립트에 이 값을 하드코딩하지 않는 것이 좋으며 적절한 포트 정보를 얻으려면 항상 환경 변수를 사용해야 합니다.
