Documentation index for AI agents

GS2-Deploy

마스터 데이터 CI/CD 기능

GS2-Deploy는 GS2의 각 마이크로서비스의 네임스페이스나 마스터 데이터를 코드로 관리하고, 선언적으로 프로비저닝하기 위한 기능을 제공합니다.
AWS의 CloudFormation과 유사한 사상으로 설계되어 있으며, 템플릿 파일에 기술한 리소스 정의를 바탕으로 여러 마이크로서비스에 걸친 환경 구축·갱신·삭제를 하나의 단위(스택)로 다룰 수 있습니다.

게임 개발에서는 마스터 데이터 조정이나 네임스페이스 구성 변경이 빈번하게 발생합니다.
GS2-Deploy를 활용함으로써 이러한 변경 사항을 Git으로 관리하고, GitHub 등의 저장소와 연동한 CI/CD 파이프라인에서 자동으로 배포하는 운영이 가능해집니다.

스택 (Stack)

스택은 GS2의 리소스를 묶어서 관리하는 단위입니다.

스택은 YAML 형식으로 기술된 템플릿을 바탕으로 생성되며, 템플릿에 기술된 리소스 정의에 따라 네임스페이스나 마스터 데이터 등을 자동으로 생성·갱신·삭제합니다.
하나의 스택에는 여러 마이크로서비스에 걸친 리소스를 포함할 수 있으며, 게임을 구성하는 일련의 설정을 하나로 묶어서 다룰 수 있습니다.

graph LR
  Template["템플릿(YAML)"] --> Stack["스택"]
  Stack --> R1["GS2-Account 네임스페이스"]
  Stack --> R2["GS2-Inventory 마스터 데이터"]
  Stack --> R3["GS2-Mission 마스터 데이터"]
  Stack --> R4["GS2-Showcase 마스터 데이터"]

스택은 내부적으로 다음과 같은 상태를 가집니다.

  • CREATE_PROCESSING: 생성 처리 중
  • CREATE_COMPLETE: 생성이 완료되어 리소스를 이용 가능
  • UPDATE_PROCESSING: 갱신 처리 중
  • UPDATE_COMPLETE: 갱신 완료
  • ROLLBACK_PROCESSING: 실패 시 롤백 처리 중
  • ROLLBACK_COMPLETE: 롤백 완료
  • DELETE_PROCESSING: 삭제 처리 중
  • DELETE_COMPLETE: 삭제 완료

스택 갱신 도중 실패한 경우에는 자동으로 변경 전 상태로 되돌리는 《롤백》 처리가 수행됩니다.

템플릿

템플릿은 YAML 형식으로 기술합니다. 기술하는 섹션은 다음과 같습니다.

  • GS2TemplateFormatVersion: 템플릿의 포맷 버전
  • Description: 스택 설명
  • Resources: 생성할 리소스의 정의
  • Outputs: 스택 생성 후 다른 시스템에서 참조할 수 있는 값의 정의

다음은 템플릿 기술 예시입니다.

GS2TemplateFormatVersion: "2019-05-01"
Description: |
  GS2-Account namespace

Resources:
  Namespace:
    Type: GS2::Account::Namespace
    Properties:
      Name: namespace-0001
      Description: anonymous account
      ChangePasswordIfTakeOver: true

Outputs:
  NamespaceId: !GetAttr Namespace.Item.NamespaceId

Type에는 생성 대상이 되는 GS2 리소스의 종류를, Properties에는 각 리소스 고유의 설정값을 지정합니다.
!GetAttr 함수를 사용하면 다른 리소스의 출력값을 참조하면서 의존 관계가 있는 리소스를 연쇄적으로 구축할 수 있습니다.

리소스 (Resource)

스택 내에 생성되는 개별 GS2 리소스를 《리소스》라고 부릅니다.
리소스에는 다음과 같은 정보가 보관됩니다.

  • type: 리소스의 종류 (GS2::Account::Namespace 등)
  • name: 템플릿 내에서 부여된 논리 이름
  • request: 리소스 생성 시 GS2 API로 전송된 요청 내용
  • response: GS2 API로부터의 응답 내용
  • rollbackContext: 롤백 실행 시 사용되는 정보

스택을 참조함으로써 스택에 포함된 모든 리소스의 생성 상황을 목록으로 확인할 수 있습니다.

출력 (Output)

템플릿의 Outputs 섹션에서 선언된 값은 스택 생성 완료 후 다른 곳에서 참조할 수 있는 출력값으로 저장됩니다.

출력은 외부 시스템 연동이나 다른 스택에서의 값 참조, 운영 도구가 GS2 리소스의 GRN을 취득하는 용도 등에 이용할 수 있습니다.

이벤트 (Event)

스택의 생성·갱신·삭제 처리 중에 발생하는 개별 작업은 《이벤트》로 기록됩니다.
스택 처리가 실패한 경우에는 이벤트 이력을 확인함으로써 어떤 리소스의 어느 단계에서 실패했는지 특정할 수 있습니다.

GitHub 연동

템플릿 파일은 GS2 관리 콘솔에서 직접 업로드하는 방법 외에, GitHub 저장소와 연동하여 가져오는 것도 가능합니다.

GitHub 연동을 이용하면 다음과 같은 운영이 가능해집니다.

  • 마스터 데이터 설정을 Pull Request 기반으로 리뷰·병합하는 워크플로우
  • main 브랜치로의 병합을 트리거로 CI에서 GS2-Deploy를 호출하여 리소스를 갱신하는 파이프라인
  • 환경별(개발·스테이징·프로덕션)로 서로 다른 브랜치·스택을 할당하는 다중 환경 운영

GitHub에서의 템플릿 취득에는 GitHub API의 액세스 토큰을 사용합니다. 프라이빗 저장소에서도 이용 가능합니다.

마스터 데이터를 코드로 관리하기

GS2-Deploy의 주요 유스케이스 중 하나는 각 마이크로서비스의 마스터 데이터를 GS2-Deploy의 템플릿을 통해 등록하는 것입니다.

네임스페이스 정의와 같은 템플릿 내에 마스터 데이터의 내용을 기술해 두면, 네임스페이스 생성부터 마스터 데이터 등록까지를 하나의 스택으로 일괄 관리할 수 있습니다.
이를 통해 마스터 데이터의 변경 이력을 Git으로 추적할 수 있으며, 과거 버전으로의 롤백이나 리뷰 전 변경 내용의 사전 확인 등도 용이해집니다.

조작 대상에 대하여

GS2-Deploy는 프로젝트 구축을 담당하는 관리 API이므로, 원칙적으로 게임 엔진 측 클라이언트(Unity / Unreal Engine / Godot 등)에서 호출하는 서비스가 아닙니다.
실제 운영에서는 관리 콘솔을 통한 조작과 CI/CD 파이프라인에서 GS2 SDK를 통해 조작하는 워크플로우가 중심이 됩니다.

구현 예제

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

따라서 게임 클라이언트에서 직접 호출하는 것이 아니라, 다음 중 하나의 수단으로 조작하는 것을 권장합니다.

  • 관리 콘솔
  • GS2 CLI
  • 각종 언어용 일반 SDK (C# / Go / Python / TypeScript / PHP / Java)
  • GS2-Deploy 자체의 템플릿에 의한 선언적 관리

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

상세 레퍼런스

GS2-Deploy API 레퍼런스