Kubernetes (Helm)

Deploy production-grade Hytale servers on Kubernetes using our Helm chart.

Prerequisites

Kubernetes 1.33+
Helm 3.x
PersistentVolume provisioner
UDP load balancer or Gateway API support

Quick Start

Add the Helm Repository

helm repo add everhytale https://everhytale.github.io/charts
helm repo update

Install the Chart

helm install my-hytale everhytale/hytale

Install with Custom Values

helm install my-hytale everhytale/hytale \
  --set jvm.maxMemory=16G \
  --set service.type=LoadBalancer

Install from Source

git clone https://github.com/everhytale/charts.git
cd charts
helm install my-hytale ./charts/hytale

Authentication

After installation, authenticate the server:

# Attach to the pod
kubectl attach -it deployment/my-hytale

# In the server console
/auth login device
/auth persistence Encrypted

# Detach: Ctrl+P, Ctrl+Q

Configuration

values.yaml Overview

# Image configuration
image:
  repository: everhytale/hytale-server
  tag: ""  # Uses Chart.AppVersion
  pullPolicy: IfNotPresent

# JVM settings
jvm:
  minMemory: "4G"
  maxMemory: "8G"

# Server settings
server:
  port: 5520
  bind: "0.0.0.0"
  authMode: "authenticated"

# Persistence
persistence:
  enabled: true
  size: 10Gi

# Service
service:
  type: ClusterIP
  port: 5520

# Resources
resources:
  requests:
    cpu: 1000m
    memory: 4Gi
  limits:
    cpu: 4000m
    memory: 8Gi

Image Parameters

Parameter	Description	Default
`image.repository`	Image repository	`everhytale/hytale-server`
`image.tag`	Image tag	`""` (Chart.AppVersion)
`image.pullPolicy`	Pull policy	`IfNotPresent`

JVM Configuration

Parameter	Description	Default
`jvm.minMemory`	Minimum heap	`4G`
`jvm.maxMemory`	Maximum heap	`8G`
`jvm.javaOpts`	Custom JVM options	`""`

Server Configuration

Parameter	Description	Default
`server.port`	UDP port	`5520`
`server.authMode`	Auth mode	`authenticated`
`server.disableSentry`	Disable Sentry	`false`
`server.useAotCache`	Use AOT cache	`true`

Backup Configuration

Parameter	Description	Default
`backup.enabled`	Enable backups	`false`
`backup.dir`	Backup directory	`/server/backups`
`backup.frequency`	Interval (minutes)	`30`
`backup.maxCount`	Max backups	`5`

Persistence

Parameter	Description	Default
`persistence.enabled`	Enable PVC	`true`
`persistence.size`	Volume size	`10Gi`
`persistence.storageClass`	Storage class	`""`
`persistence.existingClaim`	Use existing PVC	`""`

Service

Parameter	Description	Default
`service.type`	Service type	`ClusterIP`
`service.port`	Service port	`5520`
`service.nodePort`	NodePort	`null`

Resources

Parameter	Description	Default
`resources.requests.cpu`	CPU request	`1000m`
`resources.requests.memory`	Memory request	`4Gi`
`resources.limits.cpu`	CPU limit	`4000m`
`resources.limits.memory`	Memory limit	`8Gi`

Authentication Options

Option 1: Interactive (Recommended for Initial Setup)

kubectl attach -it deployment/my-hytale
/auth login device
/auth persistence Encrypted

Option 2: Values File

auth:
  ownerName: "MyUsername"
  ownerUuid: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  sessionToken: "your-session-token"
  identityToken: "your-identity-token"

Option 3: Existing Secret

# Create the secret
kubectl create secret generic hytale-auth \
  --from-literal=OWNER_NAME=MyUsername \
  --from-literal=OWNER_UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  --from-literal=SESSION_TOKEN=your-token \
  --from-literal=IDENTITY_TOKEN=your-jwt

auth:
  existingSecret: "hytale-auth"

Deployment Examples

Development Server

jvm:
  minMemory: "2G"
  maxMemory: "4G"

server:
  disableSentry: true
  authMode: "unauthenticated"

persistence:
  enabled: false

resources:
  requests:
    cpu: 500m
    memory: 2Gi
  limits:
    cpu: 2000m
    memory: 4Gi

helm install dev-server everhytale/hytale -f dev-values.yaml

Production Server

jvm:
  minMemory: "8G"
  maxMemory: "16G"

backup:
  enabled: true
  frequency: 15
  maxCount: 20

auth:
  existingSecret: "hytale-auth-prod"

machineId:
  mountFromHost: true

service:
  type: LoadBalancer
  externalTrafficPolicy: Local

persistence:
  enabled: true
  size: 50Gi
  storageClass: "fast-ssd"

resources:
  requests:
    cpu: 2000m
    memory: 8Gi
  limits:
    cpu: 8000m
    memory: 16Gi

nodeSelector:
  node-type: gaming

helm install prod-server everhytale/hytale -f prod-values.yaml

With Gateway API (UDPRoute)

service:
  type: ClusterIP

udpRoute:
  enabled: true
  parentRefs:
    - name: main-gateway
      namespace: gateway-system
      sectionName: hytale-udp

Exposing the Server

LoadBalancer (Cloud Providers)

service:
  type: LoadBalancer
  externalTrafficPolicy: Local

NodePort

service:
  type: NodePort
  nodePort: 30520

Gateway API

udpRoute:
  enabled: true
  parentRefs:
    - name: my-gateway
      namespace: gateway-system

Management Commands

View Logs

kubectl logs -l app.kubernetes.io/name=hytale -f

Access Console

kubectl attach -it deployment/my-hytale

Check Status

kubectl get pods -l app.kubernetes.io/name=hytale
kubectl describe pod -l app.kubernetes.io/name=hytale

Upgrade

helm upgrade my-hytale everhytale/hytale -f values.yaml

Uninstall

helm uninstall my-hytale

Troubleshooting

Pod Fails to Start

kubectl describe pod -l app.kubernetes.io/name=hytale
kubectl logs -l app.kubernetes.io/name=hytale --previous

Memory Issues

Ensure JVM memory matches resource limits:

jvm:
  maxMemory: "8G"
resources:
  limits:
    memory: 10Gi  # Slightly more than maxMemory

Cannot Attach to Console

Enable console access:

console:
  tty: true
  stdin: true

Authentication Fails

Mount machine-id for encrypted persistence:

machineId:
  mountFromHost: true

Next Steps

Installing Plugins - Add EverEssentials
Docker Compose - Simpler alternative