22.43. sledgehammer-builder - Sledgehammer Builder¶
The following documentation is for Sledgehammer Builder (sledgehammer-builder) content package at version v4.12.0-alpha00.78+gc037aaa40eb3ad853690ce178f9ab8a5bae4c436.
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).
## 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.
## Prerequisites
### 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. 1. The sledgehammer-builder content pack needs to be loaded. This can be done through the Catalog UX page. 1. The CentOS 8 iso needs to be loaded into DRP. This can be done by running: drpcli bootenvs uploadiso centos-8-install
That should prepare DRP for building sledgehammer.
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.
### 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.
## Building Sledgehammer
The following steps will produce a new sledgehammer image.
1. Discover machine into DRP as normal. 1. (Optional) Add sledgehammer-full-drivers profile to the machine if you wish to include the additional nic drivers. 1. Set the workflow on the machine to: sledgehammer-build 1. 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.
22.43.1. Object Specific Documentation¶
22.43.1.1. bootenvs¶
The content package provides the following bootenvs.
22.43.1.1.1. sledgehammer-8-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.
22.43.1.1.2. sledgehammer-9-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.
22.43.1.1.3. 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.
22.43.1.2. params¶
The content package provides the following params.
22.43.1.2.1. 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 Sledgehammer 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.
22.43.1.2.2. sledgehammer/disable-services¶
CentOS has serveral services enabled by default that we don’t need in Sledgehammer. This param controls the ones we will disable.
22.43.1.2.3. sledgehammer/enable-services¶
Sledgehammer needs several different services enabled in order to operate properly.
22.43.1.2.4. sledgehammer/exablaze-driver-repo¶
This param points at the Exablaze RPM repo that should be used to install current Exablaze drivers from.
22.43.1.2.5. 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.
22.43.1.2.6. sledgehammer/extra-packages¶
If you need to add extra packages to Sledgehammer 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.
22.43.1.2.7. 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.
22.43.1.2.8. sledgehammer/solarflare-driver-package¶
Tis param points at the Solarflare source tarball that should be used to install current Solarflare Ethernet drivers from.
22.43.1.2.9. sledgehammer/unwanted-kernel-modules¶
The default kernel in Sledgehammer 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.
22.43.1.2.10. sledgehammer/unwanted-packages¶
On a freshly installed Centos system, 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.
22.43.1.3. profiles¶
The content package provides the following profiles.
22.43.1.3.1. sledgehammer-full-drivers¶
This profile is used to define all the known extra drivers to build with.
Exablaze
Solarflare
Mellanox
22.43.1.4. stages¶
The content package provides the following stages.
22.43.1.4.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.
22.43.1.4.2. sledgehammer-build-8¶
This stage is responsible for building a Sledgehammer 8 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.
22.43.1.4.3. sledgehammer-build-9¶
This stage is responsible for building a Sledgehammer 9 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.
22.43.1.5. tasks¶
The content package provides the following tasks.
22.43.1.5.1. 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
22.43.1.5.2. 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.
22.43.1.5.3. sledgehammer-create-stage2¶
This task creates the live squashfs image for Sledgehammer. It is what will wind up ruinning from memory.
22.43.1.5.4. sledgehammer-customize¶
This task allows you to customize Sledgehammer by programatically inserting extra tasks via the sledgehammer/customize-tasks param.
22.43.1.5.5. 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 Sledgehammer 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.
- !!! warning
THIS DOES NOT WORK BECAUSE DKMS IS NOT FUNCTIONAL IN SLEDGEHAMMER. NEED SOURCE STYLE FOR THIS.
22.43.1.5.6. 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 Sledgehammer 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.
22.43.1.5.7. 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.
22.43.1.5.8. 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.
22.43.1.5.9. 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.
22.43.1.5.10. 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 Sledgehammer 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.
22.43.1.6. workflows¶
The content package provides the following workflows.
22.43.1.6.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.
22.43.1.6.2. sledgehammer-build-8¶
Sledghammer is the OS image Digital Rebar uses for discovery, inventory, and hardwre configuration. Sledgehammer is based on the current alma-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.
22.43.1.6.3. sledgehammer-build-9¶
Sledghammer is the OS image Digital Rebar uses for discovery, inventory, and hardwre configuration. Sledgehammer is based on the current alma-9 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.
