MTV-3443: MTV template methods

documentation/doc-Migrating_your_virtual_machines/assemblies/assembly_migrating-from-vmware.adoc

@@ -38,6 +38,8 @@ include::../modules/mtv-shared-disks-known-issues.adoc[leveloffset=+3]
 
 include::../modules/mtv-shared-disks-workarounds.adoc[leveloffset=+3]
 
+include::../modules/mtv-template-utility.adoc[leveloffset=+2]
+
 include::../modules/canceling-migration-cli.adoc[leveloffset=+2]
 
 include::../modules/canceling-migration-cli-entire.adoc[leveloffset=+3]

documentation/modules/common-attributes.adoc

@@ -21,6 +21,8 @@
 :project-short: MTV
 :project-first: {project-full} ({project-short})
 :project-version: 2.10
+:mtv-mig: https://docs.redhat.com/en/documentation/migration_toolkit_for_virtualization/{project-version}/html/migrating_your_virtual_machines_to_red_hat_openshift_virtualization/
+:mtv-plan: https://docs.redhat.com/en/documentation/migration_toolkit_for_virtualization/{project-version}/html/planning_your_migration_to_red_hat_openshift_virtualization/
 :project-z-version: 2.10.0
 :rhel-first: Red Hat Enterprise Linux (RHEL)
 :the: The

documentation/modules/creating-plan-wizard-vmware.adoc

@@ -221,7 +221,7 @@ Variable names cannot exceed 63 characters.
 
 *** Click the *Edit* icon.
 *** Click *Enter custom naming template*.
-*** Enter the template according to the instructions.
+*** Enter the template according to the instructions. Be sure that your template generates VM names that follow RFC 1123, but do not include uppercase letters.
 *** Click *Save*.
 
 ** To specify a different volume name template only for specific VMs, do the following:
@@ -230,13 +230,14 @@ Variable names cannot exceed 63 characters.
 *** Select the desired VMs.
 *** Click the {kebab} of the VM.
 *** Select *Edit Volume name template*.
-*** Enter the template according to the instructions.
+*** Enter the template according to the instructions. Be sure that your template generates VM names that follow RFC 1123, but do not include uppercase letters.
 *** Click *Save*.
 +
 [IMPORTANT]
 ====
 Changes you make on the *Virtual Machines* tab override any changes on the *Plan details* page.
 ====
++
 
 .. *PVC name template*: Specifies a template for the name of the persistent volume claim (PVC) for the VMs in your plan.
 +
@@ -258,7 +259,7 @@ Variable names cannot exceed 63 characters.
 
 *** Click the *Edit* icon.
 *** Click *Enter custom naming template*.
-*** Enter the template according to the instructions.
+*** Enter the template according to the instructions. Be sure that your template generates VM names that follow RFC 1123, but do not include uppercase letters.
 *** Click *Save*.
 
 ** To specify a PVC name template only for specific VMs, do the following:
@@ -267,7 +268,7 @@ Variable names cannot exceed 63 characters.
 *** Select the desired VMs.
 *** Click the {kebab} of the VM.
 *** Select *Edit PVC name template*.
-*** Enter the template according to the instructions.
+*** Enter the template according to the instructions. Be sure that your template generates VM names that follow RFC 1123, but do not include uppercase letters.
 *** Click *Save*.
 +
 [IMPORTANT]
@@ -295,7 +296,7 @@ Variable names cannot exceed 63 characters.
 
 *** Click the *Edit* icon.
 *** Click *Enter custom naming template*.
-*** Enter the template according to the instructions.
+*** Enter the template according to the instructions. Be sure that your template generates VM names that follow RFC 1123, but do not include uppercase letters.
 *** Click *Save*.
 
 ** To specify a different network name template only for specific VMs, do the following:
@@ -304,13 +305,18 @@ Variable names cannot exceed 63 characters.
 *** Select the desired VMs.
 *** Click the {kebab} of the VM.
 *** Select *Edit Network name template*.
