Merge pull request #35728 from codyhoag/winc-vsphere-template-updates

OSDOCS-2447 WINC vsphere golden image updates

Author: codyhoag

modules/creating-the-vsphere-windows-vm-golden-image.adoc

@@ -9,81 +9,90 @@ Create a vSphere Windows virtual machine (VM) golden image.
 
 .Prerequisites
 
-* You have installed a cluster on vSphere configured with hybrid networking using OVN-Kubernetes.
-* You have defined a custom VXLAN port in your hybrid networking configuration to work around the link:https://docs.microsoft.com/en-us/virtualization/windowscontainers/kubernetes/common-problems#pod-to-pod-connectivity-between-hosts-is-broken-on-my-kubernetes-cluster-running-on-vsphere[pod-to-pod connectivity issue between hosts].
+* You have created a private/public key pair, which is used to configure key-based authentication in the OpenSSH server. The private key must also be configured in the Windows Machine Config Operator (WMCO) namespace. This is required to allow the WMCO to communicate with the Windows VM. See the "Configuring a secret for the Windows Machine Config Operator" section for more details.
 
-.Procedure
-
-. Create the VM from an updated version of the Windows Server 1909 VM image that includes the link:https://support.microsoft.com/en-us/help/4565351/windows-10-update-kb4565351[Microsoft patch KB4565351]. This patch is required to set the VXLAN UDP port, which is required for clusters installed on vSphere. This patch is not available for the `Windows Server 2019` VM image.
+[NOTE]
+====
+You must use link:https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell[Microsoft PowerShell] commands in several cases when creating your Windows VM. PowerShell commands in this guide are distinguished by the `PS C:\>` prefix.
+====
 
-. Create the `C:\Users\Administrator\.ssh\authorized_keys` file in the Windows VM containing the public key that corresponds to the private key that resides in the secret you created in the `openshift-windows-machine-config-operator` namespace. The private key of the secret was created when first installing the Windows Machine Config Operator (WMCO) to give {product-title} access to Windows VMs. The `authorized_keys` file is used to configure SSH in the Windows VM.
+.Procedure
 
-. Configure SSH on the Windows VM by running the following Powershell script:
-+
-[source,posh]
-----
-# Powershell script to configure SSH on vSphere Windows VMs
-Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
-$firewallRuleName = "ContainerLogsPort"
-$containerLogsPort = "10250"
-New-NetFirewallRule -DisplayName $firewallRuleName -Direction Inbound -Action Allow -Protocol TCP -LocalPort $containerLogsPort -EdgeTraversalPolicy Allow
-Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force
-Install-Module -Force OpenSSHUtils
-Set-Service -Name ssh-agent -StartupType 'Automatic'
-Set-Service -Name sshd -StartupType 'Automatic'
-Start-Service ssh-agent
-Start-Service sshd
-$pubKeyConf = (Get-Content -path C:\ProgramData\ssh\sshd_config) -replace '#PubkeyAuthentication yes','PubkeyAuthentication yes'
-$pubKeyConf | Set-Content -Path C:\ProgramData\ssh\sshd_config
-$passwordConf = (Get-Content -path C:\ProgramData\ssh\sshd_config) -replace '#PasswordAuthentication yes','PasswordAuthentication yes'
-$passwordConf | Set-Content -Path C:\ProgramData\ssh\sshd_config
-$authFileConf = (Get-Content -path C:\ProgramData\ssh\sshd_config) -replace 'AuthorizedKeysFile __PROGRAMDATA__/ssh/administrators_authorized_keys','#AuthorizedKeysFile __PROGRAMDATA__/ssh/administrators_authorized_keys'
-$authFileConf | Set-Content -Path C:\ProgramData\ssh\sshd_config
-$pubKeyLocationConf = (Get-Content -path C:\ProgramData\ssh\sshd_config) -replace 'Match Group administrators','#Match Group administrators'
-$pubKeyLocationConf | Set-Content -Path C:\ProgramData\ssh\sshd_config
-Restart-Service sshd
-New-item -Path $env:USERPROFILE -Name .ssh -ItemType Directory -force
-----
+. Create a new VM in the vSphere client using the Windows Server Semi-Annual Channel (SAC): Windows Server 2004 ISO image that includes the link:https://support.microsoft.com/en-us/help/4565351/windows-10-update-kb4565351[Microsoft patch KB4565351]. This patch is required to set the VXLAN UDP port, which is required for clusters installed on vSphere. See the link:https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.hostclient.doc/GUID-FBEED81C-F9D9-4193-BDCC-CC4A60C20A4E.html[VMware documentation] for more information.
 
 . Install and configure VMware Tools version 11.0.6 or greater on the Windows VM. See the link:https://docs.vmware.com/en/VMware-Tools/index.html[VMware Tools documentation] for more information.
 
 . After installing VMware Tools on the Windows VM, verify the following:
