Merge pull request openshift#15255 from ousleyp/cnv1611-memory

CNV-1611: Manage guest memory

cnv/cnv_users_guide/cnv-managing-guest-memory.adoc

@@ -0,0 +1,17 @@
+[id="cnv-managing-guest-memory"]
+= Managing guest memory
+include::modules/cnv-document-attributes.adoc[]
+:context: cnv-managing-guest-memory
+toc::[]
+
+If you want to adjust guest memory settings to suit a specific use case, you can
+do so by editing the guest's YAML configuration file. {ProductName} allows you
+to configure guest memory overcommitment and disable guest memory overhead
+accounting.
+
+Both of these procedures carry some degree of risk. Proceed only if you are
+an experienced administrator.
+
+include::modules/cnv-configuring-guest-memory-overcommitment.adoc[leveloffset=+1]
+
+include::modules/cnv-disabling-guest-memory-overhead-accounting.adoc[leveloffset=+1]

modules/cnv-configuring-guest-memory-overcommitment.adoc

@@ -0,0 +1,54 @@
+// Module included in the following assemblies:
+//
+// * cnv/cnv_users_guide/cnv-managing-guest-memory.adoc
+
+[id="cnv-configuring-guest-memory-overcommitment_{context}"]
+= Configuring guest memory overcommitment
+
+If your virtual workload requires more memory than available, you can
+use memory overcommitment to allocate all or most of the host’s memory
+to your virtual machine instances (VMIs). Enabling memory overcommitment means
+you can maximize resources that are normally reserved for the host.
+
+For example, if the host has 32 GB RAM, you can use memory
+overcommitment to fit 8 VMs with 4 GB RAM each. This allocation works under the
+assumption that the VMs will not use all of their memory at the same
+time.
+
+
+.Procedure
+
+. To explicitly tell the VMI that it has more memory available than
+was requested from the cluster, edit the virtual machine configuration file and
+set `spec.domain.memory.guest` to a higher value than
+`spec.domain.resources.requests.memory`. This process is called memory
+overcommitment.
++
+In this example, `1024M` is requested from the cluster, but the VMI is
+told that it has `2048M` available. As long as there is enough free memory
+available on the node, the VMI will consume up to 2048M.
++
+[source,yaml]
+----
+kind: VirtualMachine
+spec:
+  template:
+    domain:
+    resources:
+        requests:
+          memory: 1024M
+    memory:
+        guest: 2048M
+----
++
+[NOTE]
+====
+The same eviction rules as those for Pods apply to the VMI if
+the node is under memory pressure.
+====
+
+. Create the virtual machine:
++
+----
+$ oc create -f <file name>.yaml
+----

modules/cnv-disabling-guest-memory-overhead-accounting.adoc

@@ -0,0 +1,50 @@
+// Module included in the following assemblies:
+//
+// * cnv/cnv_users_guide/cnv-managing-guest-memory.adoc
+
+[id="cnv-disabling-guest-memory-overhead-accounting_{context}"]
+= Disabling guest memory overhead accounting
+
+[WARNING]
+====
+This procedure is only useful in certain use-cases and must
+only be attempted by advanced users.
+====
+
+A small amount of memory is requested by each virtual machine instance in
+addition to the amount that you request. This additional memory is used for
+the infrastructure that wraps each `VirtualMachineInstance` process.
+
+Though it is not usually advisable, it is possible to increase the VMI
+density on the node by disabling guest memory overhead accounting.
+
+
+.Procedure
+
+. To disable guest memory overhead accounting, edit the YAML configuration
+file and set the `overcommitGuestOverhead` value to `true`. This parameter is
+disabled by default.
++
+[source,yaml]
+----
+kind: VirtualMachine
+spec:
+  template:
+    domain:
+    resources:
+        overcommitGuestOverhead: true
+        requests:
+          memory: 1024M
+----
++
+[NOTE]
+====
+If `overcommitGuestOverhead` is enabled, it adds the guest overhead
+to memory limits, if present.
+====
+
+. Create the virtual machine:
++
+----
+$ oc create -f <file name>.yaml
+----