21.41. sledgehammer-builder - Sledgehammer Builder

The following documentation is for Sledgehammer Builder (sledgehammer-builder) content package at version v4.8.0-alpha00.25+g8e224a5bec085c80968ec27e0332c339a65d0659.

This content pack contains the workflows and profiles needed to build Sledgehammer on CentOS 8. Additionally, the content pack contains profiles the build expanded drivers for Sledgehammer (exablaze, mellanox, solarflare smart nics).

21.41.1. Design

Following the standard RackN Digital Rebar methods, a workflow is used to build the new sledgehammer on a machine. The machine can be virtual or physical, but must have internet access.

The process drives the machine through a centos 8 installation, customs the image for sledgehammer usage, and uploads the resulting image and profiles into DRP for usage.

Customizations can be done through the parameters. This includes injecting additional tasks or data. See the sledgehammer/customize-tasks parameter for more details.

21.41.2. Prerequisites

21.41.2.1. DRP Requirements

DRP requires a couple of things to make this happen.

  1. The drp-community-content content pack needs to be loaded. This can be done through the Catalog UX page.
  2. The sledgehammer-builder content pack needs to be loaded. This can be done through the Catalog UX page.
  3. The CentOS 8 iso needs to be loaded into DRP. This can be done by running: drpcli bootenvs uploadiso centos-8

That should prepare DRP for building sledgehammer.

21.41.2.2. Machine Requirements

To build sledgehammer, a machine is needed to do an install of centos 8 and then post installation work to capture the image.

The machine needs at least 2GB of memory and 20GB of storage. The machine needs to be able to PXE to DRP and get discovered. Additionally, the machine needs to be able to access the internet. This could be through a second interface with DHCP, see the sledgehammer/extra-ifs parameter.

NOTE: This will be destructive to the machine in question.

21.41.2.3. Outbound Access

The target machine MUST have outbound internet access to get packages and components needed to build sledgehammer. To that end, there is a parameter, sledgehammer/extra-ifs that can be used to cause DHCP to run on secondary interfaces. This is particularly useful for VMs that have a second interface that has internet access.

21.41.3. Building Sledgehammer

The following steps will produce a new sledgehammer image.

  1. Discover machine into DRP as normal.
  2. (Optional) Add sledgehammer-full-drivers profile to the machine if you wish to include the additional nic drivers.
  3. Set the workflow on the machine to: sledgehammer-build
  4. Wait for the workflow to complete.

Upon completion, there will be a new iso in the isos directory and a new profile in the profiles view for the new sledgehammer. These are named by the checksum of the image. The last job log for the process contains the name if you are running this multiple times.

21.41.4. Object Specific Documentation

21.41.4.1. workflows

The content package provides the following workflows.

21.41.4.1.1. sledgehammer-build

Sledghammer is the OS image Digital Rebar uses for discovery, inventory, and hardwre configuration. Sledgehammer is based on the current centos-8 boot environment, and requires that bootenv to be present and functional to operate.

You can customize the Sledgehammer build process by adding updated versions of the follwing Params to the machine you will run this workflow on:

  • sledgehammer/extra-packages
  • sledgehammer/unwanted-packages
  • sledgehammer/unwanted-kernel-modules
  • sledgehammer/disable-services
  • sledgehammer/enable-services
  • sledgehammer/customize-tasks

Please refer to the documentation for each of those parameters for information on what they are and what they allow you to change.

Once this workflow has finished building a new image, it will upload it to dr-provision along with a profile that will allow you to start using the new image immediately, and then power off the machine that was used to build the image.

21.41.4.2. bootenvs

The content package provides the following bootenvs.

21.41.4.2.1. sledgehammer-install

This BootEnv is used as the basis for building Sledgehammer, our in-memory discovery and inventory management environment. This bootenv is reponsible for performing a basic CentOS install on a sacrificial machine. The tasks that run after the install has finished are responsible for stripping out everything we do not need for Sledgehammer to boot as an in-memory OS image and packaging everything up for distribution.

21.41.4.3. params

The content package provides the following params.

21.41.4.3.1. sledgehammer/disable-services

CentOS has serveral services enabled by default that we don’t need in Sledgeahmmer. This param controls the ones we will disable.

21.41.4.3.2. sledgehammer/enable-services

Sledgehammer needs several different services enabled in order to operate properly.

21.41.4.3.3. sledgehammer/extra-ifs

Extra interfaces to configure during sledgehammer builds. This is only required if you are building a Sledgehammer instance on a VM with nonstandard networking, and it does not have anything to do with how Sledgehammer behaves at runtime.

21.41.4.3.4. sledgehammer/solarflare-driver-package

Tis param points at the Solarflare source tarball that should be used to install current Solarflare Ethernet drivers from.

21.41.4.3.5. sledgehammer/unwanted-packages

On a freshly installed Centos syhstem, there are generally several packages that are installed by default but that are not required for Sledgehammer ot do its job. This param contains a list of such packages.

21.41.4.3.6. sledgehammer/customize-tasks

If you want to build a customized Sledgehammer, the supported way to do it is to create additional tasks to perform whatever other customization steps you want to perform, and then add them to this list. They will be performed after the built-in extra package installation, and before discarding unneeded packages and conversion to a Sledgeahmmer image.

Any extra customization tasks should make sure that no extra bits wind up in the final Sledghammer image. THis includes removing any unneedeed documentation, source code, or additional packages and files that are not needed to support proper operation of Sledgehammer.

21.41.4.3.7. sledgehammer/exablaze-driver-repo

This param points at the Exablaze RPM repo that should be used to install current Exablaze drivers from.

