This repository hosts the containment-rpm-pxe resources used to wrap the PXE images built by KIWI on OBS into RPMs.

The work is based on the original containment-rpm tool created by SUSE Studio and container-rpm-docker.

Explaining the magic

Everything starts with the user creating a package (in the build service terminology, we are not talking about .rpm files) that contains all the KIWI sources required to build a PXE image.

The build service will look at these files, figure out the operating system of the target and provision a build a PXE image of the same type. To make it clear, if the user uploaded the sources of a SLE11 SP3 appliance then the build service is going to build a SLE11 SP3 PXE image.

The build service will install all the packages required to run KIWI. It will also download all the packages required by the appliance inside of the build system. Then it will start the KIWI process like a normal KIWI user would do. However once KIWI successfully completes the creation of the appliance the build service is going to trigger a post build hook.

The post build hook will look for a file named kiwi_post_run located inside of the /usr/lib/build directory. If the file exists and is executable then the build service will invoke it. The kiwi_post_run script is where we trigger the build of a new rpm containing the output of the kiwi process.

Obviously we must make the kiwi_post_run file available on the build host. The solution is simple: create a package containing our script plus other resources and ask the build service to install this package inside of the build environment. The package containing the post build hook is usually called containment-rpm.

The package contains basically two files:

• The post build script (kiwi_post_run): it can be written in any language you want. If you use an interpreted language make sure to add it as a runtime dependency inside of the pakage spec file (containment-rpm-pxe in our case.
• The .spec file used to build the package containing the output of the kiwi build. This file is usually a template which is later customized by the kiwi_post_run script to hold the right values (e.g.: the build version).

In our case kiwi_post_run will decompress the PXE image (it supports cpio images as well), will look for the kernel and initrd, will fill image.spec.in template, and will build the RPM.

How to prepare a project on the build service

It is recommended to have a build service project dedicated to building the images.

The project must have at least two repositories:

• A KIWI repository, this is called 'images' by default by the build service.
• A repository to build the containment-rpm-docker binary.

If you plan to build PXE images for different version of SLE then you have to make sure you build the containment rpm also for these targets. You have to do that because the build host will have the same OS of the target (see previous section).

First, you need to create a package called containment-rpm-doker at the repository where you plan to build it.

Then, run the script prepare-for-obs, and a folder for_obs will be created with the spec file, changelog file and sources.

Upload them to your package at OBS (use osc CLI, or web interface, or API)

When the package is built, you need to edit the project config: osc meta -e prjconf and make sure you have something like this:

%if "%_repository" == "images"
Type: kiwi
Repotype: rpm-md
Patterntype: none
Required: containment-rpm-docker
%endif

We changed Repotype because the repository is going to have also the rpm containing the output produced by KIWI.

We added the Required statement to have the containment-rpm-docker and all its dependencies installed inside of the build environment used by the build service.

Next we need to edit the project metadata: osc meta -e prj. We have to add the repository containing the containment-rpm-pxe to the list of repositories available by the images target at build time.

  <repository name="images">
    <path project="Devel:Myproject:Where:containment-rpm-exe:is" repository="SLE_12"/>
    <arch>x86_64</arch>
  </repository>

So in the end the project will have just two packages (again, build service terminology not .rpm files):

• my-appliance: this is where the KIWI sources are placed.
• containment-rpm: this is the package containing the script called by the post build hook.

As you can notice there is no definition of the package containing the output of the KIWI process. Whenever the my-appliance package is built the rpm containing its output is going to be created. Note well: this rpm is going to be published by the build service inside of the images repository.

Using a special kiwi version

If you want to use a special version of KIWI to build your images you can either have a kiwi package inside of your project or you can reference the kiwi package from another repository.

Custom kiwi package inside of the project

This requires you to copy/link the kiwi package from somewhere to your project.

Then you have to add your repository to the list of repositories available for the images one. This is what we have already done previously to make it possible to install the containment-rpm inside of the build environment:

  <repository name="images">
    <path project="Devel:Myproject:Images" repository="SLE_12"/>
    <arch>x86_64</arch>
  </repository>

kiwi package from an external project

This is the only sane way to have a recent version of KIWI on an old system like SLE11 SP3.

First of all we have to make edit the project metadata: osc meta -e prj.

Add the path to the project containing the kiwi package to the images repository:

  <repository name="images">
    <path project="openSUSE.org:Myexternalproject" repository="SLE_12"/>
    <path project="Devel:Myproject:Images" repository="SLE_12"/>
    <arch>x86_64</arch>
  </repository>

Then add the same repository to your KIWI source file (the .kiwi file).