Skip to content

feat(containerd): Support containerd 2.x.x and 3.x.x #1658

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
k8s-ci-robot merged 5 commits into from
Aug 12, 2025
Merged

feat(containerd): Support containerd 2.x.x and 3.x.x #1658

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
615ec65
feat: add support to containerd 2.0
ffais Feb 27, 2025
edb2402
fix: use containerd_version variable to download the appropriate cont…
ffais Mar 28, 2025
8776622
feat(containerd): add support to config version 3
ffais Jul 29, 2025
efb16e2
Update docs/book/src/capi/capi.md
ffais Aug 12, 2025
afd91e4
fix(ova): create missing /usr/local/sbin directory in photon os
ffais Aug 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/book/src/capi/capi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ Several variables can be used to customize the image build.
| `remove_extra_repos` | If set to `"true"`, the package repositories added to the OS through the use of `extra_repos` will be removed at the end of the build. | `"false"` |
| `pause_image` | This can be used to override the default pause image used to hold the network namespace and IP for the pod. | `"registry.k8s.io/pause:3.10"` |
| `pip_conf_file` | The path to a file to be copied into the image at `/etc/pip.conf` for use as a global config file. This file will be removed at the end of the build if `remove_extra_repos` is `true`. | `""` |
| `containerd_additional_settings` | This is a string, base64 encoded, that contains additional configuration for containerd. It must be version 2 and not contain the pause image configuration block. See `image-builder/images/capi/ansible/roles/containerd/templates/etc/containerd/config.toml` for the template. | `null` |
| `containerd_additional_settings` | This is a string, base64 encoded, that contains additional configuration for containerd. Version 2 and 3 are supported, please use the appropriate version based on your containerd version. It must not contain the pause image configuration block. See `image-builder/images/capi/ansible/roles/containerd/templates/etc/containerd/config.toml` for the template. | `null` |
| `load_additional_components` | If set to `"true"`, the `load_additional_components` role will be executed. This needs to be set to `"true"` if any of `additional_url_images`, `additional_registry_images` or `additional_executables` are set to `"true"` | `"false"` |
| `additional_url_images` | Set this to `"true"` to load additional container images using a tar url. `additional_url_images_list` var should be set to a comma separated string of tar urls of the container images. | `"false"` |
| `additional_registry_images` | Set this to `"true"` to load additional container images using their registry url. `additional_registry_images_list` var should be set to a comma separated string of registry urls of the container images. | `"false"` |
Expand Down
6 changes: 4 additions & 2 deletions docs/book/src/capi/providers/oci.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,10 +78,12 @@ is defined in images/capi/packer/config/containerd.json.
"subnet_ocid": "Fill Subnet OCID here",
"availability_domain": "Fill Availability Domain here",
"shape": "VM.Standard.A1.Flex",
"containerd_url": "https://github.com/containerd/containerd/releases/download/v{{user `containerd_version`}}/cri-containerd-cni-{{user `containerd_version`}}-linux-arm64.tar.gz",
"containerd_url": "https://github.com/containerd/containerd/releases/download/v{{user `containerd_version`}}/containerd-{{user `containerd_version`}}-linux-arm64.tar.gz",
"crictl_url": "https://github.com/kubernetes-sigs/cri-tools/releases/download/v{{user `crictl_version`}}/crictl-v{{user `crictl_version`}}-linux-arm64.tar.gz",
"kubernetes_rpm_repo": "https://packages.cloud.google.com/yum/repos/kubernetes-el7-aarch64",
"containerd_sha256": "9ac616b5f23c1d10353bd45b26cb736efa75dfef31a2113baff2435dbc7becb8"
"containerd_sha256": "9ac616b5f23c1d10353bd45b26cb736efa75dfef31a2113baff2435dbc7becb8",
"runc_sha256": "4ef19ab21ce1ae5a01e1d3fa5b005e45cdf59f5d3ab32541c9e262cb2b2d3451",
"runc_url": "https://github.com/opencontainers/runc/releases/download/v{{user `runc_version`}}/runc.arm64",
}
```

Expand Down
70 changes: 48 additions & 22 deletions images/capi/ansible/roles/containerd/tasks/main.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,19 @@
dest: /tmp/containerd.tar.gz
mode: "0600"

- name: Download containerd.service
Copy link
Contributor

@sriramandev sriramandev Mar 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would be great if this goes behind flag? We can default the flag to download.
If not mistaken, containerd as a artifact does not publish the bundle anymore, but the scripts to generate them still exists. So if any provider/anyone still wants to use the bundle to do things, the can set the flag to false and continue to use older way.

Copy link
Contributor Author

@ffais ffais Mar 28, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we want to keep support for containerd bundles we have to put behind flag runc as well. I don't know how long the generation script is kept updated.

ansible.builtin.get_url:
url: "{{ containerd_service_url }}"
dest: /tmp/containerd.service
mode: "0600"

- name: Download runc
ansible.builtin.get_url:
url: "{{ runc_url }}"
checksum: sha256:{{ runc_sha256 }}
dest: /tmp/runc
mode: "0600"

- name: Download containerd-wasm-shims
vars:
sha256sums: "{{ containerd_wasm_shims_sha256 | from_json }}"
Expand All @@ -54,11 +67,26 @@
ansible.builtin.unarchive:
remote_src: true
src: /tmp/containerd.tar.gz
dest: "{{ containerd_prefix | default('/') }}"
dest: "{{ containerd_prefix | default('/usr/local') }}"
extra_opts:
- --no-overwrite-dir
when: ansible_os_family != "Flatcar"

- name: Copy containerd.service to /etc/systemd/system
ansible.builtin.copy:
remote_src: true
src: /tmp/containerd.service
dest: /etc/systemd/system/containerd.service
mode: "0600"

- name: Copy runc to /usr/local/sbin
ansible.builtin.copy:
remote_src: true
src: /tmp/runc
dest: /usr/local/sbin/runc
mode: "0755"
when: ansible_os_family != "Flatcar"

# Install containerd Wasm shims specified in a comma-separated string. Known runtimes are 'lunatic', 'slight', 'spin', and 'wws'.
- name: Unpack containerd-wasm-shims
ansible.builtin.unarchive:
Expand All @@ -74,15 +102,15 @@
ansible.builtin.unarchive:
remote_src: true
src: /tmp/containerd.tar.gz
dest: "{{ containerd_prefix | default('/') }}"
extra_opts:
- --absolute-names
- --transform
- s@usr@opt@
- --transform
- s@sbin@bin@
- --transform
- s@opt/local@opt@
dest: "{{ containerd_prefix | default('/opt') }}"
when: ansible_os_family == "Flatcar"

- name: Copy runc to /opt/bin
ansible.builtin.copy:
remote_src: true
src: /tmp/runc
dest: /opt/bin/runc
mode: "0755"
when: ansible_os_family == "Flatcar"

# Install containerd Wasm shims specified in a comma-separated string. Known runtimes are 'lunatic', 'slight', 'spin', and 'wws'.
Expand All @@ -96,18 +124,6 @@
when: ansible_os_family == "Flatcar" and (containerd_wasm_shims_runtimes | length > 0)
loop: "{{ containerd_wasm_shims_runtimes | split(',') }}"

# Remove /opt/cni directory, as we will install cni later
- name: Delete /opt/cni directory
ansible.builtin.file:
path: /opt/cni
state: absent

# Remove /etc/cni directory, as we will configure cni later
- name: Delete /etc/cni directory
ansible.builtin.file:
path: /etc/cni
state: absent

- name: Create unit file directory
ansible.builtin.file:
path: /etc/systemd/system/containerd.service.d
Expand Down Expand Up @@ -181,6 +197,16 @@
path: /tmp/containerd.tar.gz
state: absent

- name: Delete runc bin
ansible.builtin.file:
path: /tmp/runc
state: absent

- name: Delete containerd.service
ansible.builtin.file:
path: /tmp/containerd.service
state: absent

- name: Delete containerd-wasm-shims tarballs
ansible.builtin.file:
path: /tmp/{{ item }}_wasm_shims.tar.gz
Expand Down
6 changes: 6 additions & 0 deletions images/capi/ansible/roles/containerd/tasks/photon.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,3 +14,9 @@
---
- name: Install libseccomp package
ansible.builtin.command: tdnf install libseccomp -y

- name: Create /usr/local/sbin directory if it does not exist
ansible.builtin.file:
path: /usr/local/sbin
state: directory
mode: '0755'
39 changes: 38 additions & 1 deletion images/capi/ansible/roles/containerd/templates/etc/containerd/config.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,49 @@

# Use config version 2 to enable new configuration fields.
# Config file is parsed as version 1 by default.
version = 2
version = {% if containerd_version is version('2.0.0', '>=') %}3{% else %}2{% endif %}

{% if 'imports' not in containerd_additional_settings | b64decode %}
imports = ["/etc/containerd/conf.d/*.toml"]
{% endif %}

[plugins]
{% if containerd_version is version('2.0.0', '>=') %}
[plugins.'io.containerd.cri.v1.images'.pinned_images]
sandbox = "{{ pause_image }}"
[plugins.'io.containerd.cri.v1.images'.registry]
config_path = '/etc/containerd/certs.d'
{% if kubernetes_semver is version('v1.21.0', '>=') %}
[plugins.'io.containerd.cri.v1.runtime'.containerd.runtimes.runc]
runtime_type = 'io.containerd.runc.v2'
[plugins.'io.containerd.cri.v1.runtime'.containerd.runtimes.runc.options]
SystemdCgroup = true
{% if 'lunatic' in containerd_wasm_shims_runtimes %}
[plugins.'io.containerd.cri.v1.runtime'.containerd.runtimes.lunatic]
runtime_type = "io.containerd.lunatic.{{ runtime_versions['lunatic'] }}"
{% endif %}
{% if 'slight' in containerd_wasm_shims_runtimes %}
[plugins.'io.containerd.cri.v1.runtime'.containerd.runtimes.slight]
runtime_type = "io.containerd.slight.{{ runtime_versions['slight'] }}"
{% endif %}
{% if 'spin' in containerd_wasm_shims_runtimes %}
[plugins.'io.containerd.cri.v1.runtime'.containerd.runtimes.spin]
runtime_type = "io.containerd.spin.{{ runtime_versions['spin'] }}"
{% endif %}
{% if 'wws' in containerd_wasm_shims_runtimes %}
[plugins.'io.containerd.cri.v1.runtime'.containerd.runtimes.wws]
runtime_type = "io.containerd.wws.{{ runtime_versions['wws'] }}"
{% endif %}
{% if containerd_gvisor_runtime %}
[plugins.'io.containerd.cri.v1.runtime'.containerd.runtimes.gvisor]
runtime_type = 'io.containerd.runsc.v1'
{% endif %}
{% endif %}
{% if packer_builder_type.startswith('azure') %}
[plugins.'io.containerd.cri.v1.images'.registry.headers]
X-Meta-Source-Client = ['azure/capz']
{% endif %}
{% else %}
[plugins."io.containerd.grpc.v1.cri"]
sandbox_image = "{{ pause_image }}"
[plugins."io.containerd.grpc.v1.cri".registry]
Expand Down Expand Up @@ -43,5 +79,6 @@ imports = ["/etc/containerd/conf.d/*.toml"]
[plugins."io.containerd.grpc.v1.cri".registry.headers]
X-Meta-Source-Client = ["azure/capz"]
{% endif %}
{% endif %}

{{containerd_additional_settings | b64decode}}
15 changes: 7 additions & 8 deletions images/capi/ansible/roles/kubernetes/tasks/main.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,13 @@
- ansible.builtin.import_tasks: photon.yml
when: kubernetes_source_type == "pkg" and ansible_os_family == "VMware Photon OS"

- ansible.builtin.import_tasks: url.yml
when: kubernetes_source_type == "http" and kubernetes_cni_source_type == "http"

# must include crictl-url.yml after installing containerd,
# as the cri-containerd tarball also includes crictl.
- ansible.builtin.import_tasks: crictl-url.yml

- name: Symlink cri-tools
ansible.builtin.file:
src: /usr/local/bin/{{ item }}
Expand All @@ -37,14 +44,6 @@
- critest
when: ansible_os_family != "Flatcar"

- ansible.builtin.import_tasks: url.yml
when: kubernetes_source_type == "http" and kubernetes_cni_source_type == "http"

# must include crictl-url.yml after installing containerd,
# as the cri-containerd tarball also includes crictl.
- ansible.builtin.import_tasks: crictl-url.yml
when: crictl_source_type == "http"

- name: Create kubelet default config file
ansible.builtin.template:
src: etc/sysconfig/kubelet
Expand Down
16 changes: 14 additions & 2 deletions images/capi/ansible/windows/roles/runtimes/templates/config.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,16 +14,27 @@

root = "{{ allusersprofile }}\\containerd\\root"
state = "{{ allusersprofile }}\\containerd\\state"
version = 2
version = {% if containerd_version is version('2.0.0', '>=') %}3{% else %}2{% endif %}

{% if 'imports' not in containerd_additional_settings | b64decode %}
imports = ["{{ containerd_conf_dir }}\\conf.d\\*.toml"]
{% endif %}

[grpc]
address = "\\\\.\\pipe\\containerd-containerd"

[plugins]
{% if containerd_version is version('2.0.0', '>=') %}
[plugins.'io.containerd.cri.v1.images'.pinned_images]
sandbox = "{{ pause_image }}"
[plugins.'io.containerd.cri.v1.runtime'.cni]
bin_dir = "{{ plugin_bin_dir }}"
conf_dir = "{{ plugin_conf_dir }}"
{% if packer_builder_type.startswith('azure') %}
[plugins.'io.containerd.cri.v1.images'.registry.headers]
X-Meta-Source-Client = ["azure/capz"]
{% endif %}
{% else %}
[plugins."io.containerd.grpc.v1.cri"]
sandbox_image = "{{ pause_image }}"
[plugins."io.containerd.grpc.v1.cri".cni]
Expand All @@ -33,5 +44,6 @@ imports = ["{{ containerd_conf_dir }}\\conf.d\\*.toml"]
[plugins."io.containerd.grpc.v1.cri".registry.headers]
X-Meta-Source-Client = ["azure/capz"]
{% endif %}
{% endif %}

{{containerd_additional_settings | b64decode}}
6 changes: 5 additions & 1 deletion images/capi/packer/ami/packer.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -164,8 +164,9 @@
"builder_instance_type": "t3.small",
"containerd_gvisor_runtime": "false",
"containerd_gvisor_version": "latest",
"containerd_service_url": "https://raw.githubusercontent.com/containerd/containerd/refs/tags/v{{user `containerd_version`}}/containerd.service",
"containerd_sha256": null,
"containerd_url": "https://github.com/containerd/containerd/releases/download/v{{user `containerd_version`}}/cri-containerd-cni-{{user `containerd_version`}}-linux-amd64.tar.gz",
"containerd_url": "https://github.com/containerd/containerd/releases/download/v{{user `containerd_version`}}/containerd-{{user `containerd_version`}}-linux-amd64.tar.gz",
"containerd_version": null,
"crictl_url": "https://github.com/kubernetes-sigs/cri-tools/releases/download/v{{user `crictl_version`}}/crictl-v{{user `crictl_version`}}-linux-amd64.tar.gz",
"crictl_version": null,
Expand Down Expand Up @@ -196,6 +197,9 @@
"kubernetes_source_type": null,
"manifest_output": "manifest.json",
"python_path": "",
"runc_sha256": null,
"runc_url": "https://github.com/opencontainers/runc/releases/download/v{{user `runc_version`}}/runc.amd64",
"runc_version": null,
"skip_create_ami": "false",
"skip_profile_validation": "false",
"snapshot_groups": "all",
Expand Down
7 changes: 6 additions & 1 deletion images/capi/packer/azure/packer.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,7 @@
"plan_product": "{{user `plan_image_offer`}}",
"plan_publisher": "{{user `plan_image_publisher`}}"
},
"polling_duration_timeout": "60m",
"private_virtual_network_with_public_ip": "{{user `private_virtual_network_with_public_ip`}}",
"public_ip_sku": "Standard",
"shared_gallery_image_version_exclude_from_latest": "{{ user `exclude_from_latest` }}",
Expand Down Expand Up @@ -221,8 +222,9 @@
"community_gallery_image_id": "",
"containerd_gvisor_runtime": "false",
"containerd_gvisor_version": "latest",
"containerd_service_url": "https://raw.githubusercontent.com/containerd/containerd/refs/tags/v{{user `containerd_version`}}/containerd.service",
"containerd_sha256": null,
"containerd_url": "https://github.com/containerd/containerd/releases/download/v{{user `containerd_version`}}/cri-containerd-cni-{{user `containerd_version`}}-linux-amd64.tar.gz",
"containerd_url": "https://github.com/containerd/containerd/releases/download/v{{user `containerd_version`}}/containerd-{{user `containerd_version`}}-linux-amd64.tar.gz",
"containerd_version": null,
"containerd_wasm_shims_runtimes": null,
"crictl_url": "https://github.com/kubernetes-sigs/cri-tools/releases/download/v{{user `crictl_version`}}/crictl-v{{user `crictl_version`}}-linux-amd64.tar.gz",
Expand Down Expand Up @@ -266,6 +268,9 @@
"plan_image_sku": "",
"private_virtual_network_with_public_ip": "",
"provisioner_remote_folder": "/tmp",
"runc_sha256": null,
"runc_url": "https://github.com/opencontainers/runc/releases/download/v{{user `runc_version`}}/runc.amd64",
"runc_version": null,
"source_sig_image_name": "",
"source_sig_image_version": "",
"source_sig_name": "",
Expand Down
Loading