vSphere 6.5 – CLI VCSA Embedded Deployment Walkthrough

By | January 12, 2017

The post below will walk through the deployment of an embedded vCenter Server Appliance (VCSA) 6.5 node to a target ESXi server using the command line interface (CLI) deployment method.

If you are interested in also seeing the GUI deployment or other GUI/CLI deployments, please see my post here which has links off to other individual articles for different deployment methods.

For each of the deployment methods I am providing a video as well. Please find the video for the VCSA Embedded CLI deployment below. This has been recorded in FullHD, so best to watch it in Full Screen!

Introduction

The VCSA can be deployed using either the new GUI installer or by CLI from Windows, Mac and Linux machines. After playing with the CLI a little in the lab, it has become my preferred deployment method over the GUI. A JSON file is used to define the configuration of the node and then a one liner performs the deployment and configuration of the node without the normal GUI “Next Next” trek.

The CLI deployment is fully supported by VMware in 6.5 and they have also done a great job of providing a number of JSON template files depending on your deployment scenario.

One thing to note is that I don’t think any of the template files have the NTP server defined. In my experience, DNS and NTP are the two biggest causes of issues when performing a deployment or upgrade. In the steps below I’ll show you where to enter the NTP settings into the JSON configuration file.

Let’s go ahead and get started.

First Steps

The first thing I do before deploying any appliance is making sure there is a DNS record with forward and reverse records. For this walkthrough I’m naming the appliance testvc.lab.allford.id.au at the IP address 192.168.0.150.

Exploring the VCSA ISO

Next, let’s take a look at the VCSA ISO file that I’ve downloaded from VMware. If we mount the ISO file and then open it, you’ll see a folder named vcsa-cli-installer. Inside there, you’ll find folders for Linux, Mac and Windows, as well as a templates folder.

Let’s dive into the templates folder and take a look, as this is where the example JSON configuration files are installed. Inside the templates folder, there are subfolders for install, migrate and upgrade. The CLI tool can be used to perform a new installation, a migration from Windows VC to the appliance as well as an upgrade. Head into the install folder and you will see the JSON templates provided by VMware.

As you can see, VMware have provided template files for a number of deployment scenarios. In this walkthrough we’re going to use the first template, which is embedded_vCSA_on_ESXi.json. I’m going to copy this file from the ISO into C:\temp so I can edit it.

Create JSON file

