Building container images
vpsAdminOS comes with a tool for building, testing and deploying container
images called osctl-image. osctl-image itself doesn't know how to build
specific images, it has to be used together with build scripts. osctl-image
prepares environment for the build scripts to run, decides what should be built,
where it should be built and processes build results.
Build scripts
A set of container image build scripts is a part of vpsAdminOS, you can find
them in vpsAdminOS repository in directory image-scripts/. The interface used
for communication between the build scripts and osctl-image is described
in man osctl-image(8).
The build scripts are called in three modes: configuration, build and test.
In configuration mode, the build scripts are called from the vpsAdminOS host
where osctl-image is run. osctl-image uses the configuration mode to learn
what images can be built, what environments the builds require and what tests
can be run.
Actual builds are run within build containers prepared by osctl-image.
Build containers are created simply from previously built images, where some
additional required packages can be installed. The build scripts declare what
build containers are needed and how to set them up.
In the build mode, the build scripts are supposed to prepare a root filesystem,
which is then packed into the container image by osctl-image. The build scripts
can use whatever dependencies their build containers have at their disposal.
Tests are run from the host, but using nix-shell so that the build scripts
can use whatever dependencies from nixpkgs they require. Each test is run
with a dedicated container, the script verifies if the container passes the test.
See man osctl-image(8) for more information.
Workflow
osctl-image is a part of vpsAdminOS, so it has to be called from some
vpsAdminOS host. osctl-image looks for build scripts in the following places:
- directory given by option
--build-scripts - the current working directory
/etc/vpsadminos-image-scripts, which is a part of vpsAdminOS
List available images:
osctl-image ls
NAME DISTRIBUTION VERSION ARCH VENDOR VARIANT
ubuntu-16.04 ubuntu 16.04 x86_64 vpsadminos minimal
centos-6 centos 6 x86_64 vpsadminos minimal
gentoo gentoo 20190607 x86_64 vpsadminos minimal
alpine-3.9 alpine 3.9 x86_64 vpsadminos minimal
nixos-unstable nixos unstable-20190607 x86_64 vpsadminos minimal
nixos-19.03 nixos 19.03 x86_64 vpsadminos minimal
opensuse-tumbleweed opensuse tumbleweed-20190607 x86_64 vpsadminos minimal
devuan-2.0 devuan 2.0 x86_64 vpsadminos minimal
fedora-30 fedora 30 x86_64 vpsadminos minimal
fedora-29 fedora 29 x86_64 vpsadminos minimal
debian-8 debian 8 x86_64 vpsadminos minimal
alpine-3.8 alpine 3.8 x86_64 vpsadminos minimal
ubuntu-18.04 ubuntu 18.04 x86_64 vpsadminos minimal
centos-7 centos 7 x86_64 vpsadminos minimal
void-glibc void glibc-20190607 x86_64 vpsadminos minimal
void-musl void musl-20190607 x86_64 vpsadminos minimal
debian-9 debian 9 x86_64 vpsadminos minimal
arch arch 20190607 x86_64 vpsadminos minimal
slackware-14.2 slackware 14.2 x86_64 vpsadminos minimal
opensuse-leap-15.1 opensuse leap-15.1 x86_64 vpsadminos minimal
To build an image, you need to give osctl-image a ZFS dataset for build
purposes. The dataset should not have any data nor subdatasets that you care
about. Build selected image with:
osctl-image build --build-dataset tank/image-builds alpine-3.9
Unless changed with option --output-dir, the resulting images will be stored
in directory ./output.
Tests can be run with:
osctl-image test --build-dataset tank/image-builds alpine-3.9
If you wish to manually check the image, a container can be created as:
osctl-image instantiate --build-dataset tank/image-builds alpine-3.9
To deploy the image to a repository, use:
osctl-image deploy --build-dataset tank/image-builds alpine-3.9 /where/is/your/repository
See repositories for more information about how to manage container image repositories.
Containers managed by osctl-image can be seen using osctl-image ct ls
and deleted with osctl-image ct del.