Skip to main content

VM 생성 중에 사용자 지정 스크립트 실행 - VmStartupScript(미리 보기)

소개

이 기능은 미리 보기 상태입니다. 지금부터 사용하고 피드백을 보내주시기 바랍니다. 저희에게 연락하는 방법에 대한 지침은 문서 끝에 나와 있습니다. 미리 보기 중에는 기술 지원이 제한됩니다.
VmStartupScript를 사용하면 PlayFab 멀티플레이어 서버(MPS)에서 사용되는 가상 머신(VM)에서 사용자 지정 스크립트를 실행할 수 있습니다. MPS는 게임 서버 호스팅에 최적화되어 있어 타이틀이 수요에 따라 동적으로 확장할 수 있도록 지원합니다. VM 초기화 중에 많은 수의 서버를 빠르게 사용자 지정할 수 있도록 사용자 지정 스크립트는 게임 서버를 호스팅하는 모든 기본 VM에서 실행될 수 있습니다. 이 스크립트는 사용자 지정 소프트웨어 설치, 보안 설정 수정, 게임 서버 출력 및 메트릭 로깅에 사용자 지정 서비스 사용 등과 같은 작업을 수행하는 데 사용할 수 있습니다.
이 기능은 매우 신중하게 사용해야 하는 고급 기능입니다. 실행 중인 스크립트는 관리자(root) 권한으로 가상 머신(VM) 수준에서 실행됩니다. 제대로 사용하지 않으면 실행 중인 게임 서버의 정상적인 흐름을 방해하거나 실행 자체를 방지할 수도 있습니다. 최종 사용자는 스크립트의 내용에 대해 책임을 집니다.

VmStartupScript 사용 방법

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

스크립트 만들기

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

압축 파일 생성 및 업로드

  1. 스크립트가 사용하거나 호출할 계획인 모든 관련 소프트웨어를 폴더에 수집합니다. 스크립트가 타사 소프트웨어를 설치하는 경우 스크립트가 실행 중에 다운로드하거나 압축 파일에 함께 번들로 제공할 수 있습니다. 아무것도 설치하지 않는 경우 이 단계를 건너뛰세요.
  2. 이전 섹션에서 만든 스크립트(.sh 또는 .ps1)와 이전 단계에서 필요한 경우 수집한 소프트웨어가 포함된 압축 파일(.zip)을 만듭니다. 스크립트 파일은 디렉터리 내부가 아닌 압축 파일의 루트에 있어야 합니다. 또한 스크립트 파일 이름이 PF_StartupScript.sh(Linux) 또는 PF_StartupScript.ps1(Windows)이 아닌 경우 실행되지 않으며 게임 서버가 시작되지 않습니다.
  3. 다음 방법 중 하나를 사용하여 압축 파일을 업로드합니다.
스크립트에 필요한 모든 이진 파일과 자산을 압축 파일에 포함하는 것이 좋습니다. 이렇게 하면 실행 속도가 빨라지고 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 컨테이너로 빌드를 만든 다음 vmstartupscriptassets.zip의 스크립트를 사용하여 VM을 사용자 지정합니다.
VmStartupScript는 VM의 “Propping” 단계 중에 실행되며 게임 서버가 시작하려면 성공적으로 종료되어야 합니다. 실패하는 경우(종료 코드가 0이 아님) VM이 “Running” 상태로 전환되지 않으며 디버그하려면 VM에 RDP/SSH로 접속해야 합니다. 자세한 내용은 권장 개발자 워크플로를 참조하세요. VM은 VmStartupScript 실행을 계속 재시도합니다.

특별 고려 사항

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번 이상부터 시작한다는 것을 알게 될 것입니다. 그러나 향후 변경될 수 있으므로 스크립트에 이 값을 하드코딩하지 않는 것이 좋으며 적절한 포트 정보를 얻으려면 항상 환경 변수를 사용해야 합니다.

개발/디버깅

VmStartupScript 기능을 사용하기 전에 GitHub의 오픈 소스 리포지토리(VmStartupScriptGallery)에서 이러한 샘플 스크립트를 확인하는 것이 좋습니다. 기여를 환영합니다!

권장 개발 워크플로

처음에는 단일 VM으로 테스트 빌드를 만들어야 합니다. 이 VM은 프로덕션 빌드를 배포하려는 것과 유사한 사양이어야 합니다. 이 단일 VM이 배포되면 RDP/SSH로 접속하여 필요한 파일을 복사하고 성공할 때까지 스크립트를 편집/실행해 볼 수 있습니다. 이 VM이 실행되고 스크립트가 예상대로 작동하는 것을 확인한 후에는 스크립트와 자산을 .zip 파일에 넣을 수 있습니다. 그런 다음 업로드하고 이를 사용하여 빌드를 만들 수 있습니다. 비용을 절감하기 위해 단일 VM 빌드를 다시 만들어 보고 스크립트가 작동하는지 확실해지면 규모를 확장하세요. 스크립트 실행에 문제가 발생하면 RDP/SSH를 통해 VM에 로그인하고 스크립트의 표준 출력 및 표준 오류 스트림에 대해 각각 PF_StartupScriptStdOut.txtPF_StartupScriptStdErr.txt 파일을 확인하여 디버그할 수 있습니다. 이러한 파일은 Windows의 경우 D: 드라이브 또는 Linux의 경우 /mnt에 있습니다. 스크립트가 두 번 이상 실행될 가능성이 있으므로 스크립트는 idempotent해야 합니다. 예를 들어 스크립트가 외부 리소스를 다운로드하려고 시도하고 네트워크 문제로 인해 실패하면 MPS는 전체 스크립트 실행을 재시도합니다.

지원

MPS 서비스는 VmStartupScript에 있는 모든 항목을 실행합니다. 그러나 팀은 스크립트의 일부로 설치/실행되는 개별 작업 및 실행 파일에 대한 지원은 제공하지 않습니다. 미리 보기 중에는 PlayFab 커뮤니티 포럼Discord를 사용하여 지원을 받고 피드백을 제공하세요. VmStartupScriptGallery 리포지토리의 스크립트에 문제가 있거나 새 스크립트를 요청하려면 GitHub에서 이슈를 열어주세요.
마지막 수정일 2026년 8월 25일