K3s lets you customize containerd’s settings, but it doesn’t use the standard config.toml file you’d find in a standalone containerd installation. Instead, K3s injects its own configuration into containerd.
Here’s how to see K3s’s containerd configuration in action:
First, check the containerd process itself. K3s often runs containerd as a systemd service.
sudo systemctl status containerd
Look for the ExecStart line. You’ll likely see it pointing to a K3s-specific binary or script that then invokes the actual containerd process with arguments. K3s manipulates these arguments to apply its own defaults and your customizations.
Now, let’s look at how K3s actually manages containerd’s configuration. K3s uses a specific directory for its configuration overrides.
ls -l /var/lib/rancher/k3s/agent/etc/containerd/
You’ll typically find a file named config.toml.tmpl or similar within this directory. This is the template K3s uses to generate containerd’s runtime configuration. When K3s starts, it reads this template, merges it with its own internal defaults, and then writes the final config.toml to /var/lib/rancher/k3s/agent/etc/containerd/config.toml (or a similar path, depending on your K3s installation).
To customize settings, you don’t directly edit /var/lib/rancher/k3s/agent/etc/containerd/config.toml. Instead, you modify the config.toml.tmpl file.
Let’s say you want to change the default registry mirror for Docker Hub. You’d edit /var/lib/rancher/k3s/agent/cycle/containerd/config.toml.tmpl.
Here’s a snippet showing how you might add a registry mirror:
[plugins."io.containerd.grpc.v1.cri".registry.mirrors]
[plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
endpoint = ["https://your-mirror.example.com"]
After saving your changes to config.toml.tmpl, you need to restart the containerd service for K3s to pick them up.
sudo systemctl restart containerd
Then, verify that the generated config.toml has been updated.
sudo cat /var/lib/rancher/k3s/agent/etc/containerd/config.toml | grep -A 3 "docker.io"
You should see your added mirror in the output.
The most surprising true thing about K3s’s containerd customization is that it replaces the standard containerd configuration management entirely. You’re not just adding to an existing file; K3s is actively generating the final configuration based on its own defaults and your provided templates. This means if you were to manually edit /var/lib/rancher/k3s/agent/etc/containerd/config.toml directly, your changes would be overwritten the next time K3s restarts or updates its containerd configuration.
The key levers you control are within the config.toml.tmpl file, specifically the [plugins."io.containerd.grpc.v1.cri"] section, which governs the Container Runtime Interface (CRI) implementation for Kubernetes. This section allows you to fine-tune aspects like image service configurations, network configurations, and, as shown, registry mirrors.
The next concept you’ll want to explore is how to configure specific containerd plugins beyond the CRI, such as the io.containerd.content.v1.content plugin for managing image content, or how to set up custom snapshotters.