-*** Enter the template according to the instructions.
+*** Enter the template according to the instructions. Be sure that your template generates VM names that follow RFC 1123, but do not include uppercase letters.
 *** Click *Save*.
 +
 [IMPORTANT]
 ====
 Changes you make on the *Virtual Machines* tab override any changes on the *Plan details* page.
 ====
++
+[IMPORTANT]
+====
+{project-short} does not validate VM names generated by the templates you enter on the *Plan details* page. Migrations that include VMs whose names include uppercase letters or that violate RFC 1123 rules fail automatically. To avoid failures, you might want to run a Go script that uses the `sprig` methods that {project-short} supports. For tables documenting the methods that {project-short} supports, see {mtv-mig}assembly_migrating-from-vmware#mtv-template-utility_vmware[{project-short} template utility for {vmw} VM names].
+====
 
 .. *Raw copy mode*: By default, during migration, virtual machines (VMs) are converted using a tool named `virt-v2v` that makes them compatible with {virt}. For more information about the virt-v2v conversion process, see 'How {project-short} uses the virt-v2v tool' in _Migrating your virtual machines to Red Hat {virt}_. _Raw copy mode_ copies VMs without converting them. This allows for faster conversions, migrating VMs running a wider range of operating systems, and supporting migrating disks encrypted using Linux Unified Key Setup (LUKS) without needing keys. However, VMs migrated using raw copy mode might not function properly on {virt}.
 

documentation/modules/mtv-template-utility.adoc

