Add additional-guest-memory-overhead-ratio setting

Signed-off-by: Jian Wang <[email protected]>

docs/advanced/settings.md

@@ -299,6 +299,62 @@ A VM that is configured to use 2 CPUs (equivalent to 2,000 milliCPU) can consume
 }
 ```
 
+### `additional-guest-memory-overhead-ratio`
+
+**Definition**: The ratio to futher tune the VM memory overhead.
+
+The VM is configured with a memory value, this memory is targeted for guest OS to see and use. In Harvester, each VM is carried by a Kubernetes POD. To support the VM to run, Harvester and KubeVirt add some additional memory as the VM memory overhead. The memory overhead is computed by many factors like CPU cores. However, sometimes the OOM(Out Of Memory) can still happen.
+
+This setting is for more flexibly tuning the guest memory overhead.
+
+**Default values**: `"1.5"`
+
+A VM that is configured to have `1 CPU, 2 Gi Memory, 1 Volume and 1 NIC` will get around `240 Mi` memory overhead when the ratio is "1.0". When the ratio is "1.5", the memory overhead becomes 360 Mi. When the ratio is "3", the memory overhead becomes 720 Mi.
+
+Valid value: `""`, `"0"` and from `"1.0"` to `"10.0"`.
+
+```
+apiVersion: harvesterhci.io/v1beta1
+default: "1.5"
+kind: Setting
+metadata:
+  name: additional-guest-memory-overhead-ratio
+value: ""
+```
+When the `value` field is `""`, the `default` field is used.
+When the `value` field is `"0"`, the `additional-guest-memory-overhead-ratio` is not used, Harvester will fallback to `Reserved Memory` only.
+
+This setting is combined with the [Reserved Memroy](../vm/create-vm.md#reserved-memory).
+
+The following table shows how they work.
+
+| VM Configured Memory | Reserved Memory | additional-guest-memory-overhead-ratio| Guest OS Memory | PoD memory Limit |
+| --- | --- | --- | --- | --- |
+| 2 Gi | ""(not configured) | "0.0" | 2 Gi - 100 Mi | 2 Gi + 240 Mi |
+| 2 Gi | 256 Mi | "0.0" | 2 Gi - 256 Mi | 2 Gi + 240 Mi |
+| --- | --- | --- | --- | --- |
+| 2 Gi | ""(not configured) | "1.0" | 2 Gi | 2 Gi + 240*1.0 Mi |
+| 2 Gi | ""(not configured) | "3.0" | 2 Gi | 2 Gi + 240*3.0 Mi |
+| --- | --- | --- | --- | --- |
+| 2 Gi | ""(not configured) | "1.5" | 2 Gi | 2 Gi + 240*1.5 Mi |
+| 2 Gi | 256 Mi | "1.5" | 2 Gi - 256 Mi | 2 Gi + 240*1.5 Mi |
+
+**Example**:
+
+```
+2.0
+```
+
+:::note
+
+Harvester suggests to:
+
+- Configure this setting with value "2" to give VMs more guest memory overhead.
+
+- Configure `Reserved Memory` for some important VMs to give them even more memory overhead.
+
+:::
+
 ### `release-download-url`
 
 **Definition**: URL for downloading the software required for upgrades.

docs/vm/create-vm.md

@@ -230,6 +230,15 @@ In order to meet the scenario requirements of more users, the `RunStrategy` fiel
 - Stop: There will be no VM instance. If the guest is already running, it will be stopped. This is the same behavior as `Running: false`.
 
 
+### Reserved Memory
+
+The VM is configured with a memory value, this memory is targeted for guest OS to see and use. In Harvester, each VM is carried by a Kubernetes POD. To support the VM to run, Harvester and KubeVirt add some additional memory as the VM memory overhead. The memory overhead is computed by many factors like CPU cores. However, sometimes the OOM(Out Of Memory) can still happen.
+
+Harvester adds a `Reserved Memory` field and a setting `additional-guest-memory-overhead-ratio` for user to adjust the guest OS memory and the memory overhead.
+
+See [additional-guest-memory-overhead-ratio](../advanced/settings.md#additional-guest-memory-overhead-ratio) for more details.
+
+
 ### Cloud Configuration
 
 Harvester supports the ability to assign a startup script to a virtual machine instance which is executed automatically when the VM initializes.

versioned_docs/version-v1.3/vm/create-vm.md

@@ -134,6 +134,28 @@ In order to meet the scenario requirements of more users, the `RunStrategy` fiel
 - Stop: There will be no VM instance. If the guest is already running, it will be stopped. This is the same behavior as `Running: false`.
 
 
+### Reserved Memory
+
+The VM is configured with a memory value, this memory is targeted for guest OS to see and use. In Harvester, each VM is carried by a Kubernetes POD. To support the VM to run, Harvester and KubeVirt add some additional memory as the VM memory overhead. The memory overhead is computed by many factors like CPU cores. However, sometimes the OOM(Out Of Memory) can still happen.
+
+Harvester adds a `Reserved Memory` field for user to adjust the guest OS memory and the memory overhead.
+
+The following table shows how it works.
+
+| VM Configured Memory | Reserved Memory | Guest OS Memory |
+| --- | --- | --- |
+| 2Gi | ""(not configured) | 2 Gi - 100 Mi |
+| 2Gi | 256Mi | 2 Gi - 256 Mi |
+| 8Gi | ""(not configured) | 8 Gi - 100 Mi |
+| 8Gi | 512Mi | 8 Gi - 512 Mi |
+
+:::note
+
+When `Reserved Memory` field is not configured, Harvester will reserve 100Mi memory automatically.
+
+:::
+
+
 ### Cloud Configuration
 
 Harvester supports the ability to assign a startup script to a virtual machine instance which is executed automatically when the VM initializes.