Install Guide¶

Configuring IPA¶

ironic-python-agent is a ramdisk developed for ironic and support for ironic-inspector was added during the Liberty cycle. This is the default ramdisk starting with the Mitaka release.

To build an ironic-python-agent ramdisk, do the following:

• Get the new enough version of diskimage-builder:

  sudo pip install -U "diskimage-builder>=1.1.2"
  

• Build the ramdisk:

  disk-image-create ironic-agent fedora -o ironic-agent
  

  Note

  Replace “fedora” with your distribution of choice.

• Use the resulting files ironic-agent.kernel and ironic-agent.initramfs in the following instructions to set PXE or iPXE.

Alternatively, you can download a prebuilt TinyIPA image or use the other builders.

Configuring PXE¶

For the PXE boot environment, you’ll need:

• TFTP server running and accessible (see below for using dnsmasq). Ensure pxelinux.0 is present in the TFTP root.

  Copy ironic-agent.kernel and ironic-agent.initramfs to the TFTP root as well.

• Next, setup $TFTPROOT/pxelinux.cfg/default as follows:

  default introspect
  
  label introspect
  kernel ironic-agent.kernel
  append initrd=ironic-agent.initramfs ipa-inspection-callback-url=http://{IP}:5050/v1/continue systemd.journald.forward_to_console=yes
  
  ipappend 3
  

  Replace {IP} with IP of the machine (do not use loopback interface, it will be accessed by ramdisk on a booting machine).

  Note

  While systemd.journald.forward_to_console=yes is not actually required, it will substantially simplify debugging if something goes wrong. You can also enable IPA debug logging by appending ipa-debug=1.

  IPA is pluggable: you can insert introspection plugins called collectors into it. For example, to enable a very handy logs collector (sending ramdisk logs to ironic-inspector), modify the append line in $TFTPROOT/pxelinux.cfg/default:

  append initrd=ironic-agent.initramfs ipa-inspection-callback-url=http://{IP}:5050/v1/continue ipa-inspection-collectors=default,logs systemd.journald.forward_to_console=yes
  

  Note

  You probably want to always keep the default collector, as it provides the basic information required for introspection.

• You need PXE boot server (e.g. dnsmasq) running on the same machine as ironic-inspector. Don’t do any firewall configuration: ironic-inspector will handle it for you. In ironic-inspector configuration file set dnsmasq_interface to the interface your PXE boot server listens on. Here is an example dnsmasq.conf:

  port=0
  interface={INTERFACE}
  bind-interfaces
  dhcp-range={DHCP IP RANGE, e.g. 192.168.0.50,192.168.0.150}
  enable-tftp
  tftp-root={TFTP ROOT, e.g. /tftpboot}
  dhcp-boot=pxelinux.0
  dhcp-sequential-ip
  

  Note

  dhcp-sequential-ip is used because otherwise a lot of nodes booting simultaneously cause conflicts - the same IP address is suggested to several nodes.

Configuring iPXE¶

iPXE allows better scaling as it primarily uses the HTTP protocol instead of slow and unreliable TFTP. You still need a TFTP server as a fallback for nodes not supporting iPXE. To use iPXE, you’ll need:

• TFTP server running and accessible (see above for using dnsmasq). Ensure undionly.kpxe is present in the TFTP root. If any of your nodes boot with UEFI, you’ll also need ipxe.efi there.

• You also need an HTTP server capable of serving static files. Copy ironic-agent.kernel and ironic-agent.initramfs there.

• Create a file called inspector.ipxe in the HTTP root (you can name and place it differently, just don’t forget to adjust the dnsmasq.conf example below):

  #!ipxe
  
  :retry_dhcp
  dhcp || goto retry_dhcp
  
  :retry_boot
  imgfree
  kernel --timeout 30000 http://{IP}:8088/ironic-agent.kernel ipa-inspection-callback-url=http://{IP}>:5050/v1/continue systemd.journald.forward_to_console=yes BOOTIF=${mac} initrd=agent.ramdisk || goto retry_boot
  initrd --timeout 30000 http://{IP}:8088/ironic-agent.ramdisk || goto retry_boot
  boot
  

  Note

  Older versions of the iPXE ROM tend to misbehave on unreliable network connection, thus we use the timeout option with retries.

  Just like with PXE, you can customize the list of collectors by appending the ipa-inspector-collectors kernel option. For example:

  ipa-inspection-collectors=default,logs,extra_hardware
  

• Just as with PXE, you’ll need a PXE boot server. The configuration, however, will be different. Here is an example dnsmasq.conf:

  port=0
  interface={INTERFACE}
  bind-interfaces
  dhcp-range={DHCP IP RANGE, e.g. 192.168.0.50,192.168.0.150}
  enable-tftp
  tftp-root={TFTP ROOT, e.g. /tftpboot}
  dhcp-sequential-ip
  dhcp-match=ipxe,175
  dhcp-match=set:efi,option:client-arch,7
  dhcp-match=set:efi,option:client-arch,9
  # Client is already running iPXE; move to next stage of chainloading
  dhcp-boot=tag:ipxe,http://{IP}:8088/inspector.ipxe
  # Client is PXE booting over EFI without iPXE ROM,
  # send EFI version of iPXE chainloader
  dhcp-boot=tag:efi,tag:!ipxe,ipxe.efi
  dhcp-boot=undionly.kpxe,localhost.localdomain,{IP}
  

  First, we configure the same common parameters as with PXE. Then we define ipxe and efi tags. Nodes already supporting iPXE are ordered to download and execute inspector.ipxe. Nodes without iPXE booted with UEFI will get ipxe.efi firmware to execute, while the remaining will get undionly.kpxe.