addyvan / valheim-k8s

valheim game-server on kubernetes

valheim-k8s

Kubernetes deployment for a valheim game-server. Based off the dockerization work by lloesche here.

Usage

Note: This assumes the node you are running on can use /data/valheim mounted as a host volume for persistence.

helm repo add valheim-k8s https://addyvan.github.io/valheim-k8s/
helm repo update
helm install valheim-server valheim-k8s/valheim-k8s  \
  --set worldName=example-world-name \
  --set serverName=example-server-name \
  --set password=password \
  --set storage.kind=hostvol \
  --set storage.hostvol.path=/data/valheim

Configuration

Parameter	Description	Default
worldName	Prefix of the world files to use (will make new if missing)	example-world-name
serverName	Server name displayed in the server browser(s)	example-server-name
password	Server password	password
passwordSecret	Name of Kubernetes secret to pull secret from. Secret should contain a single field labeled password	None
storage.kind	Storage strategy/soln used to provide the game-server with persistence	hostvol
storage.hostvol.path	The folder to be mounted into /config in the game-server pod	/data/valheim
storage.pvc.storageClassName	The storageClass used to create the persistentVolumeClaim	default
storage.pvc.size	The size of the persistent volume to be created	1Gi
serverStorage.kind	Storage strategy/soln used to save the server installation files	hostvol
serverStorage.hostvol.path	The folder to be mounted into /opt/valheim in the game-server pod	/data/valheim-server
serverStorage.pvc.storageClassName	The storageClass used to create the persistentVolumeClaim	default
serverStorage.pvc.size	The size of the persistent volume to be created	5Gi
networking.serviceType	The type of service e.g NodePort, LoadBalancer or ClusterIP	LoadBalancer
networking.gamePort	The UDP start port the server will listen on	2456
networking.nodePort	When service type is NodePort, assign a fixed UDP port to the server	""
networking.publishQueryPort	Expose the Steam query port (gamePort + 1)	true
nodeSelector		{}
tolerations		[]
image.repository	Specifies container image repository	lloesche/valheim-server
image.tag	Specifies container image tag	latest
priorityClassName	Specifies the priority class name for the deployment	None

Persistence

Currently persistence is supported through mounting a hostvol or via a persistentVolumeClaim. Please create an issue if you would like support for specific cloud storage solutions via PVCs / storageclasses. They vary by provider so PRs / testers welcome for this.

You can enable persistence for both the server data (your worlds, mounted at /config and configured with the storage parameter) and the server installation (to skip downloading it every time a pod is created, mounted at /opt/valheim, configured with the serverStorage parameter).

Using a Host Volume

Note: If you are deploying to a cloud provider it is highly recommended that you use a PVC powered by a cloud-specific storageClass. Otherwise you risk losing your world.

On the node you wish to use make sure the folder you are mounting exists (ideally empty if you are starting a new world). Once you spin up the game pod you should see the following files created:

$ ls /data/valheim
adminlist.txt  backups  bannedlist.txt  permittedlist.txt  prefs  worlds

Using a persistentVolumeClaim

To use a persistentVolumeClaim for storage, you will need to first set up your CSI and StorageClass for your K8s cluster. Information regarding that differs by cloud provider and there are several guides available for configuring each of them.

Once you have your StorageClass set up, set storage.kind to persistentVolumeClaim, optionally set storage.pvc.storageClassName to the name of your previously configured StorageClass (or it will use the default StorageClass), and set storage.pvc.size to the size of the volume to create (default 1Gi).

Using an existing world

To use an existing world simply set the worldName parameter to the name of your world then save the .db and .fwl files to the directory mounted into the pod. For example, if your world is named myworld then set worldName: myworld in your values file (or --set worldName=myworld) and assuming you are mounting at /data/valheim then your directory should look like:

$ ls /data/valheim/worlds/
myworld.db  myworld.fwl

Connecting to your world

Assuming you have taken care of the networking (port-forwarding if needed, LoadBalancer IP is created, ...):

• In the steam UI (NOT IN GAME) go to view->servers->add favorite
  • set the port to 2457 (reason for that here)
• To connect double click the server in the steam servers explorer
  • You will be asked for the password in the steam ui and in game

More visual set of instructions here

Potential future updates

If there is interest I can hash out the following:

• Cronjob to save backups to s3, blob storage, or minio
  • Then clear up the space in the hostvol/pvc
• More persistence options, namely for those looking to run this on the cloud
  • I'm familiar with Azure and AWS but I'm sure GCP and others will be fairly simple to figure out if we have testers

valheim-k8s's Issues

Google Autopilot Ephemeral Storage Limit Exceeded

For whatever reason, GCP Autopilot K8s clusters set an ephemeral storage limit of 1Gi: https://cloud.google.com/kubernetes-engine/docs/concepts/autopilot-overview#default_container_resource_requests

This seems to be exceeded, at least during initial setup. I get errors in the logs that just say '/home/valheim/Steam/logs/stderr.txt', and a notice in the console that the limit has been exceeded. Does anyone know what a good value for ephemeral storage limit should be? I'm happy to make the change, just don't really know what to put in that space.

If no one responds to this in a few days I'll submit a PR with a 10Gi Ephemeral storage request.

