docs: update the runtime configuration section

[dvdksn]

relates to: docker/docs#17517

- What I did

Updated the section about runtime options, it now includes how to configure
containerd shims using the runtimeType and options fields.

Because there are now two ways to configure runtimes, it also demanded that I
refactor the entire section.

I've tried to add justification for when to use runtimeType, and when to use
path. It's quite difficult to accurately capture the distinction, while also
keeping the section somewhat intelligible. I tried.

- How I did it

- How to verify it

- Description for the changelog

- A picture of a cute animal (not mandatory but encouraged)

🌭

[codecov-commenter]

Codecov Report

Merging #4344 (6c7d17f) into master (f26ac47) will decrease coverage by 0.01%.
The diff coverage is n/a.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #4344      +/-   ##
==========================================
- Coverage   59.29%   59.29%   -0.01%     
==========================================
  Files         288      288              
  Lines       24769    24769              
==========================================
- Hits        14688    14687       -1     
- Misses       9197     9198       +1     
  Partials      884      884              

[corhere]

Looking good! Just needs a couple of tweaks first

[dvdksn]

Thanks @corhere and @thaJeztah, I've addressed the comments, hopefully we can merge now

[dvdksn]

@thaJeztah this needs to be backported to 24.0 as well (features are 23.0 and 24.0, nothing new in 25.0)

[thaJeztah]

Left some comments (sorry!) but not all of them are show-stoppers, so feel free to leave some for follow-ups (the anchor ones may be relevant if you need to link to these sections from elsewhere and if we don't want to update those links "again")

[thaJeztah]

Probably for a follow-up; we don't use the regular template for this page (yet), but perhaps we should already add the anchor (and maybe manually create an Options table with links);

Suggested change

	##### Configure runc drop-in replacements
	##### <a name="add-runtime"></a> Configure runc drop-in replacements (--add-runtime)

[thaJeztah]

Suggested change

	##### Configure the default container runtime
	##### <a name="default-runtime"></a> Configure the default container runtime (--default-runtime)

[thaJeztah]

This is not entirely true; automatic starting is mostly still there for backward-compatibility (and debugging), but the daemon will first check if /run/containerd/containerd.sock (default location for containerd's socket) is present. If that's not the case, it assumes containerd is not managed / running as a service, and it falls back to starting its own instance.

An unfortunate side-effect of that is that if (for any reason) the containerd service is not (or not YET) running, dockerd will start its own instance, which uses it's own storage location (different from the default) and other options. This can also lead to 2 instances of containerd running on the host (if the actual containerd service is started).

Setting the --containerd socket helps with such situations (race conditions, or containerd not running where it should be), as it disables the feature that automatically starts a new instance. This is also why we added this option as a default in the systemd unit we ship for docker engine; see

• systemd: set --containerd socket patch to prevent race-condition docker-ce-packaging#297

(I should mention that that there's things being discussed in this area, and we may consider using different defaults, and/or to make "starting containerd" an opt-in option (instead of opt-out)).

[dvdksn]

OK, this is quite good information. I didn't actually change this section when updating the doc; I only moved it around. So for that reason (and because this is still under discussion) I will leave it as is for now.

[thaJeztah]

Suggested change

	#### Use a manually controlled containerd daemon
	#### <a name="containerd"></a> Use a manually controlled containerd daemon (--containerd)

(see my other comment) not sure if "manually controlled" is the right wording here; this option would usually be if containerd is running as its own service (which is the default nowadays).

[dvdksn]

"Run containerd standalone"?

[thaJeztah]

Suggested change

	#### Configure container runtimes
	#### <a name="runtime"></a> Configure container runtimes (--runtime)

[neersighted]

I don't have time for a complete review yet, but I'd like to register my intention to dig in to this in the next day or so and provide feedback.

[thaJeztah]

LGTM, thanks!