Repository navigation
Please provide the full config.toml configuration documentation #9457
Description
What is the problem you're trying to solve
I'm checking the containerd configuration, but the default configuration output using the command "containerd config" is very short. For example, I learned in other documents that there is a configuration such as [plugins."io.containerd.grpc.v1.cri".registry.configs."harbor.domain.com".tls], but I don't see it in the latest official version of the docs.
The overall docs can be said to be very scattered. Each block is partially written, but it also gives people a feeling of incomplete documentation. I saw the tls line of configuration in the old version, so is it because this configuration has not changed that it has not been written, or has it been removed so that it has not been written?
I can't be sure! So I hope that each version can have a full document, just like when helm deploys an application, the default values.yaml will comment on what the configuration is used for and what parameters are optional.
Describe the solution you'd like
Each version must provide complete config.toml configuration parsing, just like helm's values.yaml.
Or tell me where the complete documentation can be found.
Additional context
No response
Activity
[-]Please provide the full config.toml configuration analysis.[/-][+]Please provide the full config.toml configuration documentation[/+]dosubot commentedon Nov 24, 2024
Hi, @yulinor. I'm Dosu, and I'm helping the containerd team manage their backlog. I'm marking this issue as stale.
Issue Summary:
config.tomlfile in containerd.values.yaml.Next Steps:
Thank you for your understanding and contribution!
balabalabutton commentedon Nov 28, 2024
It is still expected that a complete explanation of the config.toml configuration items will be provided in the latest version.
DileepAP commentedon Jan 9, 2025
Hello Team, It will be good if a documentation is provided on setting up tls authentication to a image registry without the need of username/password or token. the ctr pull works with --tlscert & --tlskey, but unable to find relevant docs to set this up in hosts.toml or in containerd-template.toml
djdongjin commentedon Jan 9, 2025
@DileepAP is the
clientfield in hosts.toml you're looking for?https://github.com/containerd/containerd/blob/main/docs/hosts.md#client-field
example hosts.toml: https://github.com/containerd/containerd/blob/main/docs/hosts.md#host-fields-in-the-toml-table-format
3 remaining items
balabalabutton commentedon Sep 24, 2025
The current documentation of the project is more inclined to write an md for the common requirements of some modules, such as mirror acceleration, you can see
hosts.md,https://github.com/containerd/containerd/blob/main/docs/hosts.md.In terms of split structure, this is indeed good.
#9089
Then I encountered the same problem as this qa, wondering what the role of this parameter
runtime_typeis. I searched some articles and there is no explanation about this configuration.Therefore, I prefer
config.mdto be similar tovalues.yamlin Helm packages.List the complete default configuration list, and then each plugin configuration block is referenced to the corresponding specialized md.
At least I think it is not easy to find the configuration instructions of the plugin now.
balabalabutton commentedon Sep 24, 2025
If the configuration explanation document can be separated, I think it will be very convenient for users, but it is quite troublesome for you.
kovan commentedon Mar 26, 2026
I looked into this and I think there's a structural challenge worth discussing before anyone writes a PR.
The request is for a comprehensive config.toml reference, similar to Helm's annotated values.yaml. But containerd's plugin architecture makes this fundamentally different from Helm: plugins are loaded dynamically, each with its own config schema. A static doc listing every plugin option would be incomplete (it can't cover third-party or proxy plugins) and hard to maintain as plugins evolve independently.
The previous PR #10920 attempted to merge CRI config into the man page, but it went stale partly because of this tension - AkihiroSuda raised concerns about scope and format.
What would be feasible and useful:
[plugins."io.containerd.xxx.v1"]structure, how options map to plugin-specific Go structs, and how plugins not compiled in are silently ignored.containerd config defaultas the primary discovery tool - explain that this command outputs the full default config for all plugins compiled into the current binary, which is the authoritative reference for a given build.This approach teaches users how to find config options for any plugin (including third-party ones) rather than trying to maintain a static list that will always be incomplete.
Would maintainers be open to a PR with this scope? Happy to work on it if so.
docs: expand config.toml man pages with discovery and plugin model
docs: expand config man pages with discovery and current plugin IDs
tomatotomata commentedon Jul 31, 2026
I was thinking of starting with a versioned reference for the current containerd config default output, then linking the plugin-specific sections that are already documented instead of trying to rewrite every option in one pass. The current tree has the man page plus CRI and plugin docs, but they do not line up as one complete reference. Would a first PR that documents the generated default config for the current 2.x line, with links out to plugin-specific details, fit the accepted scope?
balabalabutton commentedon Jul 31, 2026
I think there's no problem, and we can even encourage everyone to use containerd 2.
tomatotomata commentedon Sep 16, 2026
@djdongjin, I was thinking of keeping a first pass focused on a versioned containerd 2.x default-config reference generated from
containerd config default, with links to the existing plugin docs instead of duplicating every plugin field. Would that fit the docs direction you would expect for #9457? Let me know what you think.avneetbansal-aws commentedon Oct 7, 2026
Thanks for laying out the problem clearly. The scattered feeling is real, and the specific example you gave (the per-registry TLS settings) is a good place to anchor a first improvement rather than trying to regenerate the whole config.toml at once.
A full values.yaml-style reference for every field is a large, moving target, since the config is spread across plugins and changes between the 1.x and 2.x formats. A single sweeping PR for that would be hard to review and hard to keep current. A smaller, well-scoped pass is more likely to land and still helps the exact case you hit.
Here is what I would propose as that first pass. The current registry TLS story lives in the per-host hosts.toml mechanism (config_path and certs.d), which is the non-deprecated replacement for the old inline registry.configs."HOST".tls block you saw in older docs. docs/hosts.md already shows ca in a mirror example and skip_verify in the bypass example, but the field-by-field "hosts.toml Content Description - Detail" section only documents server and capabilities in full. The TLS-related fields a user reaches for (ca, client, and skip_verify) do not have their own entries there yet. I would add commented, copy-pasteable entries for those fields in that detail section, and add a short note in docs/cri/registry.md that points from the deprecated inline tls block to the hosts.toml equivalent, so someone searching for the old key lands in the right place.
That keeps the change bounded to the TLS gap you called out, documents the current mechanism rather than the deprecated one, and cross-links the two docs so the path is discoverable.
Before I write it, does this direction match what you had in mind, and are maintainers comfortable with the TLS/hosts.toml slice as the starting scope? If you would rather I target a different block first, happy to adjust.