Minato (南)

Minato is a Kubernetes-native platform for hosting persistent, multi-game dedicated game servers, designed for enterprise use cases: hosting providers running many games for many tenants, and operators running large fleets of persistent worlds for a single game.

Features

• Persistent-first: One GameServer = one StatefulSet = one PVC = one stable identity
• Game-agnostic operator: All game knowledge lives in agents, not the operator
• Multi-game support: Minecraft Paper, CS2, Palworld (extensible via SDK)
• Fleet management: GameServerFleet for managing N servers of the same game
• Action dispatch: Execute actions (restart, save, kick, etc.) via CRDs or API
• Console streaming: Real-time console access via WebSocket
• Agent Metrics: Agents expose /metrics endpoints for Prometheus scraping
• Snapshots: Declarative backup with retention policies using VolumeSnapshots
• Multi-tenancy: Namespace isolation with RBAC roles
• Enterprise-ready: PSS:restricted, non-root, HA, leader election

Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Control Plane  │────▶│   Minato Operator │────▶│   Game Servers  │
│   (HTTP/gRPC)    │     │   (controller)    │     │   (StatefulSet) │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                                │                          │
                                ▼                          ▼
                       ┌──────────────────┐     ┌─────────────────┐
                       │   Kubernetes     │     │   Per-Game      │
                       │   API Server     │     │   Agents        │
                       └──────────────────┘     └─────────────────┘

The operator reconciles CRDs into Kubernetes resources (StatefulSets, PVCs, Services). Per-game agents run as sidecars and implement the gRPC agent API. The control plane provides an HTTP API for user-facing operations.

Operator Scope: The operator manages only minato-native resources (GameServer, GameProfile, GameServerFleet, ActionExecution, GameSnapshot). External resources like ServiceMonitors, Gateways, and Ingress are managed by a separate Helm chart.

Quick Start

Prerequisites

• Kubernetes 1.28+ cluster
• kubectl configured
• Go 1.23+ (for building from source)
• VolumeSnapshot CRD (for backups)

Install with Helm

helm repo add minato https://7k-minato.github.io/minato
helm repo update
helm install minato minato/minato \
  --namespace minato-system \
  --create-namespace

Install from Source

git clone https://github.com/7k-minato/minato.git
cd minato
make install
make deploy

Create a Minecraft Server

Game profiles are maintained in the minato-games repository.

# Clone the games repository and apply the Minecraft Paper profile
git clone https://github.com/7k-minato/minato-games.git
cd minato-games
kubectl apply -f profiles/minecraft-paper/profile.yaml

# Create a game server
kubectl apply -f - <<EOF
apiVersion: operator.minato.io/v1
kind: GameServer
metadata:
  name: minecraft-server-1
  namespace: default
spec:
  profile: minecraft-paper
  env:
    EULA: "true"
EOF

# Check status
kubectl get gameserver minecraft-server-1 -n default

Use the Control Plane API

# List servers
curl http://localhost:8080/api/v1/gameservers

# Execute an action
curl -X POST http://localhost:8080/api/v1/gameservers/default/minecraft-server-1/actions/save-world

# List snapshots
curl http://localhost:8080/api/v1/gameservers/default/minecraft-server-1/snapshots

CRDs

GameProfile (Cluster-scoped)

Defines a reusable game configuration:

apiVersion: operator.minato.io/v1
kind: GameProfile
metadata:
  name: minecraft-paper
spec:
  displayName: "Minecraft Paper"
  image: "itzg/minecraft-server:latest"
  ports:
    - name: game
      containerPort: 25565
  storage:
    mountPath: /data
    sizeDefault: 10Gi
  agent:
    image: "harbor.7kgroup.org/7kminato-games/minato-agent-minecraft:v0.1.0"

GameServer (Namespace-scoped)

A single running game server instance:

apiVersion: operator.minato.io/v1
kind: GameServer
metadata:
  name: my-server
  namespace: default
spec:
  profile: minecraft-paper
  env:
    EULA: "true"

GameServerFleet (Namespace-scoped)

Manages N GameServers of the same profile:

apiVersion: operator.minato.io/v1
kind: GameServerFleet
metadata:
  name: production-fleet
spec:
  profile: minecraft-paper
  replicas: 5

ActionExecution (Namespace-scoped)

Audit trail for action execution:

apiVersion: operator.minato.io/v1
kind: ActionExecution
metadata:
  name: restart-action
spec:
  targetRef:
    kind: GameServer
    name: my-server
  actionName: restart

GameSnapshot (Namespace-scoped)

Declarative backups with retention:

apiVersion: operator.minato.io/v1
kind: GameSnapshot
metadata:
  name: daily-backup
spec:
  gameServerRef: my-server
  schedule: "0 2 * * *"
  retention:
    count: 7
    duration: "168h"

Supported Games

Game	Profile	Agent	Status
Minecraft Paper	✅	✅	Production-ready
Counter-Strike 2	✅	✅	Production-ready
Palworld	✅	✅	Production-ready
Generic (YAML actions)	✅	✅	Production-ready

Documentation

• Installation Guide
• Configuration Reference
• Troubleshooting Guide
• Architecture Overview
• Controller Flow
• Metrics Schema
• Multi-Tenancy
• Security
• CLI
• Runbooks
• Compliance
• Agent Quickstart
• SDK Reference

Development

# Run tests
make test

# Run integration tests
make test-integration

# Generate code
make generate

# Generate manifests
make manifests

# Run operator locally
make run-operator

Project Structure

minato/
├── api/                    # CRD Go types and protobuf definitions
├── cmd/                    # Binaries (operator, control plane, agents, CLI)
├── internal/controllers/   # Operator reconcilers
├── sdk/agent/              # Public Agent SDK
├── deploy/helm/            # Helm chart
├── deploy/helm/            # Helm chart
├── config/                 # Kustomize configs, CRDs, RBAC
└── docs/                   # Documentation

Enterprise Features

• ✅ High Availability: Leader election, multi-replica operator
• ✅ Security: PSS:restricted, non-root, no privileged containers
• ✅ RBAC: Three-tier tenant roles
• ✅ Audit: ActionExecution audit trail
• ✅ Monitoring: Agent metrics endpoints for Prometheus (external ServiceMonitor chart)
• ✅ Snapshots: VolumeSnapshot integration with retention
• ✅ Network Isolation: NetworkPolicies
• ✅ Resource Quotas: Per-tenant limits

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Security

For security concerns, please see SECURITY.md.

License

Licensed under the Apache License, Version 2.0.