Skip to content
Minecraft icon
v1.5.8App: v2026.10.0Pinned DigestS3 Backup Ready

Production Helm chart • Apache-2.0 • Zero-Root • Verified on Kubernetes v1.33-v1.36+

Minecraft Server

A Helm chart for deploying Minecraft Java Edition servers on Kubernetes using the itzg/minecraft-server container image.

Installation

HTTPS Repository

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install minecraft helmforge/minecraft --set server.eula=true

OCI Registry

helm install minecraft oci://ghcr.io/helmforgedev/helm/minecraft --set server.eula=true

Important: You must set server.eula=true to accept the Minecraft EULA. The server will not start without it.

Quick Start

helm install minecraft oci://ghcr.io/helmforgedev/helm/minecraft \
  --set server.eula=true \
  --set server.motd="My Server" \
  --set jvm.memory=2G

Features

  • Multiple Server Types — Vanilla, Paper, Spigot, Forge, Fabric, Quilt, and more via the server.type value
  • GeyserMC Cross-Play — Allow Bedrock (mobile, console) clients to join Java servers
  • Authentication & Access Control — Online/offline mode, whitelist, operators
  • RCON Remote Console — Enabled by default with auto-generated password
  • Persistent Storage — PVC for world data, configs, plugins, and mods
  • Scheduled Backups — CronJob-based backup to S3-compatible storage with RCON save coordination
  • Prometheus Monitoring — mc-monitor sidecar with ServiceMonitor support
  • Mod/Plugin Management — Modrinth, CurseForge, Spiget, and direct URL downloads
  • Optimized JVM — Aikar's GC flags for production workloads
  • Server Resource Pack — URL-based with SHA-1 verification and enforcement
  • Dual-stack — ipFamilyPolicy/ipFamilies on the game and RCON Services for IPv4/IPv6 clusters
  • ExternalSecrets — opt-in ExternalSecret to source the RCON password from an external secrets store

Supported Server Types

Type Value Description
Vanilla VANILLA Official Mojang server (default)
Paper PAPER High-performance Spigot fork (recommended for production)
Spigot SPIGOT Bukkit-based plugin server
Forge FORGE Mod platform for Java mods
Fabric FABRIC Lightweight mod loader
Quilt QUILT Community-driven Fabric fork
Auto CurseForge AUTO_CURSEFORGE CurseForge modpack auto-install

Configuration

Minimal (Simple Setup)

server:
  eula: true
  motd: "My Minecraft Server"

jvm:
  memory: 1G

persistence:
  enabled: true
  size: 10Gi

Production (Full Setup)

server:
  eula: true
  type: PAPER
  version: LATEST
  difficulty: normal
  maxPlayers: 50
  viewDistance: 8

jvm:
  memory: 4G
  useAikarFlags: true

auth:
  onlineMode: true
  whitelist: "player1,player2"
  enforceWhitelist: true
  ops: "player1"

rcon:
  enabled: true
  existingSecret: minecraft-rcon

metrics:
  enabled: true
  serviceMonitor:
    enabled: true

backup:
  enabled: true
  schedule: "0 4 * * *"
  s3:
    endpoint: https://s3.amazonaws.com
    bucket: minecraft-backups
    existingSecret: minecraft-s3

persistence:
  enabled: true
  size: 50Gi

resources:
  requests:
    cpu: "1"
    memory: 4Gi
  limits:
    cpu: "4"
    memory: 8Gi

Cross-Play (GeyserMC)

server:
  eula: true
  type: PAPER

geyser:
  enabled: true
  port: 19132

mods:
  # GeyserMC is available as a Paper plugin through Modrinth.
  # Use geyser:beta when upstream has not promoted a compatible release yet.
  modrinthProjects: "geyser:beta"

Floodgate is optional for Bedrock players without Java accounts. For Paper or Spigot servers, provide the platform-specific Floodgate plugin through mods.downloadUrls or another plugin delivery workflow rather than mods.modrinthProjects.

Parameters

Server

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

JVM

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

Authentication

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

GeyserMC

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

RCON

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

Persistence

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

Metrics

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

Backup

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

Upgrade Notes

The 2026.10.0 image updates the bundled helper and monitor components, improves archive extraction, and fixes GTNH handling. Existing defaults remain unchanged. It retains the behavior that stops startup after failed custom-server, BuildTools, Sponge, modpack or FTB installer downloads instead of continuing with incomplete artifacts. Confirm modpack downloads and installer success before rolling out. The dated image pins the container distribution, not the game: pin server.version separately to keep an image update from downloading a newer Minecraft release.

