GS2-Deploy

Master data CI/CD feature

GS2-Deploy provides the ability to manage namespaces and master data of GS2 microservices as code, and to provision them declaratively.
Designed with a philosophy similar to AWS CloudFormation, it allows you to build, update, and delete resources spanning multiple microservices as a single unit (a stack) based on resource definitions described in a template file.

In game development, adjustments to master data and changes to namespace configurations occur frequently.
By using GS2-Deploy, you can manage these changes in Git, and run CI/CD pipelines linked with repositories such as GitHub to deploy them automatically.

Stack

A stack is a unit that bundles GS2 resources for management.

A stack is created based on a YAML-formatted template, and according to the resource definitions described in the template, namespaces and master data are automatically created, updated, or deleted.
A single stack can contain resources spanning multiple microservices, allowing a related set of configurations that compose a game to be handled as a single unit.

graph LR
  Template["Template (YAML)"] --> Stack["Stack"]
  Stack --> R1["GS2-Account Namespace"]
  Stack --> R2["GS2-Inventory Master Data"]
  Stack --> R3["GS2-Mission Master Data"]
  Stack --> R4["GS2-Showcase Master Data"]

A stack internally has the following states.

  • CREATE_PROCESSING: Creation in progress
  • CREATE_COMPLETE: Creation completed and resources available
  • UPDATE_PROCESSING: Update in progress
  • UPDATE_COMPLETE: Update completed
  • ROLLBACK_PROCESSING: Rollback in progress after a failure
  • ROLLBACK_COMPLETE: Rollback completed
  • DELETE_PROCESSING: Deletion in progress
  • DELETE_COMPLETE: Deletion completed

If a stack update fails midway, a “rollback” process is performed automatically to restore the previous state.

Template

Templates are written in YAML. The following sections are described.

  • GS2TemplateFormatVersion: Template format version
  • Description: Description of the stack
  • Resources: Definitions of resources to be created
  • Outputs: Definitions of values that can be referenced from other systems after the stack is created

Below is an example of a template.

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 specifies the kind of GS2 resource to create, and Properties specifies the resource-specific configuration values.
By using the !GetAttr function, you can chain dependent resources by referencing the output values of other resources.

Resource

Each individual GS2 resource created within a stack is called a “resource”.
A resource holds the following information.

  • type: The type of resource (such as GS2::Account::Namespace)
  • name: The logical name assigned within the template
  • request: The request payload sent to the GS2 API when creating the resource
  • response: The response from the GS2 API
  • rollbackContext: Information used when a rollback is executed

By referring to the stack, you can see at a glance the creation status of all resources contained in the stack.

Output

Values declared in the Outputs section of a template are saved as output values that can be referenced from other places after the stack has been created.

Outputs can be used for integration with external systems, for referencing values from other stacks, or for operational tools to retrieve the GRN of GS2 resources.

Event

Each individual operation that occurs during the creation, update, or deletion of a stack is recorded as an “event”.
If a stack operation fails, you can identify at which resource and which stage the failure occurred by reviewing the event history.

GitHub Integration

In addition to uploading template files directly from the GS2 management console, you can also retrieve them by integrating with a GitHub repository.

By using GitHub integration, the following operations become possible.

  • A workflow for reviewing and merging master data configuration changes based on pull requests
  • A pipeline that, triggered by a merge into the main branch, calls GS2-Deploy from CI to update resources
  • Multi-environment operation with different branches and stacks assigned to each environment (development, staging, production)

A GitHub API access token is used to retrieve templates from GitHub. Private repositories are also supported.

Managing master data as code

One of the main use cases of GS2-Deploy is to register the master data of each microservice via a GS2-Deploy template.

By describing the master data content in the same template as the namespace definitions, you can manage namespace creation and master data registration in a single stack.
This allows you to track the change history of master data in Git, making it easy to roll back to past versions or preview changes before review.

About operation targets

Because GS2-Deploy is a management API responsible for project provisioning, in principle it is not a service called from game engine clients (Unity / Unreal Engine, etc.).
In practice, operations are mainly performed through the management console, or via a workflow that calls the GS2 SDK from CI/CD pipelines.

Example Implementation

GS2-Deploy is a microservice centered on management APIs. No dedicated Domain class is provided in the game engine SDKs (Unity / Unreal Engine).

Therefore, instead of calling it directly from the game client, we recommend operating it via one of the following means.

  • Management console
  • GS2 CLI
  • General-purpose SDKs for various languages (C# / Go / Python / TypeScript / PHP / Java)
  • Declarative management via GS2-Deploy’s own templates

For details on each SDK, see the corresponding reference page.

Detailed Reference

Reference of GS2-Deploy