Merge pull request #6776 from AkihiroSuda/docs-remove-runtime-v1

kzys · web-flow · commit 83f44ddab5b1 · 2022-04-05T11:13:50.000-07:00
docs: remove runtime v1; migrate config v1 to v2
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
 
@@ -87,21 +87,15 @@ 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.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"**),
-  - **runtime_root** is the root directory used by the runtime (Default: **""**),
-  - **no_shim** specifies whether to use a shim or not (Default: **false**),
-  - **shim_debug** turns on debugging for the shim (Default: **false**)
+- **[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."io.containerd.gc.v1.scheduler"]** has several options that perform advanced tuning for the scheduler:
   - **pause_threshold** is the maximum amount of time GC should be scheduled (Default: **0.02**),
   - **deletion_threshold** guarantees GC is scheduled after n number of deletions (Default: **0** [not triggered]),
   - **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
@@ -158,6 +152,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
@@ -182,23 +178,17 @@ 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
@@ -102,7 +102,7 @@ containerd itself does not actually have any persistent data that it needs to st
 │   └── ingest
 ├── io.containerd.metadata.v1.bolt
 │   └── meta.db
-├── io.containerd.runtime.v1.linux
+├── io.containerd.runtime.v2.task
 │   ├── default
 │   └── example
 ├── io.containerd.snapshotter.v1.btrfs
@@ -118,7 +118,7 @@ Sockets, pids, runtime state, mount points, and other plugin data that must not
 /run/containerd
 ├── containerd.sock
 ├── debug.sock
-├── io.containerd.runtime.v1.linux
+├── io.containerd.runtime.v2.task
 │   └── default
 │       └── redis
 │           ├── config.json
@@ -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
@@ -198,23 +200,6 @@ You will have to read the plugin specific docs to find the options that your plu
 
 See [containerd's Plugin documentation](./PLUGINS.md)
 
-### Linux Runtime Plugin
-
-The linux runtime allows a few options to be set to configure the shim and the runtime that you are using.
-
-```toml
-[plugins.linux]
-	# shim binary name/path
-	shim = ""
-	# runtime binary name/path
-	runtime = "runc"
-	# do not use a shim when starting containers, saves on memory but
-	# live restore is not supported
-	no_shim = false
-	# display shim logs in the containerd daemon's log output
-	shim_debug = true
-```
-
 ### Bolt Metadata Plugin
 
 The bolt metadata plugin allows configuration of the content sharing policy between namespaces.
@@ -229,7 +214,9 @@ 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 = "https://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"
   ...
