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