github/kata-containers
1
0
Fork 1
mirror of https://github.com/kata-containers/kata-containers.git synced 2025-06-25 06:52:13 +00:00
Code Issues Projects Releases Wiki Activity

Merge pull request #27 from jodh-intel/doc-fixes

Browse Source 
docs: General cleanup
This commit is contained in:
Jose Carlos Venegas Munoz 2018-01-18 23:45:04 -06:00 committed by GitHub
commit 25d6ed98a7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 165 additions and 113 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
README.md
View File

@ -1,33 +1,35 @@
# Overview # * [Overview](#overview)
* [Terms](#terms)
`Kata Containers runtime` creates a Virtual Machine to isolate a set of # Overview
container workloads. The Virtual Machine requires a operating system
operating (`Guest OS`) to boot and create containers inside the guest 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. environment.
This repository contains tools to create a `Guest OS` for `Kata This repository contains tools to create a guest OS disk image.
Containers`.
## 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` The root filesystem or "rootfs" is the set of files contained in the
that in conjunction work as an operating system and it is different than guest root directory that builds into a filesystem.
the host operating system.
- `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 - "Guest OS" (or "Guest Image")
a Virtual Machine by for the `Kata Containers runtime`.
- `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 See [the image builder documentation](image-builder/README.md).
guest root directory. It can be built from any Linux Distribution but
must provide at least the following components: - "Base OS"
- Kata agent
- A `init` system (for example `systemd`) witch allow to start A particular version of a Linux distribution used to create a Guest OS from.
Kata agent at boot time.

23
image-builder/README.md
View File

@ -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` # Kata Containers image generation
which uses a `rootfs` directory created by the script
`rootfs-builder/rootfs.sh`. 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: To create a guest OS image run:
@ -10,16 +14,13 @@ To create a guest OS image run:
$ ./image_builder.sh path/to/rootfs $ ./image_builder.sh path/to/rootfs
``` ```
Where `path/to/rootfs` is the directory pupulated by `rootfs.sh`. The Where `path/to/rootfs` is the directory populated by `rootfs.sh`.
script will check for following required binaries:
- `/sbin/init` : The image must contain a `init` binary ## Further information
- `/bin/kata-agent` : The image contain the Kata [agent]
More information about usage: For more information about usage (including how to adjust the size of the
image), run:
``` ```
$ ./image_builder.sh -h $ ./image_builder.sh -h
``` ```
[agent]: https://github.com/kata-containers/agent "Kata agent"

209
rootfs-builder/README.md
View File

@ -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\* ## Supported base OSs
distribution. To build a `rootfs`for your chosen distribution, run:
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 ## Rootfs requirements
-h`, it will show the supported values of `<distro>`
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 Path: `/bin/kata-agent` - Kata Containers guest.
containing the following expected files structure:
- 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 Path: `/sbin/init` - init binary called by the kernel.
must receive as first argument the path where the `rootfs` will be
populated. Path: `rootfs-builder/<distro>/rootfs_lib.sh`.
## Creating a rootfs
- A `bash(1)` file `config.sh` To build a rootfs for your chosen distribution, run:
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 $ sudo ./rootfs.sh <distro>
``` ```
After run the command above, a new directory will be created in ## Build a rootfs using Docker*
`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:
``` Depending on the base OS to build the rootfs guest OS, it is required some
./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 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 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: 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: To check if `runc` is the default runtime:
@ -106,16 +65,19 @@ must be met:
``` ```
Note: 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. more information.
3. Export `USE_DOCKER` variable 3. Export `USE_DOCKER` variable.
``` ```
$ export USE_DOCKER=true $ export USE_DOCKER=true
``` ```
4. Use `rootfs.sh:
4. Use `rootfs.sh`:
Example: Example:
``` ```
$ export USE_DOCKER=true $ export USE_DOCKER=true
@ -124,3 +86,90 @@ must be met:
$ # build image based rootfs created above $ # build image based rootfs created above
$ ./image-builder/image_builder.sh "${PWD}/fedora_rootfs" $ ./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.