Kheeper

Working with Bare Metal

Kheeper supports bare metal provisioning via iPXE. You generate a one-time boot token, point your machine at it, and the machine installs the Kheeper base image and registers as a host.

Overview

The bare metal flow works through iPXE tokens. You create a token for your org, configure a machine to boot from the token's URL, and the machine installs a Fedora bootc image with the Kheeper agent. After installation and reboot, the machine auto-registers as a host.

iPXE tokens

iPXE tokens are one-time-use URLs that serve a boot script. Each token is valid for 24 hours and is consumed after a machine successfully registers.

Creating a token

kheeper ipxe-tokens create myorg

This prints a URL like:

https://kheeper.com/api/ipxe/kh_ipxe_...

Listing active tokens

kheeper ipxe-tokens list myorg

Shows all unconsumed tokens that haven't expired.

Revoking a token

kheeper ipxe-tokens revoke myorg <token-id>

Revoked tokens can no longer be used to boot machines.

Booting a machine

How you boot from the iPXE URL depends on your hardware and hosting provider.

Hosted bare metal (e.g. latitude.sh)

Many bare metal providers support custom iPXE scripts. When ordering a server, select the custom iPXE option and enter:

#!ipxe
dhcp
chain https://kheeper.com/api/ipxe/kh_ipxe_...

iPXE shell

If your machine drops into an iPXE shell:

chain https://kheeper.com/api/ipxe/kh_ipxe_...

PXE/DHCP environment

In a network boot environment, configure your DHCP server to point iPXE clients to the token URL.

What happens during boot

  1. The machine downloads an iPXE script from the token URL
  2. The script boots a Fedora installer over the network
  3. A kickstart file partitions the disk and installs the Kheeper base image
  4. The machine reboots into the installed system
  5. On first boot, the system registers with the Kheeper registry and becomes a host

This process takes ten to twenty minutes depending on the machine and network speed.

After registration

Once the machine registers, it appears in your host list:

kheeper hosts list --org myorg

Deploy to it like any other host:

kheeper releases create myorg/my-host:v1 \
  --image kheeper.com/myorg/webapp:v1 \
  --config-file config.json

kheeper hosts activate myorg/my-host:v1

See Working with Hosts and Configuring Images for details.

Cleaning up

kheeper hosts delete myorg/my-host

This removes the host from the registry. It does not affect the running machine. To fully decommission, also shut down or reimage the physical server through your hosting provider.