Skip to content

Commit 1128d6a

Browse files
ousleypousleyp
authored
Merge pull request #75235 from ousleyp/cnv-21150
CNV#21150: instance types API
2 parents 6367b5f + da945bb commit 1128d6a

11 files changed

+372
-184
lines changed

‎modules/virt-about-instance-types.adoc

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * virt/virtual_machines/creating_vms_rh/virt-creating-vms-from-instance-types.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="virt-about-instance-types_{context}"]
7+
= About instance types
8+
9+
An instance type is a reusable object where you can define resources and characteristics to apply to new VMs. You can define custom instance types or use the variety that are included when you install {VirtProductName}.
10+
11+
To create a new instance type, you must first create a manifest, either manually or by using the `virtctl` CLI tool. You then create the instance type object by applying the manifest to your cluster.
12+
13+
{VirtProductName} provides two CRDs for configuring instance types:
14+
15+
* A namespaced object: `VirtualMachineInstancetype`
16+
* A cluster-wide object: `VirtualMachineClusterInstancetype`
17+
18+
These objects use the same `VirtualMachineInstancetypeSpec`.
19+
20+
[id="required-attributes_{context}"]
21+
== Required attributes
22+
23+
When you configure an instance type, you must define the `cpu` and `memory` attributes. Other attributes are optional.
24+
25+
[NOTE]
26+
====
27+
When you create a VM from an instance type, you cannot override any parameters defined in the instance type.
28+
29+
Because instance types require defined CPU and memory attributes, {VirtProductName} always rejects additional requests for these resources when creating a VM from an instance type.
30+
====
31+
32+
You can manually create an instance type manifest. For example:
33+
34+
.Example YAML file with required fields
35+
[source,yaml]
36+
----
37+
apiVersion: instancetype.kubevirt.io/v1beta1
38+
kind: VirtualMachineInstancetype
39+
metadata:
40+
name: example-instancetype
41+
spec:
42+
cpu:
43+
guest: 1 <1>
44+
memory:
45+
guest: 128Mi <2>
46+
----
47+
<1> Required. Specifies the number of vCPUs to allocate to the guest.
48+
<2> Required. Specifies an amount of memory to allocate to the guest.
49+
50+
You can create an instance type manifest by using the `virtctl` CLI utility. For example:
51+
52+
.Example `virtctl` command with required fields
53+
[source,terminal]
54+
----
55+
$ virtctl create instancetype --cpu 2 --memory 256Mi
56+
----
57+
58+
where:
59+
60+
`--cpu <value>`:: Specifies the number of vCPUs to allocate to the guest. Required.
61+
`--memory <value>`:: Specifies an amount of memory to allocate to the guest. Required.
62+
63+
[TIP]
64+
====
65+
You can immediately create the object from the new manifest by running the following command:
66+
67+
[source,terminal]
68+
----
69+
$ virtctl create instancetype --cpu 2 --memory 256Mi | oc apply -f -
70+
----
71+
====
72+
73+
[id="optional-attributes_{context}"]
74+
== Optional attributes
75+
76+
In addition to the required `cpu` and `memory` attributes, you can include the following optional attributes in the `VirtualMachineInstancetypeSpec`:
77+
78+
`annotations`:: List annotations to apply to the VM.
79+
`gpus`:: List vGPUs for passthrough.
80+
`hostDevices`:: List host devices for passthrough.
81+
`ioThreadsPolicy`:: Define an IO threads policy for managing dedicated disk access.
82+
`launchSecurity`:: Configure Secure Encrypted Virtualization (SEV).
83+
`nodeSelector`:: Specify node selectors to control the nodes where this VM is scheduled.
84+
`schedulerName`:: Define a custom scheduler to use for this VM instead of the default scheduler.

‎modules/virt-adding-public-key-cli.adoc

Lines changed: 10 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -39,116 +39,29 @@ endif::[]
3939

