Custom script bundle is now possible with Auto Deploy in vSphere 6.5

It has been some time since I had looked at the Auto Deploy and Host Profile feature in vSphere. As a former customer, I still remember one of the challenges I had in evaluating Auto Deploy and specifically Host Profiles was the fact that it did not cover all the possible ESXi configurations. This made it very difficult to operationalize as you still needed to handle post-configurations through other mechanisms. Trying to keep both solutions did not make sense for me and I ended up opting for the traditional scripted installation method via Kickstart which I had hooks into automate the full ESXi configuration.

In vSphere 6.5, there was a huge effort to significantly improve both Auto Deploy and Host Profile to what customers had expected of this feature, especially around bringing parity between the configurations that could be done using the vSphere Clients and/or vSphere APIs into Host Profiles. In addition, there was also several UI enhancements that now makes it possible to use both Auto Deploy and Image Builder directly from the vSphere Web Client which was never possible before. For more details, be sure to check out the What's New vSphere 6.5 white paper here.

One new feature that I think is worth calling out is the new Script Bundle capability in Auto Deploy. Previously, if a particular configuration was not available via Host Profiles, there was nothing you could really do and you had to write your own custom post-deployment script to apply to the ESXi host. As I mentioned earlier, in vSphere 6.5, we have closed the gap on the ESXi configurations that were not possible using Host Profile and will ensure that will be in sync going forward. Having said that, there are still certain configurations that are not possible today such as creating a custom ESXi firewall rule for example. For these cases, you either had to either hack it up using a method like this or to create a custom ESXi VIB which would then force customers to lower their ESXi's software acceptance level which was not ideal nor acceptable, especially for customers that are security conscious.

With this new Script Bundle capability, customers will now have the ability to add a post-deployment script that will run after all the configurations have been applied to a stateless ESXi host that has been provisioned by Auto Deploy. The script must be either be a Busybox ash or Python script as it executes within the ESXi Shell and all limitations that exists today within that environment will still apply when creating these custom scripts. To manage these Script Bundles, there are two new PowerCLI cmdlets called Add-ScriptBundle and Get-ScriptBundle Unfortunately, this new capability is not available when using the vSphere Web Client, hopefully this is something the team will be adding into a future update.

UPDATE (04/26/18) - PowerCLI 10.1.0 now adds the ability to remove a script bundle using the Remove-ScriptBundle cmdlet

A Script Bundle can be composed of multiple scripts which must be contained within a single tarball (gzip compressed tar archive) with the .tgz extension. Once uploaded, you will be able to associate a Script Bundle with an Auto Deploy rule just like you would with an Image Profile and/or Host Profile. Since I was not able to find much documentation on this feature, I figure a real life example would be helpful not only for myself but for anyone who might be interested in leveraging this new capability.

Before getting started, make sure you have a vSphere 6.5 environment (if you need to quickly deploy a full env, have a look at this blog post here) as well as PowerCLI 6.5 R1 installed on your desktop. You will also need to download the ESXi 6.5 offline depot image which will be used to boot our ESXi hosts from Auto Deploy.

For our examples script, we will using a simple ash script to create a custom ESXi firewall rule as shown in the example below:

#!/bin/ash

FIREWALL_CONFIG=virtuallyGhetto.xml

# Do not rely on external files, build ESXi firewall rule within the script
cat > /tmp/${FIREWALL_CONFIG} << __CUSTOM_ESXI_FIREWALL_RULE__
<ConfigRoot>
  <service>
    <id>virtuallyGhetto</id>
    <rule id='0000'>
      <direction>inbound</direction>
      <protocol>tcp</protocol>
      <porttype>dst</porttype>
      <port>1337</port>
    </rule>
    <rule id='0001'>
      <direction>outbound</direction>
      <protocol>tcp</protocol>
      <porttype>dst</porttype>
      <port>1337</port>
    </rule>
    <rule id='0002'>
      <direction>inbound</direction>
      <protocol>udp</protocol>
      <porttype>dst</porttype>
      <port>20201</port>
    </rule>
    <rule id='0003'>
      <direction>outbound</direction>
      <protocol>udp</protocol>
      <porttype>dst</porttype>
      <port>20201</port>
    </rule>
    <enabled>true</enabled>
    <required>false</required>
  </service>
