runtime

runtime

• Introduction
• License
• Hardware requirements
• Quick start for users
• Quick start for developers
• Community
• Configuration
• Logging
• Debugging
• Limitations
• Home Page

Introduction

cc-runtime is the next generation of Intel® Clear Containers runtime.

This tool, henceforth referred to simply as "the runtime", builds upon the virtcontainers project to provide a high-performance standards-compliant runtime that creates hardware-virtualized containers which leverage Intel's VT-x technology.

It is a re-implementation of cc-oci-runtime written in the go language and supersedes cc-oci-runtime starting from 3.0.0.

The runtime is both OCI-compatible and CRI-O-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 for further details.

Hardware requirements

The runtime has a built-in command to determine if your host system is capable of running an Intel® Clear Container. Simply run:

$ cc-runtime cc-check

Note:

If you run the command above as the root user, further checks will be performed (e.g. check if another incompatible hypervisor is running):

$ sudo cc-runtime cc-check

Quick start for users

See the installation guides available for various operating systems.

Quick start for developers

See the developer's installation guide.

Community

See the contributing document.

Configuration

The runtime uses a single configuration file called configuration.toml. Since the runtime supports a stateless system, it checks for this configuration file in multiple locations. The default location is /usr/share/defaults/clear-containers/configuration.toml for a standard system. However, if /etc/clear-containers/configuration.toml exists, this will take priority.

To see which paths the runtime will check for a configuration source, run:

$ cc-runtime --cc-show-default-config-paths

To see details of your systems runtime environment (including the location of the configuration file being used), run:

$ cc-runtime cc-env

Logging

The runtime provides --log= and --log-format= options. However, you can also configure it to log to the system log (syslog or journald) such that all log data is sent to both the specified logfile and the system log. The latter is useful as it is independent of the lifecycle of each container.

To view runtime log output:

$ sudo journalctl -t cc-runtime

To view shim log output:

$ sudo journalctl -t cc-shim

To view proxy log output:

$ sudo journalctl -t cc-proxy

Note:

The proxy log entries also include output from the agent (cc-agent) and the hypervisor, which includes the guest kernel boot-time messages.

Debugging

The runtime, the shim (cc-shim), the proxy (cc-proxy), and the hypervisor all have separate enable_debug= debug options in the configuration file. All of these debug options are disabled by default. See the comments in the installed configuration file for further details.

If you want to enable debug for all host-side components, assuming a standard configuration file path, run:

$ sudo sed -i -e 's/^#\(enable_debug\).*=.*$/\1 = true/g' /usr/share/defaults/clear-containers/configuration.toml

The agent (cc-agent) that runs inside each virtual machine is slightly different. To enable its debug, set a special guest kernel command-line parameter (agent.log) to debug. This agent looks for this special option when it starts:

$ sudo sed -i -e 's/^kernel_params = ""/kernel_params = "agent.log=debug"/g' /usr/share/defaults/clear-containers/configuration.toml

Note:

The previous command will only set the option if you have a default configuration file. If you have modified the original value of kernel_params you will need to add the agent.log value yourself.

See the agent debug document and the kernel debug document for further details.

Limitations

See the limitations file for further details.

Home Page

The canonical home page for the project is: https://github.com/clearcontainers