Two key details to keep this deterministic:

• The controller sorts and normalizes backend lists so the file is stable across reconciles.
• forwarding-secret-file is only emitted when modern forwarding is enabled and a secret is present, preventing Velocity from booting with a missing file.

Backend resolution#

Backends come from two sources:

• Selector-based resolution: serverSelector expands to Services for matching MinecraftServer resources.
• Explicit server lists: used when selectors are omitted or when static mapping is required.

If defaultServer isn’t set, the controller falls back to the first resolved backend to keep the proxy bootable while still encouraging explicit configuration.

Addons + RCON integration#

Proxy plugins are downloaded and staged by an init container. The controller treats plugins as immutable artifacts per reconcile:

• Each plugin download is validated and copied into /plugins.
• RCON support is enabled by wiring the Velocircon addon and rendering its config.
• Credentials are injected via Kubernetes secrets and exposed to the container using env vars.

This design makes plugin management declarative and reproducible across environments.

Reconciliation flow (control loop)#

The reconcile loop is intentionally linear: resolve → render → apply → report. That structure makes it easy to reason about rollouts and failure modes.

Rollouts and failure handling#

To avoid stale configs, the Deployment template includes a config hash annotation. When the hash changes (e.g., backends or proxy config update), the Deployment rolls automatically.

Failure conditions are surfaced early:

• Missing forwarding secrets or invalid plugin downloads cause a degraded status and emit events.
• Service changes reconcile in place to avoid dropping traffic.
• Pod restarts are driven by configuration changes, not by ad‑hoc scripts.

Operational considerations#

A proxy tier is the front door for player traffic, so it needs a few reliability guardrails:

• Readiness checks should validate Velocity’s port and status endpoint.
• Resource requests should reflect peak concurrency to avoid eviction under load.
• Pod disruption budgets help preserve connection continuity during node maintenance.
• Rolling updates should use maxUnavailable=0 for zero‑downtime traffic handling.

Even for a homelab, these settings significantly reduce operational noise.

Troubleshooting quick hits#

• No backends appear: verify label selectors and namespace scope.
• Players can’t join: confirm forwarding mode matches the server-side config.
• Plugins not loading: check init container logs and download URLs.
• Stuck rollouts: check the config hash annotation and Deployment events.

Wrap-up#

The MinecraftNetwork controller turns a complex proxy pipeline into a declarative, repeatable workflow. By keeping rendering deterministic and reconciling only a handful of resources, the proxy layer behaves like a first-class Kubernetes workload—and stays easy to debug when things go wrong.