26.42. vmware

The following documentation is for vmware content package at version v0.0.0.

26.43. VMware vSphere Tools

A collection of tools for managing VMware vSphere ESXi nodes via Digital Rebar Provision (DRP) workflows and content. This plugin provides content and pieces for managing ESXi infrastrcuture. In addition to standard VMware release BootEnvs for various ESXi versions, custom vendor BootEnvs are also included.

VMware vSphere ESXi installs can be highly customized via the use of DRPs templating constructs to create a complex Kickstart that is capable of doing deep configuration of the ESXi node.

The content section of this plugin also carries a few complex example Kickstart files that you can refer to for more advanced deployment ideas. They include:

esxi-example-firstboot-complex.ks.tmpl
  Includes examples for multiple NICs, vswitches, security settings
  syslog handling, firewall changes, storage changes, etc.

esxi-example-vsan.ks.tmpl
  Builds VSAN disk group and creates VSAN cluster on the ESXi node.

Additional advanced kickstart configuration examples can be found in various corners of the web, but a couple of excellent sites are as follows:

26.43.1. Kickstart Templating Usage

VMware ESXi environments are for the most part “closed appliances”, and compiling third party tools for these environments is not an easy process. Consequently, there is currently no RackN/Digital Rebar Provision Agent available to run during the ESXi install process, or as a Post OS install agent.

This means that no Workflow Stages can be run as part of the ESXi install process. You must rely completely on the Kickstart to do all of the customization necessary. Digital Rebar Provision can help piece together relatively capable kickstart via the use of our templating engine, and inherently composable content architecture.

Since there is no DRP “runner” (agent) that can run in an ESXi environment, we can not execute workflow steps post-reboot of the installer. This causes a problem since we need to notify DRP that the install has completed and that we can mark the machine done, and boot to “local” disk. There are two primary Kickstart templates used for ESXi installs with this content pack:

esxi-install.ks.tmpl      --> Python 2.x based
esxi-install.py3.ks.tmpl  --> Python 3.x based

A small Python snippet is used to make the API call back to DRP to notify that the install has finished. But, we have to use the right version of Python, since … Python. Currently this is done in the “%pre” (Python interpreter) phase.

26.43.1.1. Adding Custom Kickstart Sections

Digital Rebar Provision provides on-the-fly customization of the built Kickstart through the use of injecting Templates in to the core Kickstart file, and also providing dynamic information available on the DRP endpoint, in to the Templates.

ESXi kickstarts support three additional sections (or phases) that extra actions can be taken during the installation process:

Pre Stage (%pre)
Specifies a script to run before the kickstart configuration is evaluated. For example, you can use it to generate files for the kickstart file to include.
ESXi Installation Stage
Uses Kickstart for automating the installation; see Vmware Kickstart Documentation for more details.
Post Stage (%post)
Runs the specified script after package installation is complete. If you specify multiple %post sections, they run in the order that they appear in the installation script.
Firstboot Stage (%firstboot)
Creates an init script that runs only during the first boot. The script has no effect on subsequent boots. If multiple %firstboot sections are specified, they run in the order that they appear in the kickstart file.

DRP’s “vmware” content allows you to inject custom %pre, %post, and %firstboot scripts in to your installation kickstart. It is up to the operator to understand the ordering and proper usage of these scripts.

To do so, simply create Templates with your Kickstart snippets defined as you desire. Then use the esxi/ks-custom-sections Param structure to include the appropriate scripts in your kickstart. NOTE: the %pre %post and %firstboot separators will be injected into the Kickstart file for you (do NOT include them in the template).

Example Param definition:

##############
# YAML example
# see WARNING note about kickstart below

- "pre-busybox"
  - "my-pre-busybox-chunk1.ks.tmpl"
  - "my-pre-busybox-chunk2.ks.tmpl"
- "post-python"
  - "my-post-python3-chunk2.ks.tmpl"
- "firstboot-busybox"
  - "my-fistboot-busybox-chunk1.ks.tmpl"


##############
# JSON example
# see WARNING note about kickstart below

{
  "firstboot-busybox": [
    "my-fistboot-busybox-chunk1.ks.tmpl"
  ],
  "post-python": [
    "my-post-python3-chunk2.ks.tmpl"
  ],
  "pre-busybox": [
    "my-pre-busybox-chunk1.ks.tmpl",
    "my-pre-busybox-chunk2.ks.tmpl"
  ]
}

Note

None of the above reference templates exist in this plugin. You must create them as appropriate for your use cases.

