In IBM PureApplication System version 188.8.131.52, you are now able to deploy virtual system and virtual application workloads running Microsoft® Windows. To take advantage of this feature, you must first provide the Windows binaries using a “bring your own virtual machine” technique to create a custom Windows image for use in PureApplication System.
This article describes how to use IBM Image Construction and Composition Tool version 184.108.40.206 to capture an image of a Windows virtual machine running on a VMware ESX hypervisor external to PureApplication System. Then, after capturing the base image, you will see how you can use the tool to configure your Windows image for use in virtual system and virtual application patterns within PureApplication System.
Before you begin
Before you begin working with the Image Construction and Composition Tool, you will need a running Windows virtual machine with a compatible operating system, and you will need to install the Image Construction and Composition Tool.
Building a Windows virtual machine for base image creation
You need a running Windows virtual machine with one of the following operating systems:
- Microsoft Windows Server 2008 R2 Enterprise Edition
- Microsoft Windows Server 2012 Standard Edition
This virtual machine must be running on a VMware ESX hypervisor external to PureApplication System. The supported VMware ESX versions are:
- VMware ESX 4.0 or 4.1
- VMware ESXi 4.0, 4.1 or 5.0. (VMware ESXi 5.1 is not currently supported.)
For Windows 2012, full VMware support is enabled in ESXi 5.0 Update 1 Patch 4 (build 921926) and later. A minimum of this ESX version is required to build Windows 2012 images using Image Construction and Composition Tool.
There are various ways to create a new virtual machine in VMware ESX. Whether you clone from an existing virtual machine, deploy from a template, or build from scratch, you must ensure that these requirements are met:
- VMware Tools is installed on the virtual machine. To install VMware Tools on the running virtual machine in vSphere Client, left click on the virtual machine, select Guest > Install/Upgrade VMware Tools and go to the virtual machine console to complete the installation.
- The built-in Administrator account is enabled. Domain user account is not supported.
- Port 445 is accessible.
- IPV6 protocol is enabled.
- Business Use Notice is not set in the registry.
- Any customizations required by your organization have been made. For example, if you will require remote desktop access or a specific security policy in your final image, it should be configured at this point.
Installing the Image Construction and Composition Tool
Before you begin, you will need to install the Image Construction and Composition Tool version 220.127.116.11. In order to create a new Windows image from a virtual machine running outside of PureApplication System, your Image Construction and Composition Tool will require network connectivity to both the virtual machine you will be capturing, as well as the VMware ESX hypervisor hosting the virtual machine.
Depending on your network configuration, you can choose one of the following options for installing Image Construction and Composition Tool:
- Deploy Image Construction and Composition Tool as a virtual application instance in PureApplication System
Image Construction and Composition Tool version 18.104.22.168 can be deployed as a virtual application in PureApplication System version 1.1. If virtual machines deployed from your PureApplication System are on the same network as your external VMware ESX hypervisor and Windows virtual machines, you can choose this option to simplify the installation process.
To deploy Image Construction and Composition Tool as a virtual application:
- Deploy the ICCT virtual application pattern from the Image Construction and Composition Tool 1.2 pattern type (Figure 1).
Figure 1. Deploy Image Construction and Composition Tool as a virtual application pattern
- Launch the Image Construction and Composition Tool web interface from the endpoint link on your deployed virtual application instance (Figure 2).
Figure 2. Endpoint link to the Image Construction and Composition Tool web interface from virtual application instance
- Deploy the ICCT virtual application pattern from the Image Construction and Composition Tool 1.2 pattern type (Figure 1).
- Install Image Construction and Composition Tool on a Linux server
Image Construction and Composition Tool can also be installed as a standalone application (Figure 3). Installation is supported on SuSE Linux® Enterprise Server and Red Hat Enterprise Linux. When creating Windows images, image artifacts such as disk files will be transferred to your Image Construction and Composition Tool server. It is recommended that you allocate a minimum of 100GB disk space to ensure enough space for building your Windows images. If you plan to build particularly large images or multiple images simultaneously, additional space may be required.
Figure 3. Download link for the Image Construction and Composition Tool binaries
Creating a cloud provider
In the Image Construction and Composition Tool, cloud providers are used to define the environment used to create your images. In the Windows case, a VMware ESX cloud provider must be created with details for the ESX hypervisor hosting your running Windows virtual machine (Figure 4). The same cloud provider will also be used to deploy a temporary virtual machine when configuring the image for use in PureApplication System.
Figure 4. Manage cloud providers in Image Construction and Composition tool
You will need the following information to create a new VMware ESX cloud provider (Figure 5):
- VMware ESX IP address, user name and password: This is the hypervisor hosting your running Windows virtual machine. It will also be used to deploy a temporary virtual machine as you customize your image.
- VMware datastore and network: This information will be used to create temporary virtual machines on your ESX hypervisor as you customize your image
- Deployment subnet, netmask, gateway, DNS and IP address range: This information will be used to configure the network on your temporary virtual machines as you customize your image.
Figure 5. Summary panel of the cloud provider creation wizard
Create an image from a running virtual machine
Once you have your cloud provider defined and your target Windows virtual machine running, you are now ready to create a base image from the running virtual machine.
- Start by navigating to the Build and manage images page in your Image Construction and Composition Tool (Figure 6).
Figure 6. Build images
- Take care to select the VMware ESX cloud provider created earlier (Figure 7).
Figure 7. Select the VMware ESX cloud provider on the Build and Manage Images page
- Next, click the New Image button (Figure 8).
Figure 8. New Image button
- On the Create image dialog, select Create image from a running virtual machine (Figure 9).
Figure 9. Create image dialog
- You will be prompted to enter details about the image you are
creating. The Name, Universal ID,
Version and Description values are
used to create your new Windows image. The IP
Address, User ID and Password values are used to connect to the virtual machine you are capturing (Figure 10).
Figure 10. Import Images from Running VM dialog
- During this process, Image Construction and Composition Tool will
install the IBM Virtual Solutions Activation Engine on your Windows
virtual machine, which will be used to activate future unique deployments of this Windows image. Following this, a process known as “resetting the virtual machine” will be invoked and the virtual machine will be shut down. As part of the reset procedure, certain aspects of the machine will be generalized in order to allow the image to be customized later when deployed through PureApplication System. As a result, to access the original virtual machine, you might need to reconfigure the virtual machine network after it is captured. You will also need to reset the Administrator password, which will be set to “Passw0rd2” during the reset process. The virtual machine will then be captured and the image will be copied to the Image Construction and Composition Tool server. The time needed to complete this image import process will depends on the hypervisor environment and the network speed. Click the Refresh button on the image to check the status of the import (Figure 11).
Figure 11. Refresh button
Configure the image for use with IBM PureApplication System
Now that you have created a base Windows image from a running virtual machine, it is time to configure it for use with PureApplication System by extending and synchronizing the image using Image Construction and Composition Tool. The extend image process enables you to add several customizations, including custom software bundles, personalities, and licenses, if desired. During the image extension process, Image Construction and Composition Tool will create a temporary virtual machine on your VMware ESX cloud provider in order to make the requested configurations. The temporary virtual machine will then be captured to create a second Windows image containing the new configurations.
- Start by extending your base image (Figure 12).
Figure 12. Extend Image button
- You will be prompted to enter the Name,
Universal ID, Version and Description for the new image (Figure 13).
Figure 13. Extend Image dialog
- Once the image has been extended, you will see a new image entry created in your Image Construction and Composition Tool. You will use this new image entry to indicate what type of customizations should be made to the image. Put the image into edit mode to begin customization (Figure 14).
Figure 14. Start Editing button
You might notice that there are two software bundles already listed in your image. The first is a representation of the Windows operating system, as detected by Image Construction and Composition Tool when you initially captured the image from your running virtual machine. The other is the Enablement Bundle Windows for VMware, which permits Image Construction and Composition Tool to customize your image; if it is not already present on your image, it will be automatically added and your image will be Out of sync, meaning there is at least one software bundle planned to be installed in the image.
For use in PureApplication Systems virtual systems and virtual applications, you will also require the Enablement Bundle for Virtual Applications and System Plugins on Windows software bundle. This software bundle will be used to install the prerequisite software for PureApplication virtual applications and system plugins, such as cURL, Java™ and OpenSSL. Add this bundle to your image by clicking the Add Software button (Figures 15 and 16).
Figure 15. Add bundle to image dialog
Figure 16. Products included in the Enablement Bundle for Virtual Applications and System Plugins on Windows
- If you have created or imported any additional custom software bundles into the Image Construction and Composition Tool bundle catalog, they can be added to the extended image at this time as well, or you can choose to add them to the image at a later time by performing an additional extend image operation.
- The next step is to configure the personalities in the image. A
personality is a set of custom configuration settings
for a subset of software bundles in the image. You might require multiple personalities in your image if you are including complex software that can be configured in multiple different ways, such as IBM WebSphere® Application Server.
By default, your Windows image will have one personality by default, named OS Part. Expand this part and select the Supports IPv6, Enable instance count selection, and Enable dynamic instance count checkboxes. These settings will ensure that your Windows image is fully functional in all virtual system and virtual application patterns (Figure 17).
Figure 17. OS Part personality configuration for a Windows image that is configured for use with virtual applications and system plugins
- Finally, if you require any license agreements to be included with your image, add them now (Figure 18).
Figure 18. New license file dialog
- Save your changes, and take the image out of edit mode (Figure 19).
Figure 19. Save and Done Editing buttons
- At this point, the image status is listed as Out of Sync, indicating
that you have made changes to your image in Image Construction and
Composition Tool that are not yet installed. To synchronize your
changes, click the Synchronize button (Figure 20).
Figure 20. Synchronize button
- You will be prompted for an Administrator password and Windows Product Key. These values will be used for Image Construction and Composition Tool to create a temporary virtual machine by deploying your original image. All changes planned during the extend process will then be applied on the temporary virtual machine (Figure 21).
Figure 21. Synchronize Image dialog
- Click the Refresh button on the image to check the
synchronization status. Once the synchronization has completed, your image
status will change to Synchronized. At this time, you can log into the temporary virtual machine with Remote Desktop or the VMware vSphere client. The Administrator password will be set to the value specified in the synchronize image dialog to manually verify your changes if desired. To locate your temporary virtual machine's IP address and hostname, expand the Virtual System section in the image details view (Figure 22).
Figure 22. Virtual System details for a Synchronized image
- If you are happy with the state of the temporary virtual machine,
click the Capture button to capture those changes back into your image. The captured disk image will be saved in the Image Construction and Composition Tool (Figure 23).
Figure 23. Capture Image button in Image Construction and Composition Tool
- After all changes have been captured, your image status will change to Completed state when you refresh the image. This is a read-only state in Image Construction and Composition Tool. Additional changes can be made to the image by extending the new image and repeating the synchronization and capture steps described above.
Exporting the image as an OVA
To get your Windows image out of the Image Construction and Composition Tool, you can export the image as an OVA (Open Virtualization Archive) to any SCP-enabled location.
- Click the Export button (Figure 24).
Figure 24. Export Image as OVA button
- Fill out the destination details for your image. For the OVA file format, leave
the default selection as PureApp, IWD 3.1.x, SCP 2.x, VMware vCenter (Figure 25).
Figure 25. Export Image as an OVA dialog in Image Construction and Composition Tool
- To track the export status, click the Open the export status link. This will open a separate browser tab with status details for the export operation (Figure 26).
Figure 26. Export Image Status dialog in Image Construction and Composition Tool
When your image has been exported, the export task status will change to Ready. Once your image has been exported, you are ready to import the image into the PureApplication System catalog.
Importing the image into the PureApplication System catalog
Import the OVA exported from Image Construction and Composition Tool into the virtual image catalog. The OVA file can be imported via HTTP, HTTPS or SCP. To import the image from an HTTP or HTTPS location, simply specify the URL and credentials if required (Figure 27).
Figure 27. Import an image by specifying an HTTP URL in PureApplication System
To import the image from an SCP location, specify the URL as ipaddress:/path (Figure 28).
Figure 28. Import an image by specifying an SCP location and credentials in PureApplication System
Wait for the image import to complete. If you have added any licenses to your image during the image configuration step, you will need to accept them in PureApplication System image catalog before deploying the image for the first time
Using the Windows image in a virtual system pattern
Include your Windows image as part of a virtual system pattern by dragging and dropping the Windows image parts onto the Virtual System pattern editor. Windows parts can be deployed on their own, or in combination with other Windows or other Linux parts in more complex patterns. When deploying a Windows virtual system pattern, you will be prompted for an Administrator password and Windows Product Key. You can also change the default values of the Registered Owner and Registered Org fields, if required. The non-required capitalized parameters such as BOOTSTRAP_URL and AGENT_TOKEN will be automatically populated by PureApplication System during deployment and can be ignored (Figure 29).
Figure 29. Deploy dialog for a Windows virtual system pattern part in PureApplication System
Using the Windows image in a virtual application pattern
To use your image as the base image for virtual applications in PureApplication System, add the image to your Default Deploy Settings. If you are also managing Linux deployments in PureApplication System, you can select a default image for both Linux and Windows (Figures 30 and 31).
Figure 30. Cloud default deploy settings menu in PureApplication System
Figure 31. Add a new default Windows image to the PureSystems_ESX image list in PureApplication System
Once you have selected a Windows image to use as a default, virtual applications with support on Windows can be deployed from the Virtual Application Patterns page. For virtual application deployment, you will be prompted for an Administrator password and Windows Product Key. If the virtual application pattern supports both Linux and Windows, you can select the desired operating system under the Advanced parameters within the deploy dialog (Figure 32).
Figure 32. Deploy dialog for a Windows virtual application in PureApplication System
Automating the Windows image creation process
It is possible to automate the creation of Windows images using the Image Construction and Composition Tool command line interface. The command line interface can be downloaded from the Welcome page of your Image Construction and Composition Tool web interface.
The create_base_image_on_esx_cloud_provider.py script included with this article has been created as an example of how to automate the Windows image creation process described above. In this example, your environment details are read from a properties file, described in more detail below.
When invoked, the script will take the following actions based on the information provided in the properties file:
- Search for an existing VMware ESX cloud provider by the name specified in the properties file. If not found, a new one will be created.
- Search for an existing Windows image with the name and version specified in the properties file. If not found, a new image will be created in one of the following ways:
- Captured from a running virtual machine as described above.
- Imported from an existing OVA. This is useful if you have previously completed the capture from running virtual machine step and exported the resulting image.
- Extend the base image and make the configurations described above. This includes adding the Enablement Bundle for Virtual Applications and System Plugins on the Windows software bundle, as well as modifying the default personality in the image.
- Synchronize and Capture the changes.
- Export the new image as an OVA.
To get started using this script, you will need to provide some input data in a properties file, such as that shown in Listing 1 (see Downloads).
################################################################################ ## PROPERTIES FILE FOR WINDOWS 2008 R2 ENTERPRISE EDITION MAESTRO IMAGE CREATION ################################################################################ ## For unused properties, blank out value but do not delete the key ################################################################################ #Cloud provider properties #If a cloud provider with the specified name exists, it will be reused #Otherwise, it will be created esx.cloudprovider.name=ESX esx.cloudprovider.ipaddress=172.16.80.3 esx.cloudprovider.username=root esx.cloudprovider.password=******** esx.cloudprovider.subnet=172.16.80.0 esx.cloudprovider.netmask=255.255.248.0 esx.cloudprovider.gateway=172.16.80.1 esx.cloudprovider.primarydns=172.16.248.2 esx.cloudprovider.secondarydns= esx.cloudprovider.iprange.start=172.16.84.40 esx.cloudprovider.iprange.end=172.16.84.44 esx.cloudprovider.datastore= https://172.16.80.3/sdk#Datastore#50561174-089a33e9-32d2-0010188f2b48 esx.cloudprovider.networkname=ICON 172 VM Network #Base Image Properties #If a base image with the specified name and version exists in the cloud provider, #it will be reused. Otherwise it will be imported. Specify 'ova' or 'byovm' as #import method baseimage.name=Windows 2008 R2 Enterprise Edition - Base Operating System baseimage.uuid=com.ibm.w2k8r2.enterprise.baseos baseimage.version=22.214.171.124 baseimage.import.method=byovm baseimage.ova.url= baseimage.ipaddress=172.16.82.190 baseimage.username=Administrator baseimage.password=******** baseimage.byovm.export=True #New Image Properties #These values will be used to create the temporary image newimage.osfamily=windows newimage.ismaestro=True newimage.productkey=489J6-VHDMP-X63PK-3K798-CPX3Y newimage.password=********* newimage.name=Windows 2008 R2 Enterprise Edition - Production Image newimage.version=126.96.36.199 newimage.uuid=com.ibm.w2k8r2.enterprise.production #Image Export Properties imageexport.ipaddress=scpaddress imageexport.username=scpuser imageexport.password=scppassword imageexport.path=/exported
To run the script, use the command line interface as follows:
icct -h <hostname> -u <user> -p <password> -d -f create_base_image_on_esx_cloud_provider.py w2k8r2_maestro.properties
You can optionally pass the
-d flag when invoking
the Image Construction and Composition Tool command line
interface to enable debug logging. When invoked with the
-d flag, the command line tool will log to icct.cli\log\cli.log. This log will be overwritten each time the command line tool is invoked. Command line logging is disabled by default, as the log could contain sensitive data.
If your Image Construction and Composition Tool instance was deployed as a virtual application instance in PureApplication System, your command line user name and password will be your PureApplication System user name and password. If you have installed Image Construction and Composition Tool manually, your command line user name and password will be the same as the web interface user name and password you selected at install time.
To enhance this sample script for further customizations needed for your unique Windows images, see the command line interface reference guide in the Information Center.
Save a default product key in the image (Optional)
Before importing the OVA exported from Image Construction and Composition Tool into the PureApplication System catalog, you can manually save the product key in the OVF by completing these steps:
- Use tar to extract the contents of OVA file exported from
Image Construction and Composition Tool. Because you will need
to package the contents of the OVA file in the same order the
contents originally existed, run the following command to get
an ordered list of the files included in the OVA file:
- Modify the following line in the .ovf file, by specifying your product key as the ovf:valueattribute:
<Property ovf:key="productkey" ovf:type="string" ovf:userConfigurable="true" ovf:value="" ovf:required="true">
<Property ovf:key="productkey" ovf:type="string" ovf:userConfigurable="true" ovf:value="XXXXX-XXXXX-XXXXX-XXXXX-XXXXX" ovf:required="true">
- Modify the following line in the osNode*.xml file, by specifying your product key as the value attribute:
<rmpatt:attributedescription="ConfigProductKey.productkey.description" label="ConfigProductKey.productkey.label" key="productkey" locked="false" required="true" type="string" userConfigurable="true" value="">
<rmpatt:attributedescription="ConfigProductKey.productkey.description" label="ConfigProductKey.productkey.label" key="productkey" locked="false" required="true" type="string" userConfigurable="true" value="XXXXX-XXXXX-XXXXX-XXXXX-XXXXX">
- Use tar to package the contents of the OVA file in the same order as it was extracted at the beginning of this task, ensuring the resulting file has an .ova extension.
In the event of a failure you can take the following actions to help with problem determination:
Download logs from the web interface by clicking the Download logs link on the Welcome page, or from the Administrator > Download logs menu option. Download logs will not work properly if the /drouter directory is out of space. You can access the logs directly at the following location on the Image Construction and Composition Tool file system:
Failures during capture of a running virtual machine
Below are some common errors encountered during the capture of a running virtual machine. If you see one of these errors in the Image Construction and Composition Tool trace.log, follow the resolution steps listed below and try again.
- Error: CYOUI3088E: An error has occurred during the import
operation: CYOES0002E: Unable to establish a connection to
Resolution: Verify that the virtual machine is powered on and can be accessed from your Image Construction and Composition Tool server using port 445. Verify that the user name and password provided are correct.
- Error: CYOUI3088E: An error has occurred during the import operation: Error importing the image asset. Cloud Base Image was not created.
Resolution: Verify that the /drouter directory on your Image Construction and Composition Tool has enough space to contain the disk files for the virtual machine you are capturing.
- Error: CYOUI3088E: An error has occurred during the import operation: CYOES0030E: Could not find the virtual machine on the specified cloud provider.
Resolution: Verify that the virtual machine has VMware tools installed, and is hosted on the hypervisor used to create the VMware ESX cloud provider you are working with.
- Error: CYOES0101E: Virtual machines with snapshots are not supported. Delete the snapshots and try the operation again.
Resolution: Delete the snapshots and try the operation again.
Failures during image synchronization
In the Image Construction and Composition Tool web interface, expand the Virtual System section on the image details view to check the virtual system status (Figure 33).
Figure 33. Virtual System status after synchronizing an image in Image Construction and Composition Tool
If the virtual system is listed as Started, download the logs from the download logs link in the virtual system details. These logs contain the standard output and standard error produced by software bundle installations and other customizations that are run during the image synchronization process.
If the virtual system is listed as Deploying or Failed, the temporary virtual machine might have encountered an error during the activation process. You might need to log into the temporary virtual machine to diagnose the problem. Depending on the specific failure, your virtual machine might not be accessible on your network using Remote Desktop. In this case, the vSphere client console will be required to access your virtual machine.
If you log onto the virtual machine using the vSphere console and see the error dialog in Figure 34, check that the product key you entered is correct and valid for the specific version of Windows you are working on. Your product key might be syntactically correct but invalid for the specific OS you are working with; for example, if the Windows 2008 R2 Enterprise Edition key was provided for Windows 2012 Standard Edition OS. You can then run the synchronization again with the correct product key.
Figure 34. Windows sysprep error displayed when an invalid product key is used
Activation engine logs can be found at the following location:
You can also check the activation engine status by running:
Failures during image capture
If your image capture fails and your temporary virtual machine is still started, there might be a problem in one of your reset scripts. During image capture, the reset script for all custom software bundles added to your image will be executed. After a successful reset, the virtual machine will be powered off in preparation for the image capture. To verify there are no issues with your custom reset scripts, try running them manually on your temporary machine. If your virtual machine is powered off, verify that there is enough space on your Image Construction and Composition Tool /drouter directory to hold a new copy of the image.
Failures during image export
The most common errors during image export occur due to lack of space or network connectivity to the SCP host. If you encounter an error during image export, verify that there is enough free disk space on your Image Construction and Composition Tool server /drouter directory to enable construction of the OVA file, as well as enough free disk space on the SCP host to receive the file. Also, verify that the credentials for your SCP host are correct, and that communication over port 22 is not blocked between the Image Construction and Composition Tool and the SCP host.
In this article, you learned how to create a Windows image using IBM Image Construction and Composition Tool, including how to configure the image for use in IBM PureApplication System, and how to deploy these images from the IBM PureApplication image catalog. You also learned how to automate the image creation process using the Image Construction and Composition command line interface.
|Sample script||create_base_image_on_esx_cloud_provider.py||21 KB|
- Tuning the Windows Server 2008 R2 virtual image in PureApplication Systems W1500 environments
- IBM PureApplication System Version 1.1 Information Center
- Redbook: Creating Smart Virtual Appliances with IBM Image Construction and Composition Tool
- IBM developerWorks WebSphere
Get products and technologies
- Blog: Exploring PureApplication System pattern development
- Follow developerWorks on Twitter.
- Get involved in the developerWorks Community