</ConfigRoot>
__CUSTOM_ESXI_FIREWALL_RULE__

# Copy the new firewall rule to correct directory
cp /tmp/${FIREWALL_CONFIG} /etc/vmware/firewall/

# Delete the tmp firewall rule
rm -f /tmp/${FIREWALL_CONFIG}

# Reload the ESXi firewall for the changes to go into effect
esxcli network firewall refresh

Step 1 - Create the script(s) on a Linux/UNIX system as we will need to use the tar command to bundle them up. In our example, I have named the script vGhetto.sh but you can name it anything.

Step 2 - Create a tarball that only consists of the script(s) you want to include by running the following command (if you have multiple scripts, you will want to list all those files):

tar -cvzf vGhetto-Script.tgz vGhetto.sh

Note: Directories are not allowed within the tarball and you will get an error when trying to import the script bundle. Whatever name you chose for the tarball, it will automatically be used as the name to identify it once you have imported it. Make sure to use a name that is descriptive to help you identify the different script bundles.

Step 3 - Make sure you enable both the Auto Deploy and Image Builder Service using the vSphere Web Client under the Administration->Services tab of your vCenter Server.

Step 4 - Next, connect to your vCenter Server using thePowerCLI  Connect-VIServer cmdlet to start using the Auto Deploy and Image Builder. First, we will import our script bundle by running the following command and specifying the path to our script bundle:

Add-ScriptBundle C:\Users\primp\Desktop\vGhetto-Script.tgz

Once imported, you can run the Get-ScriptBundle command to see the list of script bundles that have been added as well as the individual script files in each bundle.

Step 5 - Next, we will import our ESXi 6.5 Image Profile by running the following command:

Add-EsxSoftwareDepot -DepotUrl C:\Users\primp\Desktop\VMware-ESXi-6.5.0-4564106-depot.zip

Once imported, you can run the Get-EsxSoftwareDepot command to retrieve the different Image Profiles that is included in the offline bundle. In our example, we will be using ESXi-6.5.0-4564106-no-tools

Step 6 - Now we will create our new Auto Deploy rule which you will need to give it a name and a list of "Items" which are strings mapping to the name of the Script Bundle and Image Profile that we had uploaded earlier. You can also specify a Host Profile if you had created one, for this example, I have opted to leave it out. The other thing you can add is a location where the ESXi host will be attached to whether that is the name of a vSphere Datacenter or vSphere Cluster. Instead of matching to a specific host pattern like MAC Address or IP Address, I just used the -AllHosts, you can change this of course.

New-DeployRule -Name "ESXi-6.5-with-vGhetto-ScriptBundle" -Item "vGhetto-Script","ESXi-6.5.0-4564106-no-tools","Datacenter" -AllHosts | Add-DeployRule

Once the Auto Deploy rule has been created, you can retrieve it by using the Get-DeployRule command or directly view the configuration from within the vSphere Web Client under the Auto Deploy UI.

Step 7 - Finally, the last step is to power on an ESXi host and watch Auto Deploy do its magic. In my environment, I just used an empty Nested ESXi VM which is probably the quickest way to test Auto Deploy and Host Profiles.

If the ESXi host had successfully booted from Auto Deploy, you should see it under the new "Deployed Hosts" tab as shown in the screenshot below.

If we go to the console of the ESXi host and enable SSH (since we are using a default Image Profile, SSH is disabled by default), we can confirm that our script executed correctly, but we can also see where the files are placed in case of troubleshooting purposes. The Script Bundle that we created will be stored in /etc/rc.local.d/autodeploy directory and it will be automatically extracted and placed into the /etc/rc.local.d/autodeploy/scripts directory for execution. I assume the scripts will be executing in alphabetical/numeric order, so if you have a set of scripts that need to run in a particular order, you may want to prefix it with 001 for example.

With all the enhancements in vSphere 6.5 for Auto Deploy, Host Profile and the new Script Bundle capability which addresses some of the challenges for stateless deployments, I think we now have a compelling and complete story that customers should consider exploring further. I know I definitely will be spending more time with both of these features going forward. If you have any feedback about this new feature or any other comments on Auto Deploy or Host Profile, feel free to leave your feedback and I will be sure to forward it over to the Product Manager.