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
vmRuntimeClass runs unmodifiedlinux/arm64images in a per-Pod micro-VM. Read Linux images and Limitations for what it supports today.
What It Stands Up#
| Object | What it is |
|---|---|
Pod temporal | temporalio/temporal, running temporal server start-dev (the server, SQLite persistence and the Web UI in one process) |
Service temporal-frontend | NodePort: 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/virtualizationA 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=10mThe 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 temporal3. 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 listkubectl 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 listSet it once for the shell instead of repeating the flag:
export TEMPORAL_ADDRESS=127.0.0.1:30733
temporal workflow listDial 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:7233Fully 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:30823For 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:30808That 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:30733Every 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-1Nothing 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.yamlDeleting 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-devrelaxes 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.dband mounting a PersistentVolumeClaim at/data. PVC storage works on thevmpath, with ceilings worth reading first: a foreignrunAsUserorfsGroupis refused at admission,hostPathis refused outright, the host volume is case-insensitive, and an unprivilegedk3sm serverneeds--pod-rootbefore any PVC binds. See Storage and Limitations. - Probes must be
execprobes.httpGet,tcpSocketand gRPC probes are dialed at the published pod IP, which avmPod does not answer; onlyexecreaches 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
vmPod 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
vmPod 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.