lxcri

README

About

lxcri is a wrapper around LXC which can be used as a drop-in container runtime replacement for use by CRI-O.

OCI compliance

With liblxc starting from lxc-4.0.0-927-gb5daeddc5 it passes all sonobuoy conformance tests.

Build

You can use the provided Dockerfile to build an

runtime only image (lxcri + lxc)

docker build --build-arg installcmd=install_runtime

or with everything required for a kubernetes node (kubelet, kubeadm, cri-o, lxcri, lxc ...)

docker build

Note: The images are not pre-configured and you must follow the steps in setup for now.

Setup

To use lxcri as OCI runtime in cri-o see setup.md

API Usage

Please have a look at the runtime tests for now.

Notes

• It's currently only tested with cgroups v2.

Documentation

Overview

Package lxcri provides an OCI specific runtime interface for lxc.

Index

• Constants
• Variables
• type Container
  • func (c Container) ConfigFilePath() string
  • func (c *Container) ContainerState() (specs.ContainerState, error)
  • func (c *Container) Exec(proc *specs.Process, execOpts *ExecOptions) (exitStatus int, err error)
  • func (c *Container) ExecDetached(proc *specs.Process, execOpts *ExecOptions) (pid int, err error)
  • func (c *Container) Release() error
  • func (c Container) RuntimePath(subPath ...string) string
  • func (c *Container) SetLog(filename string, level string) error
  • func (c *Container) State() (*State, error)
• type ContainerConfig
• type ExecOptions
• type Runtime
  • func (rt *Runtime) Create(ctx context.Context, cfg *ContainerConfig) (*Container, error)
  • func (rt *Runtime) Delete(ctx context.Context, containerID string, force bool) error
  • func (rt *Runtime) Init() error
  • func (rt *Runtime) Kill(ctx context.Context, c *Container, signum unix.Signal) error
  • func (rt *Runtime) List() ([]string, error)
  • func (rt *Runtime) Load(containerID string) (*Container, error)
  • func (rt *Runtime) Start(ctx context.Context, c *Container) error
• type RuntimeFeatures
• type State

Constants

const (
	// BundleConfigFile is the name of the OCI container bundle config file.
	// The content is the JSON encoded specs.Spec.
	BundleConfigFile = "config.json"
)

Variables

var (
	// ExecStart starts the liblxc monitor process, similar to lxc-start
	ExecStart = "lxcri-start"
	// ExecHook is run as liblxc hook and creates additional devices and remounts masked paths.
	ExecHook        = "lxcri-hook"
	ExecHookBuiltin = "lxcri-hook-builtin"
	// ExecInit is the container init process that execs the container process.
	ExecInit = "lxcri-init"
)

Required runtime executables loaded from Runtime.LibexecDir

var (
	// ErrNotExist is returned if the container (runtime dir) does not exist.
	ErrNotExist = fmt.Errorf("container does not exist")
)

Types

type Container

type Container struct {
	LinuxContainer *lxc.Container `json:"-"`
	*ContainerConfig

	CreatedAt time.Time
	// Pid is the process ID of the liblxc monitor process ( see ExecStart )
	Pid int
	// contains filtered or unexported fields
}

Container is the runtime state of a container instance.

func (Container) ConfigFilePath

func (c Container) ConfigFilePath() string

ConfigFilePath returns the path to the liblxc config file.

func (*Container) ContainerState

func (c *Container) ContainerState() (specs.ContainerState, error)

ContainerState returns the current state of the container process, as defined by the OCI runtime spec.

func (*Container) Exec

func (c *Container) Exec(proc *specs.Process, execOpts *ExecOptions) (exitStatus int, err error)

Exec executes the given process spec within the container. It waits for the process to exit and returns its exit code. The container state must either be specs.StateCreated or specs.StateRunning The given ExecOptions execOpts control the execution environment of the the process.

func (*Container) ExecDetached

func (c *Container) ExecDetached(proc *specs.Process, execOpts *ExecOptions) (pid int, err error)

ExecDetached executes the given process spec within the container. The given process is started and the process PID is returned. It's up to the caller to wait for the process to exit using the returned PID. The container state must be either specs.StateCreated or specs.StateRunning The given ExecOptions execOpts, control the execution environment of the the process.

func (*Container) Release

func (c *Container) Release() error

Release releases resources allocated by the container.

func (Container) RuntimePath

func (c Container) RuntimePath(subPath ...string) string

RuntimePath returns the absolute path to the given sub path within the container runtime directory.

func (*Container) SetLog

func (c *Container) SetLog(filename string, level string) error

SetLog changes log file path and log level of the container (liblxc) instance. The settings are only valid until Release is called on this instance. The log settings applied at Runtime.Create are active until SetLog is called.

func (*Container) State

func (c *Container) State() (*State, error)

