ESXi 5.x/6.x deployment with Foreman

First we create a dummy installation media. Technically this isn't needed, but Foreman doesn't let us proceed if we don't provide an installation media. Foreman tries to retrieve a kernel and an initial ramdisk from that source. The disadvantage of this dummy installation media is that the HTTP requests to the server usually result in 404 errors and two empty files on the TFTP server.

There is a Foreman feature request that addresses this problem. For the moment we simply ignore it.

Since we don't have a special ESXi operating system family object, we set the operating system family to Red Hat. The name and path of the installation media are free to choose:

Now we can click Submit and go on with the next step.

Next we create the operating system object. On the first panel we again choose Red Hat as our operating system family. Make also sure that you choose a supported hash function for password encryption, otherwise the installation will bail out. SHA512 should work:

On the installation media panel we select the freshly created dummy media:

For now we can click Submit and finish this dialog.

We need to create a template of type PXELinux next. The name can be chosen freely, the type is, as said before, PXELinux. We associate this template with the operation system object, that we created in a previous step. The next three screen dumps illustrate this steps:

The most interesting part is, of course, the template code itself:

<%#
kind: PXELinux
name: ESXi 6.0 (PXELinux)
oses:
- ESXi 6.0
%>
#
# This file was deployed via '<%= @template_name %>' template
#


INCLUDE goto.cfg

LABEL chainloadsyslnx386
  kernel pxechn.c32
  append /syslinux386/pxelinux.0 -p /syslinux386/

LABEL installesx60
  kernel ../esx60/mboot.c32
  append -c boot.cfg ks=<%= foreman_url('provision') %>

First you will notice the include statement. We created two files named goto.cfg in a previous step. The file in the TFTP root directory contains the statement DEFAULT chainloadsyslnx386, the other file -in the directory /syslinux386- contains the statement DEFAULT installesx60.

Depending on which variant of goto.cfg is included, syslinux executes either the actions below label chainloadsyslnx386 or the actions below label installesx60.

But how do we choose which goto.cfg is loaded? As a default the include file is loaded from the TFTP root directory. This means that after booting at first the actions below the label chainloadsyslinx386 are executed. They advise syslinux to load the chain loader module pxechn.c32. This module then loads another layer 0 network boot programme, named /syslinux386/pxelinux.0, which is the NBP that comes with syslinux 3.86. We advise this new NBP to find its configuration in the directory /syslinux386.

Now pxelinux.0, version 3.86, is loaded and it evaluates above code again. Since it looks into /syslinux386 for configuration files, the second goto.cfg is found and the default label changed to installesx60. This advises syslinux to load the mboot.c32 module from the relative directory path ../esx60. This is VMware's customised module, that now loads fine into syslinux 3.86. It is parametrised with its configuration file boot.cfg and a URL pointing to a kickstart provision file.

This little indirection allows us to boot ESXi with its vendor supported syslinux 3.86, while every other deployment task still uses the default syslinux of the Foreman installation.

Next we need a partition table. This can be as complicated as you want or as simple as removing all existing partitions:

The template code:

<%#
kind: ptable
name: ESXi 6.0 (Partitioning)
oses:
- ESXi 6.0
%>

# Clear all partitions.
clearpart --firstdisk --overwritevmfs

As this last step we create a provision template. Analogous to the PXELinux template the name can be choosen freely and we associate the template with the ESXi operating system object:

The template code is basically a standard ESXi kickstart file. It is by no means a receipt of how to configure an ESXi server. There is a lot you want to change for ESXi servers in production.

<%#
kind: provision
name: ESXi 6.0 (Provision)
oses:
- ESXi 6.0
%>

# Accept the VMware End User License Agreement.
vmaccepteula


# Set the root password for the DCUI and Tech Support Mode.
# Make sure to use a supported hash function, like SHA512.
rootpw --iscrypted <%= root_pass %>


# Partitioning.
# Default: Clear all partitions.
<% if @dynamic -%>
%include /tmp/diskpart.cfg
<% else -%>
<%= @host.diskLayout %>
<% end -%>


# Install on first disk.
install --firstdisk --overwritevmfs


# Set the network to DHCP on the first network adapter.
network --bootproto=dhcp --device=vmnic0


<% if @host.params['PerformReboot'] == '1' -%>
# Reboot after installation.
reboot
<% end -%>


# First boot script.
%firstboot --interpreter=busybox

# Do stuff to further customise your installation.

# Inform the build system that we are done.
# This is the ideal way yo do it, but it doesn't work with Foreman.
#echo "Informing Foreman that we are built"
#Older Foreman versions: wget -q -O /dev/null <%= foreman_url %>
#wget -q -O /dev/null <%= foreman_url('built') %>



%post --interpreter=busybox

# Fix DNS.
echo "nameserver <%= @host.subnet.dns_primary %>" > /etc/resolv.conf

# Inform the build system that we are done.
# This should be done in the firstboot script. But
# that isn't supported by Foreman at the moment.

echo "Informing Foreman that we are built"
#Older Foreman versions: wget -q -O /dev/null <%= foreman_url %>
wget -q -O /dev/null <%= foreman_url('built') %>

exit 0

The successful finish of the installation should be reported in a first boot script, after the machine booted for the first time into the installed system. This would also ensure that further customisations would be covered by this 'guard'.

The problem is, that Foreman does not support local reboots during the installation phase. There is a Foreman feature request to address this.

After finishing the provision template we go back to the operating system object we created earlier and assign the freshly created partition table, the PXELinux template and the provision template:

Now all preparation steps are done and we can provision a machine and test our setup.