-.. The `C:\ProgramData\VMware\VMware Tools\tools.conf` file has the following entry:
+
+.. The `C:\ProgramData\VMware\VMware Tools\tools.conf` file exists with the following entry:
 +
 [source,ini]
 ----
 exclude-nics=
 ----
 +
-This entry ensures the following:
+If the `tools.conf` file does not exist, create it with the `exclude-nics` option uncommented and set as an empty value.
++
+This entry ensures the cloned vNIC generated on the Windows VM by the hybrid-overlay is not ignored.
+
+.. The Windows VM has a valid IP address in vCenter:
++
+[source,terminal]
+----
+C:\> ipconfig
+----
+
+.. The VMTools Windows service is running:
++
+[source,posh]
+----
+PS C:\> Get-Service -Name VMTools | Select Status, StartType
+----
+
+. Install and configure the OpenSSH Server on the Windows VM. See Microsoft's documentation on link:https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse[installing OpenSSH] for more details.
+
+. Set up SSH access for an administrative user. See Microsoft's documentation on the link:https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_keymanagement#administrative-user[Administrative user] to do this.
 +
-* The cloned vNIC generated on the Windows VM by the hybrid-overlay is not ignored.
-* The VM has an IP address in vCenter.
+[IMPORTANT]
+====
+The public key used in the instructions must correspond to the private key you create later in the WMCO namespace that holds your secret. See the "Configuring a secret for the Windows Machine Config Operator" section for more details.
+====
 
-.. The VMTools Windows service is running.
+. Install the `docker` container runtime on your Windows VM following the link:https://docs.microsoft.com/en-us/virtualization/windowscontainers/quick-start/set-up-environment?tabs=Windows-Server[Microsoft documentation].
+
+. You must create a new firewall rule in the Windows VM that allows incoming connections for container logs. Run the following PowerShell command to create the firewall rule on TCP port 10250:
++
+[source,posh]
+----
+PS C:\> New-NetFirewallRule -DisplayName "ContainerLogsPort" -LocalPort 10250 -Enabled True -Direction Inbound -Protocol TCP -Action Allow -EdgeTraversalPolicy Allow
+----
 
-. Pull all of the required Windows container base images needed for your applications. The images you pull
-are dependent on the Windows kernel you are using. See Microsoft's documentation on link:https://docs.microsoft.com/en-us/virtualization/windowscontainers/manage-containers/container-base-images[pulling Windows container base images] for more information.
+. Clone the Windows VM so it is a reusable image. Follow the VMware documentation on how to link:https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-1E185A80-0B97-4B46-A32B-3EF8F309BEED.html[clone an existing virtual machine] for more details.
 
-. Run the link:+++https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/sysprep--generalize--a-windows-installation+++[Windows Sysprep tool] on the Windows VM:
+. In the cloned Windows VM, run the link:+++https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/sysprep--generalize--a-windows-installation+++[Windows Sysprep tool]:
 +
 [source,terminal]
 ----
-C:\> sysprep.exe /generalize /oobe /shutdown /unattend:<path_to_unattend.xml>
+C:\> C:\Windows\System32\Sysprep\sysprep.exe /generalize /oobe /shutdown /unattend:<path_to_unattend.xml> <1>
 ----
+<1> Specify the path to your `unattend.xml` file.
 +
