.nornir/unfold-guide.md

unfold — guide

Class: guide · audience: an operator provisioning a target. The what is in unfold-design.md; the why in unfold-reasoning.md.

The plan-first workflow

Every backend lets you render the provisioning artifact without the external tool, then drive it. Render first, inspect, then run.

KVM (local test)

use skidbladnir::unfold::{Unfold, kvm::{KvmTarget, kvm_available}};

let vm = KvmTarget::new("my-vm", "/var/lib/vms/my-vm.qcow2");
println!("{:?}", vm.qemu_argv());        // inspect the exact qemu argv (pure)
if kvm_available() { vm.unfold()?; }     // boots qemu, or bails honestly if absent

libvirt (pure-Rust, no virsh)

use skidbladnir::unfold::{Unfold, libvirt::LibvirtTarget};

let t = LibvirtTarget::new("kvm-host.internal", "my-vm", "/var/lib/libvirt/images/my-vm.qcow2")
    .resources(4096, 4);
println!("{}", t.connect_uri());         // qemu+tcp://kvm-host.internal/system
println!("{}", t.domain_xml());          // the domain XML (pure)
t.unfold()?;                             // define + create over RPC (needs a TCP host)
// … later …
t.teardown()?;                          // destroy + undefine

Redfish (bare-metal BMC, feature `redfish`)

# #[cfg(feature = "redfish")] {
use skidbladnir::unfold::{Unfold, redfish::RedfishTarget};
let t = RedfishTarget::new("https://bmc.internal", "admin", secret, "http://seed/boot.iso");
t.unfold()?;   // insert virtual media → boot from CD → force restart
# }

Without the redfish feature the same unfold() returns a clear error naming the missing feature — the pure body/path builders still work for testing.

Terraform (cloud/VM, feature `terraform`)

use skidbladnir::unfold::terraform::{TerraformTarget, render_config, write_config};

let t = TerraformTarget::new("prod", "holger").count(3);
println!("{}", render_config(&t));       // the full main.tf (pure — no binary needed)
let path = write_config(&work_dir, &t)?; // writes main.tf

# #[cfg(feature = "terraform")] {
use skidbladnir::unfold::Unfold;
t.unfold()?;                             // terraform init + apply -auto-approve
skidbladnir::unfold::terraform::destroy(&work_dir)?;   // teardown
# }

Gotchas

Pure builders always work; the drive may not. qemu_argv, domain_xml, render_config, and the Redfish bodies render with no tool installed — that is your dry-run/plan. Only unfold() executes.
libvirt needs a TCP host (qemu+tcp://…); an empty host (local unix socket) is a follow-up, so unfold() bails if you pass no host.
Redfish and Terraform are cargo features; a lean build's unfold() bails honestly rather than linking reqwest / shelling terraform.