You may also create templates that carry kickstart command directives, to customize the main body of the kickstart. Use the esxi/ks-custom-kickstart` param to specify the additional templates with kickstart directives to inject.  These will be placed after the ``esxi-network-ks.tmpl, but before any of the %pre, %post, and/or %firstboot ections are injected.

Example:

esxi/ks-custom-kickstart:
  - my-kickstart-chunk1.ks.tmpl

The above examples will generate a kickstart that looks similar to below:

# DRP provided kickstart opening statements
<template default statements go here>

# DRP provided network configuration template
<esxi-network-ks.tmpl>

# example "kickstart" customization template
<my-kickstart-chunk1.ks.tmpl>

# DRP provided kickstart template pre/post/firstboot "stock" sections
<esxi-notify-drp-py3.tmpl>
<esxi-preserve-logs.tmpl>
<esxi-enable-shells.tmpl>

# example custom sections to add
# firstboot-busybox
%pre --interpreter=busybox
<my-firstboot-busybox-chunk1.ks.tmpl>

# post-python
%pre --interpreter=python
<my-post-python3-chunk2.ks.tmpl>

# pre-busybox
%pre --interpreter=busybox
<my-pre-busybox-chunk1.ks.tmpl>
<my-pre-busybox-chunk2.ks.tmpl>

26.43.2. Network Configuration Options

The VMware plugin from RackN supports managing relatively complex network scenarious around your VMware ESXi infrastructure. There are three places within the provisioning stages that network configuration changes can be made to support different operational models.

The three primary configuration points for network settings are explained below. In all cases, we assume that the PXE start process is assigned an IP address from your DHCP infrastructure - either from Digital Rebar Provision itself, or other external DHCP services.

  1. Initial kernel network configuration. Initial DHCP/PXE services may be on an isolated network from the provisioning networks. These settings are controlled by passing values to the kernel at initial load time, via use of the kernel-options parameter.

    An example:

    ip=10.10.10.10 netmask=255.255.255.0 gateway=10.10.10.1 vlan=10

  2. Once the initial kernel has booted, the kickstart environment can be plumbed with a set of network configuration options. See the esxi/network-kickstart-type Param documentation for details on configuring the network at this stage.

  3. Once a machine has finished installing, and subsequently boots in to it’s installed operating system; it is possible to again specify different network configurations.

    This may be necessary in the case of a Provisioning network transition to a Production network configuration post-install.

    To customize the network configuration post-install, please see the esxi/network-firstboot-type parameter for options.

Some sample scenarios and how you need to configure for those use cases are listed below.

26.43.2.1. Simple DHCP Only Setup

If you are trying to simply obtain a DHCP configuration at boot time, and preserve that IP through the install and frist boot of the installed OS, you do not need to do anything. The default behavior will be to obtain DHCP and preserve it through the install.

26.43.2.2. DHCP on PXE; Configure Manual IP (kickstart and installed OS)

If you intend to acquire an IP address during initial PXE boot of the Machine, but then transition to a Static (manually) configured network configurutation during the Kickstart installation and as the final installed network config, use the following steps:

  1. Do not set any values for kernel-options
  2. Set the esxi/network-kickstart-type appropriately
  3. Follow the documentation for that Param.

26.43.2.3. DHCP ON PXE; Retain for Kickstart; Installed OS Different

If your provisioning network is defined by the PXE DHCP network configuration, but you wish to transfer the installed OS (on first boot), to a new network configuration, use the following setps:

  1. Do not set any values for kernel-options
  2. Set the esxi/network-firstboot-type appropriately
  3. Follow the documentation for that Param.

26.43.2.4. VLAN Tagged Interfaces

VLAN tagged frames can be set at any of the three primary stages of the provisioning process outlined above. Set the appropriate options for either of the following stages:

Kernel boot/kickstart VLAN tagged
Set the kernel-options param to include the vlan=N setting, where N is the VLAN ID from 1 to 4096.
Kickstart Network and/or Firstboot Network VLAN tagged
Set the Param esxi/network-*-vlan Param for the appropriate stage.

26.43.2.5. DNS, Search Domains, NTP Settings

To customize network configurations for DNS and NTP settings, please see the drp-community-content` Params:

  • dns-servers
  • ntp-servers
  • dns-search-domains

Additionally, a custom NTP configuration template can be provided to completely override the (relatively simplistic) default NTP settings supported by this content. To override the template follow the below steps:

  1. Create a new Template with your NTP configuration.
  2. (optional) You can use the existing ``ntp-servers` Param similarly to the RackN supplied content, by reviewing the following example.
restrict default kod nomodify notrap noquerynopeer
restrict 127.0.0.1
{{range $key, $ntp := .Param "ntp-servers" -}}
server {{ $ntp }} iburst
{{end -}}
  1. Set the ``esxi-ntp-conf` Param with the name of your NTP template you created above.

26.43.3. Licensing ESXI During Install

Use the esxi/license Parameter to set a License to be used during installation to enable licensed use of ESXi.

The following documentation defines the various components of the vmware content and how to use them.

26.43.4. stages

The content package provides the following stages.

26.43.4.1. esxi-550u3b-install

Provides VMware Stage for ESXi 5.5.0update3b. For more details, and Download ISO see:

26.43.4.2. esxi-6.7.1-10302608-nec-gen-6.7-install

Provides custom VMware Stage for NEC Express5800/R120h and T120h Series specific hardware and drivers. For more details, and Download ISO see:

26.43.4.3. esxi-600u3a-install

Provides VMware Stage for ESXi 6.0.0u3a. For more details, and Download ISO see:

26.43.4.4. vmware-esxi-hcl-install

This stage will install all prerequisites for the VMware HCL compatibility checker, and the python3 tool itself (compchecker.py).

26.43.4.5. esxi-lenovo_esxi6.7u1-10302608_201810-install

Provides custom VMware Stage for Lenovo specific hardware and drivers. For more details, and Download ISO see:

26.43.4.6. esxi-6.7.0-update1-10302608-custom-hitachi_0200_Blade_HA8000-install

Provides custom VMware Stage for Hitachi HA8000V Gen10 specific hardware and drivers. For more details, and Download ISO see:

26.43.4.7. esxi-600u2-install

Provides VMware Stage for ESXi 6.0.0u2. For more details, and Download ISO see:

26.43.4.8. esxi-vmware-esxi-6.7.0-10302608-custom-cisco-install

Provides custom VMware Stage for Cisco hardware and drivers. For more details, and Download ISO see:

26.43.4.9. vcf-builder-settings

This Stage will set the JSON structures needed for an ESXi node to be included in the vCloud Foundation Builder built cluster. It must be run on Sledgehammer, prior to ESXi being installed.

