> For the complete documentation index, see [llms.txt](/llms.txt)

# GS2-Deploy

마스터 데이터 CI/CD 기능




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

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

## 스택 (Stack)

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

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

```mermaid
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`: 스택 생성 후 다른 시스템에서 참조할 수 있는 값의 정의

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

```yaml
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`에는 각 리소스 고유의 설정값을 지정합니다.<br>
`!GetAttr` 함수를 사용하면 다른 리소스의 출력값을 참조하면서 의존 관계가 있는 리소스를 연쇄적으로 구축할 수 있습니다.

## 리소스 (Resource)

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

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

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

## 출력 (Output)

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

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

## 이벤트 (Event)

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

## GitHub 연동

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

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

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

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

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

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

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

## 조작 대상에 대하여

GS2-Deploy는 프로젝트 구축을 담당하는 관리 API이므로, 원칙적으로 게임 엔진 측 클라이언트(Unity / Unreal Engine / Godot 등)에서 호출하는 서비스가 아닙니다.<br>
실제 운영에서는 관리 콘솔을 통한 조작과 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 레퍼런스](../../api_reference/deploy)