Introduction

There are many ways to deploy the VMware vCenter Server appliance. For a simple one-time experience, the guided install using the web-based wizard is amazing. However, when we need to automate this, we have a few options to choose from.

The following table illustrates common deployment techniques for the VMware vCenter Server Appliance 6.7.

Tool Automated Configuration Minimum Required
Web Wizard no Full ESXi
PowerCLI yes Full Existing vCenter
PowerCLI yes Partial ESXi
OvfTool* yes Full ESXi

*OVFTool is available on the vCenter ISO

Objective

For this write-up we will use ovftool.exe from the vCenter ISO. Specifically, we will use vcsa-deploy.exe (also on the ISO) which is a VMware provided wrapper to fully handle the deployment using a JSON file you customize.

We take it a step further and handle all of the JSON for you if you download my associated GitHub script Invoke-OvfTool. We do this by taking the native options provided by the VMware JSON template on the ISO, and we overlay your runtime parameters to deploy a fully customized vCenter Server appliance.

In our requirements you will notice an extra tool known as dos2unix.exe. We use this to convert the JSON file into unix format.

Quick Start

Download the bits:

Name Download
7zip https://www.7-zip.org/download.html
dos2unix https://sourceforge.net/projects/dos2unix/files/dos2unix/
vCenter Server https://my.vmware.com/group/vmware/details?downloadGroup=VC670B&productId=742&rPId=24515
Invoke-OvfTool https://github.com/vmkdaily/Invoke-OvfTool

Step 1. Launch PowerShell as administrator (UAC)

Step 2. Import the Invoke-OvfTool Module

Import-Module c:\<path-to-bits>\Invoke-OvfTool.ps1 -Verbose

Step 3. Create OvfConfig
Modify your settings and paste into PowerShell:

$OvfConfig = @{
    esxHostName            = "esx01.lab.local"
    esxUserName            = "root"
    esxPassword            = "VMware123!!"
    esxPortGroup           = "VM Network"
    esxDatastore           = "datastore1"
    ThinProvisioned        = $true
    DeploymentSize         = "tiny"
    DisplayName            = "vcsa01"
    IpFamily               = "ipv4"
    IpMode                 = "static"
    Ip                     = "10.100.1.201"
    FQDN                   = "vcsa01.lab.local"
    Dns                    = "10.100.1.10"
    SubnetLength           = "24"
    Gateway                = "10.100.1.1"
    VcRootPassword         = "VMware123!!"
    VcNtp                  = "0.pool.ntp.org, 1.pool.ntp.org,2.pool.ntp.org,3.pool.ntp.org"
    SshEnabled             = $true
    ssoPassword            = "VMware123!!"
    ssoDomainName          = "vsphere.local"
    ceipEnabled            = $false
}

Tip: Because VMware123! is a common password used in examples, it is considered dictionary, so to pass complexity tests you should make it VMware123!! or better yet something new.

Step 4.
Create the JSON file, then save the path to a variable.

Note: This section has been updated; We added a step (4b) to have user check the JSON path.

Step 4a. Create the JSON file

$Json = Invoke-OvfTool -OvfConfig $OvfConfig -Mode Design

Step 4b. Check the results of $Json. If it is not a path (could be an array), then get the path similar to the following:

$JsonPath = $Json[1]

Or just make the variable once you know the path:

$jsonPath = "C:\Users\vmadmin\AppData\Local\Temp\myConfig.JSON"

Step 5.
Deploy the OVA

Invoke-OvfTool -OvfConfig $OvfConfig -Mode Deploy -JsonPath $JsonPath

ETA: It takes anywhere from 30 to 60 minutes depending on disk, cpu and network. Also, because the OVA deploy copies ~2.5GB across the network, proximity to target is beneficial.

This concludes the quick start. Read on for additional background detail on the topic (~2700 words).


The following is additional supporting information related to using the VMware-provided binaries and also my custom script.

You can also skip to the end of this post and start using the VMware-provided tools interactively from PowerShell.

Supported Devices

Beyond VMware's native support requirements for deployment, my kit has been tested on Windows 10 running PowerShell 5.1 and also on Windows Server 2008 R2 running PowerShell 5.1. I have not tested or written for PowerShell Core (feel free to port!). As for ESXi, I tested against vSphere ESXi 6.0 through 6.7.

Motivation

ovftool.exe (part of vCenter Server ISO) has zero dependency on existing vCenter Server to perform full configuration of a deployed appliance.

OVF vs OVA

For our purposes these terms can be used interchangeably. The image provided by VMware (inside the ISO) is in the OVA format. The tool we use has OVF nomenclature, but don't over-think it for now. Let's deploy this OVA with ovftool!

The Bits

To follow this post exactly, you will need 7zip, dos2unix.exe and the vCenter Server ISO. Finally, to automate the deployment, you can use my Invoke-OvfTool function on GitHub or write your own.

More About the Binaries


About 7zip
To get started, we need a POSIX compliant unzipper such as 7zip. Your latest and greatest Windows 10 file explorer is not smart enough. Get this tried and trusted tool and use it for everything you do in VMware (i.e. log bundles, etc.).

