orpheus/Readme.md

Orpheus

Orpheus is a backend for a pixiecore API mode. It provides boot configurations per host with specified MAC-address.

Enpoint Description

Orpheus usppose to respond on:

GET <server_url>/v1/boot/{mac_address}

with a JSON:

{
  "kernel": "https://files.local/kernel",
  "initrd": ["https://files.local/initrd"],
  "cmdline": "selinux=1 coreos.autologin",
  "message": "Booting host"
}

according pixiecore API specification:

kernel (string): the URL of the kernel to boot.
initrd (list of strings): URLs of initrds to load. The kernel will flatten all the initrds into a single filesystem.
cmdline (string): commandline parameters for the kernel. The commandline is processed by Go's text/template library. Within the template, a URL function is available that takes a URL and rewrites it such that Pixiecore proxies the request.
message (string): A message to display before booting the provided configuration. Note that displaying this message is on a best-effort basis only, as particular implementations of the boot process may not support displaying text.

Server Configuration

Orpheus using yaml file for a inventory description:

webserver: "http://my.webserver.net"
hosts:
  "aa:bb:cc:dd:ee:ff": &test
    name: my_pxe_booted_host
    version: version_of_kernel
    type: type_of_kernel
    cmdline:
      - simple_string
      - apkovl: path_to_apkovl_on_webserver.tar.gz
      - modloop
      - ds: path_to_data_source_on_webserver

  "aa:bb:cc:dd:ee:00":
    <<: *test
    name: test2

To boot alpine linux in diskless mode is required three files:

• kernel
• initrd
• modloop

All three lies in one directory on the server, to boot succesfully you have to boot kernel with the same version of initrd and modloop. So it is convinient to setup just version and type of the desired kernel.

webserver - is http webserver in local network which serves file to a booting host. hosts - is a map which contains mac addresses of the booting machines as a keys and booting parameters as value. version in the host patameter directs to the kernel-version directory, type - describes wich type of the file to request, usually it is lts, or virt.

Webserver suppose to have following directory structure: In the root there is 3 types of directories - kernel directory, directory with name apkovl and tiny-cloud. kernel directory can have any name (suppose to have name related to kernel version) and contain kernel, initrd and modloop files. apkovl directory contain aplovl files. tini-cloud directory contains subdirectories with files related to tiniy-cloud config files.

Here is an example

/
├── alpine-3.21         # kernel directory for alpine linux kernel `version` 3.21
│   ├── initramfs-lts   # initrd with `lts` type
│   ├── initramfs-virt  # initrd with `virt` is type
│   ├── modloop-lts
│   ├── modloop-virt
│   ├── vmlinuz-lts     # kernel
│   └── vmlinuz-virt
├── alpine-3.19         # kernel directory for alpine linux version 3.19
│   ├── initramfs-lts
│   ├── initramfs-virt
│   ├── modloop-lts
│   ├── modloop-virt
│   ├── vmlinuz-lts
│   └── vmlinuz-virt
├── apkovl
│   ├── my_apkovl.tar.gz
│   └── backup.apkovl.tar.gz
└── tiny-cloud
    ├── server          # contains tiny-cloud config files for a server node
    │   ├── meta-data
    │   ├── network-config
    │   ├── user-data
    │   └── vendor-data
    └── agent           # contains tiny-cloud config files for agent node
        ├── meta-data
        ├── network-config
        ├── user-data
        └── vendor-data

Usage

Run:

orpheus -i inventory.yaml server