Creating a Windows Stemcell for vSphere Using stembuild

This topic describes how to create a BOSH stemcell for Windows on vSphere using stembuild.

Overview of Windows Stemcell Creation

A BOSH stemcell is a versioned operating system image.

You must create a BOSH stemcell for Windows before you can deploy the following products on vSphere:

  • Pivotal Application Service for Windows (PASW)
  • Enterprise Pivotal Container Service (Enterprise PKS) with Windows workers in Kubernetes clusters

To create a Windows stemcell for vSphere, you create a base Windows VM from a volume-licensed ISO and subsequently maintain that base template with all Windows-recommended security updates, but without the BOSH dependencies.

The Windows VM with security updates serves as the base for all future stemcells produced from clones of that base VM. This enables you to build new stemcells without having to run Windows updates from scratch each time. You can also use a “snapshot” feature to maintain an updated Windows image that does not contain the BOSH dependencies.

Pivotal recommends installing any available critical updates and then rebuilding the stemcell from a clone of the original VM.

The BOSH stemcell that you create in this topic is based on Windows Server 2019. If you already have a BOSH stemcell for Windows on vSphere, see Monthly Stemcell Upgrades below.

For more information, see Best Practices for Stembuild for Tanzu Application Service & Tanzu Kubernetes Grid Integrated Edition in VMware Tanzu Tech Tutorials.

Overview of Stembuild

Stembuild is a binary that you use to build BOSH stemcells for Windows Server 2019.

Stembuild creates a BOSH stemcell from a base Windows image. The stembuild CLI has two commands, construct and package, which you run against a Windows Server 2019 VM. Step 4: Construct the BOSH Stemcell and Step 5: Package the BOSH Stemcell below explain how to run these commands.

Before using stembuild to create a stemcell, you need to create a Windows Server 2019 VM and update the VM with the latest Windows updates. Step 1: Create a Base VM for the BOSH Stemcell, Step 2: Configure the Base VM, and Step 3: Clone the Base VM below explain how to prepare the Windows Server 2019 VM.

Prerequisites

Before you create a BOSH stemcell for Windows on vSphere, you must have:

  • A vSphere environment. To ensure the VM hardware used by the stemcell is compatible with your deployment environment’s ESXi/ESX host and vCenter Server versions, see ESXi/ESX hosts and compatible virtual machine hardware versions list (2007240) in the VMware Knowledge Base.

  • An ISO for a Windows Server 2019 Server Core installation, build number: 17763, from Microsoft Developer Network (MSDN) or Microsoft Volume Licensing Service Center (VLSC). The Windows Server 2019 ISO must be a clean, base ISO file. You can use an evaluation copy for testing, but Pivotal does not recommend an evaluation copy for production, as the licensing expires. For more information, see the Windows Server documentation or the Microsoft Volume Licensing Service Center website.

    Note: A clean ISO file has no custom scripts or tooling. For example, the ISO must have no logging or antivirus tools installed.

  • A download of the stembuild command line interface (CLI) from a 2019.x release in Stemcells (Windows) on Pivotal Network.

    • To build a Windows stemcell for PASW or PKS, use the vSphere stembuild CLI for Windows corresponding to both the operating system of your local host and the stemcell version that you want to build.
    • For Windows stemcell and stembuild CLI version compatibilities with PKS, see the Product Snapshot table in the release notes for your PKS version:
  • Microsoft Local Group Policy Object Utility (LGPO) downloaded to the same folder as your stembuild CLI.

  • The minimum vCenter user permissions required to use stembuild for vSphere stemcells, specifically:

    • VirtualMachine.GuestOperations.Modify
    • VirtualMachine.GuestOperations.Execute
    • VirtualMachine.GuestOperations.Query
    • VirtualMachine.Config.AddRemoveDevice
    • VirtualMachine.Interact.SetCDMedia
    • VApp.Export
    • System.Anonymous*
    • System.Read*
    • System.View*

Permissions marked with an * are generated upon creating a new user in vCenter and cannot be set within the vCenter UI.

Step 1: Create a Base VM for the BOSH Stemcell

This section describes how to create, configure, and verify a base VM for Windows from a volume-licensed ISO.

Upload the Windows Server 2019 ISO