The following Optional Params will be injected in to the JSON esxiHostSpec stanzas if set. If not specified, the default values will be used.

Param Default
vcf-builder/association digitalrebar-sddc-01
vcf-builder/esxiCredentials-username root
vcf-builder/esxiCredentials-password RocketSkates
vcf-builder/vSwitch vswitch0
vcf-builder/serverId Machine.UUID

26.43.4.10. vmware-esxi-hcl-validate

This task will run the VMware ESXi HCL compatibility checker and determine if the Machine meets the HCL compatibility for ESXi.

26.43.4.11. esxi-650a-install

Provides VMware Stage for ESXi 6.5.0a. For more details, and Download ISO see:

26.43.4.12. esxi-670-install

Provides VMware Stage for ESXi 6.7.0. Download from:

26.43.4.13. vmware-vsan-hcl-validate

This stage will verify that the Machine is HCL compliant for VSAN installation.

26.43.4.14. esxi-6.7.0-update1-10302608-custom-hitachi_1200_HA8000VGen10-install

Provides custom VMware Stage for Hitachi BladeSymphony and HA8000 specific hardware and drivers. For more details, and Download ISO see:

26.43.4.15. esxi-670u1-install

Provides VMware Stage for ESXi 6.7.0. Download from:

26.43.4.16. vmware-vsan-hcl-install

This stage will install all prerequisites for the VMware VSAN HCL compatibility checker tool.

26.43.4.17. esxi-650u2-install

Provides VMware Stage for ESXi 6.5.0update2. For more details, and Download ISO see:

26.43.4.18. esxi-fujitsu-vmvisor-installer-6.7-10-install

Provides custom VMware Stage for Fujitsu specific hardware and drivers. For more details, and Download ISO see:

26.43.4.19. vmware-esxi-set-password

This task allows the operator to set an insecure cleartext password value, which will be converted to a SHA512 hash for the machine admin password to be set to.

Alternatively, a unique randomly generated password can be created using the ‘esxi/generate-random-password’ param set to ‘true’.

26.43.4.20. esxi-6.7.1-10302608-nec-6.702-install

Provides custom VMware Stage for NEC specific hardware and drivers (NOT FOR NEC Express5800/R120h and T120h Series systems). For more details, and Download ISO see:

26.43.4.21. esxi-dellemc-esxi-6.7u1-10764712-a04-install

Provides custom VMware Stage for Dell EMC specific hardware and drivers. For more details, and Download ISO see:

26.43.4.22. vmware-esxi-install

This stage will install VMware vSphere ESXi on the machine of the ESXi and VSAN compatibility checks have succeeded (both set to True).

Future implementations of this should allow for a force-install option to allow installation even if the compatibility checks have failed.

26.43.4.23. esxi-hpe-esxi-6.7.0-update1-iso-gen9p-install

Provides custom VMware Stage for HPE specific hardware and drivers. For more details, and Download ISO see:

26.43.4.24. vcf-builder-deploy

This Stage will set the JSON structures needed for an ESXi node.

Requires ovftool - which can be acquired from the docker container sygibson/vmtools - which also contains a DRP Runner for running arbitrary workflow.

Param Default
vcf-builder/association digitalrebar-sddc-01
vcf-builder/esxiCredentials-username root
vcf-builder/esxiCredentials-password RocketSkates
vcf-builder/vSwitch vswitch0
vcf-builder/serverId Machine.UUID

26.43.5. tasks

The content package provides the following tasks.

26.43.5.1. vcf-builder-deploy

This task will use ovftool to deploy a vCloud Foundation builder appliance to a specified ESXi node.

26.43.5.2. vmware-esxi-hcl-validate

This task will run the VMware ESXi HCL compatibility checker and determine if the Machine meets the HCL compatibility for ESXi.

26.43.5.3. vmware-esxi-install

If the given Machine has passed both ESXi and VSAN HCL compatibility checks, then install the VMware vSphere ESXi version specified.

Uses the vmware/esxi-version Param (enum type) to define which supported version to install.

26.43.5.4. vmware-esxi-set-password

This task allows the operator to set an insecure cleartext password value, which will be converted to a SHA512 hash for the machine admin password to be set to.

Alternatively, a unique randomly generated password can be created using the ‘esxi/generate-random-password’ param set to ‘true’.

26.43.5.5. vmware-vsan-hcl-install

This task will install all prerequisites for the VMware VSAN HCL compatibility checker tool.

26.43.5.6. vmware-vsan-hcl-validate

This task will verify that the Machine is HCL compliant for VSAN installation.

26.43.5.7. vcf-builder-settings

This task will set the JSON structures needed for an ESXi node to be included in the vCloud Foundation Builder built cluster. It must be run on Sledgehammer, prior to ESXi being installed.

26.43.5.8. vmware-esxi-hcl-install

This task will install all prerequisites for the VMware HCL compatibility checker, and the tool itself.

26.43.6. workflows

The content package provides the following workflows.

26.43.6.1. esxi-550u3b-install

Provides VMware Workflow for ESXi 5.5.0update3b. For more details, and Download ISO see:

26.43.6.2. esxi-6.7.1-10302608-nec-6.702-install

Provides custom VMware Workflow for NEC specific hardware and drivers (NOT FOR NEC Express5800/R120h and T120h Series systems). For more details, and Download ISO see:

26.43.6.3. esxi-vmware-esxi-6.7.0-10302608-custom-cisco-install

Provides custom VMware Workflow for Cisco hardware and drivers. For more details, and Download ISO see:

26.43.6.4. esxi-vsan-670u1-install

