Documentation index for AI agents

GS2-Freeze

GS2 마이크로서비스의 버전을 고정하는 엔터프라이즈 대상 기능

GS2-Freeze 는 게임에서 이용하는 GS2 마이크로서비스의 버전을 임의의 시점에 고정(freeze)하고, 운영 측이 관리하는 시점에 버전을 업데이트할 수 있도록 하기 위한 기능입니다.

일반적으로 GS2 의 마이크로서비스는 지속적으로 버전 업이 이루어지며, 게임은 항상 최신 버전의 API 를 이용하게 됩니다. 대부분의 타이틀에서는 이러한 운용에 문제가 없지만, 출시 직후의 대규모 타이틀이나 장기간에 걸쳐 안정성을 최우선으로 하고 싶은 상황에서는 서비스 측의 업데이트 시점을 게임 운영 측에서 컨트롤하고 싶다는 요구가 존재합니다. GS2-Freeze 는 이러한 요구에 응답하기 위한 엔터프라이즈 대상 기능입니다.

스테이지

GS2-Freeze 의 핵심이 되는 개념이 “스테이지 (Stage)” 입니다. 스테이지는 “특정 시점에 고정된 GS2 마이크로서비스 버전의 집합” 을 나타냅니다.

각 스테이지에는 다음의 정보가 연결됩니다.

  • 스테이지 이름 (name): 스테이지를 고유하게 식별하는 이름
  • 소스 스테이지 이름 (sourceStageName): 버전 정보를 취득하는 원본이 되는 스테이지의 이름
  • 정렬 순서 (sortNumber): 개발·검증·본번과 같은 스테이지의 정렬 순서를 나타내는 번호
  • 상태 (status): 스테이지의 상태 (프로모트 중, 롤백 중 등)

게임의 클라이언트·서버는 이용하고 싶은 스테이지를 지정하여 GS2 의 API 를 호출함으로써, 해당 스테이지에 고정된 버전의 마이크로서비스를 이용할 수 있습니다.

graph LR
  Latest["최신 GS2 마이크로서비스"] -- Promote --> StageDev["Stage: dev"]
  StageDev -- Promote --> StageStg["Stage: staging"]
  StageStg -- Promote --> StageProd["Stage: production"]
  Game["게임 클라이언트"] -- API 요청 --> StageProd

프로모트 / 롤백

스테이지의 버전을 업데이트하는 조작을 “프로모트 (Promote)” 라고 부릅니다. 프로모트를 실행하면 소스 스테이지에 고정되어 있는 버전이 대상 스테이지로 복사됩니다. 예를 들어 “staging 스테이지의 버전을 production 스테이지로 프로모트한다” 와 같은 방식으로 검증이 완료된 버전을 본번에 반영할 수 있습니다.

프로모트 후에 문제가 발견된 경우에는 “롤백 (Rollback)” 을 실행하여 직전 버전으로 되돌릴 수 있습니다.

프로모트·롤백은 시간이 걸리는 처리일 수 있으며, 내부적으로는 비동기 처리로 실행됩니다. 처리의 중간 경과는 Output 으로 기록되어, 이후에 상태를 확인할 수 있습니다.

스테이지의 정렬 순서

sortNumber 를 이용함으로써, 여러 스테이지를 “개발”, “스테이징”, “본번” 과 같은 계층으로 나열할 수 있습니다. 정렬 순서는 매니지먼트 콘솔 상의 표시 순서나, 프로모트 대상을 선택할 때의 참고 정보로 사용됩니다.

트랜잭션 액션

GS2-Freeze 에서는 트랜잭션 액션을 제공하지 않습니다.

마스터 데이터 관리

GS2-Freeze 는 스테이지 자체가 운용상의 구성 정보이며, 일반적인 마이크로서비스에 있는 “마스터 데이터 임포트 / 익스포트” 는 제공하지 않습니다. 스테이지의 생성·업데이트·삭제는 매니지먼트 콘솔이나 GS2-Deploy 에서 수행합니다.

구현 예제

GS2-Freeze 는 관리 API 중심의 마이크로서비스입니다. 게임 엔진용 SDK (Unity / Unreal Engine / Godot) 에는 전용 Domain 클래스가 제공되지 않습니다.

스테이지의 생성·프로모트·롤백과 같은 조작은 게임 클라이언트에서 직접 호출하는 것이 아니라, 다음 중 하나의 수단으로 조작할 것을 권장합니다.

  • 매니지먼트 콘솔
  • GS2 CLI
  • 각종 언어용 일반 SDK (C# / Go / Python / TypeScript / PHP / Java)
  • GS2-Deploy 를 통한 템플릿 관리

각 SDK 의 상세 내용은 해당하는 레퍼런스 페이지를 참조하세요.

보다 실전적인 정보

개발·검증·본번 3단계 스테이지 운용

대표적인 이용 패턴은 개발용·검증용·본번용의 3개 스테이지를 준비하여, 왼쪽에서 오른쪽으로 순서대로 프로모트해 가는 운용입니다.

  • 개발 스테이지 (dev): 최신 GS2 마이크로서비스를 이용하여 신규 기능의 동작 확인을 수행
  • 검증 스테이지 (staging): 개발 스테이지에서 검증이 완료된 버전을 프로모트하여 QA 나 리허설을 수행
  • 본번 스테이지 (production): 검증 스테이지에서 품질을 확인한 후 프로모트하여 게임 플레이어에게 제공

이러한 운용을 통해, GS2 측에서 새로운 릴리스가 이루어지더라도 게임 운영 측이 원하는 시점에만 본번 반영을 수행할 수 있습니다.

문제 발생 시의 즉시 롤백

본번 스테이지로 프로모트한 후 결함이 발견된 경우, 롤백을 실행하여 직전 버전으로 즉시 되돌릴 수 있습니다. 게임 측에 변경을 가하지 않고 서비스 측의 버전만 되돌릴 수 있으므로, 긴급 대응의 선택지로 유용합니다.

상세 레퍼런스

GS2-Freeze API 레퍼런스