CNV#21150: instance types CLI

modules/virt-about-instance-types.adoc

@@ -0,0 +1,68 @@
+// Module included in the following assemblies:
+//
+// * virt/virtual_machines/creating_vms_rh/virt-creating-vms-from-instance-types.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="virt-about-instance-types_{context}"]
+= About instance types
+
+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}. You can create instance types by using YAML files or the `virtctl` CLI tool.
+
+{VirtProductName} provides two CRDs for configuring instance types: 
+
+* A namespaced object: `VirtualMachineInstancetype`
+* A cluster-wide object: `VirtualMachineClusterInstancetype`
+
+These objects use the same `VirtualMachineInstancetypeSpec`.
+
+[id="required-attributes_{context}"]
+== Required attributes
+
+When you configure an instance type, you must define the `cpu` and `memory` attributes. Other attributes are optional. 
+
+[NOTE]
+====
+When you create a VM from an instance type, you cannot override any parameters defined in the instance type. 
+
+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.
+====
+
+.Example YAML file with required fields
+[source,yaml]
+----
+apiVersion: instancetype.kubevirt.io/v1beta1
+kind: VirtualMachineInstancetype
+metadata:
+  name: example-instancetype
+spec:
+  cpu:
+    guest: 1 <1>
+  memory:
+    guest: 128Mi <2>
+----
+<1> Required. Specifies the number of vCPUs to allocate to the guest.
+<2> Required. Specifies an amount of memory to allocate to the guest.
+
+.Example `virtctl` command with required fields
+[source,terminal]
+----
+$ virtctl create instancetype --cpu 2 --memory 256Mi
+----
+
+where: 
+
+`--cpu <value>`:: Specifies the number of vCPUs to allocate to the guest. Required.
+`--memory <value>`:: Specifies an amount of memory to allocate to the guest. Required.
+
+[id="optional-attributes_{context}"]
+== Optional attributes
+
+In addition to the required `cpu` and `memory` attributes, you can include the following optional attributes in the `VirtualMachineInstancetypeSpec`:
+
+`annotations`:: List annotations to apply to the VM.
+`gpus`:: List vGPUs for passthrough.
+`hostDevices`:: List host devices for passthrough.
+`ioThreadsPolicy`:: Define an IO threads policy for managing dedicated disk access.
+`launchSecurity`:: Configure Secure Encrypted Virtualization (SEV).
+`nodeSelector`:: Specify node selectors to control the nodes where this VM is scheduled.
+`schedulerName`:: Define a custom scheduler to use for this VM instead of the default scheduler.

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

@@ -39,116 +39,29 @@ endif::[]
 
 . Create a manifest file for a `VirtualMachine` object and a `Secret` object:
 +
+.Example manifest
 [source,yaml]
 ----
-apiVersion: kubevirt.io/v1
-kind: VirtualMachine
-metadata:
-  name: example-vm
-  namespace: example-namespace
-spec:
-  dataVolumeTemplates:
-  - apiVersion: cdi.kubevirt.io/v1beta1
-    kind: DataVolume
-    metadata:
-      name: example-vm-disk
-    spec:
-      sourceRef:
-        kind: DataSource
-        name: rhel9
-        namespace: openshift-virtualization-os-images
-      storage:
-        resources:
-          requests:
-            storage: 30Gi
-  running: false
-  template:
-    metadata:
-      labels:
-        kubevirt.io/domain: example-vm
-    spec:
-      domain:
-        cpu:
-          cores: 1
-          sockets: 2
-          threads: 1
-        devices:
-          disks:
-          - disk:
-              bus: virtio
-            name: rootdisk
-          - disk:
-              bus: virtio
-            name: cloudinitdisk
-          interfaces:
-          - masquerade: {}
-            name: default
-          rng: {}
-        features:
-          smm:
-            enabled: true
-        firmware:
-          bootloader:
-            efi: {}
-        resources:
-          requests:
-            memory: 8Gi
-      evictionStrategy: LiveMigrate
-      networks:
-      - name: default
-        pod: {}
-      volumes:
-      - dataVolume:
-          name: example-volume
-        name: example-vm-disk
-        - cloudInitNoCloud: <.>
-            userData: |-
-              #cloud-config
-              user: cloud-user
-              password: <password>
-              chpasswd: { expire: False }
-ifdef::dynamic-key[]
-              runcmd:
-                - [ setsebool, -P, virt_qemu_ga_manage_ssh, on ]
-endif::[]
-          name: cloudinitdisk
-      accessCredentials:
-        - sshPublicKey:
-            propagationMethod:
 ifdef::static-key[]
