Skip to content

Support containerd v3 config schema#18291

Open
rifelpet wants to merge 4 commits into
kubernetes:masterfrom
rifelpet:containerd-config-v3
Open

Support containerd v3 config schema#18291
rifelpet wants to merge 4 commits into
kubernetes:masterfrom
rifelpet:containerd-config-v3

Conversation

@rifelpet
Copy link
Copy Markdown
Member

@rifelpet rifelpet commented May 9, 2026

Summary

nodeup/pkg/model/containerd.go previously hardcoded version = 2 for the generated /etc/containerd/config.toml. containerd 2.0 introduced a v3 schema that splits the monolithic io.containerd.grpc.v1.cri plugin into separate io.containerd.cri.v1.runtime and io.containerd.cri.v1.images plugins; v2 still works on 2.x but emits deprecation warnings and will be removed in a future release.

This PR makes the schema version-aware:

  • containerd ≥ 2.0: schema version = 3 with the new plugin layout (sandbox image moves to pinned_images.sandbox, etc.).
  • containerd < 2.0: schema version = 2 kept as a legacy path that should be removed alongside k8s < 1.32 support (where the 1.7 default lives).
  • Containerd.Version that fails to parse now surfaces as a hard error instead of silently producing v2.

This also migrates registry mirrors from the deprecated inline registry.mirrors.<name>.endpoint block to the registry.config_path + per-mirror /etc/containerd/certs.d/<name>/hosts.toml layout. config_path has been supported since containerd 1.5, so this works for both schema versions. containerd watches the directory at runtime. No daemon restart on changes.

ContainerdConfig.ConfigAdditions paths are written verbatim, API docs are updated to remind users their paths must match the schema version of the configured containerd binary.

User-visible changes

  • Clusters running containerd 2.x (k8s ≥ 1.32) will get a v3 /etc/containerd/config.toml instead of a v2 one with deprecation warnings.
  • Clusters with RegistryMirrors set will no longer have an inline registry.mirrors block in config.toml. Instead they get registry.config_path = "/etc/containerd/certs.d" and one hosts.toml file per mirror under that directory. Functionally equivalent.
  • A user-supplied Containerd.Version that doesn't parse as semver now fails at provisioning time instead of silently emitting a v2 config.
  • ConfigOverride continues to bypass everything; users on that path are unaffected.

Written with assistance from Opus 4.7

@k8s-ci-robot
Copy link
Copy Markdown
Contributor

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

@k8s-ci-robot k8s-ci-robot added do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. labels May 9, 2026
@k8s-ci-robot
Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign rifelpet for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@k8s-ci-robot k8s-ci-robot requested a review from hakman May 9, 2026 02:39
@k8s-ci-robot k8s-ci-robot requested a review from olemarkus May 9, 2026 02:39
@rifelpet
Copy link
Copy Markdown
Member Author

rifelpet commented May 9, 2026

/test all

@rifelpet
Copy link
Copy Markdown
Member Author

/test all

@rifelpet rifelpet force-pushed the containerd-config-v3 branch from c3d06f3 to 96334ee Compare May 13, 2026 00:52
@rifelpet
Copy link
Copy Markdown
Member Author

/test all

@rifelpet rifelpet marked this pull request as ready for review May 13, 2026 03:01
@k8s-ci-robot k8s-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label May 13, 2026
@k8s-ci-robot k8s-ci-robot requested a review from zetaab May 13, 2026 03:01
@rifelpet
Copy link
Copy Markdown
Member Author

/cc @hakman

This is ready for review. Thoughts on enabling it for all supported containerd versions vs enabling it just for k8s 1.36+ ?

@hakman
Copy link
Copy Markdown
Member

hakman commented May 14, 2026

This is ready for review. Thoughts on enabling it for all supported containerd versions vs enabling it just for k8s 1.36+ ?

Let me get through the code first, but should be mostly fine. The main concern would be the mixed config with the additional options.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/api area/nodeup cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. size/XL Denotes a PR that changes 500-999 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants