Creating a Windows Stemcell for vSphere Using stembuild (Beta)

This topic describes how to create a BOSH stemcell for Pivotal Application Service (PAS) for Windows on VMware vSphere using stembuild.

Overview

Before you can deploy PAS for Windows on vSphere, you must create a BOSH stemcell for Windows, a versioned operating system image. The BOSH stemcell that you create in this topic is based on Windows Server, version 1803.

To create a BOSH stemcell for Windows on vSphere, do the following:

  1. Create a Base VM for the BOSH Stemcell
  2. Install Windows Updates
  3. Clone the Base VM
  4. Construct the BOSH Stemcell
  5. Package the BOSH Stemcell
  6. Upload the BOSH Stemcell to Ops Manager

If you already have a BOSH stemcell for Windows on vSphere, see Monthly Stemcell Upgrades.

Prerequisites

  • A vSphere environment
  • A Windows Server, version 1803 ISO
  • The stembuild command line interface (CLI) from a release in Stemcells for PCF (Windows) on Pivotal Network that corresponds to the operating system of your local host and the stemcell version that you want to build
  • 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, Version 1803 ISO

To upload the Windows Server, version 1803 ISO to vSphere, do the following:

  1. Log in to the vSphere Web Client.

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

  2. Click Storage and select a datastore.
  3. Select or create a folder where you want to upload the Windows Server, version 1803 ISO.
  4. Click Upload a File and select the Windows Server, version 1803 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, do the following:

  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, do the following:
    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, do the following:
    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, do the following step:
    1. For Guest OS Family, select Windows.
    2. For Guest OS Version, 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, do the following:
      1. Select Datastore ISO File.
      2. Select the Windows Server, version 1803 ISO file you uploaded to your datastore and click OK.
      3. 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, do the following:

  1. After creating the VM, click Power > Power On in the Actions tab for your VM. Power on
  2. Select Windows Server Standard.
  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:

Get-CimInstance Win32_OperatingSystem | Select-Object
Caption, Version, ServicePackMajorVersion, OSArchitecture, CSName, WindowsDirectory

The output should include Version: 10.0.17134.

Install VMware Tools

To install VMware Tools on the base VM, do the following:

  1. In the vSphere Web Client, right-click the base VM and select Guest OS > Install VMware Tools.
  2. Navigate to the D: drive and run setup64.exe.
  3. Restart the VM to complete the installation.

Step 2: Install Windows Updates

Install Windows updates on the base VM using your preferred procedure. For example, you can install Windows updates by following the steps below. This procedure requires internet access.

  1. On the base VM, run the SConfig utility.
  2. Select Download and Install Updates.
  3. Enter A to search for all updates.
  4. For Select an option, enter A to install all updates.

You may need to restart the base VM while installing the updates.

Step 3: Clone the Base VM

To clone the base VM, do the following in the vSphere Web Client:

  1. Power down the base VM.
  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 will run Windows updates on this VM for future stemcells.

Step 4: Construct the BOSH Stemcell

Before constructing the BOSH stemcell, collect the following information:

  • Target VM IP address
  • Target VM username
  • Target VM password
  • vCenter inventory path to the target VM in the /MY-DATA-CENTER/vm/MY-FOLDER/MY-VM format where:
    • MY-DATA-CENTER is the name of the data center.
    • vm is a static string.
    • MY-FOLDER is the name of the folder that contains the VM.
    • MY-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.

To construct the BOSH stemcell, run the following command from your local host:

./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

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-1803-7.
  • 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.

Note: This operation may take up to an hour to complete and results in a powered-off target Windows VM in your vSphere environment. During construct execution, the WinRM connection terminates. This behavior is expected, and the construct command is still being executed. Do not attempt to re-run the construct command.

If you want to view the status of construct, you can log in to the target VM and do the following:

  1. Start PowerShell.
  2. Run the following command:

    Get-Content -Path "C:\provision\log.log" -Wait
    

Step 5: Package the BOSH Stemcell

Before packaging the BOSH stemcell, collect the following information:

  • vCenter inventory path to the target VM in the /MY-DATA-CENTER/vm/MY-FOLDER/MY-VM format where:
    • MY-DATA-CENTER is the name of the data center.
    • vm is a static string.
    • MY-FOLDER is the name of the folder that contains the VM.
    • MY-VM is the name of the target VM.
  • vCenter username
  • vCenter password
  • vCenter URL

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

./STEMBUILD-BINARY package -vcenter-url VCENTER-URL -vcenter-username VCENTER-USERNAME -vcenter-password VCENTER-PASSWORD -vm-inventory-path INVENTORY-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-1803-7.
  • 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.

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

Step 6: Upload the BOSH Stemcell to Ops Manager

To upload the BOSH stemcell to Ops Manager, do the following:

  1. In Ops Manager, navigate to Stemcell Library.
  2. Upload your BOSH stemcell.
  3. Deploy the PAS for Windows tile.

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, do the following:

  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 PAS for Windows tile.

Known Issues

Authentication Error with Special Characters in stembuild Commands

Symptom

./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.

Workaround

If your vCenter username or password contains /, #, or :, set the following environment variables:

export GOVC_USERNAME=VCENTER-USERNAME
export GOVC_PASSWORD=VCENTER-PASSWORD

Where:

  • VCENTER-USERNAME is your vCenter account username. For example, johndoe.
  • VCENTER-PASSWORD is your vCenter account password. For example, pass#word.

If you are using other special characters, add single quotes around the input parameters. For example:

./STEMBUILD-BINARY package -vcenter-url VCENTER-URL -vcenter-username 'admin@' -vcenter-password VCENTER-PASSWORD -vm-inventory-path INVENTORY-PATH
Create a pull request or raise an issue on the source for this page in GitHub