Install 7zip and take the defaults or customize as desired. Later we can uncompress files from the context menu (i.e. Right-click file and then navigate to 7zip > Extract to. This will properly uncompress the bits.

Do not proceed if you get errors when uncompressing any binaries.

About dos2unix
We also need dos2unix.exe to take our utf-8 file and make it fully unix compliant. We should be able to do this with PowerShell only, but this step is required for now, and works well.

You can use the 32bit or 64bit version. I went with the 64bit for this and it works great. Like 7zip, dos2unix is another standard tool for me.

An example binary name that you might download:

dos2unix-7.4.0-win64.zip

To start using it, we just uncompress it where we want it. If this was a real deployment maybe you would pick a location such as Program Files (i.e. manually copy) or a bin or scripts directory of some sort.

In our case, we want the binaries right where they are, in the Downloads directory. Just use 7zip to uncompress, and when you run my Invoke-OvfTool script you will be good to go. By default my script expects the bits in $env:USERPROFILE\Downloads so no need to move them. Just uncompress. Easy!


About vCenter ISO
Finally, let's get the actual VMware vCenter Server ISO. This contains the ovftool.exe binary and also the OVA used to deploy the vCenter appliance. We can get this download from the My VMware website. An example binary is shown below:

VMware-VCSA-all-6.7.0-8832884.iso

Notable binaries inside
VMware-VCSA-all-6.7.0-8832884\vcsa\ovftool\win32\vcredist\vc_redist.x86.exe
VMware-VCSA-all-6.7.0-8832884\vcsa\ovftool\win32\ovftool.exe
VMware-VCSA-all-6.7.0-8832884\vcsa-cli-installer\win32\vcsa-deploy.exe
VMware-vCenter-Server-Appliance-6.7.0.12000-8832884_OVF10.ova

You only need the vc_redist.x86.exe if your Windows client is very old. The ovftool.exe gets called by vcsa-deploy.exe so you do not need to interact with that directly, although you could! Finally, we have the actual OVA.

Tip: In the latest versions of vCenter Server 6.7, the .OVA file extension is there by default. Previously, we had to add it manually.


Download PowerShell Script (optional)
Roll your own, or download my Invoke-OvfTool PowerShell function from GitHub:

https://github.com/vmkdaily/Invoke-OvfTool


Expected Folders

VMware has no constraints on placement of the bits. You could mount a CD and use it that way. Here we extract into the Downloads directory, because that is where my Invoke-OvfTool wants them.

Specifically, these should be located in your $env:USERPROFILE\Downloads directory, uncompressed. You can keep the original ISO and ZIP there as well, but we only read into folder objects of type Container.

In Windows Explorer you should have these folders:

dos2unix-7.4.0-win64
VMware-VCSA-all-6.7.0-8832884

Usage

Once you have the described folder layout, you can start using the tools immediately. You can interactively browse to the location of the desired VMware binary such as to the vcsa-deploy.exe binary for example.

Of course, once you have the bits, I recommend using my script (Invoke-OvfTool) from GitHub. This can be modified and enhanced, but out of the box it should work for you.

Adjusting paths using parameters

We can customize the path to our vCenter ISO if needed. This should be a real drive not a UNC path. By default the script reads from the Downloads directory of the current user.

To adjust the location, populate the Path parameter of Invoke-OvfTool.

Invoke-OvfTool -Path <mypath>

If using Fusion or Workstation, consider turning off Sharing if having issues reaching reaching your Downloads directory from PowerShell


About dos2unix.exe

The configuration file expected by VMware's ovftool.exe is in JSON format.
We run dos2unix.exe against the generated file to ensure proper unix formatting.

Skipping dos2unix.exe

You may have your own preferred way to do this. To bypass the usage of dos2unix.exe, activate the SkipDos2Unix switch on Invoke-OvfTool.

Invoke-OvfTool -SkipDos2Unix

Path to dos2unix.exe

By default we expect this to be in your downloads directory uncompressed.
However, you can adjust the path with the Dos2UnixPath parameter of Invoke-OvfTool.

Invoke-OvfTool -Dos2UnixPath "c:\temp\dos2unix-7.4.0-win64"

About JSON and Passwords

JSON is plain text. This means that your ESXi login and SSO login will be readable by anyone with permission or ability to see this file. One option is to leave passwords blank, then you will be prompted to enter login details at deploy time. Alternatively, use dummy accounts and passwords and replace them after deployment.

Create ESXi user (optional)

Because of the plain text nature of JSON, the recommendation is to create a temporary user on ESXi, deploy the OVA using that user/password (stored in JSON), and then remove the ESXi account after deployment. If someone later finds that text file containing login info, the account does not exist on ESXi.

The creation of the ESXi user is assumed to be scripted by you,(or just H5 into that sucker!). Alternatively, just use root when creating the configuration options.

Reset vCenter Passwords

After deploying the vCenter Server appliance, you may wish to reset the password for appliance root and administrator@vsphere.local.

Remember, both of these passwords were just in a plain text JSON file; Because of this, you may have chosen to use 'dummy' passwords (i.e. VMware123!) when deploying.

Currently, the automated techniques to reset passwords (not shown) involve entering your password on the command line. For this reason, you may choose to set your final password manually:

#Reset VC root here
https://<vcenter>:5480

#Reset administrator@vsphere.local here
https://<vcenter>:9443

You can also craft some handling from PowerShell and SSH to perform a onetime reset of the vCenter Password, but that is out of scope and I leave that to you.


Summary

In this session we showed how to download and uncompress the vCenter ISO. We also showed how to use a utility called dos2unix to get our config file just right.
Finally, we showed how to run a 3rd party PowerShell script known as Invoke-OvfTool to deploy a fully configured VMware vCenter Server appliance.


APPENDIX

The rabbit hole continues for the brave and those with carrots. Let's go over some additional techniques to get the most out of these tools.

Logs

By default, vcsa-deploy.exe creates logs in $env:TEMP. When using my Invoke-OvfTool script, we maintain the same structure.

workflow_<number>

Example Log Folder:

workflow_1530632181309

Logging overview
We can take the logging further by using my Invoke-OvfTool script. This is the same function we deployed with, but now we change the Mode parameter to LogView. This returns a brief summary of the log file names.

Invoke-OvfTool -Mode LogView -LogDir "$env:temp\workflow_1530632181309"

Logging detail
For even greater detail, pipe in Format-List as shown below. This returns more detailed logging from one or more previous runtimes (referred to as workflows).

Invoke-OvfTool -Mode LogView -LogDir "$env:temp\workflow_1530632181309" | fl *

ABOUT WINDOWS CLIENT REQUIREMENTS

If using an older Microsoft Windows operating system for your client, it is recommended that you run the test script that VMware includes to check for the required 32bit C++ runtime package:

vcsa-cli-installer\win32\check_windows_vc_redist.bat

If the above script indicates that you are out of date, the minimum required version is included on the vCenter Server ISO. You can also download the latest version directly from Microsoft.com.

ovftool.exe is 32bit, but it supports 64bit operating systems.


ABOUT SSL CERTIFICATE HANDLING
When using vcsa-deploy.exe (which we call in the background), one can optionally set a preference at runtime to determine how invalid certificates are handled. The --no-esx-ssl-verify is deprecated and --no-ssl-certificate-verification is used instead.

On the previous version of vCenter 6.7, I had to flip these the other way around or the deploy would hang. In the very lastest VC, running the preferred (not deprecated) command is working perfectly. The default on my PowerShell script Invoke-OvfTool uses the latest preferred syntax.

ABOUT UNICODE ESCAPE (u0027)
A PowerShell annoyance with JSON is randomly getting a bunch of u0027 characters injected into your text. This is a known issue which we handle by adjusting the Depth parameter of ConvertTo-Json at runtime.

More about unicode escape:
http://www.azurefieldnotes.com/2017/05/02/replacefix-unicode-characters-created-by-convertto-json-in-powershell-for-arm-templates/

Using NTP for the vCenter Appliance
Due to security flaws in the NTP protocol, you may find that your company blocks outbound UDP 123. This is a good practice and should not surprise you when troubleshooting NTP.

Specifically, this means you may not be able to reach pool.ntp.org or similar. Just be ready with internal time devices to point to as needed. For example a Cisco switch or Active Directory DC with the good time designation (who doesn't want that!). Ideally this should be the same device that your ESXi host, and Log Insight (or other syslog) use.

In VMware vCenter Server 6.7, passing in multiple NTP entries seems to be working fine. In some appliance deployments, we may be asked to enter only one (1) item of a given type (i.e. one DNS server or one NTP server); Then we would need to go and add the others in post. From my testing, 6.7 is working great with multiple NTP entries (have not tested multiple DNS).

Bringing it all together
Deploying an appliance with vSphere brings together all of your skills. You need:

  • Good name resolution to the ESXi host
  • Access to the host at port 902
  • Appliance being deploying has DNS A record
  • Reverse Lookup is healthy
  • Time sync is good between all devices

If you follow the example in this post, adjust your IP Addresses, etc. as needed.

Our example appliance has an IP Address of:

10.100.1.201

Before deploying, we should ensure that we have good forward and reverse lookup on that address.

nslookup 10.100.1.201
nslookup vcsa01.lab.local

Interactive

For the rebel, you followed none of this, but you have PowerShell and okay you'll download the vCenter ISO. You can play around with this setup without anything else.

Change to installer location

Set-Location C:\temp\VMware-VCSA-all-6.7.0-8832884\vcsa-cli-installer\win32

Change your prompt
Since the path to the ISO is quite lengthy

Function Prompt { ('[OVATOOL]>')

}

show help
If running the tool from PowerShell, be sure to use .\ before the tool name

.\vcsa-deploy.exe --help

show help for a sub-command
Choices are install,upgrade, or migrate

.\vcsa-deploy.exe install --help

For more help see the readme.txt in the root of the vCenter ISO. Enjoy!

-end-