docs: migrate config v1 to v2

AkihiroSuda · thaJeztah · commit fcdaf09664c0 · 2023-07-14T11:53:43.000+02:00
Signed-off-by: Akihiro Suda <akihiro.suda.cz@hco.ntt.co.jp> (cherry picked from commit 195fc74) Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
diff --git a/docs/PLUGINS.md b/docs/PLUGINS.md
@@ -50,7 +50,9 @@ section for your given plugin `[proxy_plugins.myplugin]`. The `address` must
 refer to a local socket file which the containerd process has access to. The
 currently supported types are `snapshot` and `content`.
 
-```
+```toml
+version = 2
+
 [proxy_plugins]
   [proxy_plugins.customsnapshot]
     type = "snapshot"
@@ -236,7 +238,7 @@ Plugins are configured using the `[plugins]` section of containerd's config.
 Every plugin can have its own section using the pattern `[plugins."<plugin type>.<plugin id>"]`.
 
 example configuration
-```
+```toml
 version = 2
 
 [plugins]
@@ -245,4 +247,27 @@ version = 2
 ```
 
 To see full configuration example run `containerd config default`.
-If you want to get the configuration combined with your configuration, run `containerd config dump`.
+If you want to get the configuration combined with your configuration, run `containerd config dump`.
+
+##### Version header
+
+containerd has two configuration versions:
+- Version 2 (Recommended): Introduced in containerd 1.3.
+- Version 1 (Default): Introduced in containerd 1.0. Deprecated and will be removed in containerd 2.0.
+
+A configuration with Version 2 must have `version = 2` header, and must have
+fully qualified plugin IDs in the `[plugins]` section:
+```toml
+version = 2
+
+[plugins]
+  [plugins."io.containerd.monitor.v1.cgroups"]
+    no_prometheus = false
+```
+
+A configuration with Version 1 may not have `version` header, and does not need fully qualified plugin IDs.
+```toml
+[plugins]
+  [plugins.cgroups]
+    no_prometheus = false
+```
diff --git a/docs/garbage-collection.md b/docs/garbage-collection.md
@@ -140,8 +140,9 @@ configuration is under the `scheduler` plugin.
 
 The default configuration is represented as...
 ```.toml
+version = 2
 [plugins]
-  [plugins.scheduler]
+  [plugins."io.containerd.gc.v1.scheduler"]
     pause_threshold = 0.02
     deletion_threshold = 0
     mutation_threshold = 100
diff --git a/docs/hosts.md b/docs/hosts.md
@@ -34,6 +34,8 @@ been **DEPRECATED**._ You should now point your registry `config_path` to the pa
 
 Modify your `config.toml` (default location: `/etc/containerd/config.toml`) as follows:
 ```toml
+version = 2
+
 [plugins."io.containerd.grpc.v1.cri".registry]
    config_path = "/etc/containerd/certs.d"
 ```
diff --git a/docs/man/containerd-config.toml.5.md b/docs/man/containerd-config.toml.5.md
@@ -1,4 +1,4 @@
-# /etc/containerd/config.toml 5 08/08/2018
+# /etc/containerd/config.toml 5 04/05/2022
 
 ## NAME
 
@@ -85,8 +85,8 @@ 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.
 
-- **[plugins.cgroup]** has one option __no_prometheus__ (Default: **false**)
-- **[plugins.diff]** has one option __default__, a list by default set to **["walking"]**
+- **[plugins."io.containerd.monitor.v1.cgroups"]** has one option __no_prometheus__ (Default: **false**)
+- **[plugins."io.containerd.service.v1.diff-service"]** has one option __default__, a list by default set to **["walking"]**
 - **[plugins.linux]** has several options for configuring the runtime, shim, and related options:
   - **shim** specifies the shim binary (Default: **"containerd-shim"**),
   - **runtime** is the OCI compliant runtime binary (Default: **"runc"**),
@@ -99,7 +99,7 @@ documentation.
   - **mutation_threshold** guarantees GC is scheduled after n number of database mutations (Default: **100**),
   - **schedule_delay** defines the delay after trigger event before scheduling a GC (Default **"0ms"** [immediate]),
   - **startup_delay** defines the delay after startup before scheduling a GC (Default **"100ms"**)
