Customize HookOS for EKS Anywhere on Bare Metal

Customizing HookOS for EKS Anywhere on Bare Metal

To initally PXE boot bare metal machines used in EKS Anywhere clusters, Tinkerbell acquires a kernel and initial ramdisk that is referred to as the HookOS. A default HookOS is provided when you create an EKS Anywhere cluster. However, there may be cases where you want to override the default HookOS, such as to add drivers required to boot your particular type of hardware.

The following procedure describes how to get the Tinkerbell stack’s Hook/Linuxkit OS built locally. For more information on Tinkerbell’s Hook Installation Environment, see the Tinkerbell Hook repo .

  1. Clone the hook repo or your fork of that repo:

    git clone
    cd hook/
  2. Pull down the commit that EKS Anywhere is tracking for Hook:

    git checkout -b <new-branch> 029ef8f0711579717bfd14ac5eb63cdc3e658b1d

    NOTE: This commit number can be obtained from the EKS-A build tooling repo .

  3. Make changes shown in the following diff in the Makefile located in the root of the repo using your favorite editor.

    diff —git a/Makefile b/Makefile
    index 66b7f48..f9fc283 100644
    --- a/Makefile
    +++ b/Makefile
    @@ -1,4 +1,4 @@
    -ORG ?= (
    +ORG ?= localhost:5000/tinkerbell
     ARCH := $(shell uname -m)
     GIT_VERSION ?= $(shell git log -1 —format="%h")
    @@ -53,13 +53,13 @@ dev-bootkitBuild:
     cd bootkit; docker buildx build —load -t $(ORG)/hook-bootkit:0.0 .
    -  cd bootkit; docker buildx build —platform linux/amd64,linux/arm64 —push -t $(ORG)/hook-bootkit:0.0 .
    +  cd bootkit; docker buildx build —platform linux/amd64 —push -t $(ORG)/hook-bootkit:0.0 .
     cd tink-docker; docker buildx build —load -t $(ORG)/hook-docker:0.0 .
    -  cd tink-docker; docker buildx build —platform linux/amd64,linux/arm64 —push -t $(ORG)/hook-docker:0.0 .
    +  cd tink-docker; docker buildx build —platform linux/amd64 —push -t $(ORG)/hook-docker:0.0 .

    Changes above change the ORG variable to use a local registry (localhost:5000) and change the docker build command to only build for the immediately required platform to save time.

  4. Modify the hook.yaml file located in the root of the repo with the following changes:

    diff --git a/hook.yaml b/hook.yaml
     index 0c5d789..b51b35e 100644
     net: host
    --- a/hook.yaml
    +++ b/hook.yaml
    @@ -1,5 +1,5 @@
    - image: (
    + image: localhost:5000/tinkerbell/hook-kernel:5.10.85
     cmdline: "console=tty0 console=ttyS0 console=ttyAMA0 console=ttysclp0"
     - linuxkit/init:v0.8
    @@ -42,7 +42,7 @@ services:
     - /var/run:/var/run
     - name: docker
    - image: (
    + image: localhost:5000/tinkerbell/hook-docker:0.0
     - all
     net: host
    @@ -64,7 +64,7 @@ services:
     - /var/run/docker
     - /var/run/worker
     - name: bootkit
    - image: (
    + image: localhost:5000/tinkerbell/hook-bootkit:0.0
     - all

    The changes above are for using local registry (localhost:5000) for hook-docker, hook-bootkit, and hook-kernel.

    NOTE: You may also need to modify the hook.yaml file if you want to add or change components that are used to build up the image. So far, for example, we have needed to change versions of init and getty and inject SSH keys. Take a look at the LinuxKit Examples site for examples.

  5. Make any planned custom modifications to the files under hook, if you are only making changes to bootkit or tink-docker.

  6. If you are modifying the kernel, such as to change kernel config parameters to add or modify drivers, follow these steps:

    • Change into kernel directory and make a local image for amd64 architecture:
    cd kernel; make kconfig_amd64
    • Run the image
    docker run --rm -ti -v $(pwd):/src:z
    • You can now navigate to the source code and run the UI for configuring the kernel:
    cd linux-5-10
    make menuconfig
    • Once you have changed the necessary kernel configuration parameters, copy the new configuration:
    cp .config /src/config-5.10.x-x86_64

    Exit out of container into the repo’s kernel directory and run make:

    /linux-5.10.85 # exit
    user1 % make
  7. Install Linuxkit based on instructions from the LinuxKit page.

  8. Ensure that the linuxkit tool is in your PATH:

    export PATH=$PATH:/home/tink/linuxkit/bin
  9. Start a local registry:

    docker run -d -p 5000:5000 -—name registry registry:2
  10. Compile by running the following in the root of the repo:

    make dist  
  11. Artifacts will be put under the dist directory in the repo’s root:

  12. To use the kernel (vmlinuz) and initial ram disk (initramfs) when you build your cluster, see the description of the hookImagesURLPath field in your Bare Metal configuration file.