Customize HookOS for EKS Anywhere on Bare Metal

Customizing HookOS for EKS Anywhere on Bare Metal

To network boot bare metal machines in EKS Anywhere clusters, machines acquire a kernel and initial ramdisk that is referred to as HookOS. A default HookOS is provided when you create an EKS Anywhere cluster. However, there may be cases where you want and/or need to customize the default HookOS, such as to add drivers required to boot your particular type of hardware.

The following procedure describes how to customize and build HookOS. For more information on Tinkerbell’s HookOS Installation Environment, see the Tinkerbell Hook repo .

System requirements

>= 2G memory
>= 4 CPU cores # the more cores the better for kernel building.
>= 20G disk space

Dependencies

Be sure to install all the following dependencies.

jq
envsubst
pigz
docker
curl
bash >= 4.4
git
findutils

Clone the Hook repo or your fork of that repo:

git clone https://github.com/tinkerbell/hook.git
cd hook/

Run the Linux kernel menuconfig TUI and configure the kernel as needed. Save the config before you exit. The result of this step will be a modified kernel configuration file (./kernel/configs/generic-6.6.y-x86_64).
```
./build.sh kernel-config hook-latest-lts-amd64
```
Build the kernel container image. The result of this step will be a container image. Use docker images quay.io/tinkerbell/hook-kernel to see it.
```
./build.sh kernel hook-latest-lts-amd64
```

Add the embedded Action images. This creates the file, images.txt, in the images/hook-embedded directory and runs the script, images/hook-embedded/pull-images.sh, to pull and embed the images in the HookOS initramfs. The result of this step will be a populated images file: images/hook-embedded/images.txt and a Docker directory cache of images: images/hook-embedded/images/.

BUNDLE_URL=$(eksctl anywhere version | grep "https://anywhere-assets.eks.amazonaws.com/releases/bundles" | tr -d ' ' | cut -d":" -f2,3)
IMAGES=$(curl -s $BUNDLE_URL | grep "public.ecr.aws/eks-anywhere/tinkerbell/actions/\|public.ecr.aws/eks-anywhere/tinkerbell/tink/tink-worker" | sort | uniq | tr -d ' ' | cut -d":" -f2,3)
images_file="images/hook-embedded/images.txt"
rm "$images_file"
while read -r image; do
  action_name=$(basename "$image" | cut -d":" -f1)
  echo "$image 127.0.0.1/embedded/$action_name" >> "$images_file"
done <<< "$IMAGES"
(cd images/hook-embedded; ./pull-images.sh)

Build the HookOS kernel and initramfs artifacts. The sudo command is needed as the image embedding step uses Docker-in-Docker (DinD) which changes file ownerships to the root user. The result of this step will be the kernel and initramfs. These files are located at ./out/hook/vmlinuz-latest-lts-x86_64 and ./out/hook/initramfs-latest-lts-x86_64 respectively.
```
sudo ./build.sh linuxkit hook-latest-lts-amd64
```
Note: If you did not customize the kernel configuration, you can use the latest upstream built kernel by setting the USE_LATEST_BUILT_KERNEL to yes. Run this command instead of the previous one.
```
sudo ./build.sh linuxkit hook-latest-lts-amd64 USE_LATEST_BUILT_KERNEL=yes
```

Rename the kernel and initramfs files to vmlinuz-x86_64 and initramfs-x86_64 respectively.

mv ./out/hook/vmlinuz-latest-lts-x86_64 ./out/hook/vmlinuz-x86_64
mv ./out/hook/initramfs-latest-lts-x86_64 ./out/hook/initramfs-x86_64

To use the kernel (vmlinuz-x86_64) and initial ram disk (initramfs-x86_64) when you build your EKS Anywhere cluster, see the description of the hookImagesURLPath field in your cluster configuration file.