Bridging the Last Mile: API Gateway + OKG for Seamless Game Connection Management

Game services are stateful, requiring precise handling of player connections. Traditional PC game architectures rely on four‑layer protocol gateways or dedicated direct‑connect addresses, but the rise of mini‑programs and H5 games introduces a dual challenge: controlling operational costs while supporting rapid iteration for creative validation. This drives the need for an efficient, elastic, cloud‑native architecture.

In a seven‑layer network, player state management and connection governance are tightly coupled. Dynamic scaling of service instances must be balanced with player session continuity, especially during automated operations such as instance removal or gray‑release. Achieving real‑time connection state perception and migration across the stack constitutes the "last mile" of cloud‑native game connection governance.

Business‑State‑Driven Traffic Management

OKG (OpenKruiseGame) integrates with the cloud‑native API gateway to combine fine‑grained state awareness with precise traffic control. The joint solution enables graceful server shutdown and configuration changes without touching the business code.

Graceful Shutdown Mechanism

Game services demand strict shutdown criteria; conventional methods can cause session interruption or data loss. OKG extends Kubernetes' native PreStop hook with custom lifecycle hooks that provide millisecond‑level control. When an OKG service enters the PreDelete state, the API gateway removes the instance from the service registry, preventing new requests from being routed to it while preserving existing player sessions.

The shutdown flow proceeds as follows:

State detection: the script reads /etc/gsinfo/state to obtain the current game server (GS) state.

PreDelete trigger: if the state equals PreDelete, the script queries the Prometheus metric envoy_cluster_upstream_cx_active for the active connection count of the corresponding service.

Player activity monitoring: the script continuously monitors the active connection count, using it as a proxy for player online status.

Graceful exit: the script loops until the active connection count drops to zero, then outputs done and exits with code 0, ensuring all player sessions have safely disconnected.

#!/bin/bash
file_path="/etc/gsinfo/state"
if [[ ! -f "$file_path" ]]; then exit 1; fi
state_content=$(cat "$file_path")
if [[ "$state_content" == "PreDelete" ]]; then
  data="query=sum(envoy_cluster_upstream_cx_active{cluster_name=~\"outbound_5000__${HOSTNAME}.default.svc.cluster.local\"})"
  json=$(curl -s -G --data-urlencode $data http://prometheus.com/api/v1/query)
  value=$(echo "$json" | grep -o '"value":\[[^]]*\]' | sed 's/.*"\([^\"]*\)"].*/\1/')
  if [[ -z "$value" || "$value" == "0" ]]; then
    echo "done"
    exit 0
  fi
  exit 1
fi
exit 1

Zero‑Impact Configuration Changes

Long‑lived game connections make configuration updates risky. Building on the open‑source Higress gateway, the solution adds high‑level capabilities—such as dynamic plugin addition/removal, log format changes, and global parameter updates—without breaking existing connections. This is achieved through seamless integration with OKG’s state‑aware traffic routing.

Deployment Steps

Provision an ACK managed cluster and install ack-kruise-game and ack-kruise components.

Enable the cloud‑native API gateway.

Deploy the demo game server (Posio) using a GameServerSet YAML that defines three replicas, each with a unique domain (e.g., game0.postio.example.com).

Apply the custom lifecycle hook configuration to enable graceful shutdown.

apiVersion: game.kruise.io/v1alpha1
kind: GameServerSet
metadata:
  name: postio
  namespace: default
spec:
  lifecycle:
    preDelete:
      labelsHandler:
        gs-sync/delete-block: "true"
  replicas: 3
  updateStrategy:
    rollingUpdate:
      podUpdatePolicy: InPlaceIfPossible
  network:
    networkType: Kubernetes-Ingress
    networkConf:
    - name: IngressClassName
      value: "higress"
    - name: Port
      value: "5000"
    - name: Path
      value: /
    - name: PathType
      value: Prefix
    - name: Host
      value: game<id>.postio.example.com
  gameServerTemplate:
    metadata:
      labels:
        gs-sync/delete-block: "true"
    spec:
      containers:
      - image: registry.cn-beijing.aliyuncs.com/chrisliu95/posio:8-24
        name: postio
      volumes:
      - name: gsinfo
        downwardAPI:
          items:
          - path: "state"
            fieldRef:
              fieldPath: metadata.labels['game.kruise.io/gs-state']
      serviceQualities:
      - name: healthy
        containerName: minecraft
        permanent: false
        exec:
          command: ["bash", "./probe.sh"]
        serviceQualityAction:
        - state: true
          result: done
          labels:
            gs-sync/delete-block: "false"
        - state: false
          opsState: None

Key Benefits

Zero‑code integration: OKG can be attached to any cloud‑native environment without code changes.

Rapid onboarding: deployment can be completed within minutes.

Full‑stack observability: rich Prometheus metrics and pre‑configured dashboards provide instant health visibility.

Simplified API governance: intuitive console reduces configuration complexity to a few clicks.

Out‑of‑the‑box templates for common game scenarios, covering traffic control and load balancing.

By shortening the "last mile" of cloud‑native game connection governance, the combined OKG and API gateway solution lets developers focus on core gameplay while benefiting from improved performance, operational efficiency, and uninterrupted player experience.