An open and reliable container runtime
dmcgowan Merge pull request #2724 from crosbymichael/runc-lxc
Update runc to 58592df56734acf62e574865fe40b9e53e
Latest commit 483724b Oct 17, 2018
Permalink
Failed to load latest commit information.
.github Add github issue template Jan 17, 2018
api fix: typo omitted -> ommitted Sep 20, 2018
archive archive: add support for OpenBSD Oct 12, 2018
cio Don't provide IO when it's not set Sep 7, 2018
cmd Merge pull request #2688 from crosbymichael/ctrdecodespec Oct 16, 2018
containers typo: fix misspells in comments of containers/contaienrs.go Sep 25, 2018
content Fix writer deadlock in local store Oct 15, 2018
contrib Fix typos Sep 7, 2018
defaults fix words misspell Apr 23, 2018
design Remove outdated plugin design doc Jul 26, 2018
diff Set uncompressed label on diff when already exists Oct 15, 2018
docs Website no longer managed from this repo Aug 23, 2018
errdefs Licence header added Feb 19, 2018
events Fix 'forward' typos Sep 7, 2018
filters fix words misspell Apr 23, 2018
gc Update tests to use gotest.tools angel Jun 8, 2018
identifiers Licence header added Feb 19, 2018
images Merge pull request #2696 from dmcgowan/import-docker-tar-test Oct 3, 2018
labels Licence header added Feb 19, 2018
leases Update lease service errors Jul 25, 2018
log Set default log formatting to use RFC3339Nano with fixed width Jul 24, 2018
metadata Fix writer deadlock in local store Oct 15, 2018
metrics/cgroups Merge pull request #2471 from crosbymichael/fatal Jul 23, 2018
mount mount: add support for OpenBSD Oct 12, 2018
namespaces Switch from x/net/context to context Apr 24, 2018
oci Skip AdditionalGID's for LCOW oci spec Oct 3, 2018
pkg remove pkg/testutil/loopback_linux.go and use continuity/testutil/loo… Oct 2, 2018
platforms Add support to detect ARM variant on Windows Oct 10, 2018
plugin Runtime v2 Jul 17, 2018
protobuf/plugin protobuf: remove generated google/rpc files Apr 5, 2018
reference Licence header added Feb 19, 2018
releases Update v1.2.0-rc release note. Sep 18, 2018
remotes Merge pull request #2691 from fuweid/bugfix_cache_empty_label Oct 15, 2018
reports fix typo Sep 7, 2018
rootfs Switching from crypto/rand to math/rand to avoid blocking Jul 11, 2018
runtime Revendor github.com/Microsoft/hcsshim Oct 15, 2018
script/setup Use common project repo copies of travis scripts Oct 15, 2018
services Fix writer deadlock in local store Oct 15, 2018
snapshots Revendor github.com/Microsoft/hcsshim Oct 15, 2018
sys Fix teeny tiny typos Sep 5, 2018
vendor Update runc to 58592df56734acf62e574865fe40b9e53e Oct 16, 2018
version Update version to 1.2.0-rc.2 Oct 16, 2018
windows Fix compilation failures on Go 1.11 Jul 23, 2018
.appveyor.yml build: bump to Go 1.10 Feb 27, 2018
.gitignore Add capability to build manpages from markdown Jan 31, 2018
.gometalinter.json Add unconvert linter Jan 9, 2018
.mailmap Update mailmap Sep 20, 2018
.travis.yml Use common project repo copies of travis scripts Oct 15, 2018
BUILDING.md fix typo Sep 7, 2018
LICENSE Edit Containerd license info so GitHub recognizes it Apr 2, 2018
Makefile Introduce containerd-shim-runhcs-v1 on Windows Aug 22, 2018
Makefile.darwin Licence header added Feb 19, 2018
Makefile.freebsd Licence header added Feb 19, 2018
Makefile.linux Runtime v2 Jul 17, 2018
Makefile.windows Introduce containerd-shim-runhcs-v1 on Windows Aug 22, 2018
NOTICE Update readme and documentation for release Dec 16, 2015
PLUGINS.md Document plugins Jul 26, 2018
Protobuild.toml Fixes for runtimev2 and checkpoint restore Jul 20, 2018
README.md Move common repository details to project references Oct 15, 2018
RELEASES.md Prepare 1.1.0 release Apr 24, 2018
ROADMAP.md Update roadmap.md with issue labels and milestones Jan 4, 2018
RUNC.md fix RUNC.md vs vendor.conf mismatch May 11, 2018
SCOPE.md Update readme Jun 20, 2017
benchmark_test.go Tests should set up snapshot prior to any use of fs Sep 14, 2018
client.go Add a manifest filter limiting the number of matches Aug 28, 2018
client_opts.go Add platform match comparer interface Aug 27, 2018
client_test.go fix typo Sep 13, 2018
client_unix_test.go Licence header added Feb 19, 2018
client_windows_test.go Licence header added Feb 19, 2018
code-of-conduct.md Add code of conduct Apr 4, 2017
container.go Use image constructor in client Jul 31, 2018
container_checkpoint_test.go Tests should set up snapshot prior to any use of fs Sep 14, 2018
container_linux_test.go Tests should set up snapshot prior to any use of fs Sep 14, 2018
container_opts.go ctr: make kill use stop-signal by default Sep 27, 2018
container_opts_unix.go move WithXXXX to task_opts.go Sep 10, 2018
container_test.go Tests should set up snapshot prior to any use of fs Sep 14, 2018
containerd.service Update unit file for resources and task max Aug 31, 2018
containerstore.go Add containers streaming API Jul 26, 2018
content_test.go Pass in context to lease done function in client Mar 22, 2018
daemon_config_linux_test.go Tests should set up snapshot prior to any use of fs Sep 14, 2018
daemon_test.go linux: fix runtime-root propagation Mar 5, 2018
diff.go Add service plugin and support in process integration. Mar 12, 2018
events.go Add service plugin and support in process integration. Mar 12, 2018
export.go Clean up error messages Sep 17, 2018
export_test.go Update client Image to have configurable platform Jul 17, 2018
grpc.go Switch from x/net/context to context Apr 24, 2018
helpers_unix_test.go Licence header added Feb 19, 2018
helpers_windows_test.go Licence header added Feb 19, 2018
image.go Add `Labels` to client.Image. Sep 26, 2018
image_store.go Licence header added Feb 19, 2018
image_test.go Update multi-arch image tests Aug 1, 2018
import.go Unify docker and oci importer Sep 17, 2018
import_test.go Add import integration test Oct 1, 2018
install.go Add optional install path Sep 11, 2018
install_opts.go Add optional install path Sep 11, 2018
lease.go *: replace 3600 seconds with 1 hour Aug 2, 2018
namespaces.go Licence header added Feb 19, 2018
process.go fix words misspell Apr 23, 2018
services.go Add leases manager interface Jul 18, 2018
signal_map_linux.go signals: move ParseSignal to containerd package Sep 27, 2018
signal_map_unix.go signals: move ParseSignal to containerd package Sep 27, 2018
signal_map_windows.go signals: move ParseSignal to containerd package Sep 27, 2018
signals.go ctr: make kill use stop-signal by default Sep 27, 2018
snapshot_test.go Licence header added Feb 19, 2018
snapshotter_default_linux.go Licence header added Feb 19, 2018
snapshotter_default_unix.go enable native (formerly naive) snapshotter by default Apr 2, 2018
snapshotter_default_windows.go Licence header added Feb 19, 2018
task.go Always check exists on commit error Sep 14, 2018
task_opts.go move WithXXXX to task_opts.go Sep 10, 2018
task_opts_unix.go move WithXXXX to task_opts.go Sep 10, 2018
task_opts_unix_test.go move WithXXXX to task_opts.go Sep 10, 2018
vendor.conf Update runc to 58592df56734acf62e574865fe40b9e53e Oct 16, 2018