Installs the ESXi instance for the vCloud Builder node.

26.43.6.5. vcf-builder-deploy

Workflow to install vCloud Foundation Builder VM appliance device.

26.43.6.6. esxi-6.7.1-10302608-nec-gen-6.7-install

Provides custom VMware Workflow for NEC Express5800/R120h and T120h Series specific hardware and drivers. For more details, and Download ISO see:

26.43.6.7. esxi-650a-install

Provides VMware Workflow for ESXi 6.5.0a. For more details, and Download ISO see:

26.43.6.8. esxi-650u2-install

Provides VMware Workflow for ESXi 6.5.0update2. For more details, and Download ISO see:

26.43.6.9. esxi-dellemc-esxi-6.7u1-10764712-a04-install

Provides workflow to install ESXi for Dell EMC specific hardware. For more details, and Download ISO see:

26.43.6.10. esxi-hpe-esxi-6.7.0-update1-iso-gen9p-install

Provides custom VMware Workflow for HPE specific hardware and drivers. For more details, and Download ISO see:

26.43.6.11. esxi-lenovo_esxi6.7u1-10302608_201810-install

Provides custom VMware Workflow for Lenovo specific hardware and drivers. For more details, and Download ISO see:

26.43.6.12. esxi-vsan-install

Workflow to install VSAN on ESXi 6.7.0u1 node.

26.43.6.13. esxi-6.7.0-update1-10302608-custom-hitachi_1200_HA8000VGen10-install

Provides custom VMware Workflow for Hitachi BladeSymphony and HA8000 specific hardware and drivers. For more details, and Download ISO see:

26.43.6.14. esxi-670u1-install

Provides VMware BootEnv for ESXi 6.7.0update1. For more details, and Download ISO see:

26.43.6.15. esxi-fujitsu-vmvisor-installer-6.7-10-install

Provides custom VMware Workflow for Fujitsu specific hardware and drivers. For more details, and Download ISO see:

26.43.6.16. esxi-6.7.0-update1-10302608-custom-hitachi_0200_Blade_HA8000-install

Provides custom VMware Workflow for Hitachi HA8000V Gen10 specific hardware and drivers. For more details, and Download ISO see:

26.43.6.17. esxi-600u3a-install

Provides VMware BootEnv for ESXi 6.0.0u3a. For more details, and Download ISO see:

26.43.6.18. esxi-670-install

Provides VMware Workflow for ESXi 6.7.0. Download from:

26.43.7. bootenvs

The content package provides the following bootenvs.

26.43.7.1. esxi-670u1-install

Provides VMware BootEnv for ESXi 6.7.0update1. For more details, and Download ISO see:

26.43.7.2. esxi-6.7.0-update1-10302608-custom-hitachi_1200_HA8000VGen10-install

Provides custom VMware BootEnv for Hitachi BladeSymphony and HA8000 specific hardware and drivers. For more details, and Download ISO see:

26.43.7.3. esxi-600u3a-install

Provides VMware BootEnv for ESXi 6.0.0u3a. For more details, and Download ISO see:

26.43.7.4. esxi-650u2-install

Provides VMware BootEnv for ESXi 6.5.0update2. For more details, and Download ISO see:

26.43.7.5. esxi-6.7.1-10302608-nec-gen-6.7-install

Provides custom VMware BootEnv for NEC Express5800/R120h and T120h Series specific hardware and drivers. For more details, and Download ISO see:

26.43.7.6. esxi-650a-install

Provides VMware BootEnv for ESXi 6.5.0a. For more details, and Download ISO see:

26.43.7.7. esxi-hpe-esxi-6.7.0-update1-iso-gen9p-install

Provides custom VMware BootEnv for HPE specific hardware and drivers. For more details, and Download ISO see:

26.43.7.8. esxi-dellemc-esxi-6.7u1-10764712-a04-install

Provides custom VMware BootEnv for Dell specific hardware and drivers. For more details, and Download ISO see:

26.43.7.9. esxi-fujitsu-vmvisor-installer-6.7-10-install

Provides custom VMware BootEnv for Fujitsu specific hardware and drivers. For more details, and Download ISO see:

26.43.7.10. esxi-lenovo_esxi6.7u1-10302608_201810-install

Provides custom VMware BootEnv for Lenovo specific hardware and drivers. For more details, and Download ISO see:

26.43.7.11. esxi-550u3b-install

Provides VMware BootEnv for ESXi 5.5.0update3b. For more details, and Download ISO see:

26.43.7.12. esxi-600u2-install

Provides VMware BootEnv for ESXi 6.0.0u2. For more details, and Download ISO see:

26.43.7.13. esxi-670-install

Provides VMware BootEnv for ESXi 6.7.0. Download from:

26.43.7.14. esxi-vmware-esxi-6.7.0-10302608-custom-cisco-install

Provides custom VMware BootEnv for Cisco hardware and drivers. For more details, and Download ISO see:

26.43.7.15. esxi-vsan-install

Install vSphere VSAN on top of VMware BootEnv for ESXi 6.7.0update1. For more details, and Download ISO see:

26.43.7.16. esxi-6.7.0-update1-10302608-custom-hitachi_0200_Blade_HA8000-install

Provides custom VMware BootEnv for Hitachi HA8000V Gen10 specific hardware and drivers. For more details, and Download ISO see:

26.43.7.17. esxi-6.7.1-10302608-nec-6.702-install

Provides custom VMware BootEnv for NEC specific hardware and drivers (NOT FOR NEC Express5800/R120h and T120h Series systems). For more details, and Download ISO see:

26.43.8. params

The content package provides the following params.

