kata-containers/rootfs-builder

Building a rootfs for Kata Containers Guest OS

The Kata Containers rootfs is created using rootfs.sh.

Supported base OSs

The rootfs.sh script builds a rootfs based on a particular Linux* distribution. To build a rootfsfor your chosen distribution, run:

$./rootfs.sh <distro>

To check the supported rootfs based OS run $rootfs-builder/rootfs.sh -h, it will show the supported values of <distro>

Adding support for new base OS

The script rootfs.sh will it check for immediate sub-directories containing the following expected files structure:

• A bash(1) script called rootfs_lib.sh

  This file must contain a function called build_rootfs() this function must receive as first argument the path where the rootfs will be populated. Path: rootfs-builder/<distro>/rootfs_lib.sh.

• A bash(1) file config.sh

  This represents the specific configuration for <distro>. It must provide configuration specific variables for user to modify as needed. The config.sh file will be loaded before executing build_rootfs() to provide all the needed configuration to the function. Path: rootfs-builder/<distro>/config.sh.

To create a directory with the expected file structure run:

make -f template/Makefile  ROOTFS_BASE_NAME=my_new_awesome_rootfs

After run the command above, a new directory will be created in rootfs-builder/my_new_awesome_rootfs/. To verify it is one of the options to build a rootfs run ./rootfs.sh -h, it will show my_new_awesome as one of the options to use it for:

./rootfs.sh <distro>

Now that a new directory structure was created is need to:

• If needed, add configuration variables to rootfs-builder/my_new_awesome_rootfs/config.sh
• Implement the stub build_rootfs() function from rootfs-builder/my_new_awesome_rootfs/rootfs_lib.sh

Expected rootfs directory content

After the function build_rootfs is called, the script expects the rootfs directory to contain /sbin/init and /sbin/kata-agent binaries.

(optional) Customise the rootfs

For development uses cases, developers may want to modify the guest OS. To do that it is possible to use following methods:

• Use the environment variable EXTRA_PKG to provide a list of space separated packages to be installed.

  Note: The package names may vary among Linux distributions, the extra package names must exist in the base OS flavor you use to build the rootfs*

  Example:

  EXTRA_PKG="vim emacs" ./rootfs-builder/rootfs.sh \
  -r ${PWD}/myrootfs fedora
  
  

• In rootfs-builder/<distro>/config.sh modify the variable PACKAGES. This are the minimal set of packages needed. The configuration file must use the package names from the distro was created for.

• It is possible to customise the rootfs directory before create an image based in on it.

Build rootfs using Docker*

Depending on the base OS to build the rootfs guest OS, it is required some specific programs that probably are not available or installed in the system that will build the guest image. For this case rootfs.sh can use a Docker* container to build the rootfs. The following requirements must be met:

1. Docker 1.12+ installed

2. runc is configured as the default runtime

   To check if runc is the default runtime:

   $ docker info | grep 'Default Runtime: runc'
   

   Note: This requirement is specifically when using Clear Containers runtime see issue for more information.

3. Export USE_DOCKER variable

   $ export USE_DOCKER=true
   

4. Use `rootfs.sh: Example:

   $ export USE_DOCKER=true
   $ # build guest O/S rootfs based on fedora
   $ ./rootfs-builder/rootfs.sh -r "${PWD}/fedora_rootfs" fedora
   $ # build image based rootfs created above
   $ ./image-builder/image_builder.sh "${PWD}/fedora_rootfs"