-An example `unattend.xml` is provided, which maintains all the changes needed for the WMCO. For example, the `unattend.xml` file must ensure the Administrator's home directory stays intact with the SSH public key. You must customize the example to fit your needs.
+[NOTE]
+====
+There is a limit on how many times you can run the `sysprep` command on a Windows image. Consult Microsoft's link:+++https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/sysprep--generalize--a-windows-installation#limits-on-how-many-times-you-can-run-sysprep+++[documentation] for more information.
+====
++
+An example `unattend.xml` is provided, which maintains all the changes needed for the WMCO. You must modify this example; it cannot be used directly.
 +
 .Example `unattend.xml`
 [%collapsible]
 ====
 [source,xml]
 ----
 <?xml version="1.0" encoding="UTF-8"?>
-<!--A sample unattend.xml which helps in setting admin password and running scripts on first boot-->
 <unattend xmlns="urn:schemas-microsoft-com:unattend">
    <settings pass="specialize">
-      <component xmlns:wcm="http://schemas.microsoft.com/WMIConfig/2002/State" xmlns:xsi="http:// www.w3.org/2001/XMLSchema-instance" name="Microsoft-Windows-International-Core" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="nonSxS">
+      <component xmlns:wcm="http://schemas.microsoft.com/WMIConfig/2002/State" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="Microsoft-Windows-International-Core" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="nonSxS">
          <InputLocale>0409:00000409</InputLocale>
          <SystemLocale>en-US</SystemLocale>
          <UILanguage>en-US</UILanguage>
@@ -97,19 +106,13 @@ An example `unattend.xml` is provided, which maintains all the changes needed fo
          <CEIPEnabled>0</CEIPEnabled>
       </component>
       <component xmlns:wcm="http://schemas.microsoft.com/WMIConfig/2002/State" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="Microsoft-Windows-Shell-Setup" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="nonSxS">
-         <ComputerName>windows-host</ComputerName>
-         <ProductKey>My_Product_key</ProductKey>
+         <ComputerName>winhost</ComputerName> <1>
       </component>
    </settings>
    <settings pass="oobeSystem">
       <component xmlns:wcm="http://schemas.microsoft.com/WMIConfig/2002/State" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="Microsoft-Windows-Shell-Setup" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="nonSxS">
          <AutoLogon>
-            <Password>
-               <Value>MyPassword</Value>
-               <PlainText>true</PlainText>
-            </Password>
-            <Enabled>true</Enabled>
-            <Username>Administrator</Username>
+            <Enabled>false</Enabled> <2>
          </AutoLogon>
          <OOBE>
             <HideEULAPage>true</HideEULAPage>
@@ -128,20 +131,19 @@ An example `unattend.xml` is provided, which maintains all the changes needed fo
          <TimeZone>Eastern Standard Time</TimeZone>
          <UserAccounts>
             <AdministratorPassword>
-               <Value>MyPassword</Value>
+               <Value>MyPassword</Value> <3>
                <PlainText>true</PlainText>
             </AdministratorPassword>
-            <LocalAccounts>
-               <LocalAccount wcm:action="add">
-                  <Description>Administrator</Description>
-                  <DisplayName>Administrator</DisplayName>
-                  <Group>Administrators</Group>
-                  <Name>Administrator</Name>
-               </LocalAccount>
-            </LocalAccounts>
          </UserAccounts>
       </component>
    </settings>
 </unattend>
 ----
+<1> Specify the `ComputerName`, which must follow the link:https://kubernetes.io/docs/concepts/overview/working-with-objects/names[Kubernetes' names specification]. These specifications also apply to Guest OS customization performed on the resulting template while creating new VMs.
+<2> Disable the automatic logon to avoid the security issue of leaving an open terminal with Administrator privileges at boot. This is the default value and must not be changed.
+<3> Replace the `MyPassword` placeholder with the password for the Administrator account. This prevents the built-in Administrator account from having a blank password by default. Follow Microsoft's link:https://docs.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/password-must-meet-complexity-requirements[best practices for choosing a password].
 ====
