cozystack/packages/apps/vm-instance

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:

• KubeVirt User Guide - Virtctl Client 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	""
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	Resource name of the GPU to request directly.	string	""
gpus[i].device	GPUDevice in this namespace to attach.	string	""
gpus[i].deviceTemplate	GPU device to order for this VM while it runs.	object	{}
gpus[i].deviceTemplate.className	GPUClass to order the device from.	string	""
gpus[i].deviceTemplate.count	GPUs of the class, all on one node.	int	0
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