helm-charts/minecraft-server/values.yaml

# Scale the whole chart down without uninstalling it: scaleDown: true renders
# every Deployment/StatefulSet with replicas: 0 (and suspends CronJobs) and
# takes precedence over any per-workload replicas value. PVCs, Secrets and
# Services stay in place; scaleDown: false brings the workloads back up.
scaleDown: false

image:
  # Tag of the itzg/minecraft-server image. Empty means "use the chart's
  # appVersion" (2026.8.2-java25 here), which is what every release before chart
  # 5.0.0 did unconditionally.
  #
  # WHY THIS EXISTS. Since chart 5.0.0 only the NEWEST Java line is maintained
  # (see Chart.yaml). The older lines stay published as frozen artifacts - java8
  # and java17 at chart 4.0.0, java21 at 4.1.0 - and never receive another chart
  # change. To run an older JVM with the CURRENT chart, set the tag here instead
  # of installing a frozen chart version:
  #
  #   image:
  #     tagOverride: "2026.8.2-java21"
  #   minecraft:
  #     version: "1.21.11"
  #
  # It is called tagOverride, not tag, because it is an emergency exit: it
  # decouples the running image from the chart version, so the release no longer
  # says in its metadata what it actually runs. Prefer moving to the current
  # line; use this when a modpack pins you to an older Minecraft version.
  #
  # DELIBERATELY NOT MANAGED BY RENOVATE. renovate.json5 tracks appVersion in
  # Chart.yaml (partitioned by its "java<N>" compatibility group) and nothing
  # else. A tag set here is never bumped by anything - it is yours to review.
  #
  # The Java line of the effective tag (this value, or appVersion when it is
  # empty) is checked against minecraft.version at render time; a mismatch fails
  # the render with both values named. Two cases pass unchecked on purpose: a
  # tag without a recognizable "java<N>" part, and a minecraft.version that is
  # not a plain numeric x[.y[.z]] (snapshots, pre-releases, "LATEST").
  tagOverride: ""

secrets:
  # REQUIRED - op:// item path for the 1Password operator. The OnePasswordItem
  # CR is rendered unconditionally, so this reference has to be set even when
  # nothing consumes a key from it; it has no default and would otherwise render
  # an itemPath of null. The item's CONTENT may be empty in that case: it only
  # needs to carry a "curseforge-api-key" key when curseforge.enabled is true
  # and an "rcon-password" key when server.rcon.enabled is true. Without the
  # value the render aborts - required() in minecraft-server.secret.yaml is the
  # whole enforcement, and values.schema.json cannot help here (README,
  # guideline 12).
  #
  # Documented limit (chart 3.0.0): changing this path rolls the pod (the
  # StatefulSet hashes the rendered OnePasswordItem into checksum/secret-ref),
  # but changing the item's CONTENT in the vault does not. The operator updates
  # the Kubernetes Secret, while the running pod keeps the values it read at
  # startup - the keys are consumed as environment variables, which Kubernetes
  # never refreshes in a running container.
  #
  # The operator's own "operator.1password.io/auto-restart: true" annotation
  # does NOT close this gap here, and is therefore deliberately not set: it only
  # restarts Deployments. Verified in the operator source (main, 9c3b1b9,
  # 2026-08-11): restartWorkloadsWithUpdatedSecrets lists nothing but
  # appsv1.DeploymentList, and getPodTemplate has a single case for
  # *appsv1.Deployment and returns "unsupported type" for everything else. This
  # chart is a StatefulSet, so the annotation would do nothing while suggesting
  # the opposite.
  #
  # So after rotating rcon-password or curseforge-api-key in the vault, restart
  # the workload by hand (kubectl rollout restart statefulset/...) - and expect
  # the full startup cost of ~124 s measured for ftb-skies on Longhorn.
  minecraftServerRef: null