Earlier image releases fixed Modrinth packs that require server-side mods, corrected STOP_SERVER_DELAY_COMMAND, and updated the bundled Minecraft helper tools. It retains native PREFER_IPv6 and custom SERVER_RUNNER support. Configure the first two features with server.preferIPv6 and server.runner. Review the 2026.10.0 release. Review the upstream release notes before upgrading production servers, take a world backup, and verify plugins, mods, datapacks, proxy settings, and pinned server.version values in a staging environment before reusing existing PVCs.

Security Scan

Security Scan: Kubescape local scan against MITRE,NSA,SOC2 reports a 78.79% resource summary score.

Mods & Plugins

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

Resource Pack

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

Services (Dual-Stack)

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

External Secrets Operator

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

externalSecrets.enabled=true with rcon.enabled=true requires rcon.existingSecret to prevent credential drift.

Scheduling

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

Security

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

Upgrades from releases that stored partial security-context maps are supported with both --reset-values and --reuse-values. The chart merges missing hardening defaults while retaining explicit per-key operator overrides. Custom images must support UID/GID 1000 and a read-only root filesystem, or provide matching context overrides.

Resources Generated

Resource Condition Description
Deployment Always Minecraft server (single replica, Recreate strategy)
Service Always Game port (LoadBalancer by default)
Service (RCON) rcon.serviceEnabled RCON port (ClusterIP)
PersistentVolumeClaim persistence.enabled Server data volume
Secret rcon.enabled and no existingSecret RCON password
Secret (backup) backup.enabled and no existingSecret S3 credentials
ServiceAccount serviceAccount.create Dedicated SA
ServiceMonitor metrics.serviceMonitor.enabled Prometheus scrape config
CronJob backup.enabled Scheduled S3 backup
ConfigMap (backup) backup.enabled Backup shell scripts
ExternalSecret externalSecrets.enabled Fetches RCON password from external secrets store

Dual-Stack Game Service

service:
  ipFamilyPolicy: PreferDualStack
  ipFamilies:
    - IPv4
    - IPv6

External Secrets Operator (RCON password)

rcon:
  enabled: true
  existingSecret: my-minecraft-rcon-secret
  existingSecretKey: rcon-password

externalSecrets:
  enabled: true
  secretStoreRef:
    name: my-store
    kind: ClusterSecretStore
  data:
    - secretKey: rcon-password
      remoteRef:
        key: minecraft/rcon
        property: password

Examples

Architecture Guides

Connection

After installation, retrieve the server address:

# LoadBalancer
kubectl get svc <release>-minecraft -o jsonpath='{.status.loadBalancer.ingress[0].ip}'

# RCON password
kubectl get secret <release>-minecraft -o jsonpath='{.data.rcon-password}' | base64 -d

Non-Goals

This chart intentionally does not support:

  • Multi-server proxy — Velocity/BungeeCord requires a separate chart
  • Bedrock Dedicated Server — Use itzg/minecraft-bedrock-server separately
  • Horizontal auto-scaling — Minecraft servers are single-threaded and cannot scale horizontally
  • Built-in world download/upload — Use backup/restore workflows instead

System Architecture

DESIGN.md Synced

Verified architecture contract rendered dynamically from GitHub DESIGN.md

flowchart LR
  player[Java players] --> svc[Minecraft Service]
  bedrock[Bedrock players] -. optional .-> svc
  svc --> pod[Minecraft Deployment]
  pod --> data[(World PVC)]
  rcon[RCON Service] --> pod
  secret[RCON Secret or ExternalSecret] --> pod
  backup[Backup CronJob] --> data
  backup --> s3[S3-compatible storage]
Official Contractvalues.schema.json

Minecraft Values Schema Reference

Official schema parameters, default values, and types extracted directly from the chart repository.

156 parametersValues Studio

Global(1)

ParameterTypeDefaultDescription
globalobject-Global settings shared by the chart.

Name Override(1)

ParameterTypeDefaultDescription
nameOverridestring""Override the chart name used in resource names

Fullname Override(1)

ParameterTypeDefaultDescription
fullnameOverridestring""Override the full release name used in resource names

Common Labels(1)

ParameterTypeDefaultDescription
commonLabelsobject-Labels added to every resource created by this chart

Image(3)

ParameterTypeDefaultDescription
image.repositorystringdocker.io/itzg/minecraft-serverContainer image repository
image.tagstring2026.10.0Container image tag
image.pullPolicystringIfNotPresentImage pull policy
Allowed:AlwaysIfNotPresentNever

Image Pull Secrets(1)

ParameterTypeDefaultDescription
imagePullSecretsarray-Image pull secrets for private registries

