Boot Config Service

The bootcfg HTTP service provides configs to PXE, iPXE, and Pixiecore network boot clients based on their hardware attributes to boot and configure virtual or physical machines.

Boot configs (i.e. kernel, initrd, kernel options) and cloud configs can be declared for machines by UUI, MAC address, or as the default for machines. The service renders boot configs as iPXE scripts and as JSON responses to implements the Pixiecore API spec.

Currently, bootcfg is a proof of concept, but it can make it easier to declare the desired state of network booted machines and get started with clusters of virtual or physical machines.

Usage

The bootcfg service can be run as a container to boot libvirt VMs or on a provisioner host to boot baremetal machines. Pull the container image,

docker pull quay.io/coreos/bootcfg:latest
docker tag quay.io/coreos/bootcfg:latest coreos/bootcfg:latest

or build it from source code,

./build
./docker-build

Prepare a directory with machine configs and then download CoreOS kernel and initrd image assets by

./scripts/get-coreos   # download CoreOS 835.9.0 to images/coreos/835.9.0
./scripts/get-coreos beta 877.1.0

Run the container and mount the configs and images directories as volumes.

docker run -p 8080:8080 --name=bootcfg --rm -v $PWD/data:/data:Z -v $PWD/images:/images coreos/bootcfg -address=0.0.0.0:8080

Mapping container port 8080 to host port 8080 allows the endpoints to be quickly checked. Visit /ipxe?uuid=val or /pixiecore/v1/boot/:mac to see that the correct boot iPXE script or JSON is served. Visit /cloud?uuid=val to see that the correct cloud config is served.

Endpoints

The API documents the iPXE and Pixiecore boot config endpoints, the cloud config endpoint, and image assets.

Configs

A Store maintains associations between machine attributes and different types of bootstrapping configs. Currently, bootcfg includes a FileStore which can search a filesystem directory for boot and cloud config files.

Prepare a directory of config data or use the example provided in data. The FileStore expects boot and cloud files in subdirectories, with files in nested uuid and mac subdirectories.

data
├── boot
│   └── default
└── cloud
    ├── default
    └── uuid
        └── 1cff2cd8-f00a-42c8-9426-f55e6a1847f6
    └── mac
        └── 52:54:00:c7:b6:64

To find boot configs and cloud configs, the FileStore searches the uuid directory for a file matching a client machine's UUID, then searches mac for file matching the client's MAC address, and finally falls back to using the default file if present.

You may keep the config data directory in a separate location to keep it under version control with other declarative configs.

Boot Config

Boot config files contain JSON referencing a kernel image, init RAM fileystems, and kernel options for booting a machine.

{
    "kernel": "/images/coreos/835.9.0/coreos_production_pxe.vmlinuz",
    "initrd": ["/images/coreos/835.9.0/coreos_production_pxe_image.cpio.gz"],
    "cmdline": {
        "cloud-config-url": "http://172.17.0.2:8080/cloud?uuid=${uuid}",
        "coreos.autologin": ""
    }
}

Point kernel and initrd to image URIs or to local assets. If the kernel supports the cloud-config-url option, you can set the URL to refer to the name or IP where bootcfg is running so cloud configs can also be served based on hardware attributes.

In this example, bootcfg was expected to run as the first container within Docker's virtual bridge subnet 172.17.0.0/16 under libvirt.

Cloud Config

Cloud config files are declarative configurations for customizing early initialization of machine instances. CoreOS supports a subset of the cloud-init project and supports a kernel option cloud-config-url. CoreOS downloads the HTTP config after kernel initialization.

#cloud-config
coreos:
  units:
    - name: etcd2.service
      command: start
    - name: fleet.service
      command: start
write_files:
  - path: "/home/core/welcome"
    owner: "core"
    permissions: "0644"
    content: |
      File added by the default cloud-config.

See the CoreOS cloud config docs, config validator, and implementation for more details or data for examples.

Image Assets

Optionally, bootcfg can host free-form static assets if an -images-path argument to a directory is provided. This is a quick way to serve kernel and init RAM filesystem images, GPG verify them at an origin, and lets client machines download images without using egress bandwidth.

images/
└── coreos
    └── 835.9.0
        ├── coreos_production_pxe.vmlinuz
        └── coreos_production_pxe_image.cpio.gz

Run the get-coreos script to quickly download kernel and initrd images from a recent CoreOS release into an /images directory.

./scripts/get-coreos                 # stable, 835.9.0
./scripts/get-coreos beta 877.1.0

To reference these local images, change the kernel and initrd in a boot config file. For example, change http://stable.release.core-os.net/amd64-usr/current/coreos_production_pxe.vmlinuz to /images/coreos/835.9.0/coreos_production_pxe.vmlinuz.

5.6 KiB Raw Blame History