mirror of
https://github.com/kata-containers/kata-containers.git
synced 2025-06-24 22:43:05 +00:00
Jose Carlos Venegas Munoz
GitHub
commit
25d6ed98a7
46
README.md
46
README.md
@ -1,33 +1,35 @@
|
||||
# Overview #
|
||||
* [Overview](#overview)
|
||||
* [Terms](#terms)
|
||||
|
||||
`Kata Containers runtime` creates a Virtual Machine to isolate a set of
|
||||
container workloads. The Virtual Machine requires a operating system
|
||||
operating (`Guest OS`) to boot and create containers inside the guest
|
||||
# Overview
|
||||
|
||||
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` for `Kata
|
||||
Containers`.
|
||||
This repository contains tools to create a guest OS disk image.
|
||||
|
||||
## Terms ##
|
||||
# Terms
|
||||
|
||||
This section describe the terms used as along all this document.
|
||||
This section describes the terms used for all documentation in this repository.
|
||||
|
||||
- `Guest OS`
|
||||
- rootfs
|
||||
|
||||
It is the collection of a `virtual disk` or `disk image` and `kernel`
|
||||
that in conjunction work as an operating system and it is different than
|
||||
the host operating system.
|
||||
The root filesystem or "rootfs" is the set of files contained in the
|
||||
guest root directory that builds into a filesystem.
|
||||
|
||||
- `Virtual disk` or `Guest Image`
|
||||
See [the rootfs builder documentation](rootfs-builder/README.md).
|
||||
|
||||
It is a virtual disk witch contains a `rootfs` that will be used to boot
|
||||
a Virtual Machine by for the `Kata Containers runtime`.
|
||||
- "Guest OS" (or "Guest Image")
|
||||
|
||||
- `rootfs`
|
||||
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.
|
||||
|
||||
The root filesystem or rootfs is the filesystem that is contained in the
|
||||
guest root directory. It can be built from any Linux Distribution but
|
||||
must provide at least the following components:
|
||||
- Kata agent
|
||||
- A `init` system (for example `systemd`) witch allow to start
|
||||
Kata agent at boot time.
|
||||
See [the image builder documentation](image-builder/README.md).
|
||||
|
||||
- "Base OS"
|
||||
|
||||
A particular version of a Linux distribution used to create a Guest OS from.
|
||||
|
||||
@ -1,8 +1,12 @@
|
||||
# Kata Containers image generation #
|
||||
* [Creating a guest OS image](#creating-a-guest-os-image)
|
||||
* [Further information](#further-information)
|
||||
|
||||
A Kata Containers image is generated by the script `image_builder.sh`
|
||||
which uses a `rootfs` directory created by the script
|
||||
`rootfs-builder/rootfs.sh`.
|
||||
# Kata Containers image generation
|
||||
|
||||
A Kata Containers disk image is generated using the `image_builder.sh` script.
|
||||
This uses a rootfs directory created by the `rootfs-builder/rootfs.sh` script.
|
||||
|
||||
## Creating a guest OS image
|
||||
|
||||
To create a guest OS image run:
|
||||
|
||||
@ -10,16 +14,13 @@ To create a guest OS image run:
|
||||
$ ./image_builder.sh path/to/rootfs
|
||||
```
|
||||
|
||||
Where `path/to/rootfs` is the directory pupulated by `rootfs.sh`. The
|
||||
script will check for following required binaries:
|
||||
Where `path/to/rootfs` is the directory populated by `rootfs.sh`.
|
||||
|
||||
- `/sbin/init` : The image must contain a `init` binary
|
||||
- `/bin/kata-agent` : The image contain the Kata [agent]
|
||||
## Further information
|
||||
|
||||
More information about usage:
|
||||
For more information about usage (including how to adjust the size of the
|
||||
image), run:
|
||||
|
||||
```
|
||||
$ ./image_builder.sh -h
|
||||
```
|
||||
|
||||
[agent]: https://github.com/kata-containers/agent "Kata agent"
|
||||
|
||||
@ -1,103 +1,62 @@
|
||||
# Building a rootfs for Kata Containers Guest OS #
|
||||
* [Supported base OSs](#supported-base-oss)
|
||||
* [Creating a rootfs](#creating-a-rootfs)
|
||||
* [Build a rootfs using Docker*](#build-a-rootfs-using-docker*)
|
||||
* [Adding support for a new guest OS](#adding-support-for-a-new-guest-os)
|
||||
* [Create template files](#create-template-files)
|
||||
* [Modify template files](#modify-template-files)
|
||||
* [Expected rootfs directory content](#expected-rootfs-directory-content)
|
||||
* [(optional) Customise the rootfs](#(optional)-customise-the-rootfs)
|
||||
* [Adding extra packages](#adding-extra-packages)
|
||||
* [Arbitary rootfs changes](#arbitary-rootfs-changes)
|
||||
|
||||
The Kata Containers `rootfs` is created using `rootfs.sh`.
|
||||
# Building a Guest OS rootfs for Kata Containers
|
||||
|
||||
## Supported base OSs ##
|
||||
The Kata Containers rootfs is created using the `rootfs.sh` script.
|
||||
|
||||
The `rootfs.sh` script builds a `rootfs` based on a particular Linux\*
|
||||
distribution. To build a `rootfs`for your chosen distribution, run:
|
||||
## Supported base OSs
|
||||
|
||||
The `rootfs.sh` script builds a rootfs based on a particular Linux\*
|
||||
distribution. The script supports multiple distributions and can be extended
|
||||
to add further ones.
|
||||
|
||||
To list the supported distributions, run:
|
||||
|
||||
```
|
||||
$./rootfs.sh <distro>
|
||||
$ ./rootfs.sh -h
|
||||
```
|
||||
|
||||
To check the supported `rootfs` based OS run `$rootfs-builder/rootfs.sh
|
||||
-h`, it will show the supported values of `<distro>`
|
||||
## Rootfs requirements
|
||||
|
||||
The rootfs must provide at least the following components:
|
||||
|
||||
## Adding support for new base OS ##
|
||||
- [Kata agent](https://github.com/kata-containers/agent)
|
||||
|
||||
The script `rootfs.sh` will it check for immediate sub-directories
|
||||
containing the following expected files structure:
|
||||
Path: `/bin/kata-agent` - Kata Containers guest.
|
||||
|
||||
- A `bash(1)` script called `rootfs_lib.sh`
|
||||
- An `init` system (e.g. `systemd`) to start the Kata agent
|
||||
when the guest OS boots.
|
||||
|
||||
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`.
|
||||
Path: `/sbin/init` - init binary called by the kernel.
|
||||
|
||||
## Creating a rootfs
|
||||
|
||||
- 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:
|
||||
To build a rootfs for your chosen distribution, run:
|
||||
|
||||
```
|
||||
make -f template/Makefile ROOTFS_BASE_NAME=my_new_awesome_rootfs
|
||||
$ sudo ./rootfs.sh <distro>
|
||||
```
|
||||
|
||||
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:
|
||||
## Build a rootfs using Docker*
|
||||
|
||||
```
|
||||
./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
|
||||
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
|
||||
a Docker\* container to build the rootfs. The following requirements
|
||||
must be met:
|
||||
|
||||
1. Docker 1.12+ installed
|
||||
1. Docker 1.12+ installed.
|
||||
|
||||
2. `runc` is configured as the default runtime
|
||||
2. `runc` is configured as the default runtime.
|
||||
|
||||
To check if `runc` is the default runtime:
|
||||
|
||||
@ -106,16 +65,19 @@ must be met:
|
||||
```
|
||||
|
||||
Note:
|
||||
This requirement is specifically when using Clear Containers runtime
|
||||
see [issue](https://github.com/clearcontainers/runtime/issues/828) for
|
||||
|
||||
This requirement is specific to the Clear Containers runtime.
|
||||
See [issue](https://github.com/clearcontainers/runtime/issues/828) for
|
||||
more information.
|
||||
|
||||
3. Export `USE_DOCKER` variable
|
||||
3. Export `USE_DOCKER` variable.
|
||||
|
||||
```
|
||||
$ export USE_DOCKER=true
|
||||
```
|
||||
4. Use `rootfs.sh:
|
||||
|
||||
4. Use `rootfs.sh`:
|
||||
|
||||
Example:
|
||||
```
|
||||
$ export USE_DOCKER=true
|
||||
@ -124,3 +86,90 @@ must be met:
|
||||
$ # build image based rootfs created above
|
||||
$ ./image-builder/image_builder.sh "${PWD}/fedora_rootfs"
|
||||
```
|
||||
|
||||
## Adding support for a new guest OS
|
||||
|
||||
The `rootfs.sh` script will check for immediate sub-directories
|
||||
containing the following expected files:
|
||||
|
||||
- A `bash(1)` script called `rootfs_lib.sh`
|
||||
|
||||
This file must contain a function called `build_rootfs()`, which must
|
||||
receive the path to where the rootfs is created, as its first argument.
|
||||
|
||||
Path: `rootfs-builder/<distro>/rootfs_lib.sh`.
|
||||
|
||||
|
||||
- A `bash(1)` script called `config.sh`
|
||||
|
||||
This represents the specific configuration for `<distro>`. It must
|
||||
provide configuration specific variables for the 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`.
|
||||
|
||||
### Create template files
|
||||
|
||||
To create a directory with the expected file structure run:
|
||||
|
||||
```
|
||||
$ make -f template/Makefile ROOTFS_BASE_NAME=my_new_awesome_rootfs
|
||||
```
|
||||
|
||||
After running the previous command, a new directory is created in
|
||||
`rootfs-builder/my_new_awesome_rootfs/`.
|
||||
|
||||
|
||||
To verify the directory can be used to build a rootfs, run `./rootfs.sh -h`.
|
||||
Running this script shows `my_new_awesome_rootfs` as one of the options for
|
||||
use. To use the new guest OS, follow the instructions in [Creating a rootfs](#creating-a-rootfs).
|
||||
|
||||
### Modify template files
|
||||
|
||||
After the new directory structure is created:
|
||||
|
||||
- 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 particular use cases developers might want to modify the guest OS.
|
||||
|
||||
#### Adding extra packages
|
||||
|
||||
To add additional packages, use one of the following methods:
|
||||
|
||||
- Use the environment variable `EXTRA_PKGS` to provide a list of space-separated
|
||||
packages to install.
|
||||
|
||||
Note:
|
||||
|
||||
The package names might vary among Linux distributions, the extra
|
||||
package names must exist in the base OS flavor you use to build the
|
||||
rootfs from.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
$ EXTRA_PKGS="vim emacs" ./rootfs-builder/rootfs.sh -r ${PWD}/myrootfs fedora
|
||||
```
|
||||
|
||||
- Modify the variable `PACKAGES` in `rootfs-builder/<distro>/config.sh`.
|
||||
|
||||
This variable specifies the minimal set of packages needed. The
|
||||
configuration file must use the package names from the distro for which they
|
||||
were created.
|
||||
|
||||
#### Arbitary rootfs changes
|
||||
|
||||
Once the rootfs directory is created, you can add and remove files as
|
||||
needed. Changes affect the files included in the final guest image.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user