Server(25)

ParameterTypeDefaultDescription
server.eulabooleantrueAccept the Minecraft EULA (required, must be true)
server.typestringVANILLAServer type
Allowed:VANILLAPAPERSPIGOTBUKKITFORGEFABRICQUILTFTBACURSEFORGEMODRINTHAUTO_CURSEFORGE
server.versionstringLATESTMinecraft version (LATEST, SNAPSHOT, or specific like 1.21.4)
server.preferIPv6booleanfalsePrefer the IPv6 Java network stack and addresses
server.runnerstringmc-server-runnerCommand used to supervise the Minecraft server process
server.motdstringA Minecraft Server powered by HelmForgeMessage of the day displayed in the server list
server.difficultystringnormalGame difficulty
Allowed:peacefuleasynormalhard
server.gameModestringsurvivalDefault game mode
Allowed:survivalcreativeadventurespectator
server.maxPlayersinteger20Maximum number of concurrent players
server.viewDistanceinteger10View distance in chunks (lower improves performance)
server.simulationDistanceinteger10Simulation distance in chunks
server.seedstring""World seed (leave empty for random)
server.worldSaveNamestringworldWorld name (directory under /data)
server.levelTypestringDEFAULTLevel type
Allowed:DEFAULTFLATLARGEBIOMESAMPLIFIEDCUSTOMIZED
server.pvpbooleantrueEnable player vs player combat
server.allowNetherbooleantrueEnable the Nether dimension
server.allowFlightbooleanfalseAllow flight (required for some mods)
server.enableCommandBlockbooleanfalseEnable command blocks
server.forceGameModebooleanfalseForce players into the default game mode on join
server.hardcorebooleanfalseEnable hardcore mode (permanent death)
server.spawnProtectioninteger16Spawn protection radius (0 to disable)
server.portinteger25565Server port for Java Edition clients
server.extraPropertiesobject-Extra server.properties entries as key-value pairs
server.extraEnvarray-Additional environment variables for the server container
server.extraArgsstring""Additional arguments passed to the server JAR

Jvm(6)

ParameterTypeDefaultDescription
jvm.memorystring1GJVM memory allocation (sets both -Xms and -Xmx)
jvm.initMemorystring""Override initial heap size independently
jvm.maxMemorystring""Override maximum heap size independently
jvm.useAikarFlagsbooleanfalseUse Aikar's optimized GC flags (recommended for production)
jvm.jvmOptsstring""Additional JVM options (space-delimited)
jvm.xxOptsstring""Additional -XX JVM options

Authentication(4)

ParameterTypeDefaultDescription
auth.onlineModebooleantrueEnable Mojang online authentication (set to false for offline/proxy mode)
auth.whiteliststring""Comma-separated list of whitelisted player names or UUIDs
auth.enforceWhitelistbooleanfalseEnforce whitelist immediately when changed
auth.opsstring""Comma-separated list of operator (admin) player names or UUIDs

Geyser(2)

ParameterTypeDefaultDescription
geyser.enabledbooleanfalseEnable GeyserMC plugin for Bedrock cross-play
geyser.portinteger19132Bedrock listener port

Rcon(7)

ParameterTypeDefaultDescription
rcon.enabledbooleantrueEnable RCON remote administration
rcon.portinteger25575RCON port
rcon.passwordstring""RCON password (auto-generated if empty and no existingSecret)
rcon.existingSecretstring""Use an existing secret for the RCON password
rcon.existingSecretKeystringrcon-passwordKey in the existing secret that contains the RCON password
rcon.serviceEnabledbooleanfalseExpose RCON as a separate Service
rcon.serviceTypestringClusterIPRCON service type (keep ClusterIP for security)
Allowed:ClusterIPNodePortLoadBalancer

Persistence(6)

ParameterTypeDefaultDescription
persistence.enabledbooleantrueEnable persistent storage for server data (/data)
persistence.storageClassstring""Storage class (leave empty for cluster default)
persistence.accessModestringReadWriteOnceAccess mode for the PVC
Allowed:ReadWriteOnceReadOnlyManyReadWriteMany
persistence.sizestring10GiSize of the persistent volume
persistence.existingClaimstring""Use an existing PVC instead of creating one
persistence.annotationsobject-Annotations for the PVC

Resources(1)

ParameterTypeDefaultDescription
resourcesobject-CPU and memory requests/limits for the server container

Automount Service Account Token(1)

ParameterTypeDefaultDescription
automountServiceAccountTokenbooleanfalseMount a Kubernetes API token in the pod. The Minecraft server does not query the Kubernetes API.