26.43.8.1. esxi/network-firstboot-ipaddr

Use this param with esxi/network-firstboot-type set to manual to specify the ESXi nodes network configuration post-kickstart. NOTE, you must verify that the IP addressing and Layer 2 characteristics are correct for proper network connectivity post-reboot.

26.43.8.2. esxi/network-firstboot-netmask

Use this param with esxi/network-firstboot-type set to manual to specify the ESXi nodes network configuration post-kickstart. NOTE, you must verify that the IP addressing and Layer 2 characteristics are correct for proper network connectivity post-reboot.

26.43.8.3. esxi/network-kickstart-type

This Param specifies how the ESXi node should be configured for it’s network interface during kickstart installation. The supported mode types are:

type notes
dhcp (default) requests IP info via DHCP service
convert converts the existing DHCP lease to a static assignment
manual operator provides values via additonal params

If set to manual use the following Params to configure the network

param notes
esxi/network-ipaddr sets the IP Address
esxi/network-netmask sets the subnet Netmask
esxi/network-gateway sets the Default Gateway
esxi/network-dns sets DNS server(s) (comma, no spaces separated)
esxi/network-hostname defines nodes Hostname

All values must be specified for “manual” type.

WARNING

Currently, changing the network type from DHCP will not cause any interaction with your DRP Endpoint. This means that if you use convert to static IP assignment, the DRP endpoint will not be aware of this. You will need to create a Reservation manually to insure your IP assignment isn’t stomped on.

Similarly, if you use manual, it is your responsibility to insure you do not map a manual IP assignment to any DHCP ranges, unless you also arrange to have that IP assignment converted to a Reservation (when using DRP as the DHCP service).

Future versions of this plugin should correct this issue.

26.43.8.4. esxi/ntp-conf

This is a simple string type that defines the name of a user created template file that contains your NTP configuration settings. The current /etc/ntp.conf template is somewhat rigid and only allows injecting the NTP servers to use. If you need more advanced customizations, use this to create an ntp.conf file for your needs.

You may still use the ntp-servers array if desired in your own template. See the Kickstart template on how to use the Param to inject in your own template (esxi-install-py3.ks.tmpl).

The template you specify should be a valid ntp.conf format.

26.43.8.5. esxi/shell-local

If set to True, enable the local ESXi shell during the installation of the VMware vSphere ESXi host.

By default, the shell will not be enabled.

26.43.8.6. esxi/skip-notify

This Param lets the operator skip the notification back to the DRP endpoint during kickstart installation, to set the bootenv to boot from local disk.

This option is primarily intended for debugging kickstart components that are rendered to the machine via DRP’s templating system, or to allow an operator to do continuous ESXi kickstart installations for testing purposes.

26.43.8.7. esxi/welcome-customize

By default Digital Rebar Provision VMware plugin will customize the /etc/vmware/welcome screen with DRP, RackN, and other additional information.

To disable this behavior and fall back to the product default, set this Param value to false.

26.43.8.8. vcf-builder/serverId

The ESXi server ID string in the cluster. By default the DRP Machine UUID will be used as the serverId.

If you choose to set a different value than this default behavior, then you will have to apply it as an individual Param (or as a different Profile from the vcf-builder-cluster-profile defined profile) on the given Machine.

26.43.8.9. vmware/esxi-hcl-location

The python3 path location to the installed ESXi Compatibility Checker. This should be correctly setup by the vmware-esxi-hcl-install Stage.

Note that the Compatibility Checker tool currently requires access to a vCenter server and ESXi already installed on a host to gather the compatibility report information for. Additionaly, you must have internet access to the VMware API Gateway located at:

26.43.8.10. esxi/http-mirror

This Param lets the operator override the location of the HTTP located VMware ESXi installer. Typically, an operator uses a drpcli bootenvs uploadiso <ISO_NAME> which causes the ISO image to be copied to the DRP Endpoint, and “exploded” out on the TFTP/ HTTP file serving file system.

Kickstart installation is served from this location to the installing machine. With use of this Param, the ESXi ISO contents can be relocated an altnernate HTTP Mirror which will allow for operator control over mirroring, availability, and capacity requirements.

26.43.8.11. esxi/ks-custom-sections

This Param allows an operator to create a list of additional Templates to include during the ESXi kickstart installation phase. Kicstarts support three additional installation phases supported by this Param:

  • %pre
  • %post
  • %firstboot

Each phase can use busybox (shell) or python interpreter to implement customizations. This results in the “phase” types that you can set as follows:

  • pre-busybox
  • pre-python
  • post-busybox
  • post-python
  • fistboot-busybox
  • fistboot-python

To inject custom kickstart directives, see the esxi/ks-custom-kickstart param.

Each “phase” has a an array of various templates that can be injected in that given phase to build up the Kickstart file. Below is an example:

# YAML example
esxi/ks-custom-sections:
  pre-busybox:
    - "my-pre-busybox-chunk1.ks.tmpl"
    - "my-pre-busybox-chunk2.ks.tmpl"
  post-python:
    - "my-post-python3-chunk2.ks.tmpl"
  firstboot-busybox:
    - "my-fistboot-busybox-chunk1.ks.tmpl"

# JSON example
{
  "firstboot-busybox": [
    "my-fistboot-busybox-chunk1.ks.tmpl"
  ],
  "post-python": [
    "my-post-python3-chunk2.ks.tmpl"
  ],
  "pre-busybox": [
    "my-pre-busybox-chunk1.ks.tmpl",
    "my-pre-busybox-chunk2.ks.tmpl"
  ]
}

