Palworld Operator

Spin up a Palworld dedicated server on Kubernetes with one CR. You declare a PalworldServer; the operator builds Deployment, PVC, services, and Envoy Gateway exposure around the official Pocketpair image.

Congrats to Pocketpair on Palworld 1.0 — 1.0 announcement · Steam.

Site: dataknifeai.github.io/palworld-operator · Operator image: harbor.dataknife.net/library/palworld-operator

How it works

flowchart LR
  CR["PalworldServer CR"] --> Op["Operator"]
  Op --> Stack["Deployment · PVC · Services<br/>ConfigMap · Secret"]
  Stack --> EG["Envoy Gateway"]
  EG --> Players["Players"]

Loading

• Default game image: ghcr.io/pocketpairjp/palserver
• Credentials: bring-your-own Secret refs, or set spec.generateSecrets: true
• No cluster? Same official image via Docker Compose (make compose-up)

Full resource layout: docs/ARCHITECTURE.md.

Local / minimal PC (no Kubernetes)

cp compose/.env.example compose/.env   # set SERVER_PASSWORD / ADMIN_PASSWORD
make compose-up
# Join Multiplayer Game → 127.0.0.1:8211
# Server Manager → http://127.0.0.1:8088 (admin + ADMIN_PASSWORD)
make compose-down

Details (RAM, ports, LAN, mods drop path, what needs Kubernetes): docs/LOCAL.md.

Quick start (Kubernetes)

Prerequisites: Kubernetes 1.28+, Envoy Gateway (GatewayClass envoy), a StorageClass for saves, and one dedicated external IP per server (spec.gateway.address).

# Optional: bring-your-own credentials (skip if using spec.generateSecrets: true)
kubectl -n game-servers create secret generic palworld-server-secrets \
  --from-literal=admin-password='CHANGE_ME_ADMIN' \
  --from-literal=server-password='CHANGE_ME_JOIN'

kubectl apply -k config/default
kubectl apply -f config/samples/palworld_v1alpha1_palworldserver.yaml
kubectl get palworldserver -n game-servers

Connect with .status.connectionAddress / .status.connectionPort (default 8211 UDP). The operator learns/seeds DedicatedServerName from REST worldguid (or spec.dedicatedServerName) so Recreate rolls keep the world. Opt-in image auto-update: spec.update.autoUpdateImage (see docs/PALWORLD_SERVER.md). Admin API is REST (category); Pocketpair has deprecated RCON. The operator uses REST announce + admin basic auth and does not issue RCON commands. Read join/admin passwords from the credentials Secret (docs/CONNECT.md):

kubectl get secret palworld-server-secrets -n game-servers \
  -o jsonpath='{.data.server-password}' | base64 -d; echo

Tune the sample CR for VIP, StorageClass, and resources — BYO Secret or generateSecrets: true.

Game settings (spec.optionSettings)

spec.optionSettings is a passthrough map[string]string of PalWorldSettings.ini OptionSettings keys. Pocketpair’s list is the source of truth — this repo does not copy it.

Reserved keys (ServerName, passwords, ports, RCON/REST, CrossplayPlatforms) come from dedicated CR fields and override the same keys in the map. Never put passwords here.

spec:
  optionSettings:
    bExistPlayerAfterLogout: "True"   # sleep in-place on logout

Apply: merge-patch the CR, wait for the ConfigMap, then roll the game Deployment so seed-settings re-copies the INI onto the PVC. The world save stays intact (do not delete the CR/PVC). Details: PALWORLD_SERVER.md.

Mods (Linux vs Windows)

Palworld Server does load community pak files. Only .pak is supported. Pocketpair mods (official Workshop / PalModSettings.ini / -workshopdir) plus UE4SS, Lua, and Win64 DLLs are not supported. Both the client and the server must have the mod installed; mods typically align to PC players. Opt-in spec.mods mounts a PVC plus community .pak overlays (Paks/~WorkshopMods, LogicMods). Optional spec.serverManager (spec.modManager alias) adds an authenticated Server Manager on the Gateway VIP (HTTPS :443, HTTP :8088 redirects): world stats (kick/ban), REST controls (Save & restart), Updates (image / Check now / Save & force update), save download/restore, Mods, and Settings (profile + optionSettings + credential rotate). It is not enabled on the sample live CR. REST stays on the pod — the UI proxies it. Client join policy is spec.optionSettings.bAllowClientMod only. Details: PALWORLD_SERVER.md · site § Server Manager.

Teardown (deletes the world PVC if the sample uses Delete reclaim — do not run this to change settings):

kubectl delete palworldserver palworld-server -n game-servers

Docs

Doc	Contents
docs/FAQ.md	Incapable version, passwords, world pin, optionSettings, Linux mods, updates, RCON vs REST, sizing
docs/LOCAL.md	Docker Compose — local / minimal PC
docs/CONNECT.md	In-game join, passwords, community, crossplay
docs/ARCHITECTURE.md	Owned resources, Gateway layout
docs/PALWORLD_SERVER.md	Ports, REST vs deprecated RCON, mounts, optionSettings, Linux vs Windows mods, optional Server Manager, Steam updates
docs/GITLAB_MIRROR.md	GitHub CI + GitLab Harbor publish
CHANGELOG.md	Release notes / known gaps

Development

Go 1.25+ and golangci-lint. Common targets: make generate manifests, make test, make lint, make ci, make build. See docs/GITLAB_MIRROR.md and TASKS.md.

License

Apache License 2.0 — see LICENSE. Maintained by DataKnifeAI.