Regular Nightly

Kontain

Kontain is compatible with existing Docker and Kubernetes containers, and can be used to run your existing Container workloads in a manner that is "secure, fast and small—choose three" and with no changes to CI/CD tooling. Kontain works as a runtime for Docker and Kubernetes to run existing Containers with virtual machine level isolation and security, but without traditional VM overhead. In fact, Kontain can generate smaller artifacts with much faster startup times than "classic" Docker containers. Kontain works by wrapping your code into a unikernel executable that is packaged as a standard Docker container. To distinguish a Kontain container from a "classic" container, we spell it kontainer.

Use cases for Kontain include ML inferencing, serverless/FaaS computing, mobile edge cloud, healthcare, financial services, and ecommerce. If you use containers for your application, but are sensitive to security, performance, scalability, and the cost of running your application in production, Kontain may be for you.

For Developers wanting to use Kontain to package and run their applications in Docker using Kontain secure runtime and Kubernetes, the User guide is located at:

https://kontainapp.github.io/guide/

For a quick look at how Kontain can be used to run Docker containers:

https://kontainapp.github.io/guide/quickstart/

Using Kontain to run existing Docker Containers securely without changes to CI/CD processes and tooling

Installing Kontain

short clip to show how easy it is to install Kontain.

Kontain runs on Linux kernel version 4.15 or newer, running on Intel VT (vmx) or AMD (svm) with virtualization enabled. Recommended distros are Ubuntu 20.04 and Fedora 32, or newer.

Note: If you need to build Kontain images with Dockerfile, please ensure that you have Docker installed as well.

To install ¹ the latest Kontain release in a Linux system, run:

curl -s https://raw.githubusercontent.com/kontainapp/km/current/km-releases/kontain-install.sh | sudo bash

To install a release other than latest, for example v0.9.0, the URL is:

https://raw.githubusercontent.com/kontainapp/km/v0.9.0/km-releases/kontain-install.sh

This installs the necessary files in your /opt/kontain directory and configures the Kontain runtime for docker and podman. It also executes a smoke test of the unikernel virtual machine.

MacOS or Windows machine

Currently, the only way run Kontain on MacOS or Windows is to run it in a Linux VM². To simplify running Kontain we provide pre-configured VMs available from Vagrant Cloud:

Ubuntu 20.04 – https://app.vagrantup.com/kontain/boxes/ubuntu2004-kkm-beta3
Fedora 32 – https://app.vagrantup.com/kontain/boxes/fedora32-kkm-beta3

You’ll need Vagrant (https://www.vagrantup.com) and VirtualBox (https://www.VirtualBox.org) installed on your machine.

Once the VM is up (vagrant init kontain/ubuntu2004-kkm-beta3; vagrant up) and logged in (vagrant ssh), you have Kontain installed and configured.

Starting with Kontain

To run a simple Kontain unikernel manually:

    $ /opt/kontain/bin/km /opt/kontain/tests/hello_test.km Hello, Kontain!
    Hello, world
    Hello, argv[0] = '/opt/kontain/tests/hello_test.km'
    Hello, argv[1] = 'Hello,'
    Hello, argv[2] = 'Kontain!'

km is the Kontain virtual machine monitor. _hellotest.km is a very simple unikernel that prints out its arguments then exits.

To wrap this simple unikernel in a standard container format we need this Dockerfile

    FROM scratch
    ADD hello_test.km /
    ENTRYPOINT ["/hello_test.km"]
    CMD ["from", "docker"]

Put this Dockerfile and hello_test.km in an empty directory and run:

    docker build -t try-kontain .

Now you can run your kontainer from the docker (or podman) command line using the Kontain runtime:

    $ docker run --runtime=krun --rm try-kontain:latest
    Hello, world
    Hello, argv[0] = '/hello_test.km'
    Hello, argv[1] = 'from'
    Hello, argv[2] = 'docker'

krun is the Kontain runtime.

Native Linux executables

Static native Alpine Linux executable can run under Kontain, unmodified, as a unikernel. Same applies to other static executables build with musl libc.

Using Kontain base images

Kontain provides a collection of language interpreters packaged as unikernels on Docker Hub. Let’s use one of them to create a python kontainer.

You can use the provided /opt/kontain/examples/python/micro_srv.py example, or your own program. micro_srv.py implements a RESTful API endpoint. The dockerfile looks like this:

    FROM kontainapp/runenv-python
    ADD micro_srv.py /
    EXPOSE 8080
    ENTRYPOINT ["/usr/local/bin/python3","/micro_srv.py","8080"]

Put this dockerfile and micro_srv.py in an empty directory and run:

    docker build -t try-kontain .

Run the kontainer with docker run --runtime=krun -p 8080:8080 --rm try-kontain:latest then access the API with curl:

    $ curl -s http://localhost:8080 | jq .
    {
      "sysname": "Linux",
      "nodename": "807c605eca29",
      "release": "5.11.22-100.fc32.x86_64.kontain.KVM",
      "version": "#1 SMP Wed May 19 18:58:25 UTC 2021",
      "machine": "x86_64",
      "received": "ok"
    }

The process is similar with Node.js, or Java code. Just use the appropriate kontainapp base images – kontainapp/runenv-node or kontainapp/runenv-jdk-11.

Building kontainers from compiled code

For compiled languages such as C and Go, building a kontainer involves re-linking your compiled code.

For example, let's build the web server https://github.com/davidsblog/dweb (it's written in C) into a kontainer. Begin by using standard make:

$ git clone https://github.com/davidsblog/dweb.git
$ cd dweb/dweb
$ make
gcc -o dweb dweb.c dwebsvr.c -pthread -std=gnu99

Note the action make has done. We are going do the same, but with a Kontain tool:

$ /opt/kontain/bin/kontain-gcc -o dweb dweb.c dwebsvr.c -pthread -std=gnu99

Now we need a dockerfile:

    FROM scratch
    ADD . /app/
    WORKDIR /app
    ENTRYPOINT ["/app/dweb"]
    CMD ["8080"]

To build and run the kontainer:

$ docker build -t kontain-dweb .
$ docker run -p 8080:8080 --runtime=krun --rm -i xxx

You can interact with the web server via curl http://localhost:8080 or pointing a web browser to the same address.

Documentation

Command-line help: /opt/kontain/bin/km --help

Kontain User Guide Provides information for installing Kontain and using it to run workloads.

Debugging Kontain Unikernels Provides information about how to debug a Kontain workload (unikernel) using standard debugging tools and practices.

Known Issues

FAQs

Contributing

Kontain is open source: We encourage you to work with the source code and provide feedback!

Have a general comment or question about Kontain? Want to contribute a use case? Email us: community@kontain.app.

We accept PRs here. To view/report issues, go here.

To learn about our development process, including how to set up the build environment, then build and test KM, see BUILD.md.

Please refer to CONTRIBUTING.md for general guidelines and conventions.

IMPORTANT: All contributions are subject to the terms of the kontainapp/km licensing agreement^🔗.

Notes

1. To uninstall Kontain simply run:

    sudo bash /opt/kontain/bin/kontain-install.sh -u

2. We are working on a more seamless way to run Kontain on MacOS and Windows. Stay tuned.

Licensing

🔗 kontainapp/km is licensed under the Apache 2.0 license.

kontainapp / km

readme