Skip to main content
User Data runs a shell script inside an Orka VM on its first boot. Use it to enroll a VM in MDM, register a CI agent, or apply host-specific configuration, against the same unmodified image every other VM uses. You don’t need to bake per-purpose scripts into your images or SSH into each VM after it deploys.

​
Before you begin

  • Your Orka cluster runs Orka 4.0 or later.
  • Your VMs run on Apple silicon nodes.
  • Your VM image runs the Orka 4.0 VM Tools, which ship with this release. See Orka VM Tools.

​
How the script runs

  • The script runs as root, in the background, on the first boot. The VM becomes available without waiting for it, so the VM is reachable while the script runs.
  • It runs once per VM. Orka records completion after the script finishes, whether it succeeds or fails, so a failed run doesn’t retry on the next boot.
  • If the VM reboots or stops while the script is running, the run hasn’t completed, and the script runs again on the next boot. Write scripts that are safe to run more than once.
  • There’s no timeout by default. To set one, set the ORKA_USERDATA_TIMEOUT environment variable inside the image.
  • The script’s output is written to /var/log/orka/userdata.log inside the VM.

​
Deploy a VM with User Data

Pass a path to a script file, which the CLI encodes for you, or a base64-encoded string:
Through the Orka API, pass the base64-encoded script in the userdata field of the VM deploy request.

​
Check the script status

Run orka vm list -o wide and check the USERDATA-PHASE column. The same value is returned as userdataPhase in API responses. The following table lists the possible phases. An empty value means the VM has no User Data, or the VM isn’t running. If your automation needs a signal that the VM is ready to use, wait for success, failed, skipped, or timeout. The VM reports the phase itself, through Orka VM Tools. Treat it as a progress signal, not proof that the work was done, and don’t use it as a security control. If the phase stays pending far longer than your script should take, check the Orka VM Tools version in your image. Older VM Tools never report a result, which looks the same as a script that’s still running.

​
Limitations

  • Apple silicon only.
  • 64 KiB maximum for the base64-encoded script. For a larger payload, use a small User Data script that downloads it.
  • New VMs only. Changing User Data doesn’t re-run the script on VMs that already ran it. Only newly deployed VMs pick up the new value.

​
Keep credentials safe

Orka never returns the script in API responses. However, anyone with Kubernetes-level read access to the VM’s VirtualMachineInstance resource or its pod can read the script. If other users or service accounts can read pods in your namespace, treat the script as visible to them:
  • Prefer short-lived credentials, such as MDM enrollment invitations.
  • Have the script fetch long-lived secrets from your own secret store.
  • Keep credentials out of the script’s output. Everything the script prints goes to /var/log/orka/userdata.log.
If you save or push an image from a VM that already ran its User Data, anything the original script printed to /var/log/orka/userdata.log travels with the image. The script itself isn’t saved in the image.

​
Images saved after User Data ran

An image saved or pushed from a VM that already ran its User Data also carries that VM’s run-once record. The record is tied to the deployment it ran in, so a VM deployed from the image still runs its own User Data.

​
Write reliable scripts

  • Make scripts idempotent. A reboot during the script makes it run again.
  • Wait for the network. The script starts early in boot. Retry, with a limit, before you call external services.
  • Exit non-zero on failure, so the failed phase reaches your automation.
  • Log progress, so /var/log/orka/userdata.log shows where a failed run stopped.