embedshim

README

embedshim

The embedshim is the kind of task runtime implementation, which can be used as plugin in containerd.

With current shim design, it is used to manage the lifecycle of container process and allow to be reconnected after containerd restart. The one of the key design elements of a small shim is to be a container process monitoring, at least it is important to containerd created by runC-like runtime.

Without pidfd and ebpf trace point feature, it is unlikely to receive exit notification in time and receive exit code correctly as non-parents after shim dies. And in kubernetes infra, even if the containers in pod can share one shim, the VmRSS of shim(Go Runtime) is still about 8MB.

So, this plugin aims to provide task runtime implementation with pidfd and eBPF sched_process_exit tracepoint to manage deamonless container with low overhead.

Build/Install

The embedshim needs to compile bpf with clang/llvm. So install clang/llvm as first.

$ echo "deb http://apt.llvm.org/focal/ llvm-toolchain-focal main" | sudo tee -a /etc/apt/sources.lis
$ wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -
$ sudo apt-get update -y
$ sudo apt-get install -y g++ libelf-dev clang lld llvm

And then pull the repo and build it.

$ git clone https://github.com/fuweid/embedshim.git
$ cd embedshim
$ git submodule update --init --recursive
$ make
$ sudo make install

The binary is named by embedshim-containerd which has full functionality in linux. You can just replace your local containerd with it.

$ sudo install bin/embedshim-containerd $(command -v containerd)
$ sudo systemctl restart containerd

And check plugin with ctr

$ ctr plugin ls | grep embed
io.containerd.runtime.v1        embed                    linux/amd64    ok

Status

The embedshim supports to run container in headless or with input. But it still works in progress, do not use in production.

• Support Pause/Resume
• Task Event(Create/Start/Exit/Delete/OOM) support

Requirements

• raw tracepoint bpf >= kernel v4.18
• CO-RE BTF vmlinux support >= kernel v5.4
• pidfd polling >= kernel v5.3

License

• The user space components are licensed under the Apache License, Version 2.0.
• The BPF code are under the General Public License, Version 2.0.

Documentation

Index

• func New(ic *plugin.InitContext) (interface{}, error)
• func NewPlatform() (stdio.Platform, error)
• type CheckpointConfig
• type Config
• type Process
• type TaskManager
  • func (manager *TaskManager) Add(ctx context.Context, task runtime.Task) error
  • func (manager *TaskManager) Create(ctx context.Context, id string, opts runtime.CreateOpts) (_ runtime.Task, retErr error)
  • func (manager *TaskManager) Delete(ctx context.Context, id string)
  • func (manager *TaskManager) Get(ctx context.Context, id string) (runtime.Task, error)
  • func (*TaskManager) ID() string
  • func (manager *TaskManager) Tasks(ctx context.Context, all bool) ([]runtime.Task, error)

Functions

func New

func New(ic *plugin.InitContext) (interface{}, error)

func NewPlatform

func NewPlatform() (stdio.Platform, error)

NewPlatform returns a linux platform for use with I/O operations

Types

type CheckpointConfig

type CheckpointConfig struct {
	WorkDir                  string
	Path                     string
	Exit                     bool
	AllowOpenTCP             bool
	AllowExternalUnixSockets bool
	AllowTerminal            bool
	FileLocks                bool
	EmptyNamespaces          []string
}

CheckpointConfig holds task checkpoint configuration

type Config

type Config struct{}

type Process

type Process interface {
	// ID returns the id for the process
	ID() string
	// Pid returns the pid for the process
	Pid() int
	// ExitStatus returns the exit status
	ExitStatus() int
	// ExitedAt is the time the process exited
	ExitedAt() time.Time
	// Stdin returns the process STDIN
	Stdin() io.Closer
	// Stdio returns io information for the container
	Stdio() stdio.Stdio
	// Status returns the process status
	Status(context.Context) (string, error)
	// Wait blocks until the process has exited
	Wait()
	// Resize resizes the process console
	Resize(ws console.WinSize) error
	// Start execution of the process
	Start(context.Context) error
	// Delete deletes the process and its resourcess
	Delete(context.Context) error
	// Kill kills the process
	Kill(context.Context, uint32, bool) error
	// SetExited sets the exit status for the process
	SetExited(status int)
}

Process on a system

type TaskManager

type TaskManager struct {
	// contains filtered or unexported fields
}

func (*TaskManager) Add

func (manager *TaskManager) Add(ctx context.Context, task runtime.Task) error

func (*TaskManager) Create

func (manager *TaskManager) Create(ctx context.Context, id string, opts runtime.CreateOpts) (_ runtime.Task, retErr error)

func (*TaskManager) Delete

func (manager *TaskManager) Delete(ctx context.Context, id string)

func (*TaskManager) Get

func (manager *TaskManager) Get(ctx context.Context, id string) (runtime.Task, error)

func (*TaskManager) ID

func (*TaskManager) ID() string

func (*TaskManager) Tasks

func (manager *TaskManager) Tasks(ctx context.Context, all bool) ([]runtime.Task, error)