README.md

banner

GoDoc Build Status Windows Build Status FOSSA Status Go Report Card CII Best Practices

containerd is an industry-standard container runtime with an emphasis on simplicity, robustness and portability. It is available as a daemon for Linux and Windows, which can manage the complete container lifecycle of its host system: image transfer and storage, container execution and supervision, low-level storage and network attachments, etc.

containerd is designed to be embedded into a larger system, rather than being used directly by developers or end-users.

architecture

Getting Started

See our documentation on containerd.io:

See how to build containerd from source at BUILDING.

If you are interested in trying out containerd see our example at Getting Started.

Runtime Requirements

Runtime requirements for containerd are very minimal. Most interactions with the Linux and Windows container feature sets are handled via runc and/or OS-specific libraries (e.g. hcsshim for Microsoft). The current required version of runc is always listed in RUNC.md.

There are specific features used by containerd core code and snapshotters that will require a minimum kernel version on Linux. With the understood caveat of distro kernel versioning, a reasonable starting point for Linux is a minimum 4.x kernel version.

The overlay filesystem snapshotter, used by default, uses features that were finalized in the 4.x kernel series. If you choose to use btrfs, there may be more flexibility in kernel version (minimum recommended is 3.18), but will require the btrfs kernel module and btrfs tools to be installed on your Linux distribution.

To use Linux checkpoint and restore features, you will need criu installed on your system. See more details in Checkpoint and Restore.

Build requirements for developers are listed in BUILDING.

Features

Client

containerd offers a full client package to help you integrate containerd into your platform.

import (
  "github.com/containerd/containerd"
  "github.com/containerd/containerd/cio"
)


func main() {
	client, err := containerd.New("/run/containerd/containerd.sock")
	defer client.Close()
}

Namespaces

Namespaces allow multiple consumers to use the same containerd without conflicting with each other. It has the benefit of sharing content but still having separation with containers and images.

To set a namespace for requests to the API:

context = context.Background()
// create a context for docker
docker = namespaces.WithNamespace(context, "docker")

containerd, err := client.NewContainer(docker, "id")

To set a default namespace on the client:

client, err := containerd.New(address, containerd.WithDefaultNamespace("docker"))

Distribution

// pull an image
image, err := client.Pull(context, "docker.io/library/redis:latest")

// push an image
err := client.Push(context, "docker.io/library/redis:latest", image.Target())

Containers

In containerd, a container is a metadata object. Resources such as an OCI runtime specification, image, root filesystem, and other metadata can be attached to a container.

redis, err := client.NewContainer(context, "redis-master")
defer redis.Delete(context)

OCI Runtime Specification

containerd fully supports the OCI runtime specification for running containers. We have built in functions to help you generate runtime specifications based on images as well as custom parameters.

You can specify options when creating a container about how to modify the specification.

redis, err := client.NewContainer(context, "redis-master", containerd.WithNewSpec(oci.WithImageConfig(image)))

Root Filesystems

containerd allows you to use overlay or snapshot filesystems with your containers. It comes with builtin support for overlayfs and btrfs.

// pull an image and unpack it into the configured snapshotter
image, err := client.Pull(context, "docker.io/library/redis:latest", containerd.WithPullUnpack)

// allocate a new RW root filesystem for a container based on the image
redis, err := client.NewContainer(context, "redis-master",
	containerd.WithNewSnapshot("redis-rootfs", image),
	containerd.WithNewSpec(oci.WithImageConfig(image)),
)

// use a readonly filesystem with multiple containers
for i := 0; i < 10; i++ {
	id := fmt.Sprintf("id-%s", i)
	container, err := client.NewContainer(ctx, id,
		containerd.WithNewSnapshotView(id, image),
		containerd.WithNewSpec(oci.WithImageConfig(image)),
	)
}

Tasks

Taking a container object and turning it into a runnable process on a system is done by creating a new Task from the container. A task represents the runnable object within containerd.

// create a new task
task, err := redis.NewTask(context, cio.Stdio)
defer task.Delete(context)

// the task is now running and has a pid that can be use to setup networking
// or other runtime settings outside of containerd
pid := task.Pid()

// start the redis-server process inside the container
err := task.Start(context)

// wait for the task to exit and get the exit status
status, err := task.Wait(context)

Checkpoint and Restore

If you have criu installed on your machine you can checkpoint and restore containers and their tasks. This allow you to clone and/or live migrate containers to other machines.

// checkpoint the task then push it to a registry
checkpoint, err := task.Checkpoint(context)

err := client.Push(context, "myregistry/checkpoints/redis:master", checkpoint)

// on a new machine pull the checkpoint and restore the redis container
image, err := client.Pull(context, "myregistry/checkpoints/redis:master")

checkpoint := image.Target()

redis, err = client.NewContainer(context, "redis-master", containerd.WithCheckpoint(checkpoint, "redis-rootfs"))
defer container.Delete(context)

task, err = redis.NewTask(context, cio.Stdio, containerd.WithTaskCheckpoint(checkpoint))
defer task.Delete(context)

err := task.Start(context)

Snapshot Plugins

In addition to the built-in Snapshot plugins in containerd, additional external plugins can be configured using GRPC. An external plugin is made available using the configured name and appears as a plugin alongside the built-in ones.

To add an external snapshot plugin, add the plugin to containerd's config file (by default at /etc/containerd/config.toml). The string following proxy_plugin. will be used as the name of the snapshotter and the address should refer to a socket with a GRPC listener serving containerd's Snapshot GRPC API. Remember to restart containerd for any configuration changes to take effect.

[proxy_plugins]
  [proxy_plugins.customsnapshot]
    type = "snapshot"
    address =  "/var/run/mysnapshotter.sock"

See PLUGINS.md for how to create plugins

Releases and API Stability

Please see RELEASES.md for details on versioning and stability of containerd components.

Development reports.

Weekly summary on the progress and what is being worked on. https://github.com/containerd/containerd/tree/master/reports

Communication

For async communication and long running discussions please use issues and pull requests on the github repo. This will be the best place to discuss design and implementation.

For sync communication we have a community slack with a #containerd channel that everyone is welcome to join and chat about development.

Slack: https://join.slack.com/t/dockercommunity/shared_invite/enQtNDM4NjAwNDMyOTUwLWZlMDZmYWRjZjk4Zjc5ZGQ5NWZkOWI1Yjk2NGE3ZWVlYjYxM2VhYjczOWIyZDFhZTE3NTUwZWQzMjhmNGYyZTg

Reporting security issues

If you are reporting a security issue, please reach out discreetly at security@containerd.io.

Licenses

The containerd codebase is released under the Apache 2.0 license. The README.md file, and files in the "docs" folder are licensed under the Creative Commons Attribution 4.0 International License. You may obtain a copy of the license, titled CC-BY-4.0, at http://creativecommons.org/licenses/by/4.0/.

Project details

containerd is the primary open source project within the broader containerd GitHub repository. However, all projects within the repo have common maintainership, governance, and contributing guidelines which are stored in a project repository commonly for all containerd projects.

Please find all these core project documents, including the:

information in our containerd/project repository.