server:
  # Replica count for this workload; 0 is allowed and scales it down.
  # The chart-global scaleDown flag takes precedence.
  replicas: 1

  # Port the Minecraft server listens on inside the container. It is passed to
  # the image as SERVER_PORT, used as the containerPort and as the Service's
  # target, and the probes go through the image's mc-health script, which reads
  # SERVER_PORT too - so an override stays consistent everywhere.
  port: 25565

  service:
    # ClusterIP is the default because routing to these servers is done by the
    # static mappings of the minecraft-router chart, which reaches the server
    # over its in-cluster DNS name. Set NodePort to expose the server directly
    # on a node port instead (then outwardPort applies).
    # NOTE: before chart 1.0.0 this was implied by "mcRouterIntegration.enabled",
    # which also added a misleading mc-router auto-discovery annotation. The
    # annotation is gone; only the service type remains, now named for what it
    # actually does.
    type: ClusterIP
    # Port the Service exposes in the cluster.
    port: 25565
    # Node port used only when type is NodePort. Must be inside the cluster's
    # node-port range (30000-32767 by default).
    outwardPort: 30565

  # The \u00A7 sequences are Java-properties escapes for the Minecraft colour
  # code character and must stay literal backslash sequences - server.properties
  # is a Java properties file and unescapes them itself.
  motd: 'Running \u00A72\u00A7o%MODPACK_NAME% \u00A70version \u00A7r%env:MODPACK_VERSION%'

  rcon:
    # RCON is off by default. Only when this is true does the chart set
    # ENABLE_RCON, expose the RCON container port and wire RCON_PASSWORD from
    # the secret - before chart 1.0.0 the password was pulled from the secret
    # unconditionally although RCON was hardcoded off, which made the secret
    # key mandatory for a switched-off feature.
    enabled: false
    port: 25575

  # Init container that downloads and unpacks a CurseForge server pack; only
  # used when curseforgeServerpack.enabled is true. Pinned per repo convention
  # (auxiliary images are never unpinned): before chart 1.0.0 this was a bare
  # "alpine", i.e. an implicit :latest from Docker Hub.
  initImage: alpine:3.24

  resources:
    # Limits are optional: memory and ephemeral-storage limits default to
    # limitFactor x the request, an explicitly set limit always wins, and a
    # CPU limit is only set when configured explicitly under "limits"
    # (CPU is compressible - throttling is preferable to an OOM kill).
    limitFactor: 3
    requests:
      cpu: "2"
      ephemeral-storage: "100Mi"
      # Deliberately unset: when no memory request is given, the chart derives
      # it from minecraft.resources.memory (the JVM heap) so that the heap and
      # the container's memory request/limit can never drift apart. With the
      # default heap of 4G this yields a 4Gi request and, via limitFactor 3, a
      # 12Gi limit - exactly the values that were hardcoded before chart 1.0.0.
      # Set it explicitly to decouple the two.
      memory: null

# Extra environment variables for the server container, appended to the ones
# the chart always sets. Values are rendered through tpl and support the value,
# secretKeyRef and configMapKeyRef forms:
#   - name: SOME_ENV
#     value: "{{ .Release.Name }}"
#   - name: FROM_SECRET
#     valueFrom:
#       secretKeyRef:
#         name: "some-secret"
#         key: "someKey"
#   - name: FROM_CONFIGMAP
#     valueFrom:
#       configMapKeyRef:
#         name: "some-configmap"
#         key: "someKey"
env: []

# All three probes run the image's own mc-health script, which performs a real
# Minecraft server-list ping against SERVER_PORT via mc-monitor - so "Ready"
# means the server answers players, not merely that the container process is
# alive. (Before chart 1.0.0 this chart had no probes at all, which is why a
# pod counted as Ready the moment the container started.)
livenessProbe:
  exec:
    command: ["mc-health"]
  periodSeconds: 30
  timeoutSeconds: 10
  failureThreshold: 3
readinessProbe:
  exec:
    command: ["mc-health"]
  periodSeconds: 15
  timeoutSeconds: 10
  failureThreshold: 3
# The startup probe gates liveness and readiness, so its budget has to cover
# the slowest legitimate start: on a fresh volume the image downloads the
# server jar and, for FTB/CurseForge modpacks, the whole modpack before the
# world even begins to load. Budget 15s * 80 = 20 minutes; the liveness probe
# only starts counting afterwards, so a slow start can no longer be killed.
startupProbe:
  exec:
    command: ["mc-health"]
  periodSeconds: 15
  timeoutSeconds: 10
  failureThreshold: 80

