[mfw78]

Why

The operator docs cover a run from source and Docker Compose. This adds the third common way to run the engine: a Kubernetes cluster, from the published image.

What changed

• deploy/kubernetes/ is a Kustomize base with two objects: a StatefulSet (one replica, one 2 GiB state volume) and a headless Service for the metrics listener.
• The pod runs as the image's shepherd user (id 999) with a read-only root file system, no capabilities and no service account token, so it agrees with the restricted Pod Security level. It has HTTP probes on /healthz and /readyz, the prometheus.io/* scrape annotations, and a termination grace period of 180 seconds, which is longer than the engine's 150 second drain.
• The base does not create the engine config ConfigMap or the RPC URL Secret. docs/deployment/kubernetes.md shows how to make them from engine.docker.toml, how to pin the image and the StorageClass in an overlay, how to read metrics, and how to stop and upgrade.
• README.md lists the new directory and the new guide.

No Rust code changes.

Verification

The base was applied to a local kind cluster (Kubernetes 1.36), in a namespace with pod-security.kubernetes.io/enforce=restricted, with an image built from the tree of #696 and a mainnet node:

• The pod went 1/1 Running. /readyz answered ready: true with both modules alive, and /metrics had nexum_runtime_start_time_seconds.
• Inside the container the user was 999, the root file system refused a write, and the state volume held local-store.redb.
• After kubectl delete pod, the engine wrote graceful shutdown complete. The new pod opened each event trigger at its cursor and did no backfill.
• The overlay of the guide renders with kubectl kustomize, with the image pin and the StorageClass patch, against this branch by commit.

Worth a second look

• Not tested: a network volume, a default-deny network policy, and a collector that scrapes by annotation. The guide says so. These get their first run in the soak deployment, and the "What is tested" list can gain a line after that.
• The user id 999 comes from useradd -r in the Dockerfile, which does not name an id. The manifest names 999 because Kubernetes refuses runAsNonRoot with a non-numeric image user. A later change could set the id explicitly in the Dockerfile so that the two cannot drift.
• CI does not render or apply the manifests.

AI Assistance: Claude Code used for the manifests, the guide and the test run.