.nh
.TH /etc/containerd/config.toml 5 04/05/2022
.SH NAME
containerd-config.toml \- configuration file for containerd

.SH SYNOPSIS
The \fBconfig.toml\fP file is a configuration file for the containerd daemon. The
file must be placed at \fB/etc/containerd/config.toml\fP or specified with the
\fB--config\fP option of \fBcontainerd\fP to be used by the daemon. If the file
does not exist at the appropriate location or is not provided via the
\fB--config\fP option containerd uses its default configuration settings, which
can be displayed with the \fBcontainerd config(1)\fP command.

.SH DESCRIPTION
The TOML file used to configure the containerd daemon settings has a short
list of global settings followed by a series of sections for specific areas
of daemon configuration. There is also a section for \fBplugins\fP that allows
each containerd plugin to have an area for plugin-specific configuration and
settings.

.SH FORMAT
.TP
\fBversion\fP
The version field in the config file specifies the config’s version. If no
version number is specified inside the config file then it is assumed to be a
version 1 config and parsed as such. Version 4 is the latest config version.
Older configs are automatically migrated on startup.

.TP
\fBroot\fP
The root directory for containerd metadata. (Default: "/var/lib/containerd")

.TP
\fBstate\fP
The state directory for containerd (Default: "/run/containerd")

.TP
\fBplugin_dir\fP
The directory for dynamic plugins to be stored

.TP
\fB[grpc]\fP \fI(deprecated in version 4)\fP
Section for gRPC socket listener settings. In version 4, use the server
plugins \fBio.containerd.server.v1.grpc\fP and \fBio.containerd.server.v1.grpc-tcp\fP
instead. Existing configs are migrated automatically. Contains the following
properties:

