Two paths are supported:

1. Full platform (recommended) via Helm:

2. Operator-only for CRD + controller installs:

• Apply CRDs and controller manifests from the release bundle.
• Manage the console and agent separately if needed.

Control plane and agent model#

• The console API writes actions to an operations table.
• The console agent polls that table (AGENT_POLL_INTERVAL, default 5s) and executes actions against the cluster.
• Agent metrics are exposed on /metrics and /healthz.
• A future mTLS WebSocket protocol exists in docs/agent-protocol.md, but the current implementation is DB polling.

Domain model (v1beta1)#

Versioning: v1beta1 is the storage version. New automation and examples should target v1beta1.

MinecraftServer core fields:

• edition, flavor, version, eula (validated).
• replicas (0 or 1), image, resources.
• service, ports, storage (PVC size/class or existingClaim).
• jvm, serverProperties, rcon, query.
• database (secretRef + optional envPrefix).
• security (default or restricted Pod Security profile).
• plugins, mods, and updatePolicy (cron + autoRestart).

MinecraftNetwork core fields:

• proxy (type, image or version, replicas, service, resources).
• proxy.config (motd, maxPlayers, onlineMode).
• proxy.forwarding (none, legacy, modern; modern requires secretRef).
• proxy.rcon (Velocircon integration for proxy control).
• servers list or serverSelector labels.
• defaultServer fallback.
• proxy.plugins and proxy.updatePolicy for addon automation.

Addon sources: AddonSource supports url/configMap/secret and optional sha256 plus metadata (source, project, version, platform, loader).

MinecraftServer example (v1beta1)#

MinecraftNetwork example (v1beta1)#

First controller: MinecraftServer reconciliation#

The first controller ensures a single server resource is rendered safely and repeatably.

Owned resources:

• ConfigMap: server.properties and optional whitelist/ban files.
• Service: minecraft port plus optional rcon/query ports.
• StatefulSet: single replica with mounted world PVC.
• PVC: created when existingClaim is not set, and intentionally not owned to prevent data loss.
• Secrets: RCON and database secrets must already exist; the controller fails fast if they are missing.

Spec-to-pod mapping highlights:

• spec.eula, spec.flavor, and spec.version become EULA, TYPE, and VERSION env vars.
• spec.ports drives container and Service ports; rcon requires a distinct port.
• spec.database injects env vars from a Secret (with optional prefix).
• spec.security can apply the restricted Pod Security profile (runAsNonRoot, seccomp, drop caps).
• Addons are downloaded or copied by an init container into /data/plugins or /data/mods.

Update and delete behavior:

• Pod template annotations include a spec hash to trigger rolling updates.
• Service changes (type/ports) reconcile in place.
• PVCs are retained on delete; finalizers only attempt a clean RCON stop when RCON is enabled.

Failure modes to surface#

• Missing RCON or database secrets.
• Addon download or checksum failures.
• PVC provisioning errors.
• Image pull failures.

What is next#

Part 2 covers MinecraftNetwork reconciliation and the proxy pipeline. Part 3 digs into the proxy policy DSL and the control-plane architecture.