With the JSON configuration files, you can go ahead and open these in any text editor to make the changes required. There is a bit of a description for each setting as to what is required. I recommend watching the video at the start of this post as I walk through each of the settings. Although you can open in a text editor, I came across a neat JSON online editor (http://www.jsoneditoronline.org/) that I show you in my YouTube clip as well.

I’ve put the output of my completed JSON file below. I’ve also entered in a section for the NTP server as well, which I recommend you do too. Make sure to put the comma on the line above the NTP.Servers entry and save the JSON file.

The vSphere 6.5 documentation contains information for all of the settings that can be used within the JSON file – https://pubs.vmware.com/vsphere-65/index.jsp#com.vmware.vsphere.install.doc/GUID-457EAE1F-B08A-4E64-8506-8A3FA84A0446.html

Using vcsa-deploy

Now that we have a JSON file that specifies the configuration, we can dive into running the CLI utility to verify the data in the configuration file is correct and then move onto deploying the appliance.

Open up a command prompt and browse to the following location, where the drive represents the VCSA ISO file we mounted earlier (for me this is E:\) – E:\vcsa-cli-installer\win32

Run the following command to show the help and available options for the install configuration of the tool:

vcsa-deploy.exe install -h

Verify The JSON File

This step is absolutely optional, you can just skip straight to deploying if you like, but I wanted to show that there is functionality to validate the file prior to attempting to deploy the VCSA.

Run the following command to perform a verification of the configuration file. With these switches we are acknowledging the CEIP (--acknowledge-ceip), accepting the End User License Agreement (--accept-eula--no-esx-ssl-verify). The --verify-only switch determines that we just want to validate the configuration file and the details for the target ESXi node are correct. After running the below, you’ll be prompted to enter the password for the root account for the target ESXi node.

vcsa-deploy.exe install --acknowledge-ceip --accept-eula --no-esx-ssl-verify --verify-only c:\temp\embedded_vCSA_on_ESXi.json

As you will see towards the bottom of the screenshot, the verification completed successfully, so we know that the data and ESXi host details we have provided in the JSON file are valid.


Deploy and Configure the Appliance

It’s now time to run the command that will actually do the deployment for us. The command below is similar to the above, but without the verify switch (–verify-only). This instructs the CLI utility to perform the deployment of the appliance. After running the below, you’ll be prompted to enter the password for the root account for the target ESXi node again.

vcsa-deploy.exe install --acknowledge-ceip --accept-eula --no-esx-ssl-verify c:\temp\embedded_vCSA_on_ESXi.json

Once it is started, go and grab a beer, as it will take around 15 minutes to deploy, configure and for the services to start up.


As you can see, the deployment was successful. Let’s go ahead and fire up a web browser to the FQDN of the newly deployed node, advance past the SSL cert warnings and log in to the HTML 5 interface:

Summary

As you can see, once you know how the deployment works this can become very powerful and easy to use. Entering a few details into the JSON file and then kicking off the deployment is much quicker than having to walk through the GUI installer and  the CLI deployment is required in my opinion if you are doing a lot of lab work.

I hope this post has been helpful for you and thanks for reading.

4 thoughts on “vSphere 6.5 – CLI VCSA Embedded Deployment Walkthrough

  1. aaron

    in your article’s command section you use single dashes for switches but the help section and your screenshots plainly show double dashes for the switches
    for example
    vcsa-deploy.exe install –acknowledge-ceip –accept-eula –no-esx-ssl-verify c:\temp\embedded_vCSA_on_ESXi.json <–Incorrect in article
    vcsa-deploy.exe install –-acknowledge-ceip –-accept-eula –-no-esx-ssl-verify c:\temp\embedded_vCSA_on_ESXi.json <—Fixed w double dash switches

    Reply
    1. Matt Post author

      Hi Aaron,

      Thanks for the comment and for letting me know. The text was actually correct, but WordPress was rendering this as a single dash instead of two. I’ve fixed it up now by using a code block around the commands, which was different to the previous formatting I was using.

      Cheers, Matt.

      Reply
  2. aaron

    Couple suggestions for the JSON file:
    1) for the DNS serveres your exmple uses the JSON array format for one DNS server entry but the –template -help also shows the serialized method “1.2.3.4,0,9.8.7.6,1.1.1.1.” as acceptable method which looks like a much cleaner method. Is there a reason why you used the JSON array format with the open brackets and quoted entry(ies)?
    2) the “ntp.servers” entry is not indented correctly and I’d suggest consistency of using the JSON array or serialized method siimilar to the “dns.servers” section

    Verfify JSON File errors
    Not sure if anyone has any suggestions that is more accustomed to using JSON files or Admin prompte vs Win10 PowerShell prompte .
    ENVIRONMENT: Our GPO settings PREVENT the execution of the command prompt with administrator. So I typically have to use the PowerShell to execute scripts instead. However I’m getting errors trying to verfiy the vcsa-deploy.exe with the following output:
    “A Unicode character was encountered in one of the command line arguments. For
    templates adn command line arguments, only 7-bith printable ASCII characters are
    supported”.
    This ‘error’ ouputs immediately after attempting the –verify-only command for the path.
    The JSON file I’ve verified is encoding with UTF-8 and there are no errors or erroneous characters in NotePad+++.
    I’ve tried moving the file to multiple local destinations on the hard drive and putting switches in different order or dropping them all together with no success.

    After some deeper efforts i finally figured out a way to launch an Admin Command Prompt and the –verify-only finally executed. But now i’m getting a strange socket Errno socket error SSL: UNKOWN_PROTOCOL _ssl.c:661 stating it failed to log into the target ESXi host. I’ve verified the password for ESXi host works through PuTTY (22), Web Client (443) and the thick client just fine. I’ve tried the IP and FQDN with no success. Stumped as to why it is not connecting.

    Reply
    1. Matt Post author

      Thanks for the suggestions.

      The DNS server and NTP server configuration within the JSON file in my post match the format of the templates that are provided by VMware on the vCenter Server Appliance ISO media. That is the only reason they are in the format they are in. If the other formats are more appropriate or fit your use case better then I suggest you use them.

      In regards to your verification issues, I’m not sure sorry, I’ve not seen this before.

      Reply

Leave a Reply

Your email address will not be published. Required fields are marked *