.IP \(bu 2
\fBaddress\fP (Default: "/run/containerd/containerd.sock")
.IP \(bu 2
\fBtcp_address\fP
.IP \(bu 2
\fBtcp_tls_cert\fP
.IP \(bu 2
\fBtcp_tls_key\fP
.IP \(bu 2
\fBuid\fP (Default: 0)
.IP \(bu 2
\fBgid\fP (Default: 0)
.IP \(bu 2
\fBmax_recv_message_size\fP
.IP \(bu 2
\fBmax_send_message_size\fP

.TP
\fB[ttrpc]\fP \fI(deprecated in version 4)\fP
Section for TTRPC settings. In version 4, use the server plugin
\fBio.containerd.server.v1.ttrpc\fP instead. In prior versions, when the TTRPC
address was not explicitly set it was derived from the GRPC address
(grpcAddress + ".ttrpc") and inherited GRPC’s UID/GID. In version 4, each
server plugin is independently configured; the TTRPC plugin uses its own
defaults when its configuration block is omitted. Contains properties:

.IP \(bu 2
\fBaddress\fP (Default: "")
.IP \(bu 2
\fBuid\fP (Default: 0)
.IP \(bu 2
\fBgid\fP (Default: 0)

.TP
\fB[debug]\fP \fI(deprecated in version 4)\fP
Section to enable and configure a debug socket listener. In version 4, use the
server plugin \fBio.containerd.server.v1.debug\fP instead. Contains properties:

.IP \(bu 2
\fBaddress\fP (Default: "/run/containerd/debug.sock")
.IP \(bu 2
\fBuid\fP (Default: 0)
.IP \(bu 2
\fBgid\fP (Default: 0)
.IP \(bu 2
\fBlevel\fP (Default: "info") sets the debug log level. Supported levels are:
"trace", "debug", "info", "warn", "error", "fatal", "panic"
.IP \(bu 2
\fBformat\fP (Default: "text") sets log format. Supported formats are "text" and "json"

.TP
\fB[metrics]\fP \fI(deprecated in version 4)\fP
Section to enable and configure a metrics listener. In version 4, use the
server plugin \fBio.containerd.server.v1.metrics\fP instead. Contains properties:

.IP \(bu 2
\fBaddress\fP (Default: "") Metrics endpoint does not listen by default
.IP \(bu 2
\fBgrpc_histogram\fP (Default: false) Turn on or off gRPC histogram metrics

.TP
\fBdisabled_plugins\fP
Disabled plugins are IDs of plugins to disable. Disabled plugins won't be
initialized and started.

.TP
\fBrequired_plugins\fP
Required plugins are IDs of required plugins. Containerd exits if any
required plugin doesn't exist or fails to be initialized or started.

.TP
\fB[plugins]\fP
The plugins section contains configuration options exposed from installed plugins.
The following plugins are enabled by default and their settings are shown below.
Plugins that are not enabled by default will provide their own configuration values
documentation.

.IP \(bu 2
\fB[plugins."io.containerd.server.v1.grpc"]\fP configures the main gRPC server listener (version 4):
.RS
.IP \(bu 2
\fBaddress\fP (Default: "/run/containerd/containerd.sock")
.IP \(bu 2
\fBuid\fP (Default: effective UID)
.IP \(bu 2
\fBgid\fP (Default: effective GID)
.IP \(bu 2
\fBmax_recv_message_size\fP (Default: 16777216)
.IP \(bu 2
\fBmax_send_message_size\fP (Default: 16777216)
.RE
.IP \(bu 2
\fB[plugins."io.containerd.server.v1.grpc-tcp"]\fP configures the TCP gRPC server listener (version 4).
Skipped if address is empty:
.RS
.IP \(bu 2
\fBaddress\fP (Default: "")
.IP \(bu 2
\fBtls_cert\fP, \fBtls_key\fP, \fBtls_ca\fP, \fBtls_common_name\fP
.IP \(bu 2
\fBmax_recv_message_size\fP (Default: 16777216)
.IP \(bu 2
\fBmax_send_message_size\fP (Default: 16777216)
.RE
.IP \(bu 2
\fB[plugins."io.containerd.server.v1.ttrpc"]\fP configures the TTRPC server listener (version 4).
In version 4, this plugin is configured independently from the gRPC plugin.
If the plugin block is omitted, the TTRPC server binds to its own default
address rather than deriving one from the gRPC address:
.RS
.IP \(bu 2
\fBaddress\fP (Default: "/run/containerd/containerd.sock.ttrpc")
.IP \(bu 2
\fBuid\fP (Default: effective UID)
.IP \(bu 2
\fBgid\fP (Default: effective GID)
.RE
.IP \(bu 2
\fB[plugins."io.containerd.server.v1.debug"]\fP configures the debug server listener (version 4).
Skipped if address is empty:
.RS
.IP \(bu 2
\fBaddress\fP (Default: "")
.IP \(bu 2
\fBuid\fP (Default: 0)
.IP \(bu 2
\fBgid\fP (Default: 0)
.RE
.IP \(bu 2
\fB[plugins."io.containerd.server.v1.metrics"]\fP configures the metrics HTTP listener (version 4).
Skipped if address is empty:
.RS
.IP \(bu 2
\fBaddress\fP (Default: "")
.RE
.IP \(bu 2
\fB[plugins."io.containerd.monitor.v1.cgroups"]\fP has one option \fBno_prometheus\fP (Default: \fBfalse\fP)
.IP \(bu 2
\fB[plugins."io.containerd.service.v1.diff-service"]\fP has one option \fBdefault\fP, a list by default set to \fB["walking"]\fP
.IP \(bu 2
\fB[plugins."io.containerd.gc.v1.scheduler"]\fP has several options that perform advanced tuning for the scheduler:
.RS
.IP \(bu 2
\fBpause_threshold\fP is the maximum amount of time GC should be scheduled (Default: \fB0.02\fP),
.IP \(bu 2
\fBdeletion_threshold\fP guarantees GC is scheduled after n number of deletions (Default: \fB0\fP [not triggered]),
.IP \(bu 2
\fBmutation_threshold\fP guarantees GC is scheduled after n number of database mutations (Default: \fB100\fP),
.IP \(bu 2
\fBschedule_delay\fP defines the delay after trigger event before scheduling a GC (Default \fB"0ms"\fP [immediate]),
.IP \(bu 2
\fBstartup_delay\fP defines the delay after startup before scheduling a GC (Default \fB"100ms"\fP)
.RE
.IP \(bu 2
\fB[plugins."io.containerd.runtime.v2.task"]\fP specifies options for configuring the runtime shim:
.RS
.IP \(bu 2
\fBplatforms\fP specifies the list of supported platforms
.IP \(bu 2
\fBsched_core\fP Core scheduling is a feature that allows only trusted tasks
to run concurrently on cpus sharing compute resources (eg: hyperthreads on
a core). (Default: \fBfalse\fP)
.RE
.IP \(bu 2
\fB[plugins."io.containerd.service.v1.tasks-service"]\fP has performance options:
.RS
.IP \(bu 2
\fBblockio_config_file\fP (Linux only) specifies path to blockio class definitions
(Default: \fB""\fP). Controls I/O scheduler priority and bandwidth throttling.
See blockio configuration
\[la]https://github.com/intel/goresctrl/blob/main/doc/blockio.md#configuration\[ra]
for details of the file format.
.IP \(bu 2
\fBrdt_config_file\fP (Linux only) specifies path to a configuration used for configuring
RDT (Default: \fB""\fP). Enables support for Intel RDT, a technology
for cache and memory bandwidth management.
See RDT configuration
\[la]https://github.com/intel/goresctrl/blob/main/doc/rdt.md#configuration\[ra]
for details of the file format.
.RE
.IP \(bu 2
\fB[plugins."io.containerd.grpc.v1.cri".containerd]\fP contains options for the CRI plugin, and child nodes for CRI options:
.RS
.IP \(bu 2
\fBdefault_runtime_name\fP (Default: \fB"runc"\fP) specifies the default runtime name
.RE
.IP \(bu 2
\fB[plugins."io.containerd.grpc.v1.cri".containerd.runtimes]\fP one or more container runtimes, each with a unique name
.IP \(bu 2
\fB[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.]\fP a runtime named \fB<runtime>\fR
.IP \(bu 2
\fB[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.\&.options]\fP options for the named \fB<runtime>\fR, most important:
.RS
.IP \(bu 2
\fBBinaryName\fP specifies the path to the actual runtime to be invoked by the shim, e.g. \fB"/usr/bin/runc"\fR
.RE

.TP
\fBoom_score\fP
The out of memory (OOM) score applied to the containerd daemon process (Default: 0)

.TP
\fB[cgroup]\fP
Section for Linux cgroup specific settings

.IP \(bu 2
\fBpath\fP (Default: "") Specify a custom cgroup path for created containers

.TP
\fB[proxy_plugins]\fP
Proxy plugins configures plugins which are communicated to over gRPC

.IP \(bu 2
\fBtype\fP (Default: "")
.IP \(bu 2
\fBaddress\fP (Default: "")

.TP
\fBtimeouts\fP
Timeouts specified as a duration

.TP
\fBimports\fP
Imports is a list of additional configuration files to include.
This allows to split the main configuration file and keep some sections
separately (for example vendors may keep a custom runtime configuration in a
separate file without modifying the main \fBconfig.toml\fR).
Imported files will overwrite simple fields like \fBint\fR or
\fBstring\fR (if not empty) and will append \fBarray\fR and \fBmap\fR fields.
Imported files are also versioned, and the version can't be higher than
the main config.

.PP
\fBstream_processors\fP
.IP \(bu 2
\fBaccepts\fP (Default: "[]") Accepts specific media-types
.IP \(bu 2
\fBreturns\fP (Default: "") Returns the media-type
.IP \(bu 2
\fBpath\fP (Default: "") Path or name of the binary
.IP \(bu 2
\fBargs\fP (Default: "[]") Args to the binary

.SH EXAMPLES
.SS Version 4 Configuration
The following is a \fBconfig.toml\fP example using version 4, where server
settings are configured as plugins:

.EX
version = 4

root = "/var/lib/containerd"
state = "/run/containerd"
oom_score = 0
imports = ["/etc/containerd/runtime_*.toml", "./debug.toml"]

[plugins."io.containerd.server.v1.grpc"]
  address = "/run/containerd/containerd.sock"

[plugins."io.containerd.server.v1.ttrpc"]
  address = "/run/containerd/containerd.sock.ttrpc"

[plugins."io.containerd.server.v1.debug"]
  address = "/run/containerd/debug.sock"
  level = "info"

[cgroup]
  path = ""

[plugins]
  [plugins."io.containerd.monitor.v1.cgroups"]
    no_prometheus = false
  [plugins."io.containerd.service.v1.diff-service"]
    default = ["walking"]
  [plugins."io.containerd.gc.v1.scheduler"]
    pause_threshold = 0.02
    deletion_threshold = 0
    mutation_threshold = 100
    schedule_delay = 0
    startup_delay = "100ms"
  [plugins."io.containerd.runtime.v2.task"]
    platforms = ["linux/amd64"]
    sched_core = true
  [plugins."io.containerd.service.v1.tasks-service"]
    blockio_config_file = ""
    rdt_config_file = ""
.EE

.SS Multiple Runtimes
The following is an example partial configuration with two runtimes:

.EX
[plugins]

  [plugins."io.containerd.grpc.v1.cri"]

    [plugins."io.containerd.grpc.v1.cri".containerd]
      default_runtime_name = "runc"

      [plugins."io.containerd.grpc.v1.cri".containerd.runtimes]
        [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc]
          privileged_without_host_devices = false
          runtime_type = "io.containerd.runc.v2"

          [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc.options]
            BinaryName = "/usr/bin/runc"

        [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.other]
          privileged_without_host_devices = false
          runtime_type = "io.containerd.runc.v2"

          [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.other.options]
            BinaryName = "/usr/bin/path-to-runtime"
.EE

.PP
The above creates two named runtime configurations - named \fBrunc\fR and \fBother\fR - and sets the default runtime to \fBrunc\fR\&.
The above are used \fIsolely\fP for runtimes invoked via CRI. To use the non-default "other" runtime in this example,
a spec will include the runtime handler named "other" to specify the desire to use the named runtime config.

.PP
The CRI specification includes a 
\[la]https://github.com/kubernetes/cri\-api/blob/de5f1318aede866435308f39cb432618a15f104e/pkg/apis/runtime/v1/api.proto#L476\[ra], which will reference the named runtime.

.PP
It is important to note the naming convention. Runtimes are under \fB[plugins."io.containerd.grpc.v1.cri".containerd.runtimes]\fR,
with each runtime given a unique name, e.g. \fB[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc]\fR\&.
In addition, each runtime can have shim-specific options under \fB[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.<runtime>.options]\fR,
for example, \fB[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc.options]\fR\&.

.PP
The \fBio.containerd.runc.v2\fR runtime is used to run OCI-compatible runtimes on Linux, such as runc.  In the example above, the \fBruntime_type\fR
field specifies the shim to use (\fBio.containerd.runc.v2\fR) while the \fBBinaryName\fR field is a shim-specific option which specifies the path to the
OCI runtime.

.PP
For the example configuration named "runc", the shim will launch \fB/usr/bin/runc\fR as the OCI runtime.  For the example configuration named
"other", the shim will launch \fB/usr/bin/path-to-runtime\fR instead.

.SH BUGS
Please file any specific issues that you encounter at
https://github.com/containerd/containerd.

.SH AUTHOR
Phil Estes estesp@gmail.com
\[la]mailto:estesp@gmail.com\[ra]

.SH SEE ALSO
ctr(8), containerd-config(8), containerd(8)