VM lifecycle operations

Let authorized operators start, stop, and reboot virtual machines from Renga, where they already see each VM, its hypervisor, and its guest. RFD 1 names VM lifecycle as a later control slice; RFD 11 makes VMs observable read-only. This RFD adds the operations on RFD 9's jobs, with the installation credentials from RFD 13.

Live migration and placement are deliberately later: they need capacity and affinity modeling that this RFD does not attempt.

vm.power@1 is an operate capability on hypervisor installations running the RFD 11 libvirt module. Its action parameter is one of:

start, shutdown, and force_off converge to a requested power state: asking to start a running VM succeeds and records that nothing changed. reboot and reset are imperative, non-idempotent actions; a running state before and after does not prove whether either action occurred. The job’s result records the VM’s state before and after from libvirt and whether the action’s outcome is known.

Each operation has a stable identity (the job ID) across delivery attempts, bound to its approved target and action. The agent durably records execution intent before invoking libvirt and retains known outcomes for duplicate deliveries. This prevents ordinary duplicate execution, but cannot atomically commit an external libvirt effect with the execution record.

This extends RFD 9's retry contract: lease loss for reboot or reset must not automatically requeue execution. A crash or lost completion after execution may have begun records an uncertain outcome (an explicit job outcome/event), not success or a safe-to-retry failure. Reconciliation or operator investigation must resolve it; a new attempt requires a new explicitly authorized operation. Neither an expired lease nor a durable started marker proves no effect occurred. Convergent actions may retry only against the same valid target after checking current state and authorization; no retry crosses a changed binding.

A VM’s envelope gains a desired power state. Requesting an operation records the desired state and creates the job. The VM’s observed state keeps coming from RFD 11 evidence. When the two disagree for longer than the VM’s freshness window, Renga opens a power-state drift finding.

The first release does not enforce desired state automatically. A VM that is shut down from inside the guest raises drift for an operator to resolve; Renga does not restart it on its own.

An operation requires all of these:

The RFD 13 trusted binding includes the VM resource ID, provider installation and approved key, collector ID, hypervisor identity, and libvirt domain UUID. Shared-key VM correlation or placement evidence cannot approve or redirect this binding. Migration or a provider change requires trusted rebinding and fresh authorization, not automatic retargeting of queued work. For active operations, fresh unambiguous placement must agree with the binding. Starting an inactive VM requires a fresh definition on the explicitly approved provider, not arbitrary selection among hosts that retain its definition.

force_off and reset also require a reason and a confirmation that names the VM. An organization may require a second operator’s approval for them: the job waits in queued until someone else with a grant approves it, or it expires.

Before any request, Renga shows a preview with the VM, its hypervisor, current observed state, whether a guest agent is reporting from it, and the resources that list it as a dependency. The preview captures the approved target binding and version with the action. Dispatch and the agent revalidate that target and current domain state immediately before execution. Changed binding, stale or ambiguous placement, or a conflicting state requires a new preview and approval, never silently changing the provider or VM the operator confirmed.

Every request, approval, job event, and resulting state change appears in the VM’s activity and the organization feed. Desired-state changes are ordinary change events, so the record shows who wanted the VM off and when it actually went off.

Progress is tracked in the implementation checklist.