Skip to content

Latest commit

 

History

History

hook-os

README.md

Hook microOS (Alpine Linuxkit)

Table of Contents

Overview

Hook is the Tinkerbell Installation Environment for bare-metal. It runs in-memory, installs operating system, and handles deprovisioning. It is based on LinuxKit.

This repo is forked from the open source repo github.com/tinkerbell/hook. Summary of all the changes and contributions can be found here

Following components have been added to the open source HookOS for our specific purpose

  • Device Discovery: This service can read all the hardware data (serial number, UUID etc) and send out to the Edge Orchestrator while provisioning.
  • Fluent Bit: This service helps us stream the logs of all important services to the Observability microservice of the Edge Orchestrator.
  • Caddy: This service is used as a proxy to communicate with the Edge Orchestrator securely.

Features

  • Lightweight OS: Size is less than 300MB.
  • Easy to customise: Services can be embedded within the OS using individual container images and can be configured in a simple YAML file. Files can be embedded similarly.
  • Device Discovery: This service can read all the hardware data (serial number, UUID etc) and send out to the Edge Orchestrator for provisioning.

Get Started

Instructions on how to build HookOS on your machine.

Develop the HookOS

There are several convenient make targets to support developer activities. You can use help to see a list of makefile targets. The following is a list of makefile targets that support developer activities:

  • lint to run a list of linting targets
  • build to build the compressed HookOS image in tar.gz format

Build Component

make <COMPONENT NAME>

Components can be device_discovery, fluent-bit or hook_dind

Example

make device_discovery

Build container images of all the components to be embedded

make components

Configure Edge Node and Edge Orchestrator parameters

make configure

All the configurable parameter details can be found in config.template

Create placeholder for Edge Orchestrator SSL Certificates

make certs

Build HookOS kernel container image

NOTE: This target will build kernel container image even if another image with identical tag is available locally or in the Production Release service.

make kernel

The container image tag is determined by

  1. Linux kernel version: For this project we currently support only Linux 5.10. Its a Long-Term Support (LTS) kernel which is deemed to receive security updates and bug fixes until end of 2026.
  2. Linux kernel point release: Extensive provisioning tests across various platforms have been successfully conducted using Kernel Point Release 228, which is the current default point release. This can be modified by updating HOOK_KERNEL_POINT_RELEASE inside Makefile.
  3. SHA256 hash of combined contents of Dockerfile and kernel parameters: Any change to these files will lead to a different kernel tag.

Example of a kernel tag: 5.10.228-95e4df98

NOTE: It has been observed that building the kernel with identical parameters and environment variables results in a different container image SHA ID in every run.

Builds HookOS binaries

NOTE:This target fails if the kernel container image is not available locally or in the Production Release service. So either run make kernel before executing this target or run make build to combine both.

make binaries

The output can be found in the out/ directory.

Builds the complete HookOS artifact

make build

The output can be found in the out/ directory.

This process compiles all components, creates placeholders for certificates, builds the kernel (if necessary), generates the binaries, and packages everything into a .tar.gz archive file.

The kernel image is built fresh locally only if the expected image tag is not available locally or in the Production Release service.

Publish HookOS kernel as a container image to Production Release Service

NOTE:This target is intended exclusively for use within the CI/CD pipeline.

make push-kernel-ci

This pushes the HookOS kernel image to the Release Service only if the image tag (not to be confused by image SHA ID) isn't already present in the Release Service.

Publish HookOS as a OCI artifact to Production Release Service

NOTE:This target is intended exclusively for use within the CI/CD pipeline.

make publish-binaries-ci

Publish both HookOS kernel container image and HookOS OCI artifact

NOTE:This target is intended exclusively for use within the CI/CD pipeline.

make artifact-publish

Lint for License, ShellCheck, and Markdown

make lint

Contribute

To learn how to contribute to the project, see the contributor's guide.

Community and Support

To learn more about the project, its community, and governance, visit the Edge Orchestrator Community.

For support, start with troubleshooting.

License

Edge Orchestrator is licensed under Apache License 2.0.

Last Updated Date: March 31, 2025