Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kata-containers/runtime

Kata Containers version 1.x runtime (for version 2.x see https://github.com/kata-containers/kata-containers).
https://github.com/kata-containers/runtime

container containers cri-o docker k8s kubernetes kvm oci qemu security virtual-machine virtualization

Last synced: 4 days ago
JSON representation

Kata Containers version 1.x runtime (for version 2.x see https://github.com/kata-containers/kata-containers).

Awesome Lists containing this project

README 

        
[![Build Status](https://travis-ci.org/kata-containers/runtime.svg?branch=master)](https://travis-ci.org/kata-containers/runtime)

[![Build Status](http://jenkins.katacontainers.io/job/kata-containers-runtime-ubuntu-18-04-master/badge/icon)](http://jenkins.katacontainers.io/job/kata-containers-runtime-ubuntu-18-04-master/)

[![Go Report Card](https://goreportcard.com/badge/github.com/kata-containers/runtime)](https://goreportcard.com/report/github.com/kata-containers/runtime)

[![GoDoc](https://godoc.org/github.com/kata-containers/runtime?status.svg)](https://godoc.org/github.com/kata-containers/runtime)



# Runtime



This repository contains the runtime for the

[Kata Containers](https://github.com/kata-containers) project.



For details of the other Kata Containers repositories, see the

[repository summary](https://github.com/kata-containers/kata-containers).



* [Introduction](#introduction)

* [License](#license)

* [Platform support](#platform-support)

    * [Hardware requirements](#hardware-requirements)

* [Download and install](#download-and-install)

* [Quick start for developers](#quick-start-for-developers)

* [Architecture overview](#architecture-overview)

* [Configuration](#configuration)

* [Logging](#logging)

    * [Kata OCI](#kata-oci)

    * [Kata containerd shimv2](#kata-containerd-shimv2)

* [Debugging](#debugging)

* [Limitations](#limitations)

* [Community](#community)

    * [Contact](#contact)

* [Further information](#further-information)

* [Additional packages](#additional-packages)



## Introduction



`kata-runtime`, referred to as "the runtime", is the Command-Line Interface

(CLI) part of the Kata Containers runtime component. It leverages the

[virtcontainers](virtcontainers)

package to provide a high-performance standards-compliant runtime that creates

hardware-virtualized [Linux](https://www.kernel.org/) containers running on Linux hosts.



The runtime is

[OCI](https://github.com/opencontainers/runtime-spec)-compatible,

[CRI-O](https://github.com/cri-o/cri-o)-compatible, and

[Containerd](https://github.com/containerd/containerd)-compatible,

 allowing it

to work seamlessly with both Docker and Kubernetes respectively.



## License



The code is licensed under an Apache 2.0 license.



See [the license file](LICENSE) for further details.



## Platform support



Kata Containers currently works on systems supporting the following

technologies:



- [Intel](https://www.intel.com) VT-x technology.

- [ARM](https://www.arm.com) Hyp mode (virtualization extension).

- [IBM](https://www.ibm.com) Power Systems.

- [IBM](https://www.ibm.com) Z mainframes.

### Hardware requirements



The runtime has a built-in command to determine if your host system is capable

of running and creating a Kata Container:



```bash

$ kata-runtime kata-check

```



> **Note:**

>

> - By default, only a brief success / failure message is printed.

> If more details are needed, the `--verbose` flag can be used to display the

> list of all the checks performed.

>

> - `root` permission is needed to check if the system is capable of running

> Kata containers. In this case, additional checks are performed (e.g., if another

> incompatible hypervisor is running).



## Download and install



[![Get it from the Snap Store](https://snapcraft.io/static/images/badges/en/snap-store-black.svg)](https://snapcraft.io/kata-containers)



See the [installation guides](https://github.com/kata-containers/documentation/tree/master/install/README.md)

available for various operating systems.



## Quick start for developers



See the

[developer guide](https://github.com/kata-containers/documentation/blob/master/Developer-Guide.md).



## Architecture overview



See the [architecture overview](https://github.com/kata-containers/documentation/blob/master/design/architecture.md)

for details on the Kata Containers design.



## Configuration



The runtime uses a TOML format configuration file called `configuration.toml`.

The file contains comments explaining all options.



> **Note:**

>

> The initial values in the configuration file provide a good default configuration.

> You may need to modify this file to optimise or tailor your system, or if you have

> specific requirements.



Since the runtime supports a

[stateless system](https://clearlinux.org/about),

it checks for this configuration file in multiple locations, two of which are

built in to the runtime. The default location is

`/usr/share/defaults/kata-containers/configuration.toml` for a standard

system. However, if `/etc/kata-containers/configuration.toml` exists, this

takes priority.



The below command lists the full paths to the configuration files that the

runtime attempts to load. The first path that exists will be used:



```bash

$ kata-runtime --kata-show-default-config-paths

```



Aside from the built-in locations, it is possible to specify the path to a

custom configuration file using the `--kata-config` option:



```bash

$ kata-runtime --kata-config=/some/where/configuration.toml ...

```



The runtime will log the full path to the configuration file it is using. See

the [logging](#logging) section for further details.



To see details of your systems runtime environment (including the location of

the configuration file being used), run:



```bash

$ kata-runtime kata-env

```



## Logging



For detailed information and analysis on obtaining logs for other system

components, see the documentation for the

[`kata-log-parser`](https://github.com/kata-containers/tests/tree/master/cmd/log-parser)

tool.



For runtime logs, see the following sections for the CRI-O and containerd shimv2 based runtimes.



### Kata OCI



The Kata OCI runtime (including when used with CRI-O), provides `--log=` and `--log-format=` options.

However, the runtime also always logs to the system log (`syslog` or `journald`).



To view runtime log output:



```bash

$ sudo journalctl -t kata-runtime

```



### Kata containerd shimv2



The Kata containerd shimv2 runtime logs through `containerd`, and its logs will be sent

to wherever the `containerd` logs are directed. However, the

shimv2 runtime also always logs to the system log (`syslog` or `journald`) under the

identifier name of `kata`.



To view the `shimv2` runtime log output:



```bash

$ sudo journalctl -t kata

```



## Debugging



See the

[debugging section of the developer guide](https://github.com/kata-containers/documentation/blob/master/Developer-Guide.md#troubleshoot-kata-containers).



## Limitations



See the

[limitations file](https://github.com/kata-containers/documentation/blob/master/Limitations.md)

for further details.



## Community



See [the community repository](https://github.com/kata-containers/community).



### Contact



See [how to reach the community](https://github.com/kata-containers/community/blob/master/CONTRIBUTING.md#contact).



## Further information



See the

[project table of contents](https://github.com/kata-containers/kata-containers)

and the

[documentation repository](https://github.com/kata-containers/documentation).



## Additional packages



For details of the other packages contained in this repository, see the

[package documentation](pkg).