@@ -0,0 +1,146 @@
+// Module included in the following assemblies:
+//
+// * documentation/doc-Migrating_your_virtual_machines/assembly_migrating-from-vmware.adoc
+
+:_content-type: CONCEPT
+[id="mtv-template-utility_{context}"]
+= {project-short} template utility for {vmw} VM names
+
+[role="_abstract"]
+You can use the template utility of {project-first} to generate names for your virtual machines (VMs). Using names generated by these methods reduces the possibilities of problems with your VMs after their migration to {virt}.
+
+The tables that follow describe string and mathematical functions that you can use in templates that rename VMs for use with {project-short}. 
+
+[cols="1,1,1",options="header"]
+.String functions
+
+|===
+| Function
+| Description
+| Example
+
+| `lower`
+| Converts a string to lowercase.
+| `{{ lower "TEXT" }}` → `text`
+
+| `upper`
+| Converts a string to uppercase.
+| `{{ upper "text" }}` → `TEXT`
+
+| `contains`	
+| Checks if a string contains a specific substring.
+| `{{ contains "hello" "lo" }}` → `true`
+
+| `replace`
+| Replaces occurrences in a string.
+| `{{"I Am Henry VIII" \| replace "{nbsp}" "-"}}`→ `I-Am-Henry-VIII`
+
+| `trim`
+| Removes whitespace from both ends of a string.
+| `{{ trim "  text  " }}` → `text`
+
+| `trimAll`
+| Removes specified characters from both ends of a string.
+| `{{ trimAll "$" "$5.00$" }}` → `5.00`
+
+| `trimSuffix`
+| Removes the specified suffix from a string, if it is present.
+| `{{ trimSuffix ".go" "file.go" }}` → `file`
+
+| `trimPrefix`	
+| Removes the specified prefix from a string, if it is present.
+| `{{ trimPrefix "go." "go.file" }}` → `file`
+
+| `title`
+| Converts a string to title case.
+| `{{ title "hello world" }}` → `Hello World`
+
+| `untitle`
+| Converts a string in title case to lowercase.
+| `{{ untitle "Hello World" }}`→ `hello world`
+
+| `repeat`		
+| Repeats a string _n_ times.
+| `{{ repeat 3 "abc" }}` → `abcabcabc`
+
+| `substr`		
+| Extracts substring from _index>=a_ to _b<index_.
+| `{{ substr 1 4 "abcdef" }}` → `bcd`
+
+| `nospace`	
+| Removes all whitespace from a string.	
+| `{{ nospace "a b  c" }}` → `abc`
+
+| `trunc`
+| Truncates a string to specified length.
+| `{{ trunc 3 "abcdef" }}` → `abc`
+
+| `initials` 
+| Extracts the first letter of each word in a string.
+| `{{ initials "John Doe" }} → `JD`
+
+| `hasPrefix`
+| Checks if a string starts with the specified prefix.
+| `{{ hasPrefix "go" "golang" }}` → `true`
+
+| `hasSuffix`	 
+| Checks if a string ends with the specified suffix.
+| `{{ hasSuffix "ing" "coding" }}` → `true`
+
+| `mustRegexReplaceAll`
+| Replaces matches using regular expressions with submatch expansion.
+| `{{ mustRegexReplaceAll "a(x*)b" "-ab-axxb-" "${1}W" }}` → `-W-xxW-`
+|===
+
+[cols="1,1,1",options="header"]
+.Mathematical functions
+
+|===
+| Function
+| Description
+| Example
+
+| `add`
+| Sum of the numbers that follow.
+| `{{ add 1 2 3 }}` → `6`
+
+| `add1`
+| Increment by 1.
+| `{{ add1 5 }}` → `6`
+
+| `sub`
+| Subtract the second number from the first.
+| `{{ sub 5 3 }}` → `2`
+
+| `div`
+| Integer division (remainder discarded).
+| `{{ div 10 3 }}`→`3`
+
+| `mod`
+| Modulo operation.
+| `{{ mod 10 3 }}` → `1`
+
+| `multiply`
+| Multiply the numbers that follow.
+| `{{ mul 2 3 4 }}` → `24`
+
+| `max`
+| Return the largest of the following integers.
+| `{{ max 1 5 3 }}` → `5`
+
+| `min`
+| Return the smallest of the following integers.
+| `{{ min 1 5 3 }}` → `1`
+
+| `floor`
+| Round the following number down to the nearest integer.
+| `{{ floor 3.75 }}` → `3.0`
+
+| `ceil`
+| Round the following number up to the nearest integer.
+| `{{ ceil 3.25 }}` → `4.0`
+
+| `round`
+| Round the following number to the specified number of decimal places.
+| `{{ round 3.75159 2 }}` → `3.75`
+|===

documentation/modules/proc_migrating-virtual-machines-cli.adoc

@@ -879,7 +879,13 @@ The template follows the Go template syntax and has access to the following vari
 * `"net-{{.NetworkIndex}}"`
 * `{{if eq .NetworkType "pod"}}pod{{else}}multus-{{.NetworkIndex}}{{end}}"`
 +
-Variable names cannot exceed 63 characters. This rule applies to a network name network template, a PVC name template, a VM name template, and a volume name template.
+Variable names cannot exceed 63 characters. VM names geneated by templates must not include uppercase letters or violate RFC 1123 rules.  These rules apply to a network name network template, a PVC name template, a VM name template, and a volume name template.
++
+[IMPORTANT]
+====
+{project-short} does not validate VM names generated by the templates described here. Migrations that include VMs whose names include uppercase letters or that violate RFC 1123 rules fail automatically. To avoid failures, you might want to run a Go script that uses the `sprig` methods that {project-short} supports. For tables documenting the methods that {project-short} supports, see xref:mtv-template-utility_vmware[{project-short} template utility for {vmw} VM names].
+====
++
 <10> [[callout10]]Optional. Specify a template for the persistent volume claim (PVC) name for a plan.
 The template follows the Go template syntax and has access to the following variables:
 * `.VmName`: Name of the VM.
@@ -933,6 +939,7 @@ The template follows the Go template syntax and has access to the following vari
 <26> Allowed values are `PreHook` before the migration plan starts or `PostHook` after the migration is complete.
 +
 include::snip_vmware-name-change.adoc[]
+
 endif::[]
 
 ifdef::rhv[]