To upload the Windows Server 2019 ISO to vSphere:

  1. Log in to the vSphere Web Client.

    Note: The instructions in this topic are based on vSphere v6.0.

  2. Click Storage and select a datastore.

  3. Select or create a folder where you want to upload the Windows Server 2019 ISO.

  4. Click Upload a File and select the Windows Server 2019 ISO.

You can use the scp utility instead of the vSphere Web Client to copy the file directly to the datastore server.

Create and Customize a Base VM

To create and customize a base VM:

  1. In the vSphere Web Client, click the VMs and Templates view to display the inventory objects.

  2. Right-click an object and select New Virtual Machine > New Virtual Machine.

  3. On the Select a creation type page, select Create a new virtual machine and click Next. New vm

  4. On the Select a name and folder page:

    1. Enter a name for the VM.
    2. Select a location for the VM.
    3. Click Next.
  5. On the Select a compute resource page, select a compute resource to run the VM and click Next.

  6. On the Select storage page:

    1. Select a VM Storage Policy.
    2. Select the destination datastore for the VM configuration files and virtual disks.
    3. Click Next.
  7. On the Select compatibility page, for the Compatible with configuration setting, select ESXi 6.0 and later and click Next.

  8. On the Select a guest OS page:

    1. For Guest OS Family, select Windows.
    2. For Guest OS Version, select Microsoft Windows Server 2019. If Microsoft Windows Server 2019 is not available, select Microsoft Windows Server 2016.
    3. Click Next.
  9. On the Customize hardware page, configure the VM hardware using the information below and click Next.

    1. For New Hard disk, specify 30 GB or greater.
    2. For New CD\DVD Drive:
    3. Select Datastore ISO File.
    4. Select the Windows Server 2019 ISO file you uploaded to your datastore and click OK.
    5. Enable the Connect At Power On checkbox.
  10. Review the configuration settings on the Ready to complete page and click Finish.

Install Windows Server

To install Windows Server on the base VM:

  1. After creating the VM, click Power > Power On in the Actions tab for your VM. Power on

  2. Select Windows Server 2019 Standard. Windows version

  3. Select Custom installation.

  4. Complete the installation process and enter a password for the Administrator user.

Verify OS

To verify that you are using the correct OS version, run the following PowerShell command on the base VM:

[System.Environment]::OSVersion.Version

The output should display the following:

[System.Environment]::OSVersion.Version
Major    Minor    Build    Revision
----     ----     -----    --------
10        0       17763    0

Install VMware Tools

To install VMware Tools on the base VM:

  1. In the vSphere Web Client, right-click the base VM and select Guest OS > Install VMware Tools.

  2. When prompted, choose Mount.

  3. Log in to the the VM.

  4. Navigate to the D: drive.

  5. To install the VMware Tools, run:

    setup64.exe
    
  6. Wait for a pop-up dialog.

    Note: The VMware Tools install window might display behind the command line window. To avoid this, shrink or minimize the command line window while you are waiting.

  7. When prompted, follow the instructions to finish the install.

  8. To complete the installation, restart the VM.

Step 2: Configure the Base VM

Install all the Windows Server updates so that you have the latest, most secure, version of the Windows Server operating system.

To configure the base VM network settings and install Windows updates:

  1. From the vSphere Web Client, right-click the base VM and select Open Console.

  2. On the command line, enter sconfig to run the SConfig utility.

  3. On the Server Configuration page, enter 6 for Download and Install Updates.

  4. Enter A to search for all updates.

  5. For Select an option, enter A to install all updates. You might need to restart the base VM while installing the updates.

  6. On the Server Configuration page, enter 8 for Network Settings.

  7. On the Network Settings page:

    1. Under Available Network Adapters, enter the number that corresponds to your network adapter.
    2. Enter 1 to set the network adapter address.
    3. Enter S to set a static IP address.
    4. Enter a static IP address.
    5. Enter a subnet mask, or leave the field blank to use the default value.
    6. Enter the default gateway.
    7. Enter 13 to exit to the command line.
  8. From the vSphere Web Client, select Actions > Edit Settings.

  9. In the CD/DVD drive 1 row, disable the Connected checkbox. Do not remove the CD drive.

  10. Restart the VM.

  11. After the VM restarts, verify that you can ping the IP address you assigned to the base VM.