securityContext:
  pod:
    runAsNonRoot: true
    # uid/gid 1000 is the image's "minecraft" user. The image's entrypoint
    # normally starts as root and drops to this user via gosu; starting as the
    # user directly makes it take the non-root branch, which additionally skips
    # the entrypoint's recursive chown of /data and its write to
    # /etc/nsswitch.conf - the latter would fail on a read-only root filesystem.
    runAsUser: 1000
    runAsGroup: 1000
    # fsGroup keeps the world volume writable for the minecraft user.
    # OnRootMismatch (instead of Always) avoids a recursive chown of the whole
    # world on every single pod start - on a 32Gi world that is minutes of
    # startup time. It still runs once if the volume root does not already
    # carry the group.
    fsGroup: 1000
    fsGroupChangePolicy: OnRootMismatch
  container:
    allowPrivilegeEscalation: false
    # Works because the chart mounts an emptyDir at /tmp - the image writes the
    # server-icon scratch file and mc-server-runner's console named pipe there.
    # Everything else the server writes goes to the PVC at /data.
    readOnlyRootFilesystem: true
    runAsNonRoot: true
    capabilities:
      drop:
        - ALL
      add: []

minecraft:
  # Valid values are: peaceful, easy, normal, and hard
  difficulty: "easy"
  whitelist:
    # Boolean, wired to the image's ENABLE_WHITELIST in BOTH positions since
    # chart 2.0.0 - which is what makes "false" actually switch the whitelist
    # off. server.properties lives on the PVC, so before 2.0.0 a release that
    # had once written white-list=true kept it forever: the chart only ever
    # emitted whitelist variables while enabled was true and had no way to say
    # "off". Now enabled: false emits ENABLE_WHITELIST=false, and the image
    # rewrites white-list=false into the existing file.
    #
    # >>> enabled: true WITHOUT players locks the server down completely. <<<
    # That is the image's own semantics and it is intended: white-list=true with
    # an empty whitelist.json means nobody can join - not even the ops. Set
    # players whenever this is turned on, or leave it at false.
    #
    # The default is false, matching both the image and vanilla Minecraft, which
    # start with white-list=false. (Before chart 2.0.0 the default was true with
    # players: null; that combination did nothing back then, because an empty
    # WHITELIST never enabled anything - under the new semantics it would be a
    # locked-out server, so the default is flipped.)
    enabled: false
    # How the image treats an ALREADY EXISTING whitelist.json on the volume:
    # SKIP leaves it alone, MERGE adds players to it, SYNCHRONIZE makes it match
    # players exactly (removing everyone else). Only applies while enabled.
    overridePolicy: "MERGE"
    # Comma-separated List of Players. Only passed to the image (as WHITELIST)
    # while enabled is true - a non-empty WHITELIST turns the whitelist on in
    # the image regardless of ENABLE_WHITELIST, so leaving it out is what keeps
    # enabled: false switched off even for a release that still lists players.
    players: null
  management:
    # Comma-separated List of Players. The image resolves every name against
    # the external Playerdb API and aborts startup if one does not resolve.
    opPlayers: null
    maxPlayers: 10
    forceGameMode: true
    # Valid values are: creative, survival, adventure, spectator (only for Minecraft 1.8 or later)
    gameMode: survival
    worldSaveName: world
    serverName: mc-server
  resources:
    storage: "32Gi"
    # Storage class of the world PVC. Was hardcoded to "longhorn" before chart
    # 1.0.0. Changing it on an existing release has no effect on the already
    # bound volume - storageClassName is immutable once the PVC exists.
    storageClassName: longhorn
    # JVM heap in gigabytes (passed to the image as MEMORY). Also drives the
    # container's memory request/limit unless server.resources.requests.memory
    # is set explicitly.
    memory: "4"
  # Minecraft version to run. Pinned rather than "LATEST", which would silently
  # drift to a new release on every restart.
  #
  # This value must match the Java line of the EFFECTIVE image tag - appVersion,
  # or image.tagOverride when that is set. Since chart 5.0.0 the chart checks it
  # and FAILS THE RENDER on a mismatch, naming both values; before 5.0.0 a
  # mismatch installed silently and only the container failed afterwards.
  #
  #   up to 1.16.5     Java 8
  #   1.17 - 1.17.1    Java 16   (never published as a chart line here)
  #   1.18 - 1.20.4    Java 17
  #   1.20.5 - 1.21.11 Java 21
  #   26.1 and later   Java 25
  #
  # These are Mojang's boundaries, not this chart's: javaVersion.majorVersion
  # from the piston-meta version manifest, swept over all 102 releases on
  # 2026-09-02. There are exactly four transitions and they are monotonic in
  # release order (1.6.1-1.6.4 predate the field and declare none).
  #
  # Only a plain numeric x[.y[.z]] is compared. A snapshot ("26w13a"), a
  # pre-release ("1.21.11-pre1") or "LATEST" is let through unchecked - see
  # image.tagOverride for why the two gaps are deliberate.
  #
  # Quote the value. Unquoted YAML reads 1.20 as the number 1.2, and the chart
  # would pass "1.2" to the image as VERSION.
  #
  # This chart publishes appVersion "2026.8.2-java25".
  version: "26.2"