++
+After the Sysprep tool has completed, the Windows VM will power off. You must not use or power on this VM anymore.
+
+. Convert the Windows VM to link:https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-5B3737CC-28DB-4334-BD18-6E12011CDC9F.html[a template in vCenter].

modules/machineset-yaml-vsphere.adoc

@@ -130,7 +130,7 @@ $ oc get -o jsonpath='{.status.infrastructureName}{"\n"}' infrastructure cluster
 ifndef::infra[]
 <2> Specify the infrastructure ID and node label.
 <3> Specify the node label to add.
-<4> Specify the vSphere VM network to deploy the machine set to.
+<4> Specify the vSphere VM network to deploy the machine set to. This VM network must be where other compute machines reside in the cluster.
 <5> Specify the vSphere VM clone of the template to use, such as `user-5ddjd-rhcos`.
 +
 [IMPORTANT]
@@ -149,7 +149,7 @@ ifdef::infra[]
 <2> Specify the infrastructure ID and `<infra>` node label.
 <3> Specify the `<infra>` node label.
 <4> Specify a taint to prevent user workloads from being scheduled on infra nodes.
-<5> Specify the vSphere VM network to deploy the machine set to.
+<5> Specify the vSphere VM network to deploy the machine set to. This VM network must be where other compute machines reside in the cluster.
 <6> Specify the vSphere VM template to use, such as `user-5ddjd-rhcos`.
 <7> Specify the vCenter Datacenter to deploy the machine set on.
 <8> Specify the vCenter Datastore to deploy the machine set on.

modules/windows-machineset-vsphere.adoc

@@ -67,13 +67,12 @@ $ oc get -o jsonpath='{.status.infrastructureName}{"\n"}' infrastructure cluster
 <2> Specify the Windows machine set name. The machine set name cannot be more than 9 characters long, due to the way machine names are generated in vSphere.
 <3> Configure the machine set as a Windows machine.
 <4> Configure the Windows node as a compute machine.
-<5> Specify the vSphere VM network to deploy the machine set to.
-<6> Specify the full path of the Windows vSphere VM template to use, such as `/Datacenter/vm/ocp4-llplx/windows-golden-image`. The name must be unique.
+<5> Specify the vSphere VM network to deploy the machine set to. This VM network must be where other Linux compute machines reside in the cluster.
+<6> Specify the full path of the Windows vSphere VM template to use, such as `golden-images/windows-server-template`. The name must be unique.
 +
 [IMPORTANT]
 ====
-Do not specify the original VM template. The VM template must remain off and must be cloned for new {op-system} machines. Starting the VM template configures the VM template as a VM on the platform, which prevents it from being used as a template that machine sets can apply configurations to.
-//This admonition note also appears in `modules/installation-vsphere-machines.adoc`.
+Do not specify the original VM template. The VM template must remain off and must be cloned for new Windows machines. Starting the VM template configures the VM template as a VM on the platform, which prevents it from being used as a template that machine sets can apply configurations to.
 ====
 +
 <7> The `windows-user-data` is created by the WMCO when the first Windows machine is configured. After that, the `windows-user-data` is available for all subsequent machine sets to consume.

windows_containers/creating_windows_machinesets/creating-windows-machineset-vsphere.adoc

@@ -26,6 +26,12 @@ include::modules/machine-api-overview.adoc[leveloffset=+1]
 You must prepare your vSphere environment for Windows container workloads by creating the vSphere Windows VM golden image and enabling communication with the internal API server for the WMCO.
 
 include::modules/creating-the-vsphere-windows-vm-golden-image.adoc[leveloffset=+2]
+
+[id="additional-resources_creating-windows-machineset-vsphere"]
+==== Additional resources
+
+* xref:../../windows_containers/enabling-windows-container-workloads.adoc#configuring-secret-for-wmco_enabling-windows-container-workloads[Configuring a secret for the Windows Machine Config Operator]
+
 include::modules/enabling-internal-api-server-vsphere.adoc[leveloffset=+2]
 
 include::modules/windows-machineset-vsphere.adoc[leveloffset=+1]