From c273c5b47df4cf57b757a722964be894c558fe8f Mon Sep 17 00:00:00 2001 From: Jamie Phillips Date: Mon, 11 Apr 2022 16:34:36 -0400 Subject: [PATCH 1/4] Creating docs for creating VMware vSphere VM templates. --- .gitignore | 2 + .../rke-clusters/node-pools/vsphere/_index.md | 3 +- .../vsphere/creating-a-vm-template/_index.md | 141 ++++++++++++++++++ 3 files changed, 145 insertions(+), 1 deletion(-) create mode 100644 content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/vsphere/creating-a-vm-template/_index.md diff --git a/.gitignore b/.gitignore index daefacf85e2..e50d424efcf 100644 --- a/.gitignore +++ b/.gitignore @@ -11,3 +11,5 @@ package-lock.json /scripts/converters/results_to_markdown/.terraform /scripts/converters/results_to_markdown/terraform.tfstate* /scripts/converters/results_to_markdown/*.tfvars + +.idea/ diff --git a/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/vsphere/_index.md b/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/vsphere/_index.md index 13c897c89b3..e11d83949fb 100644 --- a/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/vsphere/_index.md +++ b/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/vsphere/_index.md @@ -36,6 +36,7 @@ For the fields to be populated, your setup needs to fulfill the [prerequisites.] ### More Supported Operating Systems You can provision VMs with any operating system that supports `cloud-init`. Only YAML format is supported for the [cloud config.](https://cloudinit.readthedocs.io/en/latest/topics/examples.html) + ### Video Walkthrough of v2.3.3 Node Template Features In this YouTube video, we demonstrate how to set up a node template with the new features designed to help you bring cloud operations to on-premises clusters. @@ -54,4 +55,4 @@ For an example of how to provision storage in vSphere using Rancher, refer to [t When a cloud provider is set up in Rancher, the Rancher server can automatically provision new infrastructure for the cluster, including new nodes or persistent storage devices. -For details, refer to the section on [enabling the vSphere cloud provider.]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/cloud-providers/vsphere) \ No newline at end of file +For details, refer to the section on [enabling the vSphere cloud provider.]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/cloud-providers/vsphere) diff --git a/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/vsphere/creating-a-vm-template/_index.md b/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/vsphere/creating-a-vm-template/_index.md new file mode 100644 index 00000000000..ef49277a333 --- /dev/null +++ b/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/vsphere/creating-a-vm-template/_index.md @@ -0,0 +1,141 @@ +--- +title: Creating a vSphere Virtual Machine Template +weight: 2 +--- + +Creating virtual machines in a repeatable and reliable fashion can often be difficult. VMware vSphere offers the ability to build one VM that can then be converted to a template. The template can then be used to create identically configured VMs. Rancher leverages this capability within node pools to create identical RKE1 and RKE2 nodes. With that said, Rancher does have some specific requirements for the VM to have pre-installed to leverage the template to create new VMs. After configuring the VM with the requirements, the VM will need to be prepared before creating the template. Once preparation is complete, the VM can be converted to a template and moved into a content library, ready for Rancher node pool usage. + +- [Requirements](#requirements) +- [Template Creation](#template-creation) +- [Preparation](#preparation) +- [Converting to a Template](#converting-to-a-template) +- [Moving to a content library](#moving-to-a-content-library) +- [Other Resources](#other-resources) + +# Requirements + +There are specific tooling required for both Linux and Windows VMs to be usable by the vSphere node driver. The most critical dependency is [cloud-init](https://cloud-init.io/) for Linux and [cloudbase-init](https://cloudbase.it/cloudbase-init/) for Windows. Both of these are used for provisioning the VMs by configuring the hostname, settings up the SSH access, and default Rancher user. Users can add additional content to these as desired if additional configuration is desired. Outside of that some additional requirements will be listed below. If you have any specific firewall rules or configuration, this should be added to the VM before creating a template. + +## Linux Dependencies + +Here is the list of packages that need installed on the template. These will have slightly varied names based on distribution with some distributions shipping these by default. + +* curl +* wget +* git +* net-tools +* unzip +* apparmor-parser +* ca-certificates +* cloud-init +* cloud-guest-utils +* cloud-image-utils +* growpart +* cloud-initramfs-growroot +* open-iscsi +* openssh-server +* [open-vm-tools](https://docs.vmware.com/en/VMware-Tools/11.3.0/com.vmware.vsphere.vmwaretools.doc/GUID-8B6EA5B7-453B-48AA-92E5-DB7F061341D1.html) + +## Windows Dependencies + +Here is the list of packages that need installed on the template. + +* Windows Container Feature +* [cloudbase-init](https://cloudbase.it/cloudbase-init/#download) +* [Docker EE](https://docs.microsoft.com/en-us/virtualization/windowscontainers/quick-start/set-up-environment?tabs=Windows-Server#install-docker) - RKE1 Only + +**Now here is where the configuration for Windows templates need to differ between RKE1 and RKE2. RKE1 leverages Docker, so any templates for RKE1 will need to have Docker EE preinstalled too. RKE2 doesn't require Docker EE and doesn't require that it be installed.** + +# Template Creation + +There a few different approaches that can be pursued at this step. You can manually create your VM by following [these instructions](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-AE8AFBF1-75D1-4172-988C-378C35C9FAF2.html) from VMware. Once you have a VM running, you can manually install the dependency listed above to configure the VM correctly for the vSphere node driver. After the required dependencies are configured, you can further customize based on your specific environment and requirements. Finally, you are ready to precede with the final preparation before creating your template. + +## Alternatives to manual creation + +Alternatives to manual creation do exist and below is a list of tools that can assist. + +* [VMware PowerCLI](https://developer.vmware.com/powercli) +* [Packer](https://www.packer.io/) +* [SaltStack](https://saltproject.io/) +* [Ansible](https://www.ansible.com/) + +Packer is often used and here is a good [reference](https://github.com/vmware-samples/packer-examples-for-vsphere) for usage with vSphere. + +# Preparation + +Once you have a VM created with all the dependencies listed above and any additional items that are required, the most critical step is next. That step is preparing the VM to be turned into a template. This basically resets the VM hostname, IPs, etc. to prevent that information from being brought into a new VM. When VMs are created from a template without this step, those VMs could have the same hostname, IP address, etc. The steps differ between Linux and Windows. + +## Linux Preparation + +Here is how to achieve the different items that need reset. + +```Bash +# Cleaning logs. +if [ -f /var/log/audit/audit.log ]; then + cat /dev/null > /var/log/audit/audit.log +fi +if [ -f /var/log/wtmp ]; then + cat /dev/null > /var/log/wtmp +fi +if [ -f /var/log/lastlog ]; then + cat /dev/null > /var/log/lastlog +fi + +# Cleaning udev rules. +if [ -f /etc/udev/rules.d/70-persistent-net.rules ]; then + rm /etc/udev/rules.d/70-persistent-net.rules +fi + +# Cleaning the /tmp directories +rm -rf /tmp/* +rm -rf /var/tmp/* + +# Cleaning the SSH host keys +rm -f /etc/ssh/ssh_host_* + +# Cleaning the machine-id +truncate -s 0 /etc/machine-id +rm /var/lib/dbus/machine-id +ln -s /etc/machine-id /var/lib/dbus/machine-id + +# Cleaning the shell history +unset HISTFILE +history -cw +echo > ~/.bash_history +rm -fr /root/.bash_history + +# Truncating hostname, hosts, resolv.conf and setting hostname to localhost +truncate -s 0 /etc/{hostname,hosts,resolv.conf} +hostnamectl set-hostname localhost + +# Clean cloud-init +cloud-init clean -s -l +``` + +## Windows Preparation + +Windows has a utility called [sysprep](https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/sysprep--generalize--a-windows-installation) that is used to generalize an image and reset the same items listed above for Linux. The command would look like this. + +```PowerShell +sysprep.exe /generalize /shutdown /oobe +``` + +# Converting to a Template + +To convert a VM to a template the first step is to shut down and stop the VM. Once it has been stopped, right-click on the VM in the inventory list and select Template. Then click on `Convert to Template`. Once that process has finished, there is now a template that can be used. + +* [VMware guide](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-5B3737CC-28DB-4334-BD18-6E12011CDC9F.html) + +# Moving to a content library + +Rancher has the ability to consume templates provided by a content library. Content libraries store and manage content within vSphere. Content libraries offer the ability to publish and share that content. + +* [Create a content library](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-2A0F1C13-7336-45CE-B211-610D39A6E1F4.html) +* [Clone the template to the content library](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-AC1545F0-F8BA-4CD2-96EB-21B3DFAA1DC1.html) + +# Other Resources + +Here is a list of additional resources that may be useful. + +* [Tutorial for creating a Linux template](https://docs.microsoft.com/en-us/azure/cloud-adoption-framework/manage/hybrid/server/best-practices/vmware-ubuntu-template) +* [Tutorial for creating a Windows template](https://docs.microsoft.com/en-us/azure/cloud-adoption-framework/manage/hybrid/server/best-practices/vmware-windows-template) From f8ac666f73fdce9e3f05ce4167dadc8c0400feeb Mon Sep 17 00:00:00 2001 From: Jamie Phillips Date: Fri, 22 Apr 2022 08:45:02 -0400 Subject: [PATCH 2/4] Implementing requested changes. --- .../vsphere/creating-a-vm-template/_index.md | 24 ++++++++++++------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/vsphere/creating-a-vm-template/_index.md b/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/vsphere/creating-a-vm-template/_index.md index ef49277a333..00fdaea7956 100644 --- a/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/vsphere/creating-a-vm-template/_index.md +++ b/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/vsphere/creating-a-vm-template/_index.md @@ -1,9 +1,11 @@ --- title: Creating a vSphere Virtual Machine Template -weight: 2 +weight: 4 --- -Creating virtual machines in a repeatable and reliable fashion can often be difficult. VMware vSphere offers the ability to build one VM that can then be converted to a template. The template can then be used to create identically configured VMs. Rancher leverages this capability within node pools to create identical RKE1 and RKE2 nodes. With that said, Rancher does have some specific requirements for the VM to have pre-installed to leverage the template to create new VMs. After configuring the VM with the requirements, the VM will need to be prepared before creating the template. Once preparation is complete, the VM can be converted to a template and moved into a content library, ready for Rancher node pool usage. +Creating virtual machines in a repeatable and reliable fashion can often be difficult. VMware vSphere offers the ability to build one VM that can then be converted to a template. The template can then be used to create identically configured VMs. Rancher leverages this capability within node pools to create identical RKE1 and RKE2 nodes. + +In order to leverage the template to create new VMs, Rancher has some [specific requirements](#requirements) that the VM must have pre-installed. After you configure the VM with these requirements, you will next need to [prepare the VM](#preparing-your-vm) before [creating the template](#creating-a-template). Finally, once preparation is complete, the VM can be [converted to a template](#converting-to-a-template) and [moved into a content library](#moving-to-a-content-library), ready for Rancher node pool usage. - [Requirements](#requirements) - [Template Creation](#template-creation) @@ -14,11 +16,13 @@ Creating virtual machines in a repeatable and reliable fashion can often be diff # Requirements -There are specific tooling required for both Linux and Windows VMs to be usable by the vSphere node driver. The most critical dependency is [cloud-init](https://cloud-init.io/) for Linux and [cloudbase-init](https://cloudbase.it/cloudbase-init/) for Windows. Both of these are used for provisioning the VMs by configuring the hostname, settings up the SSH access, and default Rancher user. Users can add additional content to these as desired if additional configuration is desired. Outside of that some additional requirements will be listed below. If you have any specific firewall rules or configuration, this should be added to the VM before creating a template. +There is specific tooling required for both Linux and Windows VMs to be usable by the vSphere node driver. The most critical dependency is [cloud-init](https://cloud-init.io/) for Linux and [cloudbase-init](https://cloudbase.it/cloudbase-init/) for Windows. Both of these are used for provisioning the VMs by configuring the hostname and by setting up the SSH access and the default Rancher user. Users can add additional content to these as desired if other configuration is needed. In addition, other requirements are listed below for reference. + +**Note:** If you have any specific firewall rules or configuration, you will need to add this to the VM before creating a template. ## Linux Dependencies -Here is the list of packages that need installed on the template. These will have slightly varied names based on distribution with some distributions shipping these by default. +The packages that need to be installed on the template are listed below. These will have slightly different names based on distribution; some distributions ship these by default, for example. * curl * wget @@ -38,7 +42,7 @@ Here is the list of packages that need installed on the template. These will hav ## Windows Dependencies -Here is the list of packages that need installed on the template. +The list of packages that need to be installed on the template is as follows: * Windows Container Feature * [cloudbase-init](https://cloudbase.it/cloudbase-init/#download) @@ -124,18 +128,20 @@ sysprep.exe /generalize /shutdown /oobe To convert a VM to a template the first step is to shut down and stop the VM. Once it has been stopped, right-click on the VM in the inventory list and select Template. Then click on `Convert to Template`. Once that process has finished, there is now a template that can be used. -* [VMware guide](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-5B3737CC-28DB-4334-BD18-6E12011CDC9F.html) +For additional information on converting a VM to a template, see the [VMware guide](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-5B3737CC-28DB-4334-BD18-6E12011CDC9F.html). -# Moving to a content library +# Moving to a Content library -Rancher has the ability to consume templates provided by a content library. Content libraries store and manage content within vSphere. Content libraries offer the ability to publish and share that content. +Rancher has the ability to use templates provided by a content library. Content libraries store and manage content within vSphere, and they also offer the ability to publish and share that content. + +Below are some helpful links on content libraries: * [Create a content library](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-2A0F1C13-7336-45CE-B211-610D39A6E1F4.html) * [Clone the template to the content library](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-AC1545F0-F8BA-4CD2-96EB-21B3DFAA1DC1.html) # Other Resources -Here is a list of additional resources that may be useful. +Here is a list of additional resources that may be useful: * [Tutorial for creating a Linux template](https://docs.microsoft.com/en-us/azure/cloud-adoption-framework/manage/hybrid/server/best-practices/vmware-ubuntu-template) * [Tutorial for creating a Windows template](https://docs.microsoft.com/en-us/azure/cloud-adoption-framework/manage/hybrid/server/best-practices/vmware-windows-template) From d04785ee3067f41b8176c1737186b53ed75b66a0 Mon Sep 17 00:00:00 2001 From: Jamie Phillips Date: Tue, 26 Apr 2022 14:10:23 -0400 Subject: [PATCH 3/4] Additional changes. --- .../vsphere/creating-a-vm-template/_index.md | 39 ++++++++++++------- 1 file changed, 26 insertions(+), 13 deletions(-) diff --git a/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/vsphere/creating-a-vm-template/_index.md b/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/vsphere/creating-a-vm-template/_index.md index 00fdaea7956..d3da38f1d2d 100644 --- a/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/vsphere/creating-a-vm-template/_index.md +++ b/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/vsphere/creating-a-vm-template/_index.md @@ -8,8 +8,8 @@ Creating virtual machines in a repeatable and reliable fashion can often be diff In order to leverage the template to create new VMs, Rancher has some [specific requirements](#requirements) that the VM must have pre-installed. After you configure the VM with these requirements, you will next need to [prepare the VM](#preparing-your-vm) before [creating the template](#creating-a-template). Finally, once preparation is complete, the VM can be [converted to a template](#converting-to-a-template) and [moved into a content library](#moving-to-a-content-library), ready for Rancher node pool usage. - [Requirements](#requirements) -- [Template Creation](#template-creation) -- [Preparation](#preparation) +- [Creating a Template](#creating-a-template) +- [Preparing Your VM](#preparing-your-vm) - [Converting to a Template](#converting-to-a-template) - [Moving to a content library](#moving-to-a-content-library) - [Other Resources](#other-resources) @@ -48,30 +48,39 @@ The list of packages that need to be installed on the template is as follows: * [cloudbase-init](https://cloudbase.it/cloudbase-init/#download) * [Docker EE](https://docs.microsoft.com/en-us/virtualization/windowscontainers/quick-start/set-up-environment?tabs=Windows-Server#install-docker) - RKE1 Only -**Now here is where the configuration for Windows templates need to differ between RKE1 and RKE2. RKE1 leverages Docker, so any templates for RKE1 will need to have Docker EE preinstalled too. RKE2 doesn't require Docker EE and doesn't require that it be installed.** +**Important to note: The configuration for Windows templates varies between RKE1 and RKE2:** +- RKE1 leverages Docker, so any RKE1 templates need to have Docker EE pre-installed as well +- RKE2 does not require Docker EE, and thus it does not need to be installed -# Template Creation +# Creating a Template -There a few different approaches that can be pursued at this step. You can manually create your VM by following [these instructions](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-AE8AFBF1-75D1-4172-988C-378C35C9FAF2.html) from VMware. Once you have a VM running, you can manually install the dependency listed above to configure the VM correctly for the vSphere node driver. After the required dependencies are configured, you can further customize based on your specific environment and requirements. Finally, you are ready to precede with the final preparation before creating your template. +You may either manually create your VM or you can utilize [other alternatives](#alternatives-to-manual-creation) to create your VM. -## Alternatives to manual creation +## Manual Creation +1. Manually create your VM by following [these instructions](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-AE8AFBF1-75D1-4172-988C-378C35C9FAF2.html) from VMware. Once you have a VM running, you can manually install the dependency listed above to configure the VM correctly for the vSphere node driver. +2. Customize as needed based on your specific environment and requirements. +3. Proceed with the final preparation before creating your template. -Alternatives to manual creation do exist and below is a list of tools that can assist. +## Alternatives to Manual Creation + +Other alternative options to create VMs are listed below: * [VMware PowerCLI](https://developer.vmware.com/powercli) * [Packer](https://www.packer.io/) * [SaltStack](https://saltproject.io/) * [Ansible](https://www.ansible.com/) -Packer is often used and here is a good [reference](https://github.com/vmware-samples/packer-examples-for-vsphere) for usage with vSphere. +Packer is a frequently-used alternative. Refer to this [reference](https://github.com/vmware-samples/packer-examples-for-vsphere) for examples of its usage with vSphere. -# Preparation +# Preparing Your VM -Once you have a VM created with all the dependencies listed above and any additional items that are required, the most critical step is next. That step is preparing the VM to be turned into a template. This basically resets the VM hostname, IPs, etc. to prevent that information from being brought into a new VM. When VMs are created from a template without this step, those VMs could have the same hostname, IP address, etc. The steps differ between Linux and Windows. +After creating a VM with all the required dependencies (and any additional required items), you must perform the most critical step next: preparing the VM to be turned into a template. This preparation will reset critical data such as the VM hostname, IPs, etc., to prevent that information from being brought into a new VM. If you fail to perform this step, you could create a VM with the same hostname, IP address, etc. + +Note that these preparatory steps differ between Linux and Windows. ## Linux Preparation -Here is how to achieve the different items that need reset. +The commands below will reset your VM in Linux: ```Bash # Cleaning logs. @@ -118,7 +127,7 @@ cloud-init clean -s -l ## Windows Preparation -Windows has a utility called [sysprep](https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/sysprep--generalize--a-windows-installation) that is used to generalize an image and reset the same items listed above for Linux. The command would look like this. +Windows has a utility called [sysprep](https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/sysprep--generalize--a-windows-installation) that is used to generalize an image and reset the same items listed above for Linux. The command is as follows: ```PowerShell sysprep.exe /generalize /shutdown /oobe @@ -126,7 +135,11 @@ sysprep.exe /generalize /shutdown /oobe # Converting to a Template -To convert a VM to a template the first step is to shut down and stop the VM. Once it has been stopped, right-click on the VM in the inventory list and select Template. Then click on `Convert to Template`. Once that process has finished, there is now a template that can be used. +1. Shut down and stop the VM. +2. Right-click on the VM in the inventory list and select **Template**. +3. Click on **Convert to Template**. + +**Result:** Once the process has completed, a template will be available for use. For additional information on converting a VM to a template, see the [VMware guide](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-5B3737CC-28DB-4334-BD18-6E12011CDC9F.html). From e7013de736c330cd3d004e6a152f55c9d8dfeb11 Mon Sep 17 00:00:00 2001 From: Jamie Phillips Date: Tue, 26 Apr 2022 16:24:24 -0400 Subject: [PATCH 4/4] Correcting one last typo. --- .../node-pools/vsphere/creating-a-vm-template/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/vsphere/creating-a-vm-template/_index.md b/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/vsphere/creating-a-vm-template/_index.md index d3da38f1d2d..1ed401c2ebd 100644 --- a/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/vsphere/creating-a-vm-template/_index.md +++ b/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/vsphere/creating-a-vm-template/_index.md @@ -57,7 +57,7 @@ The list of packages that need to be installed on the template is as follows: You may either manually create your VM or you can utilize [other alternatives](#alternatives-to-manual-creation) to create your VM. ## Manual Creation -1. Manually create your VM by following [these instructions](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-AE8AFBF1-75D1-4172-988C-378C35C9FAF2.html) from VMware. Once you have a VM running, you can manually install the dependency listed above to configure the VM correctly for the vSphere node driver. +1. Manually create your VM by following [these instructions](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-AE8AFBF1-75D1-4172-988C-378C35C9FAF2.html) from VMware. Once you have a VM running, you can manually install the dependencies listed above to configure the VM correctly for the vSphere node driver. 2. Customize as needed based on your specific environment and requirements. 3. Proceed with the final preparation before creating your template.