> For the complete documentation index, see [llms.txt](https://kubevirtlegacy.gitbook.io/user-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kubevirtlegacy.gitbook.io/user-guide/docs/virtual_machines/lifecycle.md). # Lifecycle Every `VirtualMachineInstance` represents a single virtual machine *instance*. In general, the management of VirtualMachineInstances is kept similar to how `Pods` are managed: Every VM that is defined in the cluster is expected to be running, just like Pods. Deleting a VirtualMachineInstance is equivalent to shutting it down, this is also equivalent to how Pods behave. ## Launching a virtual machine In order to start a VirtualMachineInstance, you just need to create a `VirtualMachineInstance` object using `kubectl`: ``` $ kubectl create -f vmi.yaml ``` ## Listing virtual machines VirtualMachineInstances can be listed by querying for VirtualMachineInstance objects: ``` $ kubectl get vmis ``` ## Retrieving a virtual machine definition A single VirtualMachineInstance definition can be retrieved by getting the specific VirtualMachineInstance object: ``` $ kubectl get vmis testvmi ``` ## Stopping a virtual machine To stop the VirtualMachineInstance, you just need to delete the corresponding `VirtualMachineInstance` object using `kubectl`. ``` $ kubectl delete -f vmi.yaml # OR $ kubectl delete vmis testvmi ``` > Note: Stopping a VirtualMachineInstance implies that it will be deleted from the cluster. You will not be able to start this VirtualMachineInstance object again. ## Pausing and unpausing a virtual machine > Note: Pausing in this context refers to libvirt's `virDomainSuspend` command:\ > "The process is frozen without further access to CPU resources and I/O but the memory used by the domain at the hypervisor level will stay allocated" To pause a virtual machine, you need the `virtctl` command line tool. Its `pause` command works on either `VirtualMachine` s or `VirtualMachinesInstance` s: ``` $ virtctl pause vm testvm # OR $ virtctl pause vmi testvm ``` Paused VMIs have a `Paused` condition in their status: ``` $ kubectl get vmi testvm -o=jsonpath='{.status.conditions[?(@.type=="Paused")].message}' VMI was paused by user ``` Unpausing works similar to pausing: ``` $ virtctl unpause vm testvm # OR $ virtctl unpause vmi testvm ``` ## Renaming a Virtual Machine > Note: Renaming a Virtual Machine is only possible when a Virtual Machine is stopped, or has a 'Halted' run strategy. ``` $ virtctl rename vm_name new_vm_name ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://kubevirtlegacy.gitbook.io/user-guide/docs/virtual_machines/lifecycle.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.