# Clear Containers image #

This project's goal is to use LinuxKit\* to generate two components for the
Clear Containers project:

- Kernel: The Linux\* kernel for Intel® Clear Containers following LinuxKit
  philosophy.
- Image or mini-os: the minimal guest user-space image (The guest OS based in
	LinuxKit is not functional for clear-containers yet).

## What are Clear Containers? ##

Intel® Clear Containers are a collection of tools, configurations, and
techniques anchored on an implementation leveraging Intel® Architecture to
optimize hypervisor-based containers. Intel® Clear Containers enable a small
virtual machine with the isolation of virtual-machine technology along with
the deployment benefits of containers.

Today, the Intel® Clear Containers project uses a Clear Linux\* OS for Intel®
Architecture based guest OS image. The Clear Linux based image provides:

- [systemd]
- [hyperstart]

## Why use LinuxKit to build a Clear Containers guest OS?##

Using LinuxKit to build the guest OS fits the Clear Containers guest needs. LinuxKit
provides:

- An immutable Linux distribution: Write operations from the guest to the
  file system are not persistent.
- Easy tooling with easy iteration.
- A general purpose toolkit.

## Current development status ##

A Clear Containers compatible kernel can be generated using LinuxKit
which has the security features of LinuxKit and the virtualization
features required by Clear Containers.

## Getting started ##
To build the kernel, enter the following commands:


1. Build kernel

This step is required to build a kernel from source
It will use the kernel configuration file:
`projects/clear-containers/kernel/kernel_config` and
the patches from `projects/clear-containers/kernel/patches-*`

NOTE: This step also is needed meanwhile an image
`linuxkit/kernel-clear-containers:X.y.x `is pushed to docker-hub.

The following commands will build a kernel using
`projects/clear-containers/kernel/Dockerfile` :

```
pushd projects/clear-containers/kernel
make image
make tag
popd
```
2. Get a Clear Containers kernel using moby tool

To generate the kernel image called `clear-containers-bzImage`, enter the
following command:

```
./bin/linuxkit build ./projects/clear-containers/clear-containers.yml
```

3. Test kernel

The Makefile target `qemu-lite` from `projects/clear-containers/tools`
will launch the Clear Containers base OS and the 
with kernel built with moby. Use the `root` user to access to the test system,
it will ask to setup a password.

```
cd projects/clear-containers/tools
make qemu-lite
```

The file `clear-containers-bzImage`  is not a bzImage\*. The file
is a vmlinux image, see TODO. The [cc-oci-runtime] project can be
configured to use kernel generated by LinuxKit.

## TODO ##

* Create a Clear Container Mini-OS image.
* Start `hyperstart` as a privileged container.
* Add a script to launch a clear container guest.
* Sync with official kernel LinuxKit patches.
* Add an output format similar to `kernel+initrd` which extracts a vmlinux
  image. The Intel® Clear Containers project requires an uncompressed kernel
  to boot. Currently, the LinuxKit output format `kernel+initrd` extracts a
  bzImage from a LinuxKit packaged kernel. A way to extract the vmlinux image is
  still required.

[systemd]: <https://www.freedesktop.org/wiki/Software/systemd/>
[hyperstart]: <https://github.com/clearcontainers/hyperstart>
[cc-oci-runtime]: <https://github.com/01org/cc-oci-runtime>
[hyperstart container]: <https://github.com/clearcontainers/hyperstart/tree/0.7.0-clearcontainers>