## What this PR does
A `vm-instance` boots from its disks in the order they appear in
`disks`: the template hardcodes `bootOrder: {{ add $i 1 }}`. Booting
from installer or rescue media, such as an ISO attached as a CD-ROM next
to the system disk, therefore means moving that media to the front of
the list, and anything that treats `disks[0]` as the system disk then
finds the ISO there instead.
This adds an optional `bootOrder` to each entry of `disks`:
- When set, it is the disk's boot priority (1 is tried first),
independent of its position in the list.
- When unset, the disk keeps its positional order (`index + 1`), so
existing VMs render exactly as before.
- The values schema requires `bootOrder >= 1`.
- Duplicate effective boot orders are refused at render time with the
names of both disks, rather than surfacing as a KubeVirt admission error
on the VirtualMachine. This includes an explicit value colliding with
another disk's positional one, so booting from a CD-ROM in second
position means setting both disks:
```yaml
disks:
- name: system
bootOrder: 2
- name: install-iso
bus: sata
bootOrder: 1
```
`make generate` was run in the package, so the README,
`values.schema.json`, the Go type in `api/apps/v1alpha1/vminstance`
(with its regenerated deepcopy, since the field is a pointer) and the
`vm-instance-rd` OpenAPI schema are all updated.
A new suite, `tests/disk_boot_order_test.yaml`, mocks the DataVolumes
the template looks up and covers: positional order when no disk sets
`bootOrder`; a CD-ROM in second position booting first while the list
order and volumes stay unchanged; an explicit value colliding with a
positional one; two equal explicit values; and a value below 1 rejected
by the schema. Run against the previous template, the CD-ROM and
collision cases fail. `helm unittest packages/apps/vm-instance`: 6
suites, 77 tests passing.
### Screenshots
No UI change.
### Downstream repositories
- [ ] No downstream repository is affected by this change
- [ ] [cozystack/website](https://github.com/cozystack/website) -
follow-up:
- [ ]
[cozystack/terraform-provider-cozystack](https://github.com/cozystack/terraform-provider-cozystack)
- follow-up:
- [ ]
[cozystack/ansible-cozystack](https://github.com/cozystack/ansible-cozystack)
- follow-up:
- [ ] [cozystack/ccp](https://github.com/cozystack/ccp) - follow-up:
- [ ] [cozystack/talm](https://github.com/cozystack/talm) - follow-up:
- [ ] [cozystack/cozyhr](https://github.com/cozystack/cozyhr) -
follow-up:
- [ ] [cozystack/cozy-proxy](https://github.com/cozystack/cozy-proxy) -
follow-up:
- [ ]
[cozystack/cozystack-telemetry-server](https://github.com/cozystack/cozystack-telemetry-server)
- follow-up:
- [ ]
[cozystack/external-apps-example](https://github.com/cozystack/external-apps-example)
- follow-up:
- [ ] [cozystack/examples](https://github.com/cozystack/examples) -
follow-up:
- [ ] [cozystack/community](https://github.com/cozystack/community) -
follow-up:
This adds a field to `vm-instance`'s `values.schema.json`, which the
trigger map routes to `cozystack/terraform-provider-cozystack`: its
`vminstance_schema.go` and `vminstance_model.go` model `disks` by hand,
so `bootOrder` needs adding there. The follow-up has not been opened yet
and the box is left blank until it is linked. The website reference page
is regenerated from the README by the release bot; nothing else in the
map is touched.
### Release note
```release-note
feat(virtual-machine): disks in a vm-instance accept an optional `bootOrder`, so a VM can boot from an attached ISO or other rescue media without reordering its disks. Unset keeps the previous positional boot order.
```
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->
## Summary by CodeRabbit
* **New Features**
* Configure a boot priority for each VM disk. Lower values are tried
first; disks without an explicit priority use their position in the disk
list.
* Disk priorities must be unique, and values below 1 are rejected.
Priority changes do not reorder disks or their associated volumes.
* **Documentation**
* Added guidance and an example for configuring disk boot priorities.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Virtual Machine
A Virtual Machine (VM) simulates computer hardware, enabling various operating systems and applications to run in an isolated environment.
Deployment Details
The virtual machine is managed and hosted through KubeVirt, allowing you to harness the benefits of virtualization within your Kubernetes ecosystem.
- Docs: KubeVirt User Guide
- GitHub: KubeVirt Repository
Accessing virtual machine
You can access the virtual machine using the virtctl tool:
To access the serial console:
virtctl console <vm>
To access the VM using VNC:
virtctl vnc <vm>
To SSH into the VM:
virtctl ssh <user>@<vm>
Parameters
Common parameters
| Name | Description | Type | Value |
|---|---|---|---|
external |
Enable external access from outside the cluster. | bool |
false |
externalMethod |
Method to pass through traffic to the VM. | string |
PortList |
externalPorts |
Ports to forward from outside the cluster. | []int |
[22] |
externalAllowICMP |
Whether to accept ICMP traffic to the VM in PortList mode (preserves ping and PMTU discovery). No effect in WholeIP mode. Default true so ping behaves as users expect even when port filtering is in effect. | bool |
true |
runStrategy |
Requested running state of the VirtualMachineInstance | string |
Always |
instanceType |
Virtual Machine instance type. Ignored when resources sizes the VM, which needs whole-number cpu and sockets plus memory; the whole type is dropped then, so any dedicated CPU placement, hugepages, NUMA or realtime settings it carries go with it. While this field is set, a resources block that sizes only part of the VM is rejected outright instead of ignored, so complete it or clear it. |
string |
u1.medium |
instanceProfile |
Virtual Machine preferences profile. | string |
ubuntu |
disks |
List of disks to attach. | []object |
[] |
disks[i].name |
Disk name. | string |
"" |
disks[i].bus |
Disk bus type (e.g. "sata"). | string |
"" |
disks[i].bootOrder |
Boot priority of the disk, 1 being tried first. Unset falls back to the disk's position in disks (the first disk gets 1), so set it to boot from a disk other than the first, such as an attached installer or rescue ISO, without reordering the list. Effective boot orders must be unique across disks: when one disk is given a value that another takes from its position, set both. |
*int |
null |
networks |
Networks to attach the VM to. | []object |
[] |
networks[i].name |
Network attachment name. | string |
"" |
subnets |
Deprecated: use networks instead. | []object |
[] |
subnets[i].name |
Network attachment name. | string |
"" |
gpus |
List of GPUs to attach (NVIDIA driver requires at least 4 GiB RAM). | []object |
[] |
gpus[i].name |
The name of the GPU resource to attach. | string |
"" |
cpuModel |
Model specifies the CPU model inside the VMI. List of available models https://github.com/libvirt/libvirt/tree/master/src/cpu_map | string |
"" |
firmware |
Firmware and boot configuration (UEFI/BIOS selection, Secure Boot, persistent EFI NVRAM). | object |
{} |
firmware.bootloader |
Bootloader to boot the VM with: "uefi" (OVMF) or "bios" (SeaBIOS). Empty inherits the instanceProfile default. | string |
"" |
firmware.secureBoot |
Enable UEFI Secure Boot. Only applies when bootloader is "uefi". | bool |
false |
firmware.efiPersistent |
Persist EFI NVRAM (e.g. enrolled Secure Boot keys, such as an updated Microsoft UEFI CA) across reboots. Only applies when bootloader is "uefi". | bool |
false |
resources |
Resource configuration for the virtual machine. Set whole-number cpu and sockets together with memory to size the VM directly, which overrides instanceType. Alongside an instanceType, a block that sizes only part of the VM is rejected; a whole-number cpu or sockets on its own sizes nothing and is ignored. |
object |
{} |
resources.cpu |
Number of CPU cores allocated, as a positive whole number such as 2. Millicore or other unit-suffixed, fractional, zero, negative, above 4294967295 and quoted leading-zero values are rejected at render time, because the value becomes the VM's unsigned integer domain.cpu.cores. |
quantity |
"" |
resources.memory |
Amount of memory allocated, as a quantity of at least 1M such as 8Gi. Less than 1M is rejected at render time, because KubeVirt refuses a non-zero amount below 1M and a zero or negative amount sizes nothing. |
quantity |
"" |
resources.sockets |
Number of CPU sockets (vCPU topology), as a positive whole number such as 1. Millicore or other unit-suffixed, fractional, zero, negative, above 4294967295 and quoted leading-zero values are rejected at render time, because the value becomes the VM's unsigned integer domain.cpu.sockets. |
quantity |
"" |
sshKeys |
List of SSH public keys for authentication. | []string |
[] |
cloudInit |
Cloud-init user data. | string |
"" |
netplanDhcp |
Supply cloud-init network-data that requests DHCP on every en* and eth* interface and keeps the DNS search domains DHCP offers. Needed for a netplan guest (Ubuntu, Debian) to address a secondary network such as a VPC subnet. Leave it off for a guest rendered by anything other than netplan, which would lose DHCP on every interface, and for a guest that configures an interface statically through netplan, which this configuration would shadow. Turning it on for a VM that has neither cloudInit nor sshKeys adds a cloud-init disk, and the guest's next boot is then treated as a first boot. |
bool |
false |
cloudInitSeed |
Seed string to generate SMBIOS UUID for the VM. | string |
"" |
U Series
The U Series is quite neutral and provides resources for general purpose applications.
U is the abbreviation for "Universal", hinting at the universal attitude towards workloads.
VMs of instance types will share physical CPU cores on a time-slice basis with other VMs.
U Series Characteristics
Specific characteristics of this series are:
- Burstable CPU performance - The workload has a baseline compute performance but is permitted to burst beyond this baseline, if excess compute resources are available.
- vCPU-To-Memory Ratio (1:4) - A vCPU-to-Memory ratio of 1:4, for less noise per node.
O Series
The O Series is based on the U Series, with the only difference being that memory is overcommitted.
O is the abbreviation for "Overcommitted".
UO Series Characteristics
Specific characteristics of this series are:
- Burstable CPU performance - The workload has a baseline compute performance but is permitted to burst beyond this baseline, if excess compute resources are available.
- Overcommitted Memory - Memory is over-committed in order to achieve a higher workload density.
- vCPU-To-Memory Ratio (1:4) - A vCPU-to-Memory ratio of 1:4, for less noise per node.
CX Series
The CX Series provides exclusive compute resources for compute intensive applications.
CX is the abbreviation of "Compute Exclusive".
The exclusive resources are given to the compute threads of the VM. In order to ensure this, some additional cores (depending on the number of disks and NICs) will be requested to offload the IO threading from cores dedicated to the workload. In addition, in this series, the NUMA topology of the used cores is provided to the VM.
CX Series Characteristics
Specific characteristics of this series are:
- Hugepages - Hugepages are used in order to improve memory performance.
- Dedicated CPU - Physical cores are exclusively assigned to every vCPU in order to provide fixed and high compute guarantees to the workload.
- Isolated emulator threads - Hypervisor emulator threads are isolated from the vCPUs in order to reduce emaulation related impact on the workload.
- vNUMA - Physical NUMA topology is reflected in the guest in order to optimize guest sided cache utilization.
- vCPU-To-Memory Ratio (1:2) - A vCPU-to-Memory ratio of 1:2.
M Series
The M Series provides resources for memory intensive applications.
M is the abbreviation of "Memory".
M Series Characteristics
Specific characteristics of this series are:
- Hugepages - Hugepages are used in order to improve memory performance.
- Burstable CPU performance - The workload has a baseline compute performance but is permitted to burst beyond this baseline, if excess compute resources are available.
- vCPU-To-Memory Ratio (1:8) - A vCPU-to-Memory ratio of 1:8, for much less noise per node.
RT Series
The RT Series provides resources for realtime applications, like Oslat.
RT is the abbreviation for "realtime".
This series of instance types requires nodes capable of running realtime applications.
RT Series Characteristics
Specific characteristics of this series are:
- Hugepages - Hugepages are used in order to improve memory performance.
- Dedicated CPU - Physical cores are exclusively assigned to every vCPU in order to provide fixed and high compute guarantees to the workload.
- Isolated emulator threads - Hypervisor emulator threads are isolated from the vCPUs in order to reduce emaulation related impact on the workload.
- vCPU-To-Memory Ratio (1:4) - A vCPU-to-Memory ratio of 1:4 starting from the medium size.
Development
To get started with customizing or creating your own instancetypes and preferences see DEVELOPMENT.md.
Resources
The following instancetype resources are provided by Cozystack:
| Name | vCPUs | Memory |
|---|---|---|
| cx1.2xlarge | 8 | 16Gi |
| cx1.2xlarge1gi | 8 | 16Gi |
| cx1.4xlarge | 16 | 32Gi |
| cx1.4xlarge1gi | 16 | 32Gi |
| cx1.8xlarge | 32 | 64Gi |
| cx1.8xlarge1gi | 32 | 64Gi |
| cx1.large | 2 | 4Gi |
| cx1.large1gi | 2 | 4Gi |
| cx1.medium | 1 | 2Gi |
| cx1.medium1gi | 1 | 2Gi |
| cx1.xlarge | 4 | 8Gi |
| cx1.xlarge1gi | 4 | 8Gi |
| d1.2xlarge | 8 | 32Gi |
| d1.2xmedium | 2 | 4Gi |
| d1.4xlarge | 16 | 64Gi |
| d1.8xlarge | 32 | 128Gi |
| d1.large | 2 | 8Gi |
| d1.medium | 1 | 4Gi |
| d1.micro | 1 | 1Gi |
| d1.nano | 1 | 512Mi |
| d1.small | 1 | 2Gi |
| d1.xlarge | 4 | 16Gi |
| gn1.2xlarge | 8 | 32Gi |
| gn1.4xlarge | 16 | 64Gi |
| gn1.8xlarge | 32 | 128Gi |
| gn1.xlarge | 4 | 16Gi |
| m1.2xlarge | 8 | 64Gi |
| m1.2xlarge1gi | 8 | 64Gi |
| m1.4xlarge | 16 | 128Gi |
| m1.4xlarge1gi | 16 | 128Gi |
| m1.8xlarge | 32 | 256Gi |
| m1.8xlarge1gi | 32 | 256Gi |
| m1.large | 2 | 16Gi |
| m1.large1gi | 2 | 16Gi |
| m1.xlarge | 4 | 32Gi |
| m1.xlarge1gi | 4 | 32Gi |
| n1.2xlarge | 16 | 32Gi |
| n1.4xlarge | 32 | 64Gi |
| n1.8xlarge | 64 | 128Gi |
| n1.large | 4 | 8Gi |
| n1.medium | 4 | 4Gi |
| n1.xlarge | 8 | 16Gi |
| o1.2xlarge | 8 | 32Gi |
| o1.4xlarge | 16 | 64Gi |
| o1.8xlarge | 32 | 128Gi |
| o1.large | 2 | 8Gi |
| o1.medium | 1 | 4Gi |
| o1.micro | 1 | 1Gi |
| o1.nano | 1 | 512Mi |
| o1.small | 1 | 2Gi |
| o1.xlarge | 4 | 16Gi |
| rt1.2xlarge | 8 | 32Gi |
| rt1.4xlarge | 16 | 64Gi |
| rt1.8xlarge | 32 | 128Gi |
| rt1.large | 2 | 8Gi |
| rt1.medium | 1 | 4Gi |
| rt1.micro | 1 | 1Gi |
| rt1.small | 1 | 2Gi |
| rt1.xlarge | 4 | 16Gi |
| u1.2xlarge | 8 | 32Gi |
| u1.2xmedium | 2 | 4Gi |
| u1.4xlarge | 16 | 64Gi |
| u1.8xlarge | 32 | 128Gi |
| u1.large | 2 | 8Gi |
| u1.medium | 1 | 4Gi |
| u1.micro | 1 | 1Gi |
| u1.nano | 1 | 512Mi |
| u1.small | 1 | 2Gi |
| u1.xlarge | 4 | 16Gi |
The following preference resources are provided by Cozystack:
| Name | Guest OS |
|---|---|
| alpine | Alpine |
| centos.stream10 | CentOS Stream 10 |
| centos.stream10.desktop | CentOS Stream 10 |
| centos.stream9 | CentOS Stream 9 |
| centos.stream9.desktop | CentOS Stream 9 |
| centos.stream9.dpdk | CentOS Stream 9 |
| cirros | Cirros |
| debian | Debian |
| fedora | Fedora (amd64) |
| fedora.arm64 | Fedora (arm64) |
| fedora.s390x | Fedora (s390x) |
| legacy | Legacy Guest |
| linux | Linux Guest |
| linux.efi | Linux EFI Guest |
| linux.virtiotransitional | Linux Virtio Transitional Guest |
| opensuse.leap | OpenSUSE Leap |
| opensuse.tumbleweed | OpenSUSE Tumbleweed |
| oraclelinux | Oracle Linux |
| rhel.10 | Red Hat Enterprise Linux 10 (amd64) |
| rhel.10.arm64 | Red Hat Enterprise Linux 10 (arm64) |
| rhel.10.s390x | Red Hat Enterprise Linux 10 (s390x) |
| rhel.7 | Red Hat Enterprise Linux 7 |
| rhel.7.desktop | Red Hat Enterprise Linux 7 |
| rhel.8 | Red Hat Enterprise Linux 8 |
| rhel.8.desktop | Red Hat Enterprise Linux 8 |
| rhel.8.dpdk | Red Hat Enterprise Linux 8 |
| rhel.9 | Red Hat Enterprise Linux 9 (amd64) |
| rhel.9.arm64 | Red Hat Enterprise Linux 9 (arm64) |
| rhel.9.desktop | Red Hat Enterprise Linux 9 Desktop (amd64) |
| rhel.9.dpdk | Red Hat Enterprise Linux 9 DPDK (amd64) |
| rhel.9.realtime | Red Hat Enterprise Linux 9 Realtime (amd64) |
| rhel.9.s390x | Red Hat Enterprise Linux 9 (s390x) |
| sles | SUSE Linux Enterprise Server |
| ubuntu | Ubuntu |
| windows.10 | Microsoft Windows 10 |
| windows.10.virtio | Microsoft Windows 10 (virtio) |
| windows.11 | Microsoft Windows 11 |
| windows.11.virtio | Microsoft Windows 11 (virtio) |
| windows.2k12 | Microsoft Windows Server 2012/2012 R2 |
| windows.2k12.virtio | Microsoft Windows Server 2012/2012 R2 (virtio) |
| windows.2k16 | Microsoft Windows Server 2016 |
| windows.2k16.virtio | Microsoft Windows Server 2016 (virtio) |
| windows.2k19 | Microsoft Windows Server 2019 |
| windows.2k19.virtio | Microsoft Windows Server 2019 (virtio) |
| windows.2k22 | Microsoft Windows Server 2022 |
| windows.2k22.virtio | Microsoft Windows Server 2022 (virtio) |
| windows.2k25 | Microsoft Windows Server 2025 |
| windows.2k25.virtio | Microsoft Windows Server 2025 (virtio) |
| windows.2k3 | Microsoft Windows Server 2003 |
| windows.2k8 | Microsoft Windows Server 2008/2008 R2 |
| windows.2k8.virtio | Microsoft Windows Server 2008/2008 R2 (virtio) |
| windows.7 | Microsoft Windows 7 |
| windows.7.virtio | Microsoft Windows 7 (virtio) |
| windows.xp | Microsoft Windows XP |