> For the complete documentation index, see [llms.txt](https://docs.platform9.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.platform9.com/private-cloud-director/virtualized-clusters/virtualmachine.md).
# Virtual Machines
A virtual machine, or a VM, is a software-based representation of a physical computer. A VM allows you to run an operating system and applications using the resources of a host machine or a hypervisor, acting like a separate, isolated computer with its own virtual CPU, memory, storage, and network capabilities, all managed by the hypervisor.
You can create a virtual machine by first [populating an image in the image library](/private-cloud-director/images-and-image-library/image-library---images.md), then creating one or more VM flavors, and then creating a new VM.
## VM Flavors
Once you have the images you would like to use, it's time to look at the resource configuration for the VMs to be deployed. space.vars.product\_name uses T-shirt-sized configurations of resource allocations, called Flavors, to allow you to specify the resource allocation for VMs. Read more about [VM Flavors](/private-cloud-director/virtualized-clusters/virtualmachine/vm-flavors.md) here.
## VM Affinity and Anti-affinity Rules
space.vars.product\_name supports the creation of VM affinity and anti-affinity groups using a mechanism called Server Groups. Read more about [VM Affinity Anti-Affinity Rules](/private-cloud-director/virtualized-clusters/virtualmachine/vm-affinity-anti-affinity-rules.md) here.
## QEMU Guest Agent
For guests that have it installed and enabled, space.vars.product\_name uses the QEMU Guest Agent for filesystem-consistent (application-consistent on Windows) snapshots, agent-based admin password reset, and guest clock sync. Read more about the [QEMU Guest Agent](/private-cloud-director/virtualized-clusters/virtualmachine/qemu-guest-agent.md) here.
## Transfer a VM to Another Tenant
An Admin can move a VM, along with its attached volumes and network ports, to a different tenant. Read more about [Transfer a VM to Another Tenant](/private-cloud-director/virtualized-clusters/virtualmachine/vm-tenant-transfer.md) here.
## Create a VM
By now, you have your desired VM image, your preferred Flavor, and you have previously setup at least one Network that you can use to deploy your VM. So navigate to Virtual Machines in the Navigation pane and start 'Deploy Virtual Machine'.
Every VM is created into a target virtualized cluster, and assigning that cluster is required, not optional. The cluster also scopes where VM HA can evacuate the VM later, so a VM without a cluster assignment is not confined to its original cluster during a recovery. See [Virtual Machine High Availability (VM HA)](/private-cloud-director/virtualized-clusters/virtualized-cluster/virtual-machine-high-availability-vm-ha.md).
We will describe some of the VM creation options here.
### VM source
{% hint style="warning" %}
**Warning**
This is an important selection that affects where your virtual machine disk is stored, and whether the VM will be using [Ephemeral Storage](/private-cloud-director/storage/ephemeral-storage.md) or [Block Storage](/private-cloud-director/storage/block-storage.md)
{% endhint %}
#### Boot VM from Image
Use this option to provision a VM that uses [Ephemeral Storage](/private-cloud-director/storage/ephemeral-storage.md) for its root disk. This storage option is typically used for non-production VMs where the disk need not be preserved across host failures or VM deletion. The VM root disk will be created using local storage on the hypervisor on which it is provisioned and populated with the contents of the source image. If the hypervisor were to go down, it would not be possible to access or recover the VM disk till the hypervisor comes back online. If the host's local disk experiences corruption or other issues, the VM may be impacted and may be unrecoverable. If the VM were to be deleted, the VM's root disk would be deleted along with it and would not be recoverable afterward.
#### Boot VM from New Volume
Use this option if you would like to create a VM that uses [Block Storage](/private-cloud-director/storage/block-storage.md) volume for its root disk. A VM created in this manner will persist across host failures and VM termination, unless you choose to delete the volume when the VM terminates. When you choose this option, a new persistent volume is created on the block storage you configured for your virtualized cluster, and its contents are populated from the source image.
#### Boot VM from Existing Volume
This option is like the previous one, except that you choose to boot from an existing volume rather than provisioning a new volume from a base image.
#### Install OS from ISO Wizard
You can now create Windows and Linux VMs directly from installation ISOs through the **Deploy New VM** wizard in the UI. This replaces the previous CLI-only workflow documented in the [Windows](/private-cloud-director/tutorials/create-windows-vm-from-iso/creating-a-windows-virtual-machine--vm--from-an-iso-image4io.md) and [Ubuntu](/private-cloud-director/tutorials/deploy-a-virtual-machine-using-an-ubuntu-iso-image.md) tutorials.
**To install an OS from an ISO:**
1. In the **Deploy New VM** wizard, select **Install from ISO** from the **Boot VM From** dropdown.
2. Select an installation ISO from your image library and set the **Root Volume Size**. A new volume of the specified size will be created for the OS installation.
3. (Optional) For Windows installs, enable **Drivers ISO** and select the VirtIO drivers ISO for optimal performance.
4. Complete the remaining steps (optionally attach additional volumes, select a flavor, configure networking, customize VM) and click **Deploy Virtual Machine**.
5. Connect to the VM console and complete the OS installation. The VM is configured with a boot order of boot volume first, then ISO, so once the OS installer finishes and the VM reboots, it will automatically boot from the installed disk.
**Notes:**
* Only zero-disk flavors are supported, since the root disk is provided by the volume created in step 2. The VM disk size will equal the volume size.
* Bulk VM creation is not supported when installing from an ISO.
* The installation ISO can remain attached to the VM after installation. It will not interfere with boot because of the boot order, and it remains in the image library. You can detach it manually if you prefer.
#### Guest OS hostname
By default, the value you enter in the **Name** field is used both as the VM's display name in Private Cloud Director and as the guest OS hostname. To set a hostname that differs from the VM name, use the **Guest OS Hostname (Optional)** field in the **Basic VM Info** section. This is useful when you want a descriptive VM name for tracking and reporting, paired with a shorter, standards-compliant hostname inside the OS.
If you leave the **Guest OS Hostname (Optional)** empty, the **VM** **Name** is used as the guest OS hostname.
When you deploy more than one VM in a single operation, Private Cloud Director appends a numeric suffix to the hostname so that each VM has a unique name, using the same pattern as VM names.
If you set a value in **Guest OS Hostname (Optional)** and also include a cloud-init script that sets the hostname, the cloud-init script takes precedence. Use only one method to set the hostname to avoid unexpected behavior.
### Networks Available for the Selected Cluster
The **Networking** step of the **Deploy New VM** wizard lists only the networks that the cluster you selected can use. This prevents you from attaching a VM to a network its cluster cannot reach, which previously caused the VM to fail to create after you submitted the wizard.
Overlay networks, such as VXLAN networks, are available to any cluster and always appear in the list.
If you change the selected cluster after choosing networks, the wizard clears your previous network and subnet selections, so you do not carry over networks the new cluster cannot use. Reselect networks for the new cluster before continuing.
If no networks are available for the selected cluster, the **Networking** step shows the message **No networks available for the selected cluster**. Because a network is required, assign a usable network to the cluster or select a different cluster before continuing.
### Assign Custom Volume Names via API
By default, a volume that the Compute Service creates as part of provisioning a VM (from an image, from a volume snapshot, or from a VM snapshot) gets a system-generated name. The VM creation API accepts an optional `volume_names` field in the request body, letting you assign a custom name to each volume created for that VM.
{% hint style="info" %}
**No UI or pcdctl equivalent yet**
There is no UI or `pcdctl` option for this today. Call the Compute Service REST API directly to assign volume names during VM creation.
{% endhint %}
`volume_names` requires Compute API microversion 2.94 or later. Include the `OpenStack-API-Version: compute 2.94` header on the request, as shown in the examples below; without it, the API rejects the field.
`volume_names` is a map of a source identifier to the volume name you want. Which identifier you use as the key depends on how the volume is created:
* **Booting from a new volume created from an image:** use the image ID from the corresponding `block_device_mapping_v2` entry as the key.
* **Creating a VM from a volume snapshot:** use the volume snapshot ID from the corresponding `block_device_mapping_v2` entry as the key.
* **Creating a VM from a VM snapshot:** use each source volume snapshot ID that the VM snapshot expands into as the key. This applies when the original VM had more than one volume attached, so its snapshot restores into more than one volume.
**Example: Boot from a new volume, with a custom name for the boot volume**
```bash
curl -L \
--url 'https://example.platform9.com/nova/v2.1/servers' \
--header 'X-Auth-Token: YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--header 'OpenStack-API-Version: compute 2.94' \
--data '{
"server": {
"name": "vm-2",
"block_device_mapping_v2": [{
"source_type": "image",
"destination_type": "volume",
"boot_index": 0,
"delete_on_termination": true,
"uuid": "b1c21eef-ac4a-45cd-bb03-0ddaf1d3efe0",
"volume_size": 1,
"volume_type": "vt-nfs"
}],
"flavorRef": "c772132d-47ac-4345-8a99-a929c1666588",
"networks": [{"uuid": "c8788a6c-d3c5-4b08-a4c6-b7a2ce968474"}],
"availability_zone": "cluster1",
"volume_names": {"b1c21eef-ac4a-45cd-bb03-0ddaf1d3efe0": "new-vol-1"}
}
}'
```
**Example: Create a VM from a VM snapshot, naming each restored volume**
```bash
curl -L \
--url 'https://example.platform9.com/nova/v2.1/servers' \
--header 'X-Auth-Token: YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--header 'OpenStack-API-Version: compute 2.94' \
--data '{
"server": {
"name": "vm-5",
"imageRef": "0a3c8a96-f653-4d46-a81a-92bf01152463",
"flavorRef": "c772132d-47ac-4345-8a99-a929c1666588",
"networks": [{"uuid": "c8788a6c-d3c5-4b08-a4c6-b7a2ce968474"}],
"availability_zone": "cluster1",
"volume_names": {
"18e6dede-ab62-4866-a721-53a4ee3a74e0": "new-vol-2",
"a006e9dc-2d4f-40cc-84cb-c74c8498ecf6": "new-vol-3"
}
}
}'
```
Here, `imageRef` points to the image created by the VM snapshot, and each key in `volume_names` is the ID of one of the volume snapshots that the VM snapshot expanded into.
**Example: Create a VM from a volume snapshot, with a custom name for the restored volume**
```bash
curl -L \
--url 'https://example.platform9.com/nova/v2.1/servers' \
--header 'X-Auth-Token: YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--header 'OpenStack-API-Version: compute 2.94' \
--data '{
"server": {
"name": "vm-2",
"block_device_mapping_v2": [{
"source_type": "snapshot",
"destination_type": "volume",
"boot_index": 0,
"delete_on_termination": false,
"uuid": "836ceb4c-e5cc-4e81-bc46-945426a005fe"
}],
"flavorRef": "c772132d-47ac-4345-8a99-a929c1666588",
"networks": [{"uuid": "c8788a6c-d3c5-4b08-a4c6-b7a2ce968474"}],
"availability_zone": "cluster1",
"volume_names": {
"836ceb4c-e5cc-4e81-bc46-945426a005fe": "new-vol-4"
}
}
}'
```
This option applies only to volumes created as part of VM provisioning. For a volume you already created or attached separately, use `pcdctl volume set --name ` instead.
### Choose a Specific Subnet
When the network you select has more than one subnet, the **Networking** step of the **Deploy New VM** wizard displays a **Subnet** column for each network row. The selector defaults to **Automatic**; expanding it lists each available subnet as ` ()`, for example, `192.0.0.0/5 (test)`. Select one to place the VM's network interface on that specific subnet. If you leave it on **Automatic**, the Networking Service chooses the subnet for you.
Choosing a specific subnet does not limit how many VMs you can create in a single operation. If, however, you switch a network's IP mode from **Automatic** to **Private IP** and enter a specific address, the wizard's **Customize VM** step restricts you to a single VM and shows:
> You can create only 1 VM when a specific port is selected from a network.
For dual-stack or other advanced port configurations, pre-create a port on the subnet you want and attach the port during the **Networking** step. See [Virtual Network](/private-cloud-director/virtualized-networking/networks-and-ports.md) and [Add Multiple Dual Stack Ports to a VM](/private-cloud-director/tutorials/create-dual-stack-port.md).
### SSH Key
Using SSH Keys is the recommended and secure method to access your VMs. To set up your SSH Key, navigate to **Virtual Machines** > **SSH Keys** in the navigation pane, and import your SSH Keys. See [SSH Keys](/private-cloud-director/virtualized-networking/ssh-keys.md) for the full procedure.
Once you have the key imported, you can select that key when creating a new VM.
### Select Server Group
Optionally select an [affinity or anti-affinity group](#vm-affinity-and-anti-affinity-rules) for this VM to be part of. This will impact the VM's placement on a host in your virtualized cluster.
You are not limited to choosing a server group at creation time — you can also add or remove a VM from a server group afterward. See [Manage Server Group Membership](/private-cloud-director/virtualized-clusters/virtualmachine/vm-affinity-anti-affinity-rules.md#manage-server-group-membership).
### Select a Failure Domain
If the target cluster is configured with [Stretched Clusters](/private-cloud-director/virtualized-clusters/stretched-clusters.md), the **Customize VM** step of the wizard includes a **Failure Domain** section. The **Failure Domain** dropdown defaults to **None (place anywhere in the cluster)**; selecting one of the cluster's two domains instead gives the VM a soft ("should") placement preference for that domain, not a hard pin. This section only appears for clusters that have failure domains configured. See [Stretched Clusters](/private-cloud-director/virtualized-clusters/stretched-clusters.md) for the full placement and failover behavior.
### Delete Additional Volumes on VM Deletion
When you attach additional volumes in the **Attach Volumes** step of the **Deploy New VM** wizard, you can enable the **Delete attached volumes on VM deletion** toggle. With it enabled, the additional volumes you selected are deleted along with the VM when the VM is deleted; with it disabled, those volumes remain after the VM is deleted. You can also choose this behavior later, from the **Delete VM** dialog. See [Delete VM](/private-cloud-director/virtualized-clusters/virtualmachine/virtual-machine-actions.md#delete-vm).
### Using cloud-init
Using cloud-init allows you to customize the virtual machine as it boots, such as provisioning additional software or custom scripts.
### Assign Security Groups
Security groups allow you to limit port access to Virtual Machines. If you don't already have a Security Group configured, you can cover this later.
### Specify Metadata
Metadata attributes allow you to specify additional key-value pairs, which can be used to query and organize your virtual machines.
{% hint style="success" %}
**Success**
With this information specified, you should see the VM provision within a few minutes. You can then access the VM over the network or via its console.
{% endhint %}
## VM Properties
### VM UUID
Each newly created virtual machine is assigned a unique UUID. By default, this field is not displayed in the virtual machines grid view in the UI. You can change this by clicking the 'Manage Columns' button above the virtual machines grid view and selecting the UUID field. You can also select an individual VM to open the VM details view and see the ID property listed there. Alternatively, you can get VM ID using the pcdctl CLI by running the `pcdctl server list` command or the `pcdctl server show` command and supplying the name of the VM.
### VM Owner
The virtual machines grid view can also show an **Owner** column, listing the user who created each VM. Click the 'Manage Columns' button above the grid view and select the **Owner** field to display it. This visibility is available to self-service users as well as admin users, so any user with access to the VM list can identify who owns each VM.
## Migrate Existing VMs from VMware
If you have existing workloads that you would like to migrate onto your space.vars.product\_name cluster, [Project vJailbreak](https://github.com/platform9/vjailbreak) can help.
### Download the vJailbreak Appliance
Head over to Project vJailbreak to download the appliance image. The appliance is packaged as an OVA that you can deploy into your space.vars.product\_name environment. Note that vJailbreak should have access to your storage network to efficiently migrate VM data over during the data copy phase.
### Register your Source VMware Environment and Your New Virtualized Cluster
As your vJailbreak appliance loads, you'll see instructions for accessing its user interface, where you can specify your source VMware environment information, as well as the information for your new cluster.
### Select VMs and Schedule Migrations
With this information specified, you can now initiate migrations from the vJailbreak user interface.
## Related Pages
* [Virtual Machine Snapshot](/private-cloud-director/virtualized-clusters/virtualmachine/virtual-machine-snapshot.md): how VM snapshots capture root and data volumes, relevant when naming volumes restored from a VM snapshot
* [Volume Snapshot](/private-cloud-director/storage/volume/volume-snapshot.md): creating and restoring point-in-time volume snapshots
* [Volume](/private-cloud-director/storage/volume.md): volume types, backends, and how volumes relate to volume snapshots
---
# 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://docs.platform9.com/private-cloud-director/virtualized-clusters/virtualmachine.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.