Step 3: Clone the Base VM

To clone the base VM:

  1. From the vSphere Web Client, power down the base VM. This is important because your base VM and the clone VM you create share the same IP address.

  2. Right-click the base VM.

  3. Select Clone > Clone to Virtual Machine. This clone is your target VM. Clone vm

  4. Save the base VM. You run Windows updates on this VM for future stemcells.

  5. Take snapshots of both your base and target VMs. If there is an issue when you run stembuild, use these snapshots to revert to a clean state. For more information, see Managing snapshots in vSphere Web Client in the VMware Knowledge Base.

  6. To start the target VM, click Power > Power On in the Actions tab for your VM.

Step 4: Construct the BOSH Stemcell

To create your BOSH stemcell, complete the following tasks:

  1. Collect the following information from the vCenter Web Client Inventory > VMs and Templates tab:

    • Target VM IP address
    • Target VM username
    • Target VM password
    • vCenter inventory path to the target VM in the /YOUR-DATA-CENTER/vm/YOUR-FOLDER/YOUR-VM format, where:
      • YOUR-DATA-CENTER is the name of the data center.
      • vm is a static string.
      • YOUR-FOLDER is the name of the folder that contains the VM. If the target VM is not in a folder, use the /YOUR-DATA-CENTER/vm/YOUR-VM format instead.
      • YOUR-VM is the name of the target VM.
    • vCenter username
    • vCenter password
    • vCenter URL

    Note: The target VM must be routable from your local host. Before running the construct command, ensure you are logged out of the target VM.

  2. To construct the BOSH stemcell, run the following command from the folder where you downloaded the CLI:

    ./STEMBUILD-BINARY construct  ^
      -vm-ip 'TARGET-VM-IP'  ^
      -vm-username TARGET-USERNAME  ^
      -vm-password 'TARGET-VM-PASSWORD'  ^
      -vcenter-url VCENTER-URL  ^
      -vcenter-username VCENTER-USERNAME  ^
      -vcenter-password 'VCENTER-PASSWORD'  ^
      -vm-inventory-path 'INVENTORY-PATH'  ^
      -vcenter-ca-certs 'CUSTOM-CERTS-PATH'
    

    Where:

    • STEMBUILD-BINARY is the stembuild file for the version of your local host operating system and the version of the stemcell that you want to build. For example, stembuild-windows-2019-2.
    • TARGET-VM-IP is the IP address of your target VM.
    • TARGET-USERNAME is the username of an account with administrator privileges.
    • TARGET-VM-PASSWORD is the password for the administrator account. The password must be enclosed in single quotes.
    • VCENTER-URL is the URL of your vCenter.
    • VCENTER-USERNAME is the username of your account in vCenter.
    • VCENTER-PASSWORD is your password. The password must be enclosed in single quotes.
    • INVENTORY-PATH is the vCenter inventory path to the target VM.
    • CUSTOM-CERTS-PATH is the file path to custom CA certificates for the destination vCenter. The -vcenter-ca-certs flag is optional. For more information, see Authenticate into a Destination vCenter Using CA Certificates below.

    For example:

    ./STEMBUILD-BINARY construct -vm-ip '192.0.2.254' -vm-username user001 -vm-password 'P1a2s3Sword5' -vcenter-url example.com -vcenter-username user002 -vcenter-password 'P1a2s3Sword5' -vm-inventory-path '/datacenter/vm/folder/test-vm'
    2020-01-29T08:52:26.4523812-08:00 Successfully created stemcell version file.
    Finished executing setup script.
    WinRM has been disconnected so the VM can reboot. Preparing the VM to be shutdown.
    2020-01-29T16:53:27.505532+00:00 Still preparing VM...
    2020-01-29T16:54:27.94085+00:00 Still preparing VM...
    2020-01-29T16:55:28.374568+00:00 Still preparing VM...
    Stembuild construct has finished running and the VM has now been shutdown. Run 'stembuild package' to finish building the stemcell.
    

    stembuild construct creates a powered-off target Windows VM in your vSphere environment.

    Your stembuild construct operation may take up to an hour to complete. The following is an example of the messages displayed as stembuild construct runs and completes:
    2020-01-29T08:52:26.4523812-08:00 Successfully created stemcell version file.
    Finished executing setup script.
    WinRM has been disconnected so the VM can reboot. Preparing the VM to be shutdown.
    2020-01-29T16:53:27.505532+00:00 Still preparing VM...
    2020-01-29T16:54:27.94085+00:00 Still preparing VM...
    2020-01-29T16:55:28.374568+00:00 Still preparing VM...
    Stembuild construct has finished running and the VM has now been shutdown. Run 'stembuild package' to finish building the stemcell.
    

    Note: Although the WinRM connection terminates during construct execution, construct is still running. Do not attempt to re-run the construct command.

  3. (Optional) To monitor the status of your construct job:

    1. Log in to the target VM.
    2. Start PowerShell.
    3. Run:
      Get-Content -Path "C:\provision\log.log" -Wait
    


