Summary
The Host Profiles CLI Fling (hostprofilescli) is a command-line utility that allows vSphere administrators to perform several operations with Host Profiles that are either not currently possible through existing user interfaces, or possible only through graphical interfaces.
Recall that Host Profiles is a feature of VMware vSphere that allows identical configurations to be applied to multiple hosts. Customers typically use one profile per cluster, but depending on hardware and storage consistency, a single profile can be used more broadly.
This CLI utility can be used to perform the following operations:
- Customize Auto Deploy stateless hosts prior to booting and joining vCenter Server
- Import/Export Host Profile to or from local file
- Attach a profile to an existing cluster
- Set root password in a profile or configure a profile to use unique root passwords per host
- Configure system image cache setting (stateless, cached, or stateful install)
- List all host profiles in vCenter Server
Administrators of large VMware vSphere deployments who regularly deploy new clusters of VMware ESXi hosts can benefit from this additional automation for Auto Deploy and Host Profiles.
Overview of Capabilities
Pre-Customization of Auto Deploy Hosts
When using Host Profiles, most configuration settings apply equally to every host in a cluster, but certain items are unique to each individual node. These unique settings, such as a hostnames or static IP addresses, are known as customizations and are sometimes referred to as answer files. Administrators normally input these customizations with a graphical vSphere interface during the deployment process. vSphere 6.5 introduced a mechanism that allows editing customizations through a CSV file, but the feature only applies to hosts that have already been added to the vCenter Server inventory.
The stateless-template feature of this CLI utility allows administrators to pre-populate a vSphere cluster with all customizations applicable to the associated Host Profile so that VMware ESXi hosts can be fully configured and ready for use with zero manual intervention - without a GUI. The customization data, such as static IP addresses or unique root passwords, are specified using a standard CSV file. As such, this configuration data can be generated programmatically and tracked though version control mechanisms.
See the Instructions tab for more information on how to use this feature.
Host Profile Import and Export
The hostprofilescli utility can also be used to export a specific profile to a local file for backup or, in some cases, to move between test and production environments. Keep in mind that Host Profiles are very closely tied to specific hardware, I/O devices, and storage. Attempting to use a profile in another environment that is not virtually identical may require significant troubleshooting to become operational.
Examples:
hostprofilescli hostprofile --profile esxi65-nfs-gen8 export --file esxi65-nfs-gen8.vpf hostprofilescli hostprofile --profile esxi65-nfs-gen8 import --file esxi65-nfs-gen8.vpf
(Examples on this page omit the authentication parameters for brevity.)
Root Credential Management
Host Profiles can be used to specify passwords for ESXi accounts. However, since passwords are not extracted from the reference host during profile creation, they must always be set by an administrator afterwards through the Host Profile editor. The hostprofilescli utility can be used to set the root password on a profile, eliminating the need to log in and use a vSphere GUI.
Alternatively, Host Profiles can be configured to prompt a user for host passwords during customization - useful if security standards require unique root passwords for each individual ESXi host. This utility can also enable such a configuration, and if it is selected then root passwords can be specified in the customization data through the stateless-template feature described above.
Examples:
hostprofilescli hostprofile --profile esxi65-nfs-gen8 useraccount-password set --type allhosts hostprofilescli hostprofile --profile esxi65-nfs-gen8 useraccount-password set --type perhost
Attach Profile to Cluster
Once a Host Profile exists in vCenter Server, either by extracting from a host or uploading form a file, it can be attached to an existing cluster using the attach subcommand.
Example:
hostprofilescli hostprofile --profile esxi65-nfs-gen8 attach --entity dbcluster
System Image Cache Configuration
Although the most common deployment architecture for Auto Deploy is to use stateless, diskless VMware ESXi hosts, there are two other options: stateless caching and stateful installation. The hostprofilescli utility can also be used to modify this setting.
Stateless caching is used to mitigate potential performance degradation during boot storms, such as during recovery after a mass outage. With this configuration, hosts boot from a cached copy of ESXi on local storage if PXE or Auto Deploy services are not available. Important to note is that these hosts will boot and wait until Auto Deploy is available before they are re-connected to vCenter Server. Therefore, caching is not a high-availability architecture.
Stateful install is a means of using Auto Deploy to perform a traditional installation of ESXi to disk. After installation, the host is identical to hosts installed from ISO image and is no longer dependent on Auto Deploy. Choosing this option requires that physical hosts be configured to boot first from hard disk, not from network, after installation is complete.
Examples:
hostprofilescli hostprofile --profile esxi65-nfs-gen8 system-image host set \ --type stateful-install --firstdisk_arguments localesx,local --ignore_ssd --overwrite_vmfs
For more information on system image cache, see the product documentation:
Requirements
The hostprofilescli binary was tested on the following Linux distributions
- CentOS Linux release 7.3.1611
- Ubuntu 16.04.2 LTS
- VMware PhotonOS 1.0 build 13c08b6
- vCenter Server Appliance (VCSA) 6.5
Alternatively, the Python source is included and can be copied and executed directly on vCenter Server for Windows or VCSA 6+.
Tested with vSphere 6.0U3 and vSphere 6.5, on both Windows and VCSA platforms, with the following specific requirements:
All versions and platforms
- Auto Deploy service functional
- Host Profile adequately tested with intended target host hardware and storage
- Cluster in vCenter Server with above Host Profile attached
Additional prerequisites for vSphere 6.5 only
- Image Builder service functional
- Software Depot (online or custom) with desired ESXi image profile accessible
Additional prerequisites for vSphere 6.0U3 only
- PowerCLI to create a deploy rule
- Appropriate ESXi image profile, through an offline bundle, such as VMware-ESXi-6.0.0-5050593-depot.zip or from the public repository at https://hostupdate.vmware.com/software/VUM/PRODUCTION/main/vmw-depot-index.xml
Instructions
Full Instructions for stateless-template feature
Dependency Preparation
- Using Auto Deploy, boot a suitable reference host
- Configure reference host as needed, then extract and test a host profile
- Create cluster, attach host profile to cluster; ensure vSAN is not enabled on this cluster - stateless is not supported with vSAN today
Generate Template Files (JSON and CSV)
Extract the hostprofilescli zip archive on a supported system
Run the export command:
hostprofilescli stateless-template export --cluster database --templateDir db \ > --vchostname vcsa22.vcritical.com --vcusername administrator@vcritical.com
This generates two template files that correspond to the host profile associated with the target cluster. The JSON template does not normally require editing, but it can be used as a reference if any columns of the CSV are ambiguous.
Edit the cluster definition template CSV file
Create CSV file according to intended cluster membership, one row per host
The first three columns are consistent for all Host Profiles:
- F01-UniqueIdentifier: physical MAC address or BIOS UUID (preferred)
- F02-InventoryName: The host name (FQDN) as seen in vCenter; must be resolvable in DNS
- F03-hostName: The TCP/IP host name of ESXi, which is the short name without domain
Subsequent columns will vary based on specific host profile configurations. This is determined by profile settings that are configured to prompt for input. Each VMKernel interface typically includes a column for a MAC address, this is optional and values can be left blank in the CSV file.
Populate Auto Deploy Cache with intended ESXi image profile
If target cluster will boot from an ESXi image that is currently in use by other stateless hosts managed by the same vCenter, no additional action should be necessary, otherwise add an ESXi image profile to the Auto Deploy cache using one of the following approaches:
vSphere 6.5: ensure that either the online software depot is available or upload an offline bundle through the Auto Deploy Software Depots web interface
vSphere 6.0 or 6.5: create a deploy rule with PowerCLI (do not activate the rule)
- Add-EsxSoftwareDepot .\VMware-ESXi-6.0.0-5050593-depot.zip
- New-DeployRule -Name esxi60u3 -Item ESXi-6.0.0-5050593-no-tools -AllHosts
- After the cache is populated, it is ok to delete the rule, if desired
- Remove-DeployRule -DeployRule esxi60u3 -Delete
Note: the URL for online ESXi software depots is https://hostupdate.vmware.com/software/VUM/PRODUCTION/main/vmw-depot-index.xml
Import Cluster Customizations
After satisfying all the above dependencies, the cluster customizations are ready to be imported, use the following as an example:
hostprofilescli stateless-template import --cluster database \ --imageProfile ESXi-6.5.0-20170104001-no-tools \ --templateCSV db/esxi65-singlevswitch-static-nfs-template.csv \ --templateJSON db/esxi65-singlevswitch-static-nfs-template.json \ --vchostname vcsa22.vcritical.com --vcusername administrator@vcritical.com
The import process will create host objects in the specified vSphere cluster and associate the provided customizations. Verify that the process completed without errors before continuing.
Boot or Reboot Hosts
Power on, or reboot, physical hosts and wait for them to boot from Auto Deploy and become connected in vCenter Server. Cluster should be fully operational and compliant with the attached profile.
Other Points
- The Auto Deploy GUI in vSphere 6.5 has a tab called Discovered Hosts which can be used as a reference to identify unused hosts - the data can be downloaded to CSV for quick copy/paste of appropriate columns into the cluster definition CSV file. The host UUID is part of this discovered data.
- Physical hosts that are powered on and booted from the Auto Deploy network, but do not match any deploy rules, will automatically reboot every 5 minutes.
Contributors
Similar Flings
Cross vCenter VM Mobility - CLI
Cross vCenter VM Mobility - CLI is a command line interface (CLI) tool that can be used to migrate or clone a VM from one host to another host managed by a linked or isolated vCenter (VC) instance.
Virtual Machine Desired State Configuration
Virtual Machine Desired State Configuration (VMDSC) allows virtual administrators to specify VM CPU/Memory desired state which will take effect upon the next Guest OS reboot. This removes the burden of having to schedule a downtime window with the business/app owners.
vSphere Diagnostic Tool
vSphere Diagnostic Tool is a python script that runs diagnostic commands on the Photon Appliance or ESXi platform to return useful troubleshooting data while running within the confines of the local environment with out upstream dependencies.