State returns the runtime state of the containers process. The State.Pid value is the PID of the liblxc container monitor process (lxcri-start).

type ContainerConfig

type ContainerConfig struct {
	// The Spec used to generate the liblxc config file.
	// Any changes to the spec after creating the liblxc config file have no effect
	// and should be avoided.
	// NOTE The Spec must be serialized with the runtime config (lxcri.json)
	// This is required because Spec.Annotations are required for Container.State()
	// and spec.Namespaces are required for attach.
	Spec *specs.Spec

	// ContainerID is the identifier of the container.
	// The ContainerID is used as name for the containers runtime directory.
	// The ContainerID must be unique at least through all containers of a runtime.
	// The ContainerID should match the following pattern `[a-z][a-z0-9-_]+`
	ContainerID string

	// BundlePath is the OCI bundle path.
	BundlePath string

	ConsoleSocket string `json:",omitempty"`

	// MonitorCgroupDir is the cgroup directory path
	// for the liblxc monitor process `lxcri-start`
	// relative to the cgroup root.
	MonitorCgroupDir string

	CgroupDir string

	// LogFile is the liblxc log file path
	LogFile string

	// LogLevel is the liblxc log level
	LogLevel string

	// Log is the container Logger
	Log zerolog.Logger `json:"-"`
}

ContainerConfig is the configuration for a single Container instance.

type ExecOptions

type ExecOptions struct {
	// Namespaces is the list of container namespaces that the process is attached to.
	// The process will is attached to all container namespaces if Namespaces is empty.
	Namespaces []specs.LinuxNamespaceType
}

ExecOptions contains options for Container.Exec and Container.ExecDetached

type Runtime

type Runtime struct {
	// Log is the logger used by the runtime.
	Log zerolog.Logger `json:"-"`

	// Root is the file path to the runtime directory.
	// Directories for containers created by the runtime
	// are created within this directory.
	Root string

	// Use systemd encoded cgroup path (from crio-o/conmon)
	// is true if /etc/crio/crio.conf#cgroup_manager = "systemd"
	SystemdCgroup bool

	// Path for lxc monitor cgroup (lxc specific feature).
	// This is the cgroup where the liblxc monitor process (lxcri-start)
	// will be placed in. It's similar to /etc/crio/crio.conf#conmon_cgroup
	MonitorCgroup string

	// LibexecDir is the the directory that contains the runtime executables.
	LibexecDir string

	// Featuress are runtime (security) features that apply to all containers
	// created by the runtime.
	Features RuntimeFeatures

	specs.Hooks
	// contains filtered or unexported fields
}

Runtime is a factory for creating and managing containers. The exported methods of Runtime are required to implement the OCI container runtime interface spec (CRI). It shares the common settings

func (*Runtime) Create

func (rt *Runtime) Create(ctx context.Context, cfg *ContainerConfig) (*Container, error)

Create creates a single container instance from the given ContainerConfig. Create is the first runtime method to call within the lifecycle of a container. A created Container must be released with Container.Release after use. You should call Runtime.Delete to cleanup container runtime state, even if the Create returned with an error.

func (*Runtime) Delete

func (rt *Runtime) Delete(ctx context.Context, containerID string, force bool) error

Delete removes the container from the runtime directory. The container must be stopped or force must be set to true. If the container is not stopped but force is set to true, the container will be killed with unix.SIGKILL.

func (*Runtime) Init

func (rt *Runtime) Init() error

Init initializes the runtime instance. It creates required directories and checks the runtimes system configuration. Unsupported runtime features are disabled and a warning message is logged. Init must be called once for a runtime instance before calling any other method.

func (*Runtime) Kill

func (rt *Runtime) Kill(ctx context.Context, c *Container, signum unix.Signal) error

Kill sends the signal signum to the container init process.

func (*Runtime) List

func (rt *Runtime) List() ([]string, error)

List returns the IDs for all existing containers.

func (*Runtime) Load

func (rt *Runtime) Load(containerID string) (*Container, error)

Load loads a container from the runtime directory. The container must have been created with Runtime.Create. The logger Container.Log is set to Runtime.Log by default. A loaded Container must be released with Container.Release after use.

func (*Runtime) Start

func (rt *Runtime) Start(ctx context.Context, c *Container) error

Start starts the given container. Start simply unblocks the init process `lxcri-init`, which then executes the container process. The given container must have been created with Runtime.Create.

type RuntimeFeatures

type RuntimeFeatures struct {
	Seccomp       bool
	Capabilities  bool
	Apparmor      bool
	CgroupDevices bool
}

RuntimeFeatures are (security) features supported by the Runtime. The supported features are enabled on any Container instance created by Runtime.Create.

type State

type State struct {
	ContainerState string
	RuntimePath    string
	SpecState      specs.State
}

State wraps specs.State and adds runtime specific state.