[pve-devel] [PATCH pve-docs] fix #4717: Expanded the section on VM templates

[Alexander Abraham]

The documentation on VM templates has been expanded and
explanations added about advantages/disadvantages, how
they can be worked with and how to create them.

Signed-off-by: Alexander Abraham <a.abraham at proxmox.com>
---
 qm.adoc | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 77 insertions(+), 2 deletions(-)

diff --git a/qm.adoc b/qm.adoc
index 8b9e096..557cb1f 100644
--- a/qm.adoc
+++ b/qm.adoc
@@ -1749,8 +1749,83 @@ setting.
 Virtual Machine Templates
 -------------------------
 
-One can convert a VM into a Template. Such templates are read-only,
-and you can use them to create linked clones.
+Virtual machine templates are fully pre-configured operating
+system images that can be used to deploy KVM-based virtual
+machines. In some cases creating a special template is
+preferrable over cloning another virtual machine. PVE streamlines
+the process of using templates for deployment of a virtual machine
+to such a degree that this process is very fast, easy, and if used
+with linked clones, optimizes your storage by using base images
+and thin-provisioning. Proxmox VE supported this functionality
+since 2008 in the 3.x series. Additionally, templates for KVM-based
+virtual machines can be created and deployed.
+
+Advantages and Disadvantages
+----------------------------
+
+Using virtual machine templates for deploying virtual machines makes it
+possible to quickly deploy reproducible environments. The downside to
+this is that if something has to be changed in the template,
+re-deploying all virtual machines using this template may be a lengthy
+process.
+
+Creating Virtual Machine Templates
+----------------------------------
+
+Proxmox VE's web-based UI offers an option inside the context
+menu of a virtual machine to convert that virtual machine
+into a template. The following steps outline measures to
+be taken to create a template.
+
+- 1.) Create a VM with all drivers and install a system with all needed
+  software packages.
+- 2.) Remove all user data and passwords. To do this on Windows, run
+  `sysprep`. To achieve the same result on Linux, run any tools that
+  do something similar.
+- 3.) Right-click the VM and select "Convert to template".
+
+Once the virtual machine has been converted, it cannot be started
+anymore. The icon in the web-based UI changes to symbolize this change.
+To modify an existing template, the template will have to be deployed
+and the steps outlined above must be repeated.
+
+OS-specific Notes for Templates
+-------------------------------
+
+For productive usage it is highly recommended that a template does not
+include any data, user accounts or SSH keys. You should remove all of
+these pieces of data before you convert a virtual machine into a
+template. On Linux systems you should remove SSH host keys, persistent
+network MAC configuration, and user accounts and data. On Windows there
+exist many tools to achieve this task, most notably `sysprep`. In a
+testing environment it may be useful to use a fully-installed system as
+a template. Listed below are some ways to achieve this on different
+platforms.
+
+- GNU/Linux:
+  - Ubuntu: Install Ubuntu in OEM mode (F4 must be pressed).
+  - CentOS7: Most steps outlined here will also work for Proxmox VE.
+
+- Windows: Please follow Microsoft's full guide
+  https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-7/ee523217(v=ws.10)?redirectedfrom=MSDN[here].
+
+Deploy a Virtual Machine from a Template
+----------------------------------------
+
+To deploy a virtual machine from a template, right-click the template
+and select "Clone". This will deploy a virtual machine with the chosen
+template. There are two types of deployments from a virtual machine
+template: A full clone and a linked clone.
+
+A full-clone virtual machine is a complete copy and is fully independent
+from the original virtual machine or resulting template, but it requires
+the same disk space as the original.
+
+A linked-clone virtual machine requires less disk space but cannot run
+without access to the base virtual machine template. Linked clones work
+well with the following storage formats: Raw files, qcow2, vmdk (local
+or on a network share), LVM-thin, ZFS, rbd, sheepdog, and nexenta. LVM
+and ISCSI are not supported.
 
 NOTE: It is not possible to start templates, because this would modify
 the disk images. If you want to change the template, create a linked
-- 
2.39.5