26.43.8.12. esxi/network-firstboot-hostname

Use this param with esxi/network-firstboot-type set to manual to specify the ESXi nodes network configuration post-kickstart. NOTE, you must verify that the IP addressing and Layer 2 characteristics are correct for proper network connectivity post-reboot.

26.43.8.13. esxi/network-kickstart-gateway

Use this param with esxi/network-kickstart-type set to manual to specify the ESXi nodes network configuration post-kickstart. NOTE, you must verify that the IP addressing and Layer 2 characteristics are correct for proper network connectivity post-reboot.

26.43.8.14. esxi/network-kickstart-vlan

Sets the VLAN tag ID (VLANID) for the kickstart installation network settings.

Note that there are three possible places you may want/need to set a VLANID:

  1. At PXE boot time for the kernel - use kernel-options and vlanid=N syntax
  2. During the installation phase in the kickstart process - use the Param esxi/network-kickstart-vlan
  3. After final reboot, to transition to a “production” or similar network, use the Param esxi/network-firstboot-vlan

In many cases, the provisioning network may or may not be a VLAN tagged network, which may very likely be different from the final installed ESXi production use case network configuration. On ``firstboot`, you can specify values separately from the installation phases to support network transitions from install to production use.

If you set a different value for the firstboot stage VLANID, you must also insure the network settings are correctly reflected for the new VLAN. Your options are to use DHCP or Manual modes in this case (see esxi/network-type Param). Convert would not be correct in this case as the provisioning network is likely to not be the same IP address space as a production network when changing VLANIDs.

Valid values as defined by VMware for this field are from 1 to 4095.

26.43.8.15. vmware/vsan-hcl-completed

Defines if the machine has run the VMware vSphere VSAN HCL compliance check tool.

26.43.8.16. vsan/license

If specified, sets the license ID to assign to the installed ESXi VSAN appliance.

If not specified, then VSAN will be installed in evaluation mode.

26.43.8.17. esxi/generate-random-password

If specified, the ‘esxi-insecure-password.sh.tmpl’ template will dynamically generate a random password. This will be recorded in the insecure param ‘esxi/insecure-password’, then converted to a SHA512 hash value used to set the root/admin password.

Future iterations of this may include the ability to store the generated password on a remote password keeper, secrets vault, or whatever.

The default operation is to not generate a random password, but to use the value set in the ‘esxi/insecure-password’ param.

26.43.8.18. esxi/network-kickstart-dns

Use this param with esxi/network-kickstart-type set to manual to specify the ESXi nodes network configuration post-kickstart. NOTE, you must verify that the IP addressing and Layer 2 characteristics are correct for proper network connectivity post-reboot.

Up to two DNS nameservers may be specified by separating them with a comma (,) without any spaces (eg. 1.1.1.1,1.0.0.1

The two nameserver and format limitation is a VMware defined limit.

26.43.8.19. vmware/vsan-hcl-validated

Defines if the machine has been validated for VMware vSphere VSAN installation by the validation tool.

26.43.8.20. vcf-builder/esxiCredentials-password

Defines the ESXi password for vCF Builder to be able to access and manage the nodes.

26.43.8.21. esxi/disk-install-override-custom

Use this Param to specify additional custom templates to include in to the ‘esxi-disk-install-override.tmpl’ tool for setting custom strategies for the ESXi disk selection for install location.

This is intended to inject ESXi BASH “name() { … }” function stanzas in the existing ‘esxi-disk-install-override.tmpl’ template to extend the functionality to include on-the-fly strategy types discovered in the field.

# YAML example - “my-esxi-disk-override-1.tmpl” - “my-esxi-disk-override-2.tmpl”

# JSON example [

“my-esxi-disk-override-1.tmpl”, “my-esxi-disk-override-2.tmpl”

]

WARNING - The executing environment is ESXi kickstart installer (Weasel). You
must insure that the Function you inject operates correctly in this environment. For reference, see the Functions in the existing Template “esxi-disk-install-override.tmpl”.

Any functions MUST set the shell global variable named ‘SET_DISK’ to a correct value for defining which disk to install to. The values are documented in the ESXi documenation, for example:

Valid examples include:

  • –firstboot
  • –disk=mpx.vmhba1:C0:T0:L0

26.43.8.22. esxi/insecure-password

If specified, defines a HIGHLY INSECURE cleartext password to be converted to a SHA512 hash for the ‘root’ account on an ESXi instance.

Typically, the workflow will get a desired password from a remote infrastructure system (password manager, vault, etc.) as an API call, and then convert to a SHA512 for the ‘root’ account.

26.43.8.23. esxi/network-firstboot-dns

Use this param with esxi/network-firstboot-type set to manual to specify the ESXi nodes network configuration post-kickstart. NOTE, you must verify that the IP addressing and Layer 2 characteristics are correct for proper network connectivity post-reboot.

Up to two DNS nameservers may be specified by separating them with a comma (,) without any spaces (eg. 1.1.1.1,1.0.0.1

The two nameserver and format limitation is a VMware defined limit.

26.43.8.24. esxi/network-firstboot-vlan

Sets the VLAN tag ID (VLANID) for the installed ESXi instance on first boot.

Note that there are three possible places you may want/need to set a VLANID:

  1. At PXE boot time for the kernel - use kernel-options and vlanid=N syntax
  2. During the installation phase in the kickstart process - use the Param esxi/network-kickstart-vlan
  3. After final reboot, to transition to a “production” or similar network, use the Param esxi/network-firstboot-vlan

In many cases, the provisioning network may or may not be a VLAN tagged network, which may very likely be different from the final installed ESXi production use case network configuration. On ``firstboot`, you can specify values separately from the installation phases to support network transitions from install to production use.