-              noCloud: {}
+include::snippets/virt-static-key.yaml[]
 endif::[]
+
 ifdef::dynamic-key[]
-              qemuGuestAgent:
-                users: ["user1","user2","fedora"] <.>
+include::snippets/virt-dynamic-key.yaml[]
 endif::[]
-            source:
-              secret:
-                secretName: authorized-keys <.>
----
-apiVersion: v1
-kind: Secret
-metadata:
-  name: authorized-keys
-data:
-  key:  |
-      MIIEpQIBAAKCAQEAulqb/Y... <.>
 ----
-<.> Specify the `cloudInitNoCloud` data source.
-ifdef::dynamic-key[]
-<.> Specify the user names.
-endif::[]
-<.> Specify the `Secret` object name.
-<.> Paste the public SSH key.
+<1> Specify the `cloudInitNoCloud` data source.
+<2> Specify the `Secret` object name.
+<3> Paste the public SSH key.
 
-. Create the `VirtualMachine` and `Secret` objects:
+. Create the `VirtualMachine` and `Secret` objects by running the following command:
 +
 [source,terminal]
 ----
 $ oc create -f <manifest_file>.yaml
 ----
 
-. Start the VM:
+. Start the VM by running the following command:
 +
 [source,terminal]
 ----
@@ -182,7 +95,7 @@ ifdef::static-key[]
 endif::[]
 ifdef::dynamic-key[]
               qemuGuestAgent:
-                users: ["user1","user2","fedora"]
+                users: ["cloud-user"]
 endif::[]
             source:
               secret:

modules/virt-common-instancetypes.adoc

@@ -0,0 +1,82 @@
+// Module included in the following assemblies:
+//
+// * virt/virtual_machines/creating_vms_rh/virt-creating-vms-from-instance-types.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="virt-common-instancetypes_{context}"]
+= Pre-defined instance types 
+
+{VirtProductName} includes a set of pre-defined instance types called `common-instancetypes`. Some are specialized for specific workloads and others are workload-agnostic.
+
+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`.
+
+.`common-instancetypes` series comparison
+
+[cols="2a,1a,2a,1a,2a"][%collapsible]
+|===
+^.^|Use case ^.^|Series ^.^|Characteristics ^.^|vCPU to memory ratio ^.^|Example resource
+
+^.^|Universal
+^.^|U 
+a| 
+* Burstable CPU performance
+^.^|1:4
+.^a|`u1.medium`:: 
+* 1 vCPUs
+* 4 Gi memory
+
+^.^|Overcommitted
+^.^|O
+a| 
+* Overcommitted memory
+* Burstable CPU performance
+^.^|1:4
+.^a|`o1.small`::
+* 1 vCPU
+* 2Gi memory
+
+^.^|Compute-exclusive
+^.^|CX
+a| 
+* Hugepages
+* Dedicated CPU
+* Isolated emulator threads
+* vNUMA
+^.^|1:2
+.^a|`cx1.2xlarge`::
+* 8 vCPUs
+* 16Gi memory
+
+^.^|NVIDIA GPU
+^.^|GN
+a|
+* For VMs that use GPUs provided by the NVIDIA GPU Operator
+* Has predefined GPUs
+* Burstable CPU performance
+^.^|1:4
+.^a|`gn1.8xlarge`::
+* 32 vCPUs
+* 128Gi memory
+
+^.^|Memory-intensive
+^.^|M 
+a| 
+* Hugepages
+* Burstable CPU performance
+^.^|1:8
+.^a|`m1.large`::
+* 2 vCPUs
+* 16Gi memory
+
+^.^|Network-intensive
+^.^|N
+a| 
+* Hugepages
+* Dedicated CPU
+* Isolated emulator threads
+* Requires nodes capable of running DPDK workloads
+^.^|1:2
+.^a|`n1.medium`::
+* 4 vCPUs
+* 4Gi memory
+|===