# curseforge, ftb and curseforgeServerpack are mutually exclusive - enabling
# more than one is rejected by the chart (before 1.0.0 it silently rendered a
# duplicate TYPE env entry and the last one won).
curseforge:
  enabled: false
  forceReload: false
  modpack:
    slug: null
    versionId: null
    exclude: null
    excludeOverride: null
    include: null
ftb:
  enabled: false
  modpackId: null
  versionId: null
curseforgeServerpack:
  enabled: false
  # Both values below are rendered into the init.sh ConfigMap. Since chart 3.0.0
  # a change here rolls the pod (checksum/config on the StatefulSet), which is
  # what makes it take effect at all - init.sh is mounted with subPath and only
  # read at pod start. The restart is not free: ~124 s measured for ftb-skies on
  # Longhorn.
  downloadUrl: null
  workingDirectory: '/data/serverpack'

# ---------------------------------------------------------------------------
# NetworkPolicy (Gitea #5). On by default. The reference implementation with
# the full reasoning is template-chart; the convention is in README, "Chart
# style guidelines", and the operator's view on this chart's wiki page.
# ---------------------------------------------------------------------------
networkPolicy:
  # THIS IS ONE OF THE TIGHTEST POLICIES IN THE REPOSITORY, and the reason is
  # the probes: all three are EXEC probes, which run inside the container and
  # put no packet on the network. So there is no kubelet traffic to
  # accommodate, every port can be restricted by source, and no probeSources
  # value is needed at all.
  #
  # WHAT IT ALLOWS, inbound:
  #   - the game port (server.port): OPEN when server.service.type is NodePort
  #     (players arrive from the internet, already masqueraded), and
  #     RESTRICTED to this namespace plus allowedNamespaces otherwise - which
  #     is the default. Both branches read the same value the Service does.
  #   - RCON (server.rcon.port) and metrics (19565): always restricted. RCON is
  #     full administrative control of the server, so this is the rule with the
  #     most security value here, and it costs nothing.
  # Outbound: DNS and TCP 443 (Mojang's session server for online-mode, plus
  # resource packs and mods).
  #
  # PUT THE ROUTER'S NAMESPACE IN allowedNamespaces when the Service is not a
  # NodePort. In this cluster players reach the server through
  # minecraft-router, in its own namespace; without that entry the server is
  # unreachable and the symptom is a timeout in a game client with a healthy
  # pod behind it. The same applies to a Prometheus scraping 19565.
  enabled: true
  # Namespaces whose pods may reach this workload, in addition to the release's
  # own namespace, which is always allowed. Empty means: own namespace only.
  #
  # Matched on the "kubernetes.io/metadata.name" label Kubernetes sets on every
  # namespace itself, so no labelling work is needed on a namespace this chart
  # does not own - and no typo protection either: a name that does not exist
  # matches nothing and is silently ineffective. Note the granularity: an entry
  # opens the port to EVERY pod in that namespace.
  allowedNamespaces: []

  # The policy's INBOUND side. Mind the three names that overlap as substrings,
  # because a search for "ingress" matches all of them and they are different
  # things:
  #
  #   ingress                          (top level) the Ingress OBJECT this chart
  #                                    renders - host, TLS, className
  #   networkPolicy.ingress            this block: what the policy lets IN
  #   networkPolicy.ingressController  the SOURCE SELECTOR for the ingress
  #                                    controller's pods. A SIBLING of this block
  #                                    and NO PART OF IT, despite the name.
  ingress:
    # Opens the pod for Istio's ambient mesh (Gitea #143). OFF by default and
    # additive: while it is false this chart renders byte for byte as it did
    # before the value existed.
    #
    # It renders 15008/TCP inbound - ztunnel's HBONE tunnel. Every inbound mesh
    # connection arrives on it, and ambient "does not and will never bypass
    # Kubernetes NetworkPolicy enforcement", so without this port a pod whose
    # namespace has joined the mesh is unreachable.
    #
    # ONE HALF SHORTER THAN ELSEWHERE, deliberately. In other charts this switch
    # also adds 169.254.7.127/32 as a probe source, because inside the mesh the
    # kubelet's probes are redirected away from the worker node's address. This
    # chart has no networkPolicy.probeSources at all, so the rule carrying the
    # probe port is never restricted by source - and an unrestricted rule needs
    # no probe address. An ipBlock for one would match nothing while making the
    # rule look like it did something, which is the kind of strict-looking empty
    # rule ci/run-networkpolicy-test.sh exists to catch; that script ties the
    # exemption to the absence of probeSources rather than to a chart name.
    #
    # NOT PROVEN: that 15008 alone is enough comes from Istio's documentation;
    # measured on this cluster is only which listeners ztunnel opens, and no
    # namespace carries istio.io/dataplane-mode yet.
    # BOTH NUMBERS BELOW ARE ISTIO CONSTANTS, NOT STANDARDS, and they are values
    # rather than template literals for exactly that reason: a vendor constant
    # can change, and an operator should be able to correct it without waiting
    # for a chart release. Their provenance is written on each one.
    #
    # DELETING THIS OBJECT IS SAFE. Every read falls back to the defaults
    # declared here (#99), so "ambientMesh: null", or an object carrying only
    # "enabled: true", renders the documented defaults instead of failing.
    ambientMesh:
      # The switch. Everything else here is inert while it is false, and the
      # chart renders exactly as it did before the object existed.
      enabled: false

      # ISTIO'S HBONE PORT. A constant Istio chose, not a standard: not
      # registered with IANA for this, prescribed by no protocol, and unknown to
      # Kubernetes. Read for ztunnel 1.30.6 (measured on this cluster: ztunnel
      # opens [::]:15008 as its inbound listener).
      #
      # If Istio changes it, a pod in the mesh cannot be reached. Change it here
      # in all 30 charts AND in the pinned expectation inside
      # ci/run-networkpolicy-test.sh - the test is deliberately what forces
      # someone to look, because the exception it grants this port is pinned to
      # the number IT knows and not to whatever this value says. A value-driven
      # exception would let a mistyped port through, which is the hole design A
      # of #143 was rejected for.
      #
      # NOT MEASURED: that this port ALONE suffices comes from Istio's
      # documentation. Measured here is only which listeners ztunnel opens, and
      # no namespace carries istio.io/dataplane-mode yet.
      port: 15008

  egress:
    # Additional outbound TCP ports. DNS (UDP and TCP 53) is always allowed and
    # has no switch - a knob whose only other setting breaks every name lookup
    # in the pod is a trap, not a feature.
    #
    # PORTS, NOT DESTINATIONS, and that is a limit of the object rather than
    # laziness: a NetworkPolicy matches CIDRs and selectors and never hostnames,
    # so "only to the database host" cannot be written at all. Each entry
    # permits its port to ANY destination. What the cap still buys is real: a
    # compromised pod cannot open arbitrary outbound connections.
    #
    # Add a port for a mod pack that calls out somewhere other than 443 - an
    # authentication proxy, a map renderer upload, a Discord bridge.
    extraPorts: []