github/kata-containers
1
0
Fork 2
mirror of https://github.com/kata-containers/kata-containers.git synced 2025-09-16 22:39:01 +00:00
Code Issues Projects Releases Wiki Activity

osbuilder: move code into tools directory

Browse Source 
move all osbuilder files into `tools` directory to be able
to merge this into kata-containers repo.

Signed-off-by: Salvador Fuentes <salvador.fuentes@intel.com>
This commit is contained in:
Salvador Fuentes
2020-04-29 16:45:00 -05:00
parent eb128f8558
commit 715d342519
61 changed files with 0 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files

212
tools/osbuilder/README.md Normal file
View File

@@ -0,0 +1,212 @@
[![Build Status](https://travis-ci.org/kata-containers/osbuilder.svg?branch=master)](https://travis-ci.org/kata-containers/osbuilder)
# osbuilder
* [osbuilder](#osbuilder)
* [Introduction](#introduction)
* [Terms](#terms)
* [Building](#building)
* [Rootfs creation](#rootfs-creation)
* [Rootfs with systemd as init](#rootfs-with-systemd-as-init)
* [Rootfs with the agent as init](#rootfs-with-the-agent-as-init)
* [dracut based rootfs](#dracut-based-rootfs)
* [Image creation](#image-creation)
* [Image with systemd as init](#image-with-systemd-as-init)
* [Image with the agent as init](#image-with-the-agent-as-init)
* [dracut based image](#dracut-based-image)
* [Initrd creation](#initrd-creation)
* [Rootfs based initrd](#rootfs-based-initrd)
* [dracut based initrd](#dracut-based-initrd)
* [dracut options](#dracut-options)
* [Add kernel modules](#add-kernel-modules)
* [Testing](#testing)
* [Platform-Distro Compatibility Matrix](#platform-distro-compatibility-matrix)
## Introduction
The Kata Containers runtime creates a virtual machine (VM) to isolate a set of
container workloads. The VM requires a guest kernel and a guest operating system
("guest OS") to boot and create containers inside the guest
environment.
This repository contains tools to create a guest OS disk image.
## Terms
This section describes the terms used for all documentation in this repository.
- rootfs
The root filesystem or "rootfs" is a slight misnomer as it is not a true filesystem. It is a tree of files contained in a particular directory, which represents the root disk layout. A rootfs can be turned into either an image or an initrd.
See the [rootfs creation](#rootfs-creation) section.
- "Guest OS" (or "Guest Image")
A "virtual disk" or "disk image" built from a rootfs. It contains a
filesystem that is used by the VM, in conjunction with a guest kernel, to
create an environment to host the container. Neither the guest OS nor the
guest kernel need to be the same as the host operating system.
See the [image creation](#image-creation) section.
- initrd (or "initramfs")
A compressed `cpio(1)` archive, created from a rootfs which is loaded into memory and used as part of the Linux startup process. During startup, the kernel unpacks it into a special instance of a `tmpfs` that becomes the initial root filesystem.
See the [initrd creation](#initrd-creation) section.
- "Base OS"
A particular version of a Linux distribution used to create a rootfs from.
- dracut
A guest OS build method where the building host is used as the Base OS.
For more information refer to the [dracut homepage](https://dracut.wiki.kernel.org/index.php/Main_Page).
## Building
The top-level `Makefile` contains an example of how to use the available components.
Set `DEBUG=true` to execute build scripts in debug mode.
Two build methods are available, `distro` and `dracut`.
By default, the `distro` build method is used, and this creates a rootfs using
distro specific commands (e.g.: `debootstrap` for Debian or `yum` for CentOS).
The `dracut` build method uses the distro-agnostic tool `dracut` to obtain the same goal.
By default components are run on the host system. However, some components
offer the ability to run from within a container (for ease of setup) by setting the
`USE_DOCKER=true` or `USE_PODMAN=true` variable. If both are set, `USE_DOCKER=true`
takes precedence over `USE_PODMAN=true`.
For more detailed information, consult the documentation for a particular component.
When invoking the appropriate make target as showed below, a single command is used
to generate an initrd or an image. This is what happens in details:
1. A rootfs is generated based on the specified target distribution.
2. The rootfs is provisioned with Kata-specific components and configuration files.
3. The rootfs is used as a base to generate an initrd or an image.
When using the dracut build method however, the build sequence is different:
1. An overlay directory is populated with Kata-specific components.
2. dracut is instructed to merge the overlay directory with the required host-side
filesystem components to generate an initrd.
3. When generating an image, the initrd is extracted to obtain the base rootfs for
the image.
### Rootfs creation
This section shows how to build a basic rootfs using the default distribution.
For further details, see
[the rootfs builder documentation](rootfs-builder/README.md).
#### Rootfs with systemd as init
```
$ sudo -E PATH=$PATH make USE_DOCKER=true rootfs
```
#### Rootfs with the agent as init
```
$ sudo -E PATH=$PATH make USE_DOCKER=true AGENT_INIT=yes rootfs
```
#### dracut based rootfs
> **Note**: the dracut build method does not need a rootfs as a base for an image or initrd.
However, a rootfs can be generated by extracting the generated initrd.
```
$ sudo -E PATH=$PATH make BUILD_METHOD=dracut rootfs
```
### Image creation
This section shows how to create an image from the already-created rootfs. For
further details, see
[the image builder documentation](image-builder/README.md).
#### Image with systemd as init
```
$ sudo -E PATH=$PATH make USE_DOCKER=true image
```
#### Image with the agent as init
```
$ sudo -E PATH=$PATH make USE_DOCKER=true AGENT_INIT=yes image
```
#### dracut based image
> Note: the dracut build method generates an image by first building an initrd,
and then using the rootfs extracted from it.
```
$ sudo -E PATH=$PATH make BUILD_METHOD=dracut image
```
### Initrd creation
#### Rootfs based initrd
Create an initrd from the already-created rootfs and with the agent acting as the init daemon
using:
```
$ sudo -E PATH=$PATH make AGENT_INIT=yes initrd
```
#### dracut based initrd
Create an initrd using the dracut build method with:
```
$ sudo -E PATH=$PATH make BUILD_METHOD=dracut AGENT_INIT=yes initrd
```
For further details,
see [the initrd builder documentation](initrd-builder/README.md).
### dracut options
#### Add kernel modules
If the initrd or image needs to contain kernel modules, this can be done by:
1. Specify the name of the modules (as reported by `modinfo MODULE-NAME`) in
`dracut/dracut.conf.d/10-drivers.conf`. For example this file can contain:
```
drivers="9p 9pnet 9pnet_virtio"
```
2. Set the `DRACUT_KVERSION` make variable to the release name of the kernel that
is paired with the built image or initrd, using the `uname -r` format. For example:
```
$ make BUILD_METHOD=dracut DRACUT_KVERSION=5.2.1-23-kata AGENT_INIT=yes initrd
```
## Testing
```
$ make test
```
For further details, see [the tests documentation](tests/README.md).
## Platform-Distro Compatibility Matrix
The following table illustrates what target architecture is supported for each
of the the osbuilder distributions.
> Note: this table is not relevant for the dracut build method, since it supports
any Linux distribution and architecture where dracut is available.
| |Alpine |CentOS |Clear Linux |Debian/Ubuntu |EulerOS |Fedora |openSUSE |
|-- |-- |-- |-- |-- |-- |-- |-- |
|**ARM64** |:heavy_check_mark:|:heavy_check_mark:| | |:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|
|**PPC64le**|:heavy_check_mark:|:heavy_check_mark:| |:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|
|**s390x** |:heavy_check_mark:| | |:heavy_check_mark:| |:heavy_check_mark:| |
|**x86_64** |:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|