Skip to content

Commit

Permalink
Update the HookOS customization doc: (#8181)
Browse files Browse the repository at this point in the history 
There is a new and much simpler process now.

Signed-off-by: Jacob Weinstock <[email protected]>
  • Loading branch information
@jacobweinstock
jacobweinstock committed Jun 20, 2024
1 parent 336551f commit 8832fe5
Showing 1 changed file with 31 additions and 160 deletions.
191 changes: 31 additions & 160 deletions docs/content/en/docs/getting-started/baremetal/customize/bare-custom-hookos.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,191 +8,62 @@ description: >
Customizing HookOS for EKS Anywhere on Bare Metal
---

To initially network boot bare metal machines used in EKS Anywhere clusters, Tinkerbell acquires a kernel and initial ramdisk that is referred to as the HookOS.
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 to override the default HookOS, such as to add drivers required to boot your particular type of hardware.
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 get the Tinkerbell stack’s Hook/Linuxkit OS built locally.
For more information on Tinkerbell’s Hook Installation Environment, see the [Tinkerbell Hook repo](https://github.com/tinkerbell/hook).
The following procedure describes how to customize and build HookOS.
For more information on Tinkerbell’s HookOS Installation Environment, see the [Tinkerbell Hook repo](https://github.com/tinkerbell/hook).

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

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

1. Pull down the commit that EKS Anywhere is tracking for Hook:

```bash
git checkout -b <new-branch> 03a67729d895635fe3c612e4feca3400b9336cc9
```

>**_NOTE_**: This commit number can be obtained from the [EKS-A build tooling repo](https://github.com/aws/eks-anywhere-build-tooling/blob/main/projects/tinkerbell/hook/GIT_TAG).
>

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

```bash
diff --git a/Makefile b/Makefile
index e7fd844..8e87c78 100644
--- a/Makefile
+++ b/Makefile
@@ -2,7 +2,7 @@
### !!NOTE!!
# If this is changed then a fresh output dir is required (`git clean -fxd` or just `rm -rf out`)
# Handling this better shows some of make's suckiness compared to newer build tools (redo, tup ...) where the command lines to tools invoked isn't tracked by make
-ORG := quay.io/tinkerbell
+ORG := localhost:5000/tinkerbell
# makes sure there's no trailing / so we can just add them in the recipes which looks nicer
ORG := $(shell echo "${ORG}" | sed 's|/*$$||')
```

Changes above change the ORG variable to use a local registry (`localhost:5000`)

1. Make changes shown in the following `diff` in the `rules.mk` located in the root of the repo using your favorite editor.

```bash
diff --git a/rules.mk b/rules.mk
index b2c5133..64e32b1 100644
--- a/rules.mk
+++ b/rules.mk
@@ -22,7 +22,7 @@ ifeq ($(ARCH),aarch64)
ARCH = arm64
endif
-arches := amd64 arm64
+arches := amd64
modes := rel dbg
hook-bootkit-deps := $(wildcard hook-bootkit/*)
@@ -87,13 +87,12 @@ push-hook-bootkit push-hook-docker:
docker buildx build --platform $$platforms --push -t $(ORG)/$(container):$T $(container)
.PHONY: dist
-dist: out/$T/rel/amd64/hook.tar out/$T/rel/arm64/hook.tar ## Build tarballs for distribution
+dist: out/$T/rel/amd64/hook.tar ## Build tarballs for distribution
dbg-dist: out/$T/dbg/$(ARCH)/hook.tar ## Build debug enabled tarball
dist dbg-dist:
for f in $^; do
case $$f in
*amd64*) arch=x86_64 ;;
- *arm64*) arch=aarch64 ;;
*) echo unknown arch && exit 1;;
esac
d=$$(dirname $$(dirname $$f))
```

Above changes are for the `docker build` command to only build for the immediately required platform (amd64 in this case) to save time.
## System requirements

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

1. Modify the `hook.yaml` file located in the root of the repo with the following changes:
## Dependencies

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

The changes above are for using local registry (localhost:5000) for hook-docker, hook-bootkit, and hook-kernel.
Be sure to install all the following dependencies.

>**_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](https://github.com/linuxkit/linuxkit/tree/master/examples) site for examples.
>
- `jq`
- `envsubst`
- `pigz`
- `docker`
- `curl`
- `bash` >= 4.4
- `git`
- `findutils`

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


1. 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:
1. Clone the Hook repo or your fork of that repo:

```bash
cd kernel; make kconfig_amd64
```

* Run the image

```bash
docker run --rm -ti -v $(pwd):/src:z quay.io/tinkerbell/kconfig
```

* You can now navigate to the source code and run the UI for configuring the kernel:

```bash
cd linux-5-10
make menuconfig
```

* Once you have changed the necessary kernel configuration parameters, copy the new configuration:

```bash
cp .config /src/config-5.10.x-x86_64
git clone https://github.com/tinkerbell/hook.git
cd hook/
```

Exit out of container into the repo’s kernel directory and run make:
1. Run the Linux kernel [menuconfig](https://en.wikipedia.org/wiki/Menuconfig) TUI and configuring the kernel as needed. Be sure to save the config before exiting. The result of this step will be a modified kernel configuration file (`./kernel/configs/generic-6.6.y-x86_64`).

```bash
/linux-5.10.85 # exit
user1 % make
./build.sh kernel-config hook-latest-lts-amd64
```

1. Install Linuxkit based on instructions from the [LinuxKit](https://github.com/linuxkit/linuxkit) page.


1. Ensure that the `linuxkit` tool is in your PATH:
1. 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.

```bash
export PATH=$PATH:/home/tink/linuxkit/bin
./build.sh kernel hook-latest-lts-amd64
```

1. Start a local registry:
1. Build the HookOS kernel and initramfs artifacts. 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.

```bash
docker run -d -p 5000:5000 --name registry registry:2
./build.sh linuxkit hook-latest-lts-amd64
```

1. Compile by running the following in the root of the repo:

```bash
make dist
```
1. Artifacts will be put under the `dist` directory in the repo’s root:
1. Rename the kernel and initramfs files to `vmlinuz-x86_64` and `initramfs-x86_64` respectively.

```bash
./initramfs-aarch64
./initramfs-x86_64
./vmlinuz-aarch64
./vmlinuz-x86_64
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
```

1. 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.
1. 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`]({{< relref "../bare-spec#hookimagesurlpath-optional" >}}) field in your cluster configuration file.

0 comments on commit 8832fe5

Please sign in to comment.