github.com/containerd/containerd@v22.0.0-20200918172823-438c87b8e050+incompatible/README.md (about)

     1  ![containerd banner](https://raw.githubusercontent.com/cncf/artwork/master/projects/containerd/horizontal/color/containerd-horizontal-color.png)
     2  
     3  [![GoDoc](https://godoc.org/github.com/containerd/containerd?status.svg)](https://godoc.org/github.com/containerd/containerd)
     4  [![Build Status](https://github.com/containerd/containerd/workflows/CI/badge.svg)](https://github.com/containerd/containerd/actions?query=workflow%3ACI)
     5  [![Windows Build Status](https://ci.appveyor.com/api/projects/status/github/containerd/containerd?branch=master&svg=true)](https://ci.appveyor.com/project/mlaventure/containerd-3g73f?branch=master)
     6  [![Nightlies](https://github.com/containerd/containerd/workflows/Nightly/badge.svg)](https://github.com/containerd/containerd/actions?query=workflow%3ANightly)
     7  [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fcontainerd%2Fcontainerd.svg?type=shield)](https://app.fossa.io/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fcontainerd%2Fcontainerd?ref=badge_shield)
     8  [![Go Report Card](https://goreportcard.com/badge/github.com/containerd/containerd)](https://goreportcard.com/report/github.com/containerd/containerd)
     9  [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/1271/badge)](https://bestpractices.coreinfrastructure.org/projects/1271)
    10  
    11  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.
    12  
    13  containerd is a member of CNCF with ['graduated'](https://landscape.cncf.io/selected=containerd) status.
    14  
    15  containerd is designed to be embedded into a larger system, rather than being used directly by developers or end-users.
    16  
    17  ![architecture](design/architecture.png)
    18  
    19  ## Now Recruiting
    20  
    21  We are a large inclusive OSS project that is welcoming help of any kind shape or form:
    22  * Documentation help is needed to make the product easier to consume and extend.
    23  * We need OSS community outreach / organizing help to get the word out; manage
    24  and create messaging and educational content; and to help with social media, community forums/groups, and google groups.
    25  * We are actively inviting new [security advisors](https://github.com/containerd/project/blob/master/GOVERNANCE.md#security-advisors) to join the team.
    26  * New sub-projects are being created, core and non-core that could use additional development help.
    27  * Each of the [containerd projects](https://github.com/containerd) has a list of issues currently being worked on or that need help resolving.
    28    - If the issue has not already been assigned to someone, or has not made recent progress and you are interested, please inquire.
    29    - 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)
    30  
    31  ## Getting Started
    32  
    33  See our documentation on [containerd.io](https://containerd.io):
    34  * [for ops and admins](docs/ops.md)
    35  * [namespaces](docs/namespaces.md)
    36  * [client options](docs/client-opts.md)
    37  
    38  See how to build containerd from source at [BUILDING](BUILDING.md).
    39  
    40  If you are interested in trying out containerd see our example at [Getting Started](docs/getting-started.md).
    41  
    42  ## Nightly builds
    43  
    44  There are nightly builds available for download [here](https://github.com/containerd/containerd/actions?query=workflow%3ANightly).
    45  Binaries are generated from `master` branch every night for `Linux` and `Windows`.
    46  
    47  Please be aware: nightly builds might have critical bugs, it's not recommended for use in prodution and no support provided.
    48  
    49  ## Runtime Requirements
    50  
    51  Runtime requirements for containerd are very minimal. Most interactions with
    52  the Linux and Windows container feature sets are handled via [runc](https://github.com/opencontainers/runc) and/or
    53  OS-specific libraries (e.g. [hcsshim](https://github.com/Microsoft/hcsshim) for Microsoft). The current required version of `runc` is always listed in [RUNC.md](/RUNC.md).
    54  
    55  There are specific features
    56  used by containerd core code and snapshotters that will require a minimum kernel
    57  version on Linux. With the understood caveat of distro kernel versioning, a
    58  reasonable starting point for Linux is a minimum 4.x kernel version.
    59  
    60  The overlay filesystem snapshotter, used by default, uses features that were
    61  finalized in the 4.x kernel series. If you choose to use btrfs, there may
    62  be more flexibility in kernel version (minimum recommended is 3.18), but will
    63  require the btrfs kernel module and btrfs tools to be installed on your Linux
    64  distribution.
    65  
    66  To use Linux checkpoint and restore features, you will need `criu` installed on
    67  your system. See more details in [Checkpoint and Restore](#checkpoint-and-restore).
    68  
    69  Build requirements for developers are listed in [BUILDING](BUILDING.md).
    70  
    71  ## Features
    72  
    73  ### Client
    74  
    75  containerd offers a full client package to help you integrate containerd into your platform.
    76  
    77  ```go
    78  
    79  import (
    80    "github.com/containerd/containerd"
    81    "github.com/containerd/containerd/cio"
    82  )
    83  
    84  
    85  func main() {
    86  	client, err := containerd.New("/run/containerd/containerd.sock")
    87  	defer client.Close()
    88  }
    89  
    90  ```
    91  
    92  ### Namespaces
    93  
    94  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.
    95  
    96  To set a namespace for requests to the API:
    97  
    98  ```go
    99  context = context.Background()
   100  // create a context for docker
   101  docker = namespaces.WithNamespace(context, "docker")
   102  
   103  containerd, err := client.NewContainer(docker, "id")
   104  ```
   105  
   106  To set a default namespace on the client:
   107  
   108  ```go
   109  client, err := containerd.New(address, containerd.WithDefaultNamespace("docker"))
   110  ```
   111  
   112  ### Distribution
   113  
   114  ```go
   115  // pull an image
   116  image, err := client.Pull(context, "docker.io/library/redis:latest")
   117  
   118  // push an image
   119  err := client.Push(context, "docker.io/library/redis:latest", image.Target())
   120  ```
   121  
   122  ### Containers
   123  
   124  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.
   125  
   126  ```go
   127  redis, err := client.NewContainer(context, "redis-master")
   128  defer redis.Delete(context)
   129  ```
   130  
   131  ### OCI Runtime Specification
   132  
   133  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.
   134  
   135  You can specify options when creating a container about how to modify the specification.
   136  
   137  ```go
   138  redis, err := client.NewContainer(context, "redis-master", containerd.WithNewSpec(oci.WithImageConfig(image)))
   139  ```
   140  
   141  ### Root Filesystems
   142  
   143  containerd allows you to use overlay or snapshot filesystems with your containers.  It comes with builtin support for overlayfs and btrfs.
   144  
   145  ```go
   146  // pull an image and unpack it into the configured snapshotter
   147  image, err := client.Pull(context, "docker.io/library/redis:latest", containerd.WithPullUnpack)
   148  
   149  // allocate a new RW root filesystem for a container based on the image
   150  redis, err := client.NewContainer(context, "redis-master",
   151  	containerd.WithNewSnapshot("redis-rootfs", image),
   152  	containerd.WithNewSpec(oci.WithImageConfig(image)),
   153  )
   154  
   155  // use a readonly filesystem with multiple containers
   156  for i := 0; i < 10; i++ {
   157  	id := fmt.Sprintf("id-%s", i)
   158  	container, err := client.NewContainer(ctx, id,
   159  		containerd.WithNewSnapshotView(id, image),
   160  		containerd.WithNewSpec(oci.WithImageConfig(image)),
   161  	)
   162  }
   163  ```
   164  
   165  ### Tasks
   166  
   167  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.
   168  
   169  ```go
   170  // create a new task
   171  task, err := redis.NewTask(context, cio.NewCreator(cio.WithStdio))
   172  defer task.Delete(context)
   173  
   174  // the task is now running and has a pid that can be use to setup networking
   175  // or other runtime settings outside of containerd
   176  pid := task.Pid()
   177  
   178  // start the redis-server process inside the container
   179  err := task.Start(context)
   180  
   181  // wait for the task to exit and get the exit status
   182  status, err := task.Wait(context)
   183  ```
   184  
   185  ### Checkpoint and Restore
   186  
   187  If you have [criu](https://criu.org/Main_Page) 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.
   188  
   189  ```go
   190  // checkpoint the task then push it to a registry
   191  checkpoint, err := task.Checkpoint(context)
   192  
   193  err := client.Push(context, "myregistry/checkpoints/redis:master", checkpoint)
   194  
   195  // on a new machine pull the checkpoint and restore the redis container
   196  checkpoint, err := client.Pull(context, "myregistry/checkpoints/redis:master")
   197  
   198  redis, err = client.NewContainer(context, "redis-master", containerd.WithNewSnapshot("redis-rootfs", checkpoint))
   199  defer container.Delete(context)
   200  
   201  task, err = redis.NewTask(context, cio.NewCreator(cio.WithStdio), containerd.WithTaskCheckpoint(checkpoint))
   202  defer task.Delete(context)
   203  
   204  err := task.Start(context)
   205  ```
   206  
   207  ### Snapshot Plugins
   208  
   209  In addition to the built-in Snapshot plugins in containerd, additional external
   210  plugins can be configured using GRPC. An external plugin is made available using
   211  the configured name and appears as a plugin alongside the built-in ones.
   212  
   213  To add an external snapshot plugin, add the plugin to containerd's config file
   214  (by default at `/etc/containerd/config.toml`). The string following
   215  `proxy_plugin.` will be used as the name of the snapshotter and the address
   216  should refer to a socket with a GRPC listener serving containerd's Snapshot
   217  GRPC API. Remember to restart containerd for any configuration changes to take
   218  effect.
   219  
   220  ```
   221  [proxy_plugins]
   222    [proxy_plugins.customsnapshot]
   223      type = "snapshot"
   224      address =  "/var/run/mysnapshotter.sock"
   225  ```
   226  
   227  See [PLUGINS.md](PLUGINS.md) for how to create plugins
   228  
   229  ### Releases and API Stability
   230  
   231  Please see [RELEASES.md](RELEASES.md) for details on versioning and stability
   232  of containerd components.
   233  
   234  Downloadable 64-bit Intel/AMD binaries of all official releases are available on
   235  our [releases page](https://github.com/containerd/containerd/releases), as well as
   236  auto-published to the [cri-containerd-release storage bucket](https://console.cloud.google.com/storage/browser/cri-containerd-release?pli=1).
   237  
   238  For other architectures and distribution support, you will find that many
   239  Linux distributions package their own containerd and provide it across several
   240  architectures, such as [Canonical's Ubuntu packaging](https://launchpad.net/ubuntu/bionic/+package/containerd).
   241  
   242  #### Enabling command auto-completion
   243  
   244  Starting with containerd 1.4, the urfave client feature for auto-creation of bash and zsh
   245  autocompletion data is enabled. To use the autocomplete feature in a bash shell for example, source
   246  the autocomplete/ctr file in your `.bashrc`, or manually like:
   247  
   248  ```
   249  $ source ./contrib/autocomplete/ctr
   250  ```
   251  
   252  #### Distribution of `ctr` autocomplete for bash and zsh
   253  
   254  For bash, copy the `contrib/autocomplete/ctr` script into
   255  `/etc/bash_completion.d/` and rename it to `ctr`. The `zsh_autocomplete`
   256  file is also available and can be used similarly for zsh users.
   257  
   258  Provide documentation to users to `source` this file into their shell if
   259  you don't place the autocomplete file in a location where it is automatically
   260  loaded for the user's shell environment.
   261  
   262  ### Communication
   263  
   264  For async communication and long running discussions please use issues and pull requests on the github repo.
   265  This will be the best place to discuss design and implementation.
   266  
   267  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)
   268  
   269  ### Security audit
   270  
   271  A third party security audit was performed by Cure53 in 4Q2018; the [full report](docs/SECURITY_AUDIT.pdf) is available in our docs/ directory.
   272  
   273  ### Reporting security issues
   274  
   275  __If you are reporting a security issue, please reach out discreetly at security@containerd.io__.
   276  
   277  ## Licenses
   278  
   279  The containerd codebase is released under the [Apache 2.0 license](LICENSE).
   280  The README.md file, and files in the "docs" folder are licensed under the
   281  Creative Commons Attribution 4.0 International License. You may obtain a
   282  copy of the license, titled CC-BY-4.0, at http://creativecommons.org/licenses/by/4.0/.
   283  
   284  ## Project details
   285  
   286  **containerd** is the primary open source project within the broader containerd GitHub repository.
   287  However, all projects within the repo have common maintainership, governance, and contributing
   288  guidelines which are stored in a `project` repository commonly for all containerd projects.
   289  
   290  Please find all these core project documents, including the:
   291   * [Project governance](https://github.com/containerd/project/blob/master/GOVERNANCE.md),
   292   * [Maintainers](https://github.com/containerd/project/blob/master/MAINTAINERS),
   293   * and [Contributing guidelines](https://github.com/containerd/project/blob/master/CONTRIBUTING.md)
   294  
   295  information in our [`containerd/project`](https://github.com/containerd/project) repository.
   296  
   297  ## Adoption
   298  
   299  Interested to see who is using containerd? Are you using containerd in a project?
   300  Please add yourself via pull request to our [ADOPTERS.md](./ADOPTERS.md) file.