4040
. Create a manifest file for a `VirtualMachine` object and a `Secret` object:
4141
+
42+
.Example manifest
4243
[source,yaml]
4344
----
44-
apiVersion: kubevirt.io/v1
45-
kind: VirtualMachine
46-
metadata:
47-
name: example-vm
48-
namespace: example-namespace
49-
spec:
50-
dataVolumeTemplates:
51-
- apiVersion: cdi.kubevirt.io/v1beta1
52-
kind: DataVolume
53-
metadata:
54-
name: example-vm-disk
55-
spec:
56-
sourceRef:
57-
kind: DataSource
58-
name: rhel9
59-
namespace: openshift-virtualization-os-images
60-
storage:
61-
resources:
62-
requests:
63-
storage: 30Gi
64-
running: false
65-
template:
66-
metadata:
67-
labels:
68-
kubevirt.io/domain: example-vm
69-
spec:
70-
domain:
71-
cpu:
72-
cores: 1
73-
sockets: 2
74-
threads: 1
75-
devices:
76-
disks:
77-
- disk:
78-
bus: virtio
79-
name: rootdisk
80-
- disk:
81-
bus: virtio
82-
name: cloudinitdisk
83-
interfaces:
84-
- masquerade: {}
85-
name: default
86-
rng: {}
87-
features:
88-
smm:
89-
enabled: true
90-
firmware:
91-
bootloader:
92-
efi: {}
93-
resources:
94-
requests:
95-
memory: 8Gi
96-
evictionStrategy: LiveMigrate
97-
networks:
98-
- name: default
99-
pod: {}
100-
volumes:
101-
- dataVolume:
102-
name: example-volume
103-
name: example-vm-disk
104-
- cloudInitNoCloud: <.>
105-
userData: |-
106-
#cloud-config
107-
user: cloud-user
108-
password: <password>
109-
chpasswd: { expire: False }
110-
ifdef::dynamic-key[]
111-
runcmd:
112-
- [ setsebool, -P, virt_qemu_ga_manage_ssh, on ]
113-
endif::[]
114-
name: cloudinitdisk
115-
accessCredentials:
116-
- sshPublicKey:
117-
propagationMethod:
11845
ifdef::static-key[]
119-
noCloud: {}
46+
include::snippets/virt-static-key.yaml[]
12047
endif::[]
48+
12149
ifdef::dynamic-key[]
122-
qemuGuestAgent:
123-
users: ["user1","user2","fedora"] <.>
50+
include::snippets/virt-dynamic-key.yaml[]
12451
endif::[]
125-
source:
126-
secret:
127-
secretName: authorized-keys <.>
128-
---
129-
apiVersion: v1
130-
kind: Secret
131-
metadata:
132-
name: authorized-keys
133-
data:
134-
key: |
135-
MIIEpQIBAAKCAQEAulqb/Y... <.>
13652
----
137-
<.> Specify the `cloudInitNoCloud` data source.
138-
ifdef::dynamic-key[]
139-
<.> Specify the user names.
140-
endif::[]
141-
<.> Specify the `Secret` object name.
142-
<.> Paste the public SSH key.
53+
<1> Specify the `cloudInitNoCloud` data source.
54+
<2> Specify the `Secret` object name.
55+
<3> Paste the public SSH key.
14356

144-
. Create the `VirtualMachine` and `Secret` objects:
57+
. Create the `VirtualMachine` and `Secret` objects by running the following command:
14558
+
14659
[source,terminal]
14760
----
14861
$ oc create -f <manifest_file>.yaml
14962
----
15063

151-
. Start the VM:
64+
. Start the VM by running the following command:
15265
+
15366
[source,terminal]
15467
----
@@ -182,7 +95,7 @@ ifdef::static-key[]
18295
endif::[]
18396
ifdef::dynamic-key[]
18497
qemuGuestAgent:
185-
users: ["user1","user2","fedora"]
98+
users: ["cloud-user"]
18699
endif::[]
187100
source:
188101
secret:

‎modules/virt-common-instancetypes.adoc

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * virt/virtual_machines/creating_vms_rh/virt-creating-vms-from-instance-types.adoc
4+
5+
:_mod-docs-content-type: REFERENCE
6+
[id="virt-common-instancetypes_{context}"]
7+
= Pre-defined instance types
8+
9+
{VirtProductName} includes a set of pre-defined instance types called `common-instancetypes`. Some are specialized for specific workloads and others are workload-agnostic.
10+
11+
These instance type resources are named according to their series, version, and size. The size value follows the `.` delimiter and ranges from `nano` to `8xlarge`.
12+
13+
.`common-instancetypes` series comparison
14+
15+
[cols="2a,1a,2a,1a,2a"][%collapsible]
16+
|===
17+
^.^|Use case ^.^|Series ^.^|Characteristics ^.^|vCPU to memory ratio ^.^|Example resource
18+
19+
^.^|Universal
20+
^.^|U
21+
a|
22+
* Burstable CPU performance
23+
^.^|1:4
24+
.^a|`u1.medium`::
25+
* 1 vCPUs
26+
* 4 Gi memory
27+
28+
^.^|Overcommitted
29+
^.^|O
30+
a|
31+
* Overcommitted memory
32+
* Burstable CPU performance
33+
^.^|1:4
34+
.^a|`o1.small`::
35+
* 1 vCPU
36+
* 2Gi memory
37+
38+
^.^|Compute-exclusive
39+
^.^|CX
40+
a|
41+
* Hugepages
42+
* Dedicated CPU
43+
* Isolated emulator threads
44+
* vNUMA
45+
^.^|1:2
46+
.^a|`cx1.2xlarge`::
47+
* 8 vCPUs
48+
* 16Gi memory
49+
50+
^.^|NVIDIA GPU
51+
^.^|GN
52+
a|
53+
* For VMs that use GPUs provided by the NVIDIA GPU Operator
54+
* Has predefined GPUs
55+
* Burstable CPU performance
56+
^.^|1:4
57+
.^a|`gn1.8xlarge`::
58+
* 32 vCPUs
59+
* 128Gi memory
60+
61+
^.^|Memory-intensive
62+
^.^|M
63+
a|
64+
* Hugepages
65+
* Burstable CPU performance
66+
^.^|1:8
67+
.^a|`m1.large`::
68+
* 2 vCPUs
69+
* 16Gi memory
70+
71+
^.^|Network-intensive
72+
^.^|N
73+
a|
74+
* Hugepages
75+
* Dedicated CPU
76+
* Isolated emulator threads
77+
* Requires nodes capable of running DPDK workloads
78+
^.^|1:2
79+
.^a|`n1.medium`::
80+
* 4 vCPUs
81+
* 4Gi memory
82+
|===

0 commit comments

Comments
 (0)