Ecosyste.ms: Awesome

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

https://github.com/containerd/containerd

An open and reliable container runtime
https://github.com/containerd/containerd

cncf containerd containers cri docker hacktoberfest kubernetes oci

Last synced: about 2 months ago
JSON representation

An open and reliable container runtime

Lists

README 

        
![containerd banner light mode](https://raw.githubusercontent.com/cncf/artwork/master/projects/containerd/horizontal/color/containerd-horizontal-color.png#gh-light-mode-only)

![containerd banner dark mode](https://raw.githubusercontent.com/cncf/artwork/master/projects/containerd/horizontal/white/containerd-horizontal-white.png#gh-dark-mode-only)



[![PkgGoDev](https://pkg.go.dev/badge/github.com/containerd/containerd/v2)](https://pkg.go.dev/github.com/containerd/containerd/v2)

[![Build Status](https://github.com/containerd/containerd/actions/workflows/ci.yml/badge.svg?event=merge_group)](https://github.com/containerd/containerd/actions?query=workflow%3ACI+event%3Amerge_group)

[![Nightlies](https://github.com/containerd/containerd/workflows/Nightly/badge.svg)](https://github.com/containerd/containerd/actions?query=workflow%3ANightly)

[![Go Report Card](https://goreportcard.com/badge/github.com/containerd/containerd/v2)](https://goreportcard.com/report/github.com/containerd/containerd/v2)

[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/1271/badge)](https://bestpractices.coreinfrastructure.org/projects/1271)

[![Check Links](https://github.com/containerd/containerd/actions/workflows/links.yml/badge.svg)](https://github.com/containerd/containerd/actions/workflows/links.yml)



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 a member of CNCF with ['graduated'](https://landscape.cncf.io/?selected=containerd) status.



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



![architecture](docs/historical/design/architecture.png)



## Announcements



### Hello Kubernetes v1.24!

The containerd project would like to announce containerd [v1.6.4](https://github.com/containerd/containerd/releases/tag/v1.6.4). While other prior releases are supported, this latest release and the containerd [v1.5.11](https://github.com/containerd/containerd/releases/tag/v1.5.11) release are recommended for Kubernetes v1.24.



We felt it important to announce this, particularly in view of [the dockershim removal from this release of Kubernetes](https://kubernetes.io/blog/2022/05/03/dockershim-historical-context/).



It should be noted here that moving to CRI integrations has been in the plan for many years.  `containerd` began as part of `Docker` and was donated to `CNCF`. `containerd` remains in use today by Docker/moby/buildkit etc., and has many other [adopters](https://github.com/containerd/containerd/blob/main/ADOPTERS.md). `containerd` has a namespace that isolates use of `containerd` from various clients/adopters. The Kubernetes namespace is appropriately named `k8s.io`. The CRI API and `containerd` CRI plugin project has, from the start, been an effort to reduce the impact surface for Kubernetes container runtime integration. If you can't tell, we are excited to see this come to fruition.



If you have any concerns or questions, we will be here to answer them in [issues, discussions, and/or on slack](#communication). Below you will find information/detail about our [CRI Integration](#cri) implementation.



For containerd users already on v1.6.0-v1.6.3, there are known issues addressed by [v1.6.4](https://github.com/containerd/containerd/releases/tag/v1.6.4). The issues are primarily related to [CNI setup](https://github.com/kubernetes/website/blob/dev-1.24/content/en/docs/tasks/administer-cluster/migrating-from-dockershim/troubleshooting-cni-plugin-related-errors.md)



### Now Recruiting



We are a large inclusive OSS project that is welcoming help of any kind shape or form:

* Documentation help is needed to make the product easier to consume and extend.

* We need OSS community outreach/organizing help to get the word out; manage

and create messaging and educational content; and help with social media, community forums/groups, and google groups.

* We are actively inviting new [security advisors](https://github.com/containerd/project/blob/main/GOVERNANCE.md#security-advisors) to join the team.

* New subprojects are being created, core and non-core that could use additional development help.

* Each of the [containerd projects](https://github.com/containerd) has a list of issues currently being worked on or that need help resolving.

  - If the issue has not already been assigned to someone or has not made recent progress, and you are interested, please inquire.

  - If you are interested in starting with a smaller/beginner-level issue, look for issues with an `exp/beginner` tag, for example [containerd/containerd beginner issues.](https://github.com/containerd/containerd/issues?q=is%3Aissue+is%3Aopen+label%3Aexp%2Fbeginner)



## Getting Started



See our documentation on [containerd.io](https://containerd.io):

* [for ops and admins](docs/ops.md)

* [namespaces](docs/namespaces.md)

* [client options](docs/client-opts.md)



To get started contributing to containerd, see [CONTRIBUTING](CONTRIBUTING.md).



If you are interested in trying out containerd see our example at [Getting Started](docs/getting-started.md).



## Nightly builds



There are nightly builds available for download [here](https://github.com/containerd/containerd/actions?query=workflow%3ANightly).

Binaries are generated from `main` branch every night for `Linux` and `Windows`.



Please be aware: nightly builds might have critical bugs, it's not recommended for use in production and no support provided.



## Kubernetes (k8s) CI Dashboard Group



The [k8s CI dashboard group for containerd](https://testgrid.k8s.io/containerd) contains test results regarding

the health of kubernetes when run against main and a number of containerd release branches.



- [containerd-periodics](https://testgrid.k8s.io/containerd-periodic)



## Runtime Requirements



Runtime requirements for containerd are very minimal. Most interactions with

the Linux and Windows container feature sets are handled via [runc](https://github.com/opencontainers/runc) and/or

OS-specific libraries (e.g. [hcsshim](https://github.com/Microsoft/hcsshim) for Microsoft).

The current required version of `runc` is described in [RUNC.md](docs/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](#checkpoint-and-restore).



Build requirements for developers are listed in [BUILDING](BUILDING.md).



## Supported Registries



Any registry which is compliant with the [OCI Distribution Specification](https://github.com/opencontainers/distribution-spec)

is supported by containerd.



For configuring registries, see [registry host configuration documentation](docs/hosts.md)



## Features



### Client



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



```go



import (

  "context"



  containerd "github.com/containerd/containerd/v2/client"

  "github.com/containerd/containerd/v2/pkg/cio"

  "github.com/containerd/containerd/v2/pkg/namespaces"

)



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 while maintaining separation with containers and images.



To set a namespace for requests to the API:



```go

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:



```go

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

```



### Distribution



```go

// 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.



```go

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.



```go

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 built-in support for overlayfs and btrfs.



```go

// 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.



```go

// create a new task

task, err := redis.NewTask(context, cio.NewCreator(cio.WithStdio))

defer task.Delete(context)



// the task is now running and has a pid that can be used 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](https://criu.org/Main_Page) installed on your machine you can checkpoint and restore containers and their tasks.  This allows you to clone and/or live migrate containers to other machines.



```go

// 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

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



redis, err = client.NewContainer(context, "redis-master", containerd.WithNewSnapshot("redis-rootfs", checkpoint))

defer container.Delete(context)



task, err = redis.NewTask(context, cio.NewCreator(cio.WithStdio), 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](/docs/PLUGINS.md) for how to create plugins



### Releases and API Stability



Please see [RELEASES.md](RELEASES.md) for details on versioning and stability

of containerd components.



Downloadable 64-bit Intel/AMD binaries of all official releases are available on

our [releases page](https://github.com/containerd/containerd/releases).



For other architectures and distribution support, you will find that many

Linux distributions package their own containerd and provide it across several

architectures, such as [Canonical's Ubuntu packaging](https://launchpad.net/ubuntu/bionic/+package/containerd).



#### Enabling command auto-completion



Starting with containerd 1.4, the urfave client feature for auto-creation of bash and zsh

autocompletion data is enabled. To use the autocomplete feature in a bash shell for example, source

the autocomplete/ctr file in your `.bashrc`, or manually like:



```

$ source ./contrib/autocomplete/ctr

```



#### Distribution of `ctr` autocomplete for bash and zsh



For bash, copy the `contrib/autocomplete/ctr` script into

`/etc/bash_completion.d/` and rename it to `ctr`. The `zsh_autocomplete`

file is also available and can be used similarly for zsh users.



Provide documentation to users to `source` this file into their shell if

you don't place the autocomplete file in a location where it is automatically

loaded for the user's shell environment.



### CRI



`cri` is a [containerd](https://containerd.io/) plugin implementation of the Kubernetes [container runtime interface (CRI)](https://github.com/kubernetes/cri-api/blob/master/pkg/apis/runtime/v1/api.proto). With it, you are able to use containerd as the container runtime for a Kubernetes cluster.



![cri](./docs/cri/cri.png)



#### CRI Status



`cri` is a native plugin of containerd. Since containerd 1.1, the cri plugin is built into the release binaries and enabled by default.



> **Note:** As of containerd 1.5, the `cri` plugin is merged into the containerd/containerd repo. For example, the source code previously stored under [`containerd/cri/pkg`](https://github.com/containerd/cri/tree/release/1.4/pkg)

was moved to [`containerd/containerd/pkg/cri` package](https://github.com/containerd/containerd/tree/main/pkg/cri).



The `cri` plugin has reached GA status, representing that it is:

* Feature complete

* Works with Kubernetes 1.10 and above

* Passes all [CRI validation tests](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-node/cri-validation.md).

* Passes all [node e2e tests](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-node/e2e-node-tests.md).

* Passes all [e2e tests](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-testing/e2e-tests.md).



See results on the containerd k8s [test dashboard](https://testgrid.k8s.io/containerd)



#### Validating Your `cri` Setup

A Kubernetes incubator project, [cri-tools](https://github.com/kubernetes-sigs/cri-tools), includes programs for exercising CRI implementations. More importantly, cri-tools includes the program `critest` which is used for running [CRI Validation Testing](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-node/cri-validation.md).



#### CRI Guides

* [Installing with Ansible and Kubeadm](contrib/ansible/README.md)

* [For Non-Ansible Users, Preforming a Custom Installation Using the Release Tarball and Kubeadm](docs/getting-started.md)

* [CRI Plugin Testing Guide](./docs/cri/testing.md)

* [Debugging Pods, Containers, and Images with `crictl`](./docs/cri/crictl.md)

* [Configuring `cri` Plugins](./docs/cri/config.md)

* [Configuring containerd](https://github.com/containerd/containerd/blob/main/docs/man/containerd-config.8.md)



### 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 catch us in the `#containerd` and `#containerd-dev` Slack channels on Cloud Native Computing Foundation's (CNCF) Slack - `cloud-native.slack.com`. Everyone is welcome to join and chat. [Get Invite to CNCF Slack.](https://slack.cncf.io)



### Security audit



Security audits for the containerd project are hosted on our website. Please see the [security page at containerd.io](https://containerd.io/security/) for more information.



### Reporting security issues



Please follow the instructions at [containerd/project](https://github.com/containerd/project/blob/main/SECURITY.md#reporting-a-vulnerability)



## Licenses



The containerd codebase is released under the [Apache 2.0 license](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 organization.

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:

 * [Project governance](https://github.com/containerd/project/blob/main/GOVERNANCE.md),

 * [Maintainers](https://github.com/containerd/project/blob/main/MAINTAINERS),

 * and [Contributing guidelines](https://github.com/containerd/project/blob/main/CONTRIBUTING.md)



information in our [`containerd/project`](https://github.com/containerd/project) repository.



## Adoption



Interested to see who is using containerd? Are you using containerd in a project?

Please add yourself via pull request to our [ADOPTERS.md](./ADOPTERS.md) file.