-- **[plugins."io.containerd.runtime-shim.v2.shim"]** specifies options for configuring the runtime shim:
+- **[plugins."io.containerd.runtime.v2.task"]** specifies options for configuring the runtime shim:
   - **platforms** specifies the list of supported platforms
   - **sched_core** Core scheduling is a feature that allows only trusted tasks
     to run concurrently on cpus sharing compute resources (eg: hyperthreads on
@@ -156,6 +156,8 @@ the main config.
 The following is a complete **config.toml** default configuration example:
 
 ```
+version = 2
+
 root = "/var/lib/containerd"
 state = "/run/containerd"
 oom_score = 0
@@ -180,23 +182,23 @@ imports = ["/etc/containerd/runtime_*.toml", "./debug.toml"]
   path = ""
 
 [plugins]
-  [plugins.cgroups]
+  [[plugins."io.containerd.monitor.v1.cgroups"]
     no_prometheus = false
-  [plugins.diff]
+  [plugins."io.containerd.service.v1.diff-service"]
     default = ["walking"]
   [plugins.linux]
     shim = "containerd-shim"
     runtime = "runc"
     runtime_root = ""
     no_shim = false
     shim_debug = false
-  [plugins.scheduler]
+  [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-shim.v2.shim"]
+  [plugins."io.containerd.runtime.v2.task"]
     platforms = ["linux/amd64"]
     sched_core = true
   [plugins."io.containerd.service.v1.tasks-service"]
diff --git a/docs/managed-opt.md b/docs/managed-opt.md
@@ -11,7 +11,9 @@ Configuration:
 
 *containerd config:*
 ```toml
-[plugins.opt]
+version = 2
+
+[plugins."io.containerd.internal.v1.opt"]
 	path = "/opt/mypath"
 
 ```
diff --git a/docs/ops.md b/docs/ops.md
@@ -154,6 +154,8 @@ They should not be tampered with as corruption and bugs can and will happen.
 External apps reading or watching changes in these directories have been known to cause `EBUSY` and stale file handles when containerd and/or its plugins try to cleanup resources.
 
 ```toml
+version = 2
+
 # persistent data location
 root = "/var/lib/containerd"
 # runtime state information
@@ -229,6 +231,8 @@ Both modes share backing data, while "shared" will reduce total bandwidth across
 The default is "shared". While this is largely the most desired policy, one can change to "isolated" mode with the following configuration:
 
 ```toml
-[plugins.bolt]
+version = 2
+
+[plugins."io.containerd.metadata.v1.bolt"]
 	content_sharing_policy = "isolated"
 ```
diff --git a/docs/stream_processors.md b/docs/stream_processors.md
@@ -33,6 +33,8 @@ Processor Fields:
 * `args` - Arguments passed to the processor binary.
 
 ```toml
+version = 2
+
 [stream_processors]
   [stream_processors."io.containerd.processor.v1.pigz"]
 	accepts = ["application/vnd.docker.image.rootfs.diff.tar.gzip"]
diff --git a/docs/tracing.md b/docs/tracing.md
@@ -9,6 +9,8 @@ By configuring `io.containerd.tracing.processor.v1.otlp` plugin.
 containerd daemon can send traces to the specified OpenTelemetry endpoint.
 
 ```toml
+version = 2
+
 [plugins."io.containerd.tracing.processor.v1.otlp"]
     endpoint = "http://localhost:4318"
 ```
@@ -26,6 +28,8 @@ The sampling ratio and the service name on the traces could be configured by
 `io.containerd.internal.v1.tracing` plugin.
 
 ```toml
+version = 2
+
 [plugins."io.containerd.internal.v1.tracing"]
     sampling_ratio = 1.0
     service_name = "containerd"
diff --git a/snapshots/devmapper/README.md b/snapshots/devmapper/README.md
@@ -10,10 +10,12 @@ This file is typically located at `/etc/containerd/config.toml`.
 
 Here's minimal sample entry that can be made in the configuration file:
 
-```
+```toml
+version = 2
+
 [plugins]
   ...
-  [plugins.devmapper]
+  [plugins."io.containerd.snapshotter.v1.devmapper"]
     pool_name = "containerd-pool"
     base_image_size = "8192MB"
   ...