Pod Security(3)

ParameterTypeDefaultDescription
podSecurityContext.fsGroupinteger1000Group ID for volume ownership
podSecurityContext.fsGroupChangePolicystringAlwaysPolicy for changing volume ownership
Allowed:AlwaysOnRootMismatch
podSecurityContext.seccompProfile.typestringRuntimeDefaultSeccomp profile type

Container Security(6)

ParameterTypeDefaultDescription
securityContext.runAsUserinteger1000User ID for the server process
securityContext.runAsGroupinteger1000Group ID for the server process
securityContext.runAsNonRootbooleantrueRequire a non-root server process
securityContext.allowPrivilegeEscalationbooleanfalsePrevent privilege escalation
securityContext.readOnlyRootFilesystembooleantrueKeep the image filesystem read-only
securityContext.capabilities.droparray["ALL"]Chart configuration parameter

Startup Probe(5)

ParameterTypeDefaultDescription
startupProbe.enabledbooleantrueEnable startup probe (recommended for slow-loading modpacks)
startupProbe.initialDelaySecondsinteger30Initial delay before first check
startupProbe.periodSecondsinteger10Interval between checks
startupProbe.timeoutSecondsinteger5Timeout per check
startupProbe.failureThresholdinteger30Number of failures before the container is restarted

Liveness Probe(5)

ParameterTypeDefaultDescription
livenessProbe.enabledbooleantrueEnable liveness probe
livenessProbe.initialDelaySecondsinteger0Chart configuration parameter
livenessProbe.periodSecondsinteger15Chart configuration parameter
livenessProbe.timeoutSecondsinteger5Chart configuration parameter
livenessProbe.failureThresholdinteger3Chart configuration parameter

Readiness Probe(5)

ParameterTypeDefaultDescription
readinessProbe.enabledbooleantrueEnable readiness probe
readinessProbe.initialDelaySecondsinteger0Chart configuration parameter
readinessProbe.periodSecondsinteger10Chart configuration parameter
readinessProbe.timeoutSecondsinteger5Chart configuration parameter
readinessProbe.failureThresholdinteger3Chart configuration parameter

Service & Networking(6)

ParameterTypeDefaultDescription
service.typestringLoadBalancerService type for the game port
Allowed:ClusterIPNodePortLoadBalancer
service.portinteger25565Game port (must match server.port)
service.nodePortstringinteger""Node port (only used when service.type is NodePort)
service.annotationsobject-Annotations for the game service
service.ipFamilyPolicystringnull-Dual-stack ipFamilyPolicy (GR-058)
Allowed:nullSingleStackPreferDualStackRequireDualStack
service.ipFamiliesarray-Dual-stack ipFamilies (GR-058)

Service Account(3)

ParameterTypeDefaultDescription
serviceAccount.createbooleanfalseCreate a dedicated ServiceAccount
serviceAccount.namestring""Name override (auto-generated if empty)
serviceAccount.annotationsobject-Annotations for the ServiceAccount

Metrics & Observability(14)

ParameterTypeDefaultDescription
metrics.enabledbooleanfalseEnable Prometheus metrics via mc-monitor sidecar
metrics.image.repositorystringdocker.io/itzg/mc-monitormc-monitor image repository
metrics.image.tagstring0.16.1mc-monitor image tag
metrics.image.pullPolicystringIfNotPresentmc-monitor pull policy
Allowed:AlwaysIfNotPresentNever
metrics.portinteger8080Port for the Prometheus metrics endpoint
metrics.securityContext.runAsUserinteger-Chart configuration parameter
metrics.securityContext.runAsGroupinteger-Chart configuration parameter
metrics.securityContext.runAsNonRootboolean-Chart configuration parameter
metrics.securityContext.allowPrivilegeEscalationboolean-Chart configuration parameter
metrics.securityContext.readOnlyRootFilesystemboolean-Chart configuration parameter
metrics.securityContext.capabilities.droparray-Chart configuration parameter
metrics.serviceMonitor.enabledbooleanfalseCreate a ServiceMonitor resource
metrics.serviceMonitor.intervalstring30sScrape interval
metrics.serviceMonitor.labelsobject-Additional labels for the ServiceMonitor

Backup(21)