If you set a different value for the firstboot stage VLANID, you must also insure the network settings are correctly reflected for the new VLAN. Your options are to use DHCP or Manual modes in this case (see esxi/network-type Param). Convert would not be correct in this case as the provisioning network is likely to not be the same IP address space as a production network when changing VLANIDs.

Valid values as defined by VMware for this field are from 1 to 4095.

26.43.8.25. esxi/network-kickstart-netmask

Use this param with esxi/network-kickstart-type set to manual to specify the ESXi nodes network configuration post-kickstart. NOTE, you must verify that the IP addressing and Layer 2 characteristics are correct for proper network connectivity post-reboot.

26.43.8.26. esxi/serial-console

Sets the serial console for the ESXi host. By default this is not enabled.

For Packet environment, insure to set com port to com2 like:

gdbPort=none logPort=none tty2Port=com2

26.43.8.27. vcf-builder/association

Defines the grouping for the vCloud Foundation Builder association between elements.

Example:
digitalrebar-sddc-01

26.43.8.28. vcf-builder/esxiCredentials-username

Used to connect to the ESXi instance for vCloud Builder to manage the nodes.

26.43.8.29. vmware/esxi-hcl-completed

Set to true if the Compatibility Checker has already been run for the given host.

26.43.8.30. vmware/esxi-version

This Param can be used to specify which supported version of VMware vSphere to install on a given Machine. Note that the version must be a supported BootEnv (the version matches the BootEnv, minus the -install trailer) type on the DRP Endpoint.

Supported versions are:
  • esxi-550u3b
  • esxi-600u2
  • esxi-600u3a
  • esxi-650a
  • esxi-650u2
  • esxi-670
  • esxi-670u1
  • esxi-6.7.0-update1-10302608-custom-hitachi_0200_Blade_HA8000
  • esxi-6.7.0-update1-10302608-custom-hitachi_1200_HA8000VGen10
  • esxi-6.7.1-10302608-nec-6.702
  • esxi-6.7.1-10302608-nec-gen-6.7
  • esxi-dellemc-esxi-6.7u1-10764712-a04
  • esxi-fujitsu-vmvisorer-6.7-10
  • esxi-hpe-esxi-6.7.0-update1-iso-gen9p
  • esxi-lenovo_esxi6.7u1-10302608_201810
  • esxi-vmware-esxi-6.7.0-10302608-custom-cisco

If nothing is specified, the default value is esxi-670u1

26.43.8.31. esxi/ks-custom-kickstart

This Param allows an operator to create a list of additional “kickstart” directives to apply to generated kickstart file. These directives will be placed after the network template, but before any other %pre, %post, and/or %firstboot sections.

If you wish to add additional templates for %pre, %post, and/or %firstboot sections, use the esxi/ks-custom-sections param.

Multiple additional templates can be called with kickstart commands in them. Below is an example:

# YAML example
esxi/ks-custom-kickstart:
  - "my-kickstart-1.ks.tmpl"
  - "my-kickstart-2.ks.tmpl"

# JSON example
{
  [
    "my-kickstart-1.ks.tmpl",
    "my-kickstart-2.ks.tmpl"
  ]
}

26.43.8.32. esxi/network-kickstart-hostname

Use this param with esxi/network-kickstart-type set to manual to specify the ESXi nodes network configuration post-kickstart. NOTE, you must verify that the IP addressing and Layer 2 characteristics are correct for proper network connectivity post-reboot.

26.43.8.33. esxi/skip-tools

If set to True, the tools.t00 module will be removed from the modules list at install time of the ESXi node. Since this module is over 155 MB in size, this increases the speed of the install and reduces the bandwidth needed to for pulling down the modules.

This is typically used in a dev/test environment where rapid (re)build of ESXi hypervisors is occuring, or in environments where the Guest tools are staged in an alternate location, or injected in to prebuilt images.

26.43.8.34. esxi/skip-version

This Param lets the operator skip the version call back to the DRP endpoint during kickstart installation. It is used to get the DRP version info and inject it in to the DCUI screen for identify verification purposes on a built DRP endpoint.

This option is primarily intended for debugging kickstart components that are rendered to the machine via DRP’s templating system.

26.43.8.35. vcf-builder/cluster-profile

This parameter is used to identify the Profile name to record the vCloud Foundation Builder build information.

26.43.8.36. vmware/esxi-hcl-validated

Once the VMware ESXi Compatibility Checker has been completed, this Param will contain the results of the check. If the machine is marked compatible by the VMware tools, then the value will be set to True otherwise, it’s False

If True then it is implied the machine is compliant with the HCL.

Note that both this Param and vmware/esxi-hcl-completed should be set to True to insure that the tooling ran, and the machine passed validation.

However, in DevTest situations, you may set the value to True to allow for subsequent installers to complete successfully, regardless of the actual HCL compatibility check results.

26.43.8.37. esxi/shell-remote

If set to True, enable the remote ESXi shell (SSH access) during the installation of the VMware vSphere ESXi hypervisor.

By default, the remote shell will not be enabled.

26.43.8.38. esxi/disk-install-override

