k3sm

Example: A Durable-Execution Server


The temporalio/temporal image (project site) is an open-source durable-execution service: a gRPC frontend, a history and matching engine, a worker service and a Web UI over a SQL store. It ships as linux/arm64 container images, so on k3sm it runs under the vm RuntimeClass, with each Pod in its own micro-VM on Virtualization.framework, while the node stays an ordinary Mac.

That combination is the point of this example. The server is a Linux system running on your Mac, and the client is the native macOS temporal binary from Homebrew, talking to it over a Service.

Requirements: Apple Silicon, macOS 26+, a running k3sm cluster (Quickstart), a node that advertises k3sm.io/virtualization, and network access to pull images from a public OCI registry.

The vm RuntimeClass runs unmodified linux/arm64 images in a per-Pod micro-VM. Read Linux images and Limitations for what it supports today.

What It Stands Up#

ObjectWhat it is
Pod temporaltemporalio/temporal, running temporal server start-dev (the server, SQLite persistence and the Web UI in one process)
Service temporal-frontendNodePort: gRPC 7233 on node port 30733, Web UI 8233 on node port 30823
Pod temporal-ui (optional)temporalio/ui, the standalone Web UI server, reaching the frontend through its Service
Service temporal-ui (optional)NodePort: 8080 on node port 30808

Both manifests are in examples/temporal/. The optional pair is a second file you can skip: the dev server already serves a Web UI.

A vm Pod runs one image. Every container in it shares one root filesystem, so a Pod naming two images runs the second container’s command against the first container’s image. The service’s production shape, with server, datastore and UI as separate images, must therefore be separate Pods here. The dev server collapses the service into a single image, which is why the one-Pod form is the simplest one.

1. Check the Node Can Run a Micro-VM#

kubectl get nodes -L k3sm.io/virtualization

A node without that label cannot run a vm Pod, and the Pod stays Pending. If the Mac is capable but the label is missing, the capability was probed at daemon start; see Linux images.

2. Apply the Server#

kubectl apply -f examples/temporal/temporal-dev-server.yaml
kubectl get pod temporal -o wide
kubectl wait --for=condition=Ready pod/temporal --timeout=10m

The first start pulls a multi-arch image and boots a guest; later starts reuse the cached image. Watch the server come up with:

kubectl logs -f temporal

3. Drive It From Inside the Cluster#

The image ships the temporal CLI as its entrypoint, so the fastest check needs no networking at all:

kubectl exec -it temporal -- temporal operator cluster health
kubectl exec -it temporal -- temporal operator namespace list

kubectl exec reaches into the guest directly. Use it whenever you want to separate “is the server healthy?” from “can I reach the server?”.

4. Connect the macOS-Native temporal CLI#

Install the CLI as a native arm64 binary and point it at the node port:

brew install temporal

temporal --address 127.0.0.1:30733 operator cluster health
temporal --address 127.0.0.1:30733 operator namespace list

Set it once for the shell instead of repeating the flag:

export TEMPORAL_ADDRESS=127.0.0.1:30733
temporal workflow list

Dial the Service, never the Pod. A NodePort answers on 127.0.0.1 and the node’s own address, and on every interface the Mac has once you run sudo k3sm network lan on (new installs start with LAN access off). k3sm’s userspace Service proxy is what carries the connection into the guest. A vm Pod’s pod IP is its published cluster identity rather than a live address, so kubectl get pod -o wide gives you an address that nothing answers on, as do headless Services and per-Pod DNS names. From inside the cluster, use the Service’s DNS name instead, fully qualified:

temporal-frontend.default.svc.cluster.local:7233

Fully qualified matters inside a vm Pod, because a guest’s resolver may ignore the search list.

5. Open the Web UI#

The dev server serves the UI itself:

open http://127.0.0.1:30823

For the multi-Pod shape, where a separate UI server image reaches the frontend over the network the way a production deployment is arranged, apply the optional manifest as well:

kubectl apply -f examples/temporal/temporal-web-ui.yaml
kubectl wait --for=condition=Ready pod/temporal-ui --timeout=10m
open http://127.0.0.1:30808

That Pod is a second Linux guest consuming the first one through cluster DNS and a Service.

6. Run a Workflow#

A workflow needs a worker, which is your own code using one of the service’s SDKs. Run it as a native macOS process against the same address the CLI uses:

export TEMPORAL_ADDRESS=127.0.0.1:30733

Every SDK takes that host and port when it builds a client (the Go SDK’s client.Dial with HostPort, the Python and TypeScript SDKs’ address/target_host). Start from the project’s own samples and change only the address. Once a worker is polling a task queue, start a workflow from the CLI:

temporal workflow start --type YourWorkflow --task-queue YourTaskQueue --workflow-id demo-1
temporal workflow list
temporal workflow describe --workflow-id demo-1

Nothing about the worker is k3sm-specific. It is a normal macOS process talking to a normal frontend that happens to be a Linux Pod on the same machine.

7. Tear It Down#

kubectl delete -f examples/temporal/temporal-web-ui.yaml --ignore-not-found
kubectl delete -f examples/temporal/temporal-dev-server.yaml

Deleting the Pod destroys its guest, and with it the workflow history, because the example keeps state in memory. Nothing is left on disk beyond the cached image.

Things to Know#

  • This is a development server. temporal server start-dev relaxes checks that a production deployment enforces, and it is a single instance with no replication. It is the right shape for a demo, a local integration test or a CI job, and not for production traffic.
  • Persisting workflow state means adding --db-filename /data/temporal.db and mounting a PersistentVolumeClaim at /data. PVC storage works on the vm path, with ceilings worth reading first: a foreign runAsUser or fsGroup is refused at admission, hostPath is refused outright, the host volume is case-insensitive, and an unprivileged k3sm server needs --pod-root before any PVC binds. See Storage and Limitations.
  • Probes must be exec probes. httpGet, tcpSocket and gRPC probes are dialed at the published pod IP, which a vm Pod does not answer; only exec reaches into the guest.
  • A container restart recreates the whole VM. There is no in-guest supervisor, because the container is the guest. The recreate is fast, and a crash-loop behaves as it would anywhere else.
  • Resources size the guest. The containers’ memory limits are summed into the guest’s RAM ceiling, and their CPU limits are summed and rounded up to whole vCPUs. Raising the limits gives the server a bigger machine.
  • NetworkPolicy will not isolate this. It is enforced only on Service-mediated ingress and cannot yet name a vm Pod as an allowed traffic source. Treat it as a hint, not a boundary (Limitations).
  • Keep it on one node. Cross-node traffic to or from a vm Pod is out of scope for this release, so run the server and anything in-cluster that talks to it on the same Mac.

Next#

  • Linux images, the RuntimeClass this example runs on.
  • Limitations, the measured ceilings referenced throughout.
  • Supported workloads, which workloads run natively and which need a guest.
  • Images, how images are pulled, cached and selected per platform.