ParameterTypeDefaultDescription
backup.enabledbooleanfalseEnable scheduled backups to S3-compatible storage
backup.schedulestring0 4 * * *Cron schedule for backups (default: daily at 04:00 UTC)
backup.suspendbooleanfalseSuspend the CronJob without deleting it
backup.concurrencyPolicystringForbidConcurrency policy
Allowed:ForbidReplaceAllow
backup.successfulJobsHistoryLimitinteger3Number of successful job records to keep
backup.failedJobsHistoryLimitinteger3Number of failed job records to keep
backup.backoffLimitinteger1Maximum retries per backup job
backup.archivePrefixstringminecraftPrefix for backup archive filenames
backup.excludesstring*.jar cache logsDirectories to exclude from the backup archive (space-separated)
backup.images.workerstringdocker.io/itzg/minecraft-server:2026.10.0Image used for RCON commands and tar archiving (must have sh, tar, and rcon-cli)
backup.images.uploaderstringdocker.io/helmforge/mc:1.0.0Image used for S3 upload (MinIO client)
backup.resourcesobject-Resources for backup containers
backup.s3.endpointstring""S3-compatible endpoint URL (e.g., https://s3.amazonaws.com, https://minio.example.com)
backup.s3.bucketstring""Target bucket name
backup.s3.prefixstringminecraftKey prefix within the bucket
backup.s3.createBucketIfNotExistsbooleantrueAuto-create the bucket if it does not exist
backup.s3.existingSecretstring""Use an existing secret for S3 credentials
backup.s3.existingSecretAccessKeyKeystringaccess-keyKey in the existing secret for the access key
backup.s3.existingSecretSecretKeyKeystringsecret-keyKey in the existing secret for the secret key
backup.s3.accessKeystring""Inline S3 access key (ignored when existingSecret is set)
backup.s3.secretKeystring""Inline S3 secret key (ignored when existingSecret is set)

Mods(7)

ParameterTypeDefaultDescription
mods.genericPacksstring""Comma-separated generic pack URLs or OCI references applied in order
mods.genericPacksOciAuthFilestring""Container path to a registry auth file for private OCI generic packs
mods.modrinthProjectsstring""Modrinth project slugs or IDs (comma-separated)
mods.curseforgeApiKeystring""CurseForge API key (required for CurseForge downloads)
mods.autoCurseforgeSlugstring""Auto CurseForge modpack slug (requires server.type: AUTO_CURSEFORGE)
mods.spigetResourcesstring""Spiget resource IDs for Bukkit/Spigot plugins (comma-separated)
mods.downloadUrlsstring""URLs to download plugins or mods from (newline-separated)

Resource Pack(3)

ParameterTypeDefaultDescription
resourcePack.urlstring""URL to a server resource pack
resourcePack.sha1string""SHA-1 hash of the resource pack for verification
resourcePack.enforcebooleanfalseForce clients to accept the resource pack

Node Selector(1)

ParameterTypeDefaultDescription
nodeSelectorobject-Node selector for pod scheduling

Tolerations(1)

ParameterTypeDefaultDescription
tolerationsarray-Tolerations for pod scheduling

Affinity(1)

ParameterTypeDefaultDescription
affinityobject-Affinity rules for pod scheduling

Topology Spread Constraints(1)

ParameterTypeDefaultDescription
topologySpreadConstraintsarray-Topology spread constraints

Priority Class Name(1)

ParameterTypeDefaultDescription
priorityClassNamestring""Priority class name

Termination Grace Period Seconds(1)

ParameterTypeDefaultDescription
terminationGracePeriodSecondsinteger120Grace period for server shutdown (seconds, allow time for save-all)

Pod Labels(1)

ParameterTypeDefaultDescription
podLabelsobject-Additional labels for the pod

Pod Annotations(1)

ParameterTypeDefaultDescription
podAnnotationsobject-Additional annotations for the pod

Extra Volume Mounts(1)

ParameterTypeDefaultDescription
extraVolumeMountsarray-Additional volume mounts for the server container

Extra Volumes(1)

ParameterTypeDefaultDescription
extraVolumesarray-Additional volumes for the pod

Extra Manifests(1)

ParameterTypeDefaultDescription
extraManifestsarray-Extra Kubernetes manifests to deploy alongside the chart

External Secrets(7)

ParameterTypeDefaultDescription
externalSecrets.enabledbooleanfalseChart configuration parameter
externalSecrets.apiVersionstringexternal-secrets.io/v1Chart configuration parameter
externalSecrets.refreshIntervalstring0Chart configuration parameter
externalSecrets.secretStoreRef.namestring-Chart configuration parameter
externalSecrets.secretStoreRef.kindstringSecretStoreChart configuration parameter
Allowed:SecretStoreClusterSecretStore
externalSecrets.target.creationPolicystringOwnerChart configuration parameter
Allowed:OwnerMergeNoneOrphan
externalSecrets.dataarray-Chart configuration parameter