Some hardware (namely HPE with “Smart” Array controllers do not iterate the disks smartly. This causes the ESXi install strategy to fail when the RAID controller is specified as a RAID 1 device with passthrough mode for the remainder of the devices. ESXi does not build an appropriate device type for us to handle with the –disk=mpx.vmhb0:… strategy.

This Param will override the ESXi Kickstart install … directive and select a given supported strategy for finding the disk to install to.

The currently supported install directives are defined below:

directive notes
first_disk Sets the install disk target to the default value of ‘–firstdisk’. Primarily useful only for testing the code path of this content, since this is the default behavior if nothing else is specified.
find_first_naa Selects the first device that is iterated in the /vmfs/devices/disks directory, with the name beginning with ‘naa.*’

Using the above listed strategies will set the Kickstart install command as follows:

install --disk=<FOUND_DEVICE>

If other install options need to be specified (eg –overwritevmfs), you must also set those as the Param esxi/disk-install-override-options and they will be appended to the above example install command. Here is an example:

# with 'esxi/disk-install-override-options' set to '--overwritevmfs'
# the 'install' command will be built up as follows:

install --disk=/vmfs/devices/disks/naa.60... --overwritevmfs

Note that custom functions can be injected in to the template to support strategies that are not directly released with this content. This allows for custom in-the-field templates to be built, and injected in to the DRP endpoint to support new “strategies” as needed.

If new strategies are developed/used, please contact RackN to help insure these are added in to standard product so field customizations are not necessary.

The Param type definition does not include an enum: … list as custom strategies may be injected via the esxi/disk-install-override-custom Param.

26.43.8.39. esxi/disk-install-override-options

Sets addtional options to add to the esxi/disk-install-override strategy that is defined. See that param for more documentation.

Defaults to setting –overwritevmfs for the Kickstart install command.

26.43.8.40. esxi/drp-port-disable

For installtion of ESXi to succeed, the Machine being installed must be able to reach the DRP API service port. This allows for some Python hackery to notify DRP to set the Machine to boot local disk, and other actions.

Once the Machine has been installed, it is possible to disable the outbound open port access in the firstboot section. Doing so will disable the ESXi instance from being able to communicate with the dr-provision API service unless the port is opened again.

You can manually enable/disable the API service port access with the following esxcli (or equivalent localcli) command:

esxcli network firewall ruleset set --ruleset-id=dr-provision --enabled=true

Set the true state to false to disable the port access.

26.43.8.41. esxi/is-nested

If set to true, set the VHV value duing install to flag that we’re running in a nested setup environment (ESXi on a hypervisor).

By default, this option is false.

26.43.8.42. esxi/network-firstboot-gateway

Use this param with esxi/network-firstboot-type set to manual to specify the ESXi nodes network configuration post-kickstart. NOTE, you must verify that the IP addressing and Layer 2 characteristics are correct for proper network connectivity post-reboot.

26.43.8.43. esxi/network-firstboot-type

This Param specifies how the ESXi node should be configured for it’s network interface post-kickstart. The supported mode types are:

type notes
dhcp (default) requests IP info via DHCP service
manual operator provides values via additonal params

If set to manual use the following Params are required to configure the network:

param notes
esxi/network-firstboot-ipaddr sets the IP Address
esxi/network-firstboot-netmask sets the subnet Netmask
esxi/network-firstboot-gateway sets the Default Gateway
WARNING

Currently, changing the network type from DHCP will not cause any interaction with your DRP Endpoint. This means that if you use convert to static IP assignment, the DRP endpoint will not be aware of this. You will need to create a Reservation manually to insure your IP assignment isn’t stomped on.

Similarly, if you use manual, it is your responsibility to insure you do not map a manual IP assignment to any DHCP ranges, unless you also arrange to have that IP assignment converted to a Reservation (when using DRP as the DHCP service).

Future versions of this plugin should correct this issue.

26.43.8.44. esxi/network-kickstart-ipaddr

Use this param with esxi/network-kickstart-type set to manual to specify the ESXi nodes network configuration post-kickstart. NOTE, you must verify that the IP addressing and Layer 2 characteristics are correct for proper network connectivity post-reboot.

26.43.8.45. esxi/vmnic-device

Use this param to specify the device to plumb the network configuration up with post install. By default we assume “vmnic0”, however, this may not be correct. This param allows the operator to override the defined NIC for the installed OS.

It is possible the Classify content can be used to identify the machine devices to set the Param on the machine for the correct NIC name.

26.43.8.46. vcf-builder/vSwitch

Sets the management vSwitch information to use for managing the ESXi instance via vCF Builder bringup.

Defaults to:
vSwitch0

26.43.8.47. esxi/disk-install-options

This Param lets the operator define any customizations to the ``install …` directive in the kickstart. If not specified, the default behavior is to set the directive as follows:

::
install –firstdisk –overwritevmfs

Setting this value will override the “--firstdisk --overwritevmfs” values with whatever the operator specifies. For options and details, see the VMware documentation:

26.43.8.48. esxi/license

If specified, sets the license ID to assign to the installed ESXi VMware vSphere hypervisor.

If not specified, then the hypervisor will be installed in evaluation mode.

26.43.8.49. esxi/network-firstboot-vmk

Use this param to specify the device to plumb the network configuration up with post install. By default we assume “vmk0”, however, this may not be correct. This param allows the operator to override the Management NIC for the installed OS.

26.43.8.50. esxi/python-sleep

Sets a number of seconds to sleep in python code, after making a Firewall transition change. On some hardware (eg. HPE Moonshot cartridges), there may be a timing issue that requires a temporary sleep to allow the firewall changes to “settle”.

The default value is 0 seconds (no sleep) if not otherwise specified, and can range from 0 to a maximum of 300 seconds. Partial second values are allowed (eg .300 for 300 microseconds).

26.43.8.51. esxi/skip-reboot

This Param lets the operator skip the reboot in to the installed ESXi node. Typically used for debugging purposes to examine the installed node, prior to it rebooting.