Sick stuff btw! Thank you!

Add support for Storage Classes

Add support for using kubernetes storage classes.
With only host mount support the server has be pinned to the same host. (partial fix #14 )
Could be setup similar to https://github.com/bitnami/charts/tree/master/bitnami/mysql

Warn user of HostVol volatility on a Managed GCloud

Today my node got updated automaticaly by GCloud.
Unfortunalty the node containing the HostVol and thus our game world was deleted.

I think it would be nice to warn of this issue on the Readme.

I was kindof aware of this issue with hostvol but didn't realy pay enough attention to it.
Also i wasn't expecting my node to be updated, but it's too late.

tcp/http health probe endpoint

This is more or less a painful unresolved Microsoft issue, but it is not possible to use the a Microsoft Azure load balancer udp rule without a tcp/http health probe. The Valheim pod is UDP-only and has no tcp/http health endpoints so it is necessary to create an addon DaemonSet to cover this need. But this really does not show the health status of the Valheim instance...

Having all the great support services already on board it would be great having a health endpoint, too.

Please consider marking the world-data PVC as "do not delete"

To avoid surprise world-data loss when upgrading or modifying charts, I'd suggest marking the world-data PVC with the "helm.sh/resource-policy": keep annotation.

It might make sense for this to be configurable in the values.yaml, both to support existing behaviour, and to not surprise users who expect to lose their data when uninstalling the chart.

I'm not sure about doing the same thing for the server-data PVC, since it's not unique/special, just big. It's hence more-costly to forget, i.e. 60c/month on AWS EBS vs 12c/month for the world-data.

hostpath can't be set through helm

I tried to install valheim server on k8s, but set storage.hostvol.path as /var/data/valheim.

Container stucked on status ContainerCreating because of wrong hostpath. It was set /data/valheim

deployment template exposes TCP instead of UDP

deployment template exposes TCP container ports instead of UDP.

        ports:
        - containerPort: 2456
          name: game1
        - containerPort: 2457
          name: game2
        - containerPort: 2458
          name: game3

Should be

        ports:
        - containerPort: 2456
          protocol: UDP
          name: game1
        - containerPort: 2457
          protocol: UDP
          name: game2
        - containerPort: 2458
          protocol: UDP
          name: game3

Please support custom annotations on the Service

There are two important use-cases for custom annotations on services:

• Integrating with things like external-dns to auto-register a DNS entry for the Service when the external-dns.alpha.kubernetes.io/hostname annotation is present, which makes life much easier for unpublished servers.
• Various cloud provider Load Balancers use annotations on the Service to configure various options. Particularly for AWS, this will be necessary as the default ELB load balancer doesn't support UDP.

This is a pretty common setup and shouldn't be hard to add. I might have a burl at it later myself, but in the meantime, it's low-hanging fruit for someone keen.

You can see how it's done in the helm create Ingress template and Values template.

Examples for deploying to different cloud providers

• GKE
• AWS
• Digital Ocean
• Azure

• The only real difference between theses providers, assuming managed clusters, would be the storage plugins and load balancer provisioning / networking.
• NGINX also supports UDP Load Balancing with support for ingress. Although, I haven't tried UDP over ingress myself and it seems a bit hacky.
  • Ingress yamls would be a nice way to help people easily expose multiple servers over a single load balancer if desired (something I don't see myself ever wanted personally but hey).

Add nodeSelector support

This'll make sure that multi-node homelabs won't lose state between pod recreations.

serverStorage isn't provisioned

Hello, I'm passing such values:

worldName: "ZadupieNowe3"
serverName: "NieliszCycowNiemce"
password: "secret"
storage:
  kind: "persistentVolumeClaim"
  pvc:
    storageClassName: "longhorn"
    size: 5Gi

serverStorage:
  kind: "persistentVolumeClaim"
  pvc:
    storageClassName: "longhorn"
    size: 5Gi

and only storage is created, serverStorage isn't provisioned for some reason

➜  ~ kubectl -n valheim get pvc
NAME                        STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS   AGE
valheim-server-world-data   Bound    pvc-4ef318bf-0730-4ba9-81cc-79238c14349d   5Gi        RWO            longhorn       21h

Please use the Release name in the name of created k8s objects

Using the Release name in the k8s object names ensures that multiple installations of the chart in a single namespace cannot conflict, and also helps identify resources that belong together.

The default helm create template provides an example for this as a named template <CHART>.fullname, which also supports overriding either the entire 'fullname' or just the .Chart.Name aspect, and can then be used as the name or name prefix for objects created by the chart.

Helpfully, all resources currently created have "valheim-server" as a name or prefix, so this is a reasonably easy thing to change.

However, for continuity when upgrading, either the default for fullnameOverride would be "valheim-server", and that's stuck there forever, or at some point users upgrading need to know to add that setting to their config when upgrading. Either one is a pain. >_<

v1.0.5 introduced a bug in the node port setup

Upgrade "valheim" failed: cannot patch "valheim-server" with kind Service: Service "valheim-server" is invalid: spec.ports[0].nodePort: Invalid value: 2456: provided port is not in the valid range.  │
│ The range of valid ports is 30000-32767