AuroraBoot
AuroraBoot is a tool designed to make the process of bootstrapping Kairos machines quick, simple and efficient. It is specifically designed for the Kairos operating system and provides a comprehensive solution for downloading required artifacts and provisioning a machine, both from network or manually via flashing to USB stick.
With AuroraBoot, you can prepare the environment for network-based bootstrapping, download the necessary release assets, and also customize the installation media for USB-based mass-installations. Whether you’re looking to install Kairos on a single machine or multiple machines, AuroraBoot makes it easy and efficient.
AuroraBoot can be useful to:
- prepare multiple-nodes in a lab before shipment
- offer a simple, intuitive and streamlined way to deploy Kairos automatically and manually
- deploy Kairos nodes in a network segment where we can already send workload to (running AuroraBoot in an already-existing downstream cluster)
Scope
AuroraBoot has the following scope:
- Download release assets in order to provision one or more machines
- Prepare automatically the environment to boot from network
- Provision machines from network with a version of Kairos and cloud config
- Customize The installation media for installations from USB
Prerequisites
docker
or a container engine of your choice- Port
8090
,8080
and67
free on the host running AuroraBoot - The machine running AuroraBoot have to be on the same network segment of the nodes to be bootstrapped
- The nodes need to be configured to boot over network, or be capable of booting via USB for offline mode
ProxyDHCP
supported by theDHCP
network attempting to netboot (see also pixiecore architecture). There should be an already runningDHCP
server on your network. AuroraBoot doesn’t take over theDHCP
server, neither require you to do any specific configuration, however aDHCP
server which is compliant toProxyDHCP
requests should be present in the same network running AuroraBoot and the machines to boot.
MacOS
Unfortunately for macOS systems we cannot run the netboot through docker as it’s run inside a VM, as it can’t see the host network.
Building ISOs still works as long as you mount the container /tmp
disk to a local dir so its exported there like so:
docker run --rm -ti -v "$PWD"/config.yaml:/config.yaml -v ${PWD}:/tmp quay.io/kairos/auroraboot \
--set "artifact_version=v3.2.3" \
--set "release_version=v3.2.3" \
--set "flavor=@flavor" \
--set "flavor_release=@flavorRelease" \
--set "repository=kairos-io/kairos" \
--set "disable_http_server=true" \
--set "disable_netboot=true" \
--cloud-config /config.yaml
This will build the ISO and put the generated artifacts in the current dir under the ${PWD}/iso
dir.
For netboot, we recommend that you run the AuroraBoot binary directly by grabbing it from the releases page.
This requires just one dependency that you can install via brew with brew install xorriso
Windows
Netboot in windows is not supported, only iso creation via the docker image.
Overview
To run AuroraBoot, simply use docker
or the container engine of your choice (such as podman
, …). AuroraBoot images are published in quay and the source code is available in GitHub.
The basic usage of AuroraBoot involves passing it several parameters that define the installation environment, such as the version of Kairos you want to install, the cloud config you want to use, and other customizations you may need. You can pass these parameters either as command-line arguments, or as a full YAML configuration file.
AuroraBoot will download the artifacts required for bootstrapping the nodes, and prepare the environment required for a zero-touch deployment.
For example, to netboot a machine with the latest version of Kairos and @flavor
using a cloud config, you would run the following command:
docker run --rm -ti --net host quay.io/kairos/auroraboot \
--set "artifact_version=v3.2.3" \
--set "release_version=v3.2.3" \
--set "flavor=@flavor" \
--set repository="kairos-io/kairos" \
--cloud-config https://...
This command will download the necessary artifacts and start the provisioning process. The machine will attempt to boot from network, and will be configured with the specified version of Kairos.
Network-based bootstrapping
By default AuroraBoot will automatically attempt to bootstrap other machines, which are configured to boot from network, within the same network. No further configuration or settings necessary.
There are only 3 steps involved in the process:
- Select the release of Kairos that you want to deploy and optionally a cloud config (see also our examples)
- Run AuroraBoot in your workstation with the appropriate CLI args
- Boot up other nodes, already configured to boot from network
1. Selecting a release
AuroraBoot can bootstrap container images or released assets from our GitHub release process.
To use GitHub releases set a release version with --set release_version
(the GitHub release), an artifact version with --set artifact_version
(the artifact version) a flavor with --set flavor
and a repository with --set repository
.
Kairos has releases with (standard) and without (core) k3s both can be downloaded in the release page at kairos.
To use a container image, you can use the Kairos released images or customized by specifying --set container_image
instead with the container image of choice.
2. Run AuroraBoot
Now we can run AuroraBoot with the version we selected, either from GitHub releases or directly from a container image.
In the example below we selected v3.2.3-k3sv1.31.2+k3s1
, @flavor
flavor, so we would run either one of the following:
By indicating a container_image
, AuroraBoot will pull the image locally and start to serve it for network booting.
You can use the Kairos released images or your own.
docker run --rm -ti --net host quay.io/kairos/auroraboot \
--set "container_image=quay.io/kairos/@flavor:@flavorRelease-standard-amd64-generic-v3.2.3-k3sv1.31.2-k3s1"
By indicating a container_image
prefixed with docker://
, AuroraBoot will pull the image from the local daemon and start to serve it for network booting.
This implies that the host has a docker daemon, and we have to give access to its socket with -v /var/run/docker.sock:/var/run/docker.sock
.
docker pull quay.io/kairos/@flavor:@flavorRelease-standard-amd64-generic-v3.2.3-k3sv1.31.2-k3s1
# This will use the container image from the host's docker daemon
docker run --rm -ti -v /var/run/docker.sock:/var/run/docker.sock --net host quay.io/kairos/auroraboot \
--set "container_image=docker://quay.io/kairos/@flavor:@flavorRelease-standard-amd64-generic-v3.2.3-k3sv1.31.2-k3s1"
By indicating a artifact_version
, a release_version
, a flavor
and a repository
, AuroraBoot will use GitHub released assets.
docker run --rm -ti --net host quay.io/kairos/auroraboot \
--set "artifact_version=v3.2.3-k3sv1.31.2-k3s1" \
--set "release_version=v3.2.3" \
--set "flavor=@flavor" \
--set "flavor_release=@flavorRelease" \
--set "repository=kairos-io/provider-kairos"
To specify a cloud config, you can set it with --cloud-config
. See the sections below for further examples.
3. Start nodes
Generic hardware based netbooting is out of scope for this document.
Nodes need to be configured to boot over network, and after AuroraBoot is started should be ready to accept a connection, a typical output of a successfull run is:
2023/02/08 14:27:30 DHCP: Offering to boot 08:00:27:54:1a:d1
2023/02/08 14:27:30 TFTP: Sent "08:00:27:54:1a:d1/4" to 192.168.68.113:6489
2023/02/08 14:27:36 DHCP: Offering to boot 08:00:27:54:1a:d1
2023/02/08 14:27:36 HTTP: Sending ipxe boot script to 192.168.68.113:45435
2023/02/08 14:27:36 HTTP: Sent file "kernel" to 192.168.68.113:45435
2023/02/08 14:27:36 HTTP: Sent file "initrd-0" to 192.168.68.113:45435
2023/02/08 14:27:49 HTTP: Sent file "other-0" to 192.168.68.113:43044
If trying on a VM, for instance on VirtualBox or QEMU, a typical setup might be:
- Set Netboot as first boot in the boot process order
- Use bridge networking with the host (if running AuroraBoot and the VM in the same host)
USB-based bootstrapping
AuroraBoot by default prepares an ISO with the custom cloud init prepared for being flashed to an USB stick either with dd
or with BalenaEtcher.
To disable netboot and provide only offline artifacts, run auroraboot
with --set disable_netboot=true
.
1. Node configuration
Create a cloud config file, see our documentation for ready-to use examples, but a minimal configuration that automatically installs, and allows us to login afterward can be the following:
#cloud-config
install:
auto: true
device: "auto"
reboot: true
# Define the user accounts on the node.
users:
- name: "kairos" # The username for the user.
passwd: "kairos" # The password for the user.
ssh_authorized_keys: # A list of SSH keys to add to the user's authorized keys.
# - github:mudler # A key from the user's GitHub account.
# - "ssh-rsa AAA..." # A raw SSH key.
Save the file locally or remotely, you can pass it by in the arguments with --cloud-config
to AuroraBoot. Note that can also be a remote http(s) path.
2. Create an offline ISO
Run AuroraBoot with a cloud-config to create an ISO with the embedded configuration:
Check we have the cloud config file:
ls
# config.yaml
Build the ISO:
docker run -v "$PWD"/config.yaml:/config.yaml \
-v "$PWD"/build:/tmp/auroraboot \
--rm -ti quay.io/kairos/auroraboot \
--set container_image=quay.io/kairos/@flavor:@flavorRelease-core-amd64-generic-v3.2.3 \
--set "disable_http_server=true" \
--set "disable_netboot=true" \
--cloud-config /config.yaml \
--set "state_dir=/tmp/auroraboot"
Results should be available under build/
in the current directory:
sudo ls -liah build/iso
#
# total 778M
# 34648528 drwx------ 2 root root 4.0K Feb 8 16:39 .
# 34648526 drwxr-xr-x 5 root root 4.0K Feb 8 16:38 ..
# 34648529 -rw-r--r-- 1 root root 253 Feb 8 16:38 config.yaml
# 34649370 -rw-r--r-- 1 root root 389M Feb 8 16:38 kairos.iso
# 34649372 -rw-r--r-- 1 root root 389M Feb 8 16:39 kairos.iso.custom.iso
# 34649371 -rw-r--r-- 1 root root 76 Feb 8 16:39 kairos.iso.sha256
Check we have the cloud config file:
ls
# config.yaml
Build the ISO:
docker run -v "$PWD"/build:/tmp/auroraboot -v /var/run/docker.sock:/var/run/docker.sock --rm -ti quay.io/kairos/auroraboot \
--set "artifact_version=v3.2.3-k3sv1.31.2-k3s1" \
--set "release_version=v3.2.3" \
--set "flavor=@flavor" \
--set "flavor_release=@flavorRelease" \
--set "repository=kairos-io/provider-kairos" \
--set "disable_http_server=true" \
--set "disable_netboot=true" \
--cloud-config /config.yaml \
--set "state_dir=/tmp/auroraboot"
Results should be available under build/
in the current directory:
sudo ls -liah build/iso
#
# total 778M
# 34648528 drwx------ 2 root root 4.0K Feb 8 16:39 .
# 34648526 drwxr-xr-x 5 root root 4.0K Feb 8 16:38 ..
# 34648529 -rw-r--r-- 1 root root 253 Feb 8 16:38 config.yaml
# 34649370 -rw-r--r-- 1 root root 389M Feb 8 16:38 kairos.iso
# 34649372 -rw-r--r-- 1 root root 389M Feb 8 16:39 kairos.iso.custom.iso
# 34649371 -rw-r--r-- 1 root root 76 Feb 8 16:39 kairos.iso.sha256
The result process will write an iso kairos.iso.custom.iso
under build/iso
. That is the iso with our embedded cloud-config.
2. Run the image
The iso now is ready to be written to USB stick with either dd
or with BalenaEtcher, or attached to a VM.
When deploying on a bare metal server, directly flash the image into a USB stick. There are multiple ways to do this:
From the command line using the dd
command
dd if=build/kairos.iso.custom.iso of=/path/to/dev bs=4MB
or with BalenaEtcher.
Warning
Make sure you have KVM enabled, this will improve the performance of your VM significantly!
virt-install --name my-first-kairos-vm \
--vcpus 1 \
--memory 1024 \
--cdrom build/kairos.iso.custom.iso \
--disk size=30 \
--os-variant opensuse-factory \
--virt-type kvm
virt-viewer my-first-kairos-vm
Configuration
The AuroraBoot configuration file reference is the following:
# Corresponding artifact versions from the kairos release page (e.g. kubernetes version included)
artifact_version: "v..."
# Version of the release in github
release_version: "v3.2.3"
# Flavor
flavor: "@flavor"
# Github repository
repository: "kairos-io/kairos"
# Container image (takes over)
container_image: "..."
# Disable netboot
disable_netboot: true
# Disable http server for serving offline generated ISOs
disable_http_server: true
# Specify a directory that will be used by auroraboot to download artifacts
# Reuse the same to cache artifacts.
state_dir: "/tmp/auroraboot"
# Default http binding port for offline ISO generation
listen_addr: ":8080"
# Cloud config to use when booting the machine.
cloud_config: |
Option | Description |
---|---|
artifact_version | Corresponding artifact versions from the Kairos release page (e.g. Kubernetes version included). |
release_version | Version of the release in GitHub. |
flavor | The Kairos flavor to use. See the Kairos support matrix for a list. |
repository | Github repository to use. This can either be kairos-io/kairos or kairos-io/provider-kairos for images with k3s prior to v2.4.0. |
container_image | Container image. If prefixed with docker:// it will try to pull from the local docker daemon. If a container_image is specified, artifact_version , flavor and release_version are ignored. |
disable_netboot | Disable netboot. |
disable_http_server | Disable http server for serving offline generated ISOs. |
netboot_http_port | Specify a netboot HTTP port (defaults to 8090 ). |
state_dir | Specify a directory that will be used by auroraboot to download artifacts and reuse the same to cache artifacts. |
listen_addr | Default http binding port for offline ISO generation. |
cloud_config | Cloud config path to use for the machines. A URL can be specified, use - to pass-by the cloud-config from STDIN |
iso.data | Defines a path to be embedded into the resulting iso. When booting, the files will be accessible at /run/initramfs/live |
netboot.cmdline | Override the automatically generated cmdline with a custom one to use during netboot. config_url and rootfs are automatically constructed. A reasonable value can be netboot.cmdline=rd.neednet=1 ip=dhcp rd.cos.disable netboot install-mode console=tty0 |
To use the configuration file with AuroraBoot, run AuroraBoot specifying the file or URL of the config as first argument:
docker run --rm -ti -v "$PWD"/config.yaml:/config.yaml --net host quay.io/kairos/auroraboot /config.yaml
The CLI options can be used in place of specifying a file, and to set fields of it. Any field of the YAML file, excluding cloud_config
can be configured with the --set
for instance, to disable netboot we can run AuroraBoot with:
docker run --rm -ti --net host quay.io/kairos/auroraboot .... --set "disable_netboot=true"
To specify a cloud config file instead, use --cloud-config
(can be also url):
docker run --rm -ti -v "$PWD"/config.yaml:/config.yaml --net host quay.io/kairos/auroraboot .... --cloud-config /config.yaml
Both the config file and the cloud-config file can be a URL.
Cloud config
A custom cloud configuration file can be passed either with the --cloud-config
flag, or in the AuroraBoot configuration file under the cloud_config
key.
It is possible to apply templating to a cloud config. Indeed any value passed to --set
is accessible as a template in the cloud config file with the [[
and ]]
delimiter, for instance consider the following cloud config file, which allows to set a password for the kairos
user and a GitHub handle allowed to login to the machine:
#cloud-config
install:
auto: true
device: "auto"
reboot: true
# Define the user accounts on the node.
users:
- name: "kairos" # The username for the user.
passwd: "[[.kairos.password]]" # The password for the user.
ssh_authorized_keys: # A list of SSH keys to add to the user's authorized keys.
- github:[[.github.user]]
We would then set the user to mudler
and the password to foobar
when running AuroraBoot like the following:
docker run --rm -ti -v "$PWD"/config.yaml:/config.yaml --net host \
quay.io/kairos/auroraboot \
--cloud-config /config.yaml \
--set "github.user=mudler" \
--set "kairos.password=foobar"
Config files can be also hosted remotely, and given as URLs to AuroraBoot.
We can indeed use the template in the example folder with the command above:
docker run --rm -ti --net host \
quay.io/kairos/auroraboot \
--cloud-config https://raw.githubusercontent.com/kairos-io/kairos/master/examples/auroraboot/master-template.yaml \
--set "github.user=mudler" \
--set "kairos.password=foobar"
To pass-by a cloud-config via pipes, set --cloud-config -
, for example:
cat <<EOF | docker run --rm -i --net host quay.io/kairos/auroraboot \
--cloud-config - \
--set "container_image=quay.io/kairos/@flavor:@flavorRelease-standard-amd64-generic-v3.2.3-k3sv1.31.2-k3s1"
#cloud-config
install:
device: "auto"
auto: true
reboot: true
hostname: metal-bundle-test-{{ trunc 4 .MachineID }}
users:
- name: kairos
# Change to your pass here
passwd: kairos
ssh_authorized_keys:
# Replace with your github user and un-comment the line below:
- github:mudler
k3s:
enabled: true
# Specify the bundle to use
bundles:
- targets:
- run://quay.io/kairos/community-bundles:system-upgrade-controller_latest
- run://quay.io/kairos/community-bundles:cert-manager_latest
- run://quay.io/kairos/community-bundles:kairos_latest
kairos:
entangle:
enable: true
EOF
Examples
Note
The example below are implying aconfig.yaml
cloud config file to be present in the current directory.Offline ISO build from local container image
First make sure we have the image locally with:
docker pull <IMAGE>
Build the custom ISO with the cloud config:
docker run -v "$PWD"/config.yaml:/config.yaml \
-v "$PWD"/build:/tmp/auroraboot \
-v /var/run/docker.sock:/var/run/docker.sock \
--rm -ti quay.io/kairos/auroraboot \
--set container_image=docker://<IMAGE> \
--set "disable_http_server=true" \
--set "disable_netboot=true" \
--cloud-config /config.yaml \
--set "state_dir=/tmp/auroraboot"
Offline ISO build from container images
Build the custom ISO with the cloud config:
docker run -v "$PWD"/config.yaml:/config.yaml \
-v "$PWD"/build:/tmp/auroraboot \
--rm -ti quay.io/kairos/auroraboot \
--set container_image=quay.io/kairos/@flavor:@flavorRelease-core-amd64-generic-v3.2.3 \
--set "disable_http_server=true" \
--set "disable_netboot=true" \
--cloud-config /config.yaml \
--set "state_dir=/tmp/auroraboot"
Override GRUB config file
It is possible to override the default GRUB config file of the ISO by creating a directory that contains the files that we want to add or replace in it.
For example, to override the GRUB config file:
mkdir -p data/boot/grub2
# You can replace this step with your own grub config. This GRUB configuration is the boot menu of the ISO
wget https://raw.githubusercontent.com/kairos-io/packages/main/packages/livecd/grub2/config/grub_live_bios.cfg -O data/boot/grub2/grub.cfg
docker run -v "$PWD"/config.yaml:/config.yaml \
-v "$PWD"/data:/tmp/data \
-v "$PWD"/build:/tmp/auroraboot \
--rm -ti quay.io/kairos/auroraboot \
--set container_image=quay.io/kairos/@flavor:@flavorRelease-core-amd64-generic-v3.2.3 \
--set "disable_http_server=true" \
--set "disable_netboot=true" \
--cloud-config /config.yaml \
--set "state_dir=/tmp/auroraboot" \
--set "iso.data=/tmp/data"
Prepare ISO for Airgap installations
See the Airgap example in the examples section.
Netboot with core images from Github releases
docker run -v "$PWD"/config.yaml:/config.yaml --rm -ti --net host quay.io/kairos/auroraboot \
--set "artifact_version=v3.2.3" \
--set "release_version=v3.2.3" \
--set "flavor=@flavor" \
--set repository="kairos-io/kairos" \
--cloud-config /config.yaml
Netboot with k3s images from Github releases
docker run -v "$PWD"/config.yaml:/config.yaml --rm -ti --net host quay.io/kairos/auroraboot \
--set "artifact_version=v3.2.3-k3sv1.31.2-k3s1" \
--set "release_version=v3.2.3" \
--set "flavor=@flavor" \
--set "flavor_release=@flavorRelease" \
--set "repository=kairos-io/provider-kairos" \
--cloud-config /config.yaml
Netboot from container images
docker run -v "$PWD"/config.yaml:/config.yaml --rm -ti --net host quay.io/kairos/auroraboot \
--set container_image=quay.io/kairos/@flavor:@flavorRelease-core-amd64-generic-v3.2.3
--cloud-config /config.yaml
Generate RAW disk image (EFI)
AuroraBoot can generate raw disk images (EFI) that can be used as cloud images (for example as AWS AMI images) or QEMU.
Consider the following example:
docker run -v /var/run/docker.sock:/var/run/docker.sock --net host \
-v $PWD:/aurora --rm -ti quay.io/kairos/auroraboot \
--debug \
--set "disable_http_server=true" \
--set "container_image=quay.io/kairos/@flavor:@flavorRelease-standard-amd64-generic-v3.2.3-k3sv1.31.2-k3s1" \
--set "disable_netboot=true" \
--cloud-config /aurora/config.yaml \
--set "disk.raw=true" \
--set "state_dir=/aurora"
The raw disk image will be available in iso/disk.raw
The cloud config file (config.yaml
) should look like the following:
#cloud-config
hostname: kairos
## Login
users:
- name: "kairos"
lock_passwd: true
ssh_authorized_keys:
# here add github username or ssh keys
# - github:mudler
## First Setup
## This block is needed as the image will boot to rescue mode and configure the drive of the
## VM.
name: "Default deployment"
stages:
boot:
- name: "Repart image"
layout:
device:
path: /dev/sdb
add_partitions:
- fsLabel: COS_STATE
size: 150240
pLabel: state
- name: "Repart image"
layout:
device:
path: /dev/sda
add_partitions:
- fsLabel: COS_PERSISTENT
pLabel: persistent
size: 0 # all space
- if: '[ -f "/run/cos/recovery_mode" ] && [ ! -e /usr/local/.deployed ]'
name: "Deploy kairos"
commands:
- kairos-agent --debug reset --unattended
- touch /usr/local/.deployed
- reboot
Note
To generate GCE and VHD images set disk.gce=true
or disk.vhd=true
respectively in the AuroraBoot command. For example:
# Build a GCE-compatible image
docker run -v /var/run/docker.sock:/var/run/docker.sock --net host \
-v $PWD:/aurora --rm -ti quay.io/kairos/auroraboot \
--debug \
--set "disable_http_server=true" \
--set "container_image=quay.io/kairos/@flavor:@flavorRelease-standard-amd64-generic-v3.2.3-k3sv1.31.2-k3s1" \
--set "disable_netboot=true" \
--cloud-config /aurora/config.yaml \
--set "disk.gce=true" \
--set "state_dir=/aurora"
or for VHD images:
# Build a VHD image compatible with Azure
docker run -v /var/run/docker.sock:/var/run/docker.sock --net host \
-v $PWD:/aurora --rm -ti quay.io/kairos/auroraboot \
--debug \
--set "disable_http_server=true" \
--set "container_image=quay.io/kairos/@flavor:@flavorRelease-standard-amd64-generic-v3.2.3-k3sv1.31.2-k3s1" \
--set "disable_netboot=true" \
--cloud-config /aurora/config.yaml \
--set "disk.vhd=true" \
--set "state_dir=/aurora"
Use the config file
Write down an aurora config file as aurora.yaml
:
container_image: "quay.io/kairos/@flavor:@flavorRelease-core-amd64-generic-v3.2.3"
cloud_config: |
#cloud-config
install:
auto: true
device: "auto"
reboot: true
# Define the user accounts on the node.
users:
- name: "kairos" # The username for the user.
passwd: "kairos" # The password for the user.
ssh_authorized_keys: # A list of SSH keys to add to the user's authorized keys.
# - github:mudler # A key from the user's GitHub account.
# - "ssh-rsa AAA..." # A raw SSH key.
And then run:
docker run -v "$PWD"/aurora.yaml:/aurora.yaml --rm -ti --net host quay.io/kairos/auroraboot /aurora.yaml