21.41.4.3.8. sledgehammer/extra-packages

If you need to add extra packages to Sledgeahmmer that are available from the usual install repos and/or EPEL, you can do so via this parameter. You need to take care that the settings for the sledgehammer/unwanted-packages leave enough of these dependencies alone to allow for proper package operation.

21.41.4.3.9. sledgehammer/mellanox-driver-package

THis param points at the Mellanox EN source tarball that should be used to install current Mellanox Ehternet drivers from. Please note that this task only installs the basic Ethernet driver packages, it does not attempt to install the drivers that enable Infiniband or RDMA.

21.41.4.3.10. sledgehammer/unwanted-kernel-modules

The default kernel in Sledgeahmmer includes a lot of additional modules that are neither required nor wanted ion a datacenter provisioning enviromnent. This parameter controls which drivers we will get rid of.

21.41.4.4. profiles

The content package provides the following profiles.

21.41.4.4.1. sledgehammer-full-drivers

This profile is used to define all the known extra drivers to build with.

  • Exablaze
  • Solarflare
  • Mellanox

21.41.4.5. stages

The content package provides the following stages.

21.41.4.5.1. sledgehammer-build

This stage is responsible for building a Sledgehammer image. To use it, set a machine to this Stage and reboot it. dr-provision will then install a trimmed-down version of CentOS on the machine, strip out non -essential bits, then package the remainder up as a Sledgehammer image that everyone will be able to use.

21.41.4.6. tasks

The content package provides the following tasks.

21.41.4.6.1. sledgehammer-mellanox-current-drivers

This task installs up-to-date Mellanox drivers from the sourec package defined in the sledgehammer/mellanox-driver-package param.

This task is not included in Sledgehammer by default – to include it, add it to sledgehammer/customize-tasks and rebuild Sledgehammer.

Please note that a Sledgeahmmer image built using this task will not be compatible with UEFI Secure Boot, as the resulting kernel modules will not be signed by the CentOS signing authority.

Please also note that this task is designed to only install the Ethernet drivers, not the RDMA or Infiniband driver set. If you need those, you may need to spin your own custom version of Sledgehammer using a new task.

21.41.4.6.2. sledgehammer-place-start-up

This task places a few static assets that are needed for the Sledgehammer start-up process. It handles the following assets:

  • sledgehammer-start-up.sh

    This script is run as a systemd service once Sledgehammer has started. It is responsible for making sure the image was booted with the necessary kernel parameters and then downloading and executing the machine-independent startup script from dr-provision.

  • sledgehammer-motd

    This sets the default login banner.

  • sledgehammer-ssh-config

    This sets the default sshd configuration. We default to allowing root logins only via key based authentication and allowing sftp.

  • sledgehammer-service

    This is the systemd unit file that is responsible for starting sledgehammer-start-up.sh when Sledgehammer boots. It waits until the network has been configured and is online before starting.

21.41.4.6.3. sledgehammer-prepare-for-image-creation

This task prepares the installed OS before we capture it as a bootable Sledgehammer image. It is responsible for removing any unneeded packages, files, and other data that is not required for Sledgehammer to perform its tasks. It also arranges for all the services to be set up properly.

21.41.4.6.4. sledgehammer-solarflare-current-drivers

This task installs up-to-date Solarflare drivers from the source package defined in the sledgehammer/solarflare-driver-package param.

This task is not included in Sledgehammer by default – to include it, add it to sledgehammer/customize-tasks and rebuild Sledgehammer.

Please note that a Sledgeahmmer image built using this task will not be compatible with UEFI Secure Boot, as the resulting kernel modules will not be signed by the CentOS signing authority.

21.41.4.6.5. sledgehammer-create-stage1

We need the stage1 image to be as small as we can get it, and still be possible to load the stage2 image. That means that the stage1 image has little more than busybox, a few required modules, and a swuashfs that contains only modules that may be required for fetching the stage2 image.

21.41.4.6.6. sledgehammer-create-stage2

This task creates the live squashfs image for Sledgehammer. It is what will wind up ruinning from memory.

21.41.4.6.7. sledgehammer-customize

This task allows you to customize Sledgehammer by programatically inserting extra tasks via the ‘sledgehammer/customize-tasks’ param.

21.41.4.6.8. sledgehammer-create-image

Now that all the bits are staged, create a tarball that contains everything properly built and signed. When finished, upload the ISO and the profile with bootenv overrides to dr-provision

21.41.4.6.9. sledgehammer-exablaze-current-drivers

This task installs up-to-date Exablaze drivers from the source repo defined in the sledgehammer/exablaze-driver-repo param.

This task is not included in Sledgehammer by default – to include it, add it to sledgehammer/customize-tasks and rebuild Sledgehammer.

Please note that a Sledgeahmmer image built using this task will not be compatible with UEFI Secure Boot, as the resulting kernel modules will not be signed by the CentOS signing authority.

THIS DOES NOT WORK BECAUSE DKMS IS NOT FUNCTIONAL IN SLEDGEHAMMER. NEED SOURCE STYLE FOR THIS.

21.41.4.6.10. sledgehammer-place-stage1-assets

This task places the stage1 assets where they must be present for the stage1 initramfs to be built. The assets placed are:

  • sledgehammer-stage1-init

    This script is run when the Sledgehammer kernel and initrd have been loaded. It is responsible for transferring the stage2 image from dr-provision and transferring control to it.

  • sledgehammer-stage1-udhcpc-config

    This script is invoked by udhcpc whenever it gets or releases a lease. It is responsible for actually configuring the network interface.

  • squashfs-excludes

    this file defines what will be excluded from the stage2 squashfs image.