For more information about stembuild construct, see stembuild construct in the Cloud Foundry stembuild GitHub repository.

Step 5: Package the BOSH Stemcell

To package the BOSH stemcell:

  1. Gather the vCenter Web Client VMs and Templates information that you recorded in the previous step:

    • vCenter inventory path to the target VM in the /YOUR-DATA-CENTER/vm/YOUR-FOLDER/YOUR-VM format, where:
      • YOUR-DATA-CENTER is the name of the data center.
      • vm is a static string.
      • YOUR-FOLDER is the name of the folder that contains the VM. If the target VM is not in a folder, use the /YOUR-DATA-CENTER/vm/MY-VM format instead.
      • YOUR-VM is the name of the target VM.
    • vCenter username
    • vCenter password
    • vCenter URL
  2. Shut down the VM. If you do not shut down the VM before you continue to the next step, the package command fails stating that the storage location for the VM could not be read.

  3. To package the BOSH stemcell, run the following PowerShell command from your local host:

    ./STEMBUILD-BINARY package ^
      -vcenter-url VCENTER-URL ^
      -vcenter-username VCENTER-USERNAME ^
      -vcenter-password VCENTER-PASSWORD ^
      -patch-version PATCH-VERSION ^
      -vm-inventory-path 'INVENTORY-PATH'  ^
      -vcenter-ca-certs 'CUSTOM-CERTS-PATH'
    

    Where:

    • STEMBUILD-BINARY is the stembuild file for the version of your local host operating system and the version of the stemcell that you want to build. For example, stembuild-windows-2019-2.
    • VCENTER-URL is the URL of your vCenter.
    • VCENTER-USERNAME is the username of your account in vCenter.
    • VCENTER-PASSWORD is your password. The password must be enclosed in single quotes.
    • INVENTORY-PATH is the vCenter inventory path to the target VM.
    • CUSTOM-CERTS-PATH is the file path to custom CA certificates for the destination vCenter. The -vcenter-ca-certs flag is optional. For more information, see Authenticate into a Destination vCenter Using CA Certificates below.

      Note: This command creates a stemcell on your local host in the folder where you ran the command and might take up to 30 minutes to complete.

For more information about stembuild package, see stembuild package in the Cloud Foundry stembuild GitHub repository.

Step 6: Upload the BOSH Stemcell to Ops Manager

To upload the BOSH stemcell to Ops Manager:

  1. In Ops Manager, navigate to Stemcell Library.

  2. Upload your BOSH stemcell.

  3. Deploy the PASW or Enterprise PKS tile.


For more information about stembuild, see Stembuild in the Cloud Foundry stembuild GitHub repository.

Monthly Stemcell Upgrades

After Microsoft releases operating system updates, you should upgrade your BOSH stemcell. Microsoft typically releases Windows updates on the second Tuesday of each month.

To upgrade your BOSH stemcell:

  1. Install Windows Updates on the base VM.

  2. Clone the Base VM.

  3. Construct the BOSH Stemcell.

  4. Package the BOSH Stemcell.

  5. Replace the existing stemcell in the Ops Manager stemcell library with this new stemcell.

  6. Deploy the PASW or Enterprise PKS tile.

Known Issues

Authentication Error with Special Characters in stembuild Commands

Symptom

You authenticate with vCenter and see this error:

./out/stembuild: ServerFaultCode: Cannot complete login due to an incorrect user name or password.
vcenter_client - unable to validate url: vcenter.example.com

