Distrobuilder
Distrobuilder is an integration tool used to create LXC, LXD or Incus container images. It takes a YAML-formatted configuration file as input and generates compressed image files which can be imported to a local repository or provided remotely via a repository server.
Installation
Kernel
Distrobuilder requires overlay filesystem support in order to work.
File systems --->
<*> Overlay filesystem support
USE flags
USE flags for app-containers/distrobuilder System container image builder for LXC and incus
verify-sig
|
Verify upstream signatures on distfiles |
Emerge
root #
emerge --ask app-emulation/distrobuilder
Additional software
The app-emulation/distrobuilder package does not include any YAML templates. The upstream templates can be a useful guide when generating custom images. They may be found at github.com/lxc/lxc-ci.
Usage
Like Docker, Distrobuilder builds images by following definitions from a YAML file.
The YAML template
The upstream Gentoo templates are intentionally kept very slim. What follows are some sensible improvements.
Managing packages
Package management is determined by the packages: section:
packages:
manager: portage
update: false
cleanup: true
sets:
- packages:
- cloud-init
action: install
variants:
- cloud
- packages:
- gentoo-kernel-bin
- grub
- syslog-ng
- sys-power/acpid
action: install
types:
- vm
- packages: demarcates the section.
- manager: tells distrobuilder what package manager the image uses. portage is predefined.
- update: If set to
true
, all installed packages are updated at the time the image is created. The upstream templates use the stage 3 tarball and haveupdate: false
, which means the repo directory in the container is empty andportage
will fail. To avoid this, setupdate: true
. Please note, settingupdate: true
will make the image larger. - cleanup: If set to true, the package manager will perform a cleanup operation to which usually cleans up cached files. It is not clear what operation this makes
portage
perform. - sets: Contains a list of packages following a bullet point
-
and the keywordremove
, anaction:
, and optional filters such asvariants
andtypes
. The packages are defined using standard portage package atoms;action:
must be set to eitherinstall
orremove
. Thetypes
determine whether a container or a virtual machine is built; this is set via a switch to distrobuilder at the time of image creation. Similarly,variants
allow different configurations based on the same base template.
packages:
manager: portage
update: true
cleanup: true
sets:
- packages:
- sys-apps/portage
- www-servers/nginx
- net-misc/openssh
- app-portage/eix
- app-editors/vim
- app-portage/gentoolkit
- app-portage/portage-utils
- app-admin/eselect
- sys-apps/mlocate
- app-admin/sysklogd
action: install
- packages:
- cloud-init
action: install
variants:
- cloud
- packages:
- gentoo-kernel-bin
- grub
- syslog-ng
- sys-power/acpid
action: install
types:
- vm
Create your own container images
You can create your own container images based on Gentoo's downloadable stages. You can control the image variant with -o source.variant option, initd variant with -o image.variant, and architecture with -o image.architecture. See examples below.
See https://github.com/lxc/lxc-ci/blob/master/images/gentoo.yaml for latest available yaml config which we're using.
For each example below create or download gentoo.yaml:
user $
mkdir -p ~/distrobuilder/gentoo
user $
cd ~/distrobuilder/gentoo
Examples below uses incus as the main container management system, but created containers are compatible with LXC and LXD. Just replace incus with lxc in command invocations.
Example: LLVM container
To create an llvm container for example, follow these steps:
user $
cd ~/distrobuilder/gentoo
user $
mkdir llvm
user $
cd llvm
distrobuilder requires a root access, straight by suing or sudoing, because it needs access to /dev etc.
root #
distrobuilder build-incus ../gentoo.yaml -o image.architecture=amd64 -o image.variant=openrc -o source.variant=llvm-openrc
user $
incus image import incus.tar.xz rootfs.squashfs --alias gentoo-amd64-llvm
user $
incus launch gentoo-amd64-llvm gentoo-llvm-test
user $
incus exec gentoo-llvm-test bash
For an x86 arch testing container on amd64, just specify architecture:
root #
distrobuilder build-incus ../gentoo.yaml -o image.architecture=x86 -o image.variant=openrc -o source.variant=openrc
Example: musl container
To create an musl container for example, follow these steps:
user $
cd ~/distrobuilder/gentoo
user $
mkdir musl
user $
cd musl
root #
distrobuilder build-incus ../gentoo.yaml -o image.architecture=amd64 -o image.variant=openrc -o source.variant=musl
user $
incus image import incus.tar.xz rootfs.squashfs --alias gentoo-amd64-musl
user $
incus launch gentoo-amd64-musl gentoo-musl-test
user $
incus exec gentoo-musl-test bash
Building Windows Image
Distrobuilder can also create Windows Image for LXD with an official Windows iso file.
Dependencies
The package is not shipped with these dependencies, as their are only used for Windows building:
root #
USE=fuse emerge --ask hivex wimlib
Building your own image
You'll first need to download an official iso of Windows. Distrobuilder will download the drivers to pack them with it. You just have to mount the iso inside a LXD VM and install it.
root #
distrobuilder repack-windows Win10.iso Win10-distrobuilder.iso