Build and publish on a build host

This page shows how to build Templates and Platforms with kibo-build on a separate build host, then hand the output to an Operator to publish to the catalog. Both image builders and Operators take part in this flow.

• To build your first Template and go from an OCI image all the way to creating a Workspace, see Build your own Template.
• For approval and default revision settings after publishing, see Catalog.

OverviewCopy Anchor Link

Building and publishing are split across two machines and two accounts:

1. The build host runs kibo-build as root and produces Template results and Platform archives. It needs no Operator, ctrl, or store credentials.
2. The Operator takes the output and uploads it to the catalog from their own workstation with kibo template publish and kibo platform publish.

Build tools and Debian packagesCopy Anchor Link

At startup, kibo-build checks for the host tools it needs. The tools each kind of build needs, and their Debian/Ubuntu packages:

Notes:

• Generating a rootfs requires root. Importing from an image registry does not need Docker. Generating content from a Containerfile and building Platform containers need Docker and Buildx.
• kibo-build works with OCI images through Skopeo and umoci on the host. It contains no libraries of its own for image transport or unpacking.
• If a tool is missing, the build fails immediately. kibo-build does not download or install tools automatically, and it does not escalate privileges.
• Building the KiboVM standalone kernel also needs source, OCI images, Debian package sources, and Go modules prepared according to the lock file. See Build inputs and cache.
• Buildx must be found under an isolated HOME. A plugin installed only in a personal HOME does not qualify.
• BuildKit garbage collection keeps at least 20 GB of reusable cache, uses at most 80% of the storage, and tries to leave 20 GB free. Size the build host for this.

Standalone build tools packageCopy Anchor Link

kibo-build_VERSION_amd64.deb contains kibo-build and normalize-ext4. Install it on a Linux amd64 build host, and apt also installs Skopeo, umoci, the ext4 tools, and their runtime libraries. The build host needs no Go, Git, C compiler, or source code.

sudo apt-get install ./kibo-build_0.0.0-rc.1_amd64.deb

Notes:

• The minimum tool versions are e2fsprogs 1.47.0, util-linux 2.39, umoci 0.4.7, and Skopeo 1.9.0. Newer versions work, and the tool versions actually used are recorded in the cache and the results. Different versions may produce different ext4 bytes.
• For building a Template with this package, from an image registry or from a local OCI image, see Build your own Template and Importing a local OCI image.
• The publishing account must be able to read the build output. If you use a custom output path, its parent directories must let that account enter.

Building Templates and PlatformsCopy Anchor Link

When source code is neededCopy Anchor Link

StepsCopy Anchor Link

Run the following commands as root on the build host:

build_root=/var/lib/kibotos/build
install -d -m 0755 "$build_root"
printf 'root = "%s"\n' "$build_root" > "$build_root/config.toml"
export KIBOTOS_BUILD_CONFIG="$build_root/config.toml"
source_root=/srv/kibotos
rootfs_result=$(kibo-build template "$source_root/templates/minimal/template.json")
firecracker_archive=$(kibo-build firecracker --source-root "$source_root")
kibovm_archive=$(kibo-build kibovm --source-root "$source_root" \
  --runtime-lock "$source_root/build/kibovm/runtime-artifact.json" \
  --runtime-cache "$source_root/.cache/kibovm-runtime")

• The example builds the smallest verification Template in the repository. Use a different definition file to build a different Template. Capacity and sources are declared in the definition file.
• When a non-root account runs the build, the administrator creates the build directory first and grants that account access.
• You can also skip building a Platform yourself and use kibotos-platform-<backend>_<tag>_amd64.tar.zst (for example kibotos-platform-kibovm_v0.2.0_amd64.tar.zst) from the release set. It has the same format as a locally built archive.

Handoff and publishingCopy Anchor Link

The handoffCopy Anchor Link

PublishingCopy Anchor Link

Run this on the Operator workstation. It does not need the build host's configuration file. Pass --build-cache-root the stage cache root itself, which is cache/stages under the kibo-build build root:

• It directly contains the cache marker file and another stages/ directory inside.
• It is not its parent, <build root>/cache. If you pass the parent, the command fails before connecting to the network and shows the exact path to pass.
• On the build host, kibo-build cache root prints this path.

In the example below, the build root /srv/build-root has been copied as is to /srv/build-handoff on the Operator workstation:

kibo template publish /srv/build-handoff/results/rootfs-result \
  --build-cache-root /srv/build-handoff/cache/stages --json
kibo platform publish /srv/build-handoff/platform.tar.zst --json

Next stepsCopy Anchor Link

Publishing only puts the revision into the catalog. Templates and Platforms are approved separately, and neither affects the other:

1. Run kibo platform approve and kibo platform set-default with the revision returned by kibo platform publish.
2. Run kibo template approve and kibo template set-default with the Template ID and revision returned by kibo template publish.

For command details, see Catalog. To pin a Template revision when creating a Workspace, see Template and resources. To prepare a Template on a node before its first use, see kibo template prepare.

Cleaning the build cacheCopy Anchor Link

Run this on the build host:

sudo kibo-build cache clean

• Cleaning does not affect object storage, node caches, or published Templates, Platforms, and Launches.
• After updating the build or publishing tools, clean the old cache, discard unpublished old results, and build or assemble again.