Explanation

stembuild uses govc libraries. These libraries cannot parse the special characters /, #, and :. This results in errors when authenticating with vCenter.

You might also experience this issue on Windows if your password includes a single quote character, '. This also affects the Inventory path if it contains a single quote or a space.

Workaround

If your vCenter username or password contains /, #, or :, or ' on Windows, set these environment variables:

  • For Linux:

    export GOVC_USERNAME=VCENTER-USERNAME
    export GOVC_PASSWORD=VCENTER-PASSWORD
    
  • For Windows:

    set GOVC_USERNAME=VCENTER-USERNAME
    set GOVC_PASSWORD=VCENTER-PASSWORD
    set GOVC_PATH=VCENTER-INVENTORY-PATH
    

Where:

  • VCENTER-USERNAME is your vCenter account username. For example, johndoe.
  • VCENTER-PASSWORD is your vCenter account password. For example, pass#word.
  • VCENTER-INVENTORY-PATH is the location of your VM in the cluster inventory.

If you use other special characters, add single quotes around the input parameters, or set them in an environment variable as described above.

For example:

  • For Linux:

    ./STEMBUILD-BINARY package \
      -vcenter-url VCENTER-URL \
      -vcenter-username 'admin@' \
      -vcenter-password VCENTER-PASSWORD \
      -patch-version PATCH-VERSION \
      -vm-inventory-path 'INVENTORY-PATH' \
      -vcenter-ca-certs 'CUSTOM-CERTS-PATH'
    

    Where:

    • STEMBUILD-BINARY is the stembuild file for the version of your local host operating system and the version of the stemcell that you want to build. For example, stembuild-windows-2019-2.
    • VCENTER-URL is the URL of your vCenter.
    • VCENTER-PASSWORD is your password. The password must be enclosed in single quotes.
    • INVENTORY-PATH is the vCenter inventory path to the target VM.
    • CUSTOM-CERTS-PATH is the file path to custom CA certificates for the destination vCenter. The -vcenter-ca-certs flag is optional. For more information, see Authenticate into a Destination vCenter Using CA Certificates below.
  • For Windows:

    set GOVC_PASSWORD=VCENTER-PASSWORD
    ./STEMBUILD-BINARY package ^
      -vcenter-url VCENTER-URL ^
      -vcenter-username %GOVC_USERNAME% ^
      -vcenter-password %GOVC_PASSWORD% ^
      -patch-version PATCH-VERSION ^
      -vm-inventory-path %GOVC_PATH% ^
      -vcenter-ca-certs 'CUSTOM-CERTS-PATH'
    

    Where:

    • VCENTER-PASSWORD is your vCenter account password. For example, A_Strange!PAssword@Here#1.
    • STEMBUILD-BINARY is the stembuild file for the version of your local host operating system and the version of the stemcell that you want to build. For example, stembuild-windows-2019-2.
    • VCENTER-URL is the URL of your vCenter.
    • PATCH-VERSION is the patch version for the stemcell being built. PATCH-VERSION can be specified as an unquoted version name, for example 2019.12.3, or as a quoted patch number, for example “3”.
    • CUSTOM-CERTS-PATH is the file path to custom CA certificates for the destination vCenter. The -vcenter-ca-certs flag is optional. For more information, see Authenticate into a Destination vCenter Using CA Certificates below.

      Note: Windows environment variables do not automatically override vCenter command line parameters, so you must specify the environment variables in the vCenter command as shown above.

Authenticate into a Destination vCenter Using CA Certificates

Symptom

You are running stembuild from a location outside of your destination vCenter and stembuild is unable to authenticate.

Explanation

You are running stembuild from a location with different vCenter permissions than your target VM.

Solution

You must provide stembuild with the CA certificates needed to authenticate into your destination vCenter.

To stage CA certificates for stembuild to use to access a target VM in the destination vCenter:

  1. Open your destination vCenter’s homepage.
  2. Go to the bottom of the grey box on the right side of the vCenter homepage.
  3. Select Download trusted root CA certificates.
  4. Copy the downloaded CA certificates to a path accessible to stembuild.

To use the staged CA certificates with stembuild, include the optional -vcenter-ca-certs flag in your stembuild command as shown in the example construct and package command lines above.