Mastering Containerd: From crictl to nerdctl – Commands, Configs, and Real‑World Usage

Overview

Containerd has been able to integrate directly with Kubelet since Kubernetes 1.7, but many clusters still used the default dockershim because of familiarity with Docker. Starting with kubelet version V1.24, dockershim was removed and Containerd became the default runtime, optionally using the cri-dockerd adapter to integrate Docker Engine with Kubernetes.

https://kubernetes.io/zh-cn/docs/setup/production-environment/container-runtimes/#docker

Common Containerd Commands

After switching to Containerd, the traditional Docker commands are replaced by crictl (a CRI‑compliant client) and ctr (the Containerd client).

crictl

is used to inspect and manage containers and images on a kubelet node. ctr is the native Containerd client. ctr -v shows the Containerd version; crictl -v shows the Kubernetes version.

Typically crictl is available only after installing Kubernetes, while ctr works as soon as Containerd is installed.

Before using crictl, configure /etc/crictl.yaml:

runtime-endpoint: unix:///run/containerd/containerd.sock
image-endpoint: unix:///run/containerd/containerd.sock
timeout: 10
debug: false

Or set it via commands:

crictl config runtime-endpoint unix:///run/containerd/containerd.sock
crictl config image-endpoint unix:///run/containerd/containerd.sock

Command Mapping (Docker ↔ ctr ↔ crictl)

Key operations such as listing containers, viewing images, checking logs, inspecting containers, starting/stopping containers, building images, tagging, and pushing/pulling are performed with equivalent docker, ctr, and crictl commands. For example, docker ps maps to ctr task ls or crictl ps.

nerdctl – Containerd‑compatible Docker CLI

Install nerdctl to get Docker‑compatible syntax. Two distribution options are available:

Slim package ( nerdctl‑linux‑amd64.tar.gz) – contains only nerdctl.

Full package ( nerdctl‑full‑linux‑amd64.tar.gz) – includes Containerd, runc, CNI, etc.

nerdctl also adds features Docker lacks, such as lazy‑pulling and image encryption.

BuildKit Integration

BuildKit is a C/S architecture build tool that works with Containerd. Install BuildKit, configure its systemd socket and service files, then start it:

systemctl daemon-reload
systemctl enable buildkit --now
systemctl status buildkit containerd

Practical Operations

1. Modify Containerd Configuration

containerd config default > /etc/containerd/config.toml

Example snippet to configure a private registry (skip TLS verification, set credentials, define mirrors):

[plugins."io.containerd.grpc.v1.cri".registry]
  config_path = ""
  [plugins."io.containerd.grpc.v1.cri".registry.auths]
  [plugins."io.containerd.grpc.v1.cri".registry.configs]
    [plugins."io.containerd.grpc.v1.cri".registry.configs."myharbor-minio.com".tls]
      insecure_skip_verify = true
      ca_file = "/etc/containerd/myharbor-minio.com/ca.crt"
    [plugins."io.containerd.grpc.v1.cri".registry.configs."myharbor-minio.com".auth]
      username = "admin"
      password = "Harbor12345"
  [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."myharbor-minio.com"]
      endpoint = ["https://myharbor-minio.com"]

Reload and restart Containerd:

# Reload configuration
systemctl daemon-reload
# Restart Containerd
systemctl restart containerd

This config is used by crictl and kubelet ; ctr does not read it because it does not use CRI.

2. Pull and Push Images with ctr

# Push image to Harbor
ctr --namespace=k8s.io images push myharbor-minio.com/bigdata/minio:2022.8.22-debian-11-r0 --skip-verify --user admin:Harbor12345
# Pull image with TLS verification
ctr images pull --user admin:Harbor12345 --tlscacert=/etc/containerd/myharbor-minio.com/ca.crt myharbor-minio.com/bigdata/minio:2022.8.22-debian-11-r0

If you prefer not to specify credentials each time, use nerdctl instead.

3. Build Images

cat > Dockerfile <<EOF
FROM nginx:alpine
RUN echo 'Hello Nerdctl From Containerd' > /usr/share/nginx/html/index.html
EOF

Build with nerdctl, specifying the Kubernetes namespace:

nerdctl -n k8s.io build -t nginx:nerctl -f ./Dockerfile .

4. Tag Images

# Using nerdctl (requires namespace)
nerdctl -n k8s.io tag nginx:nerctl myharbor-minio.com/bigdata/nginx:nerctl
# Verify
nerdctl -n k8s.io images myharbor-minio.com/bigdata/nginx:nerctl

5. Push to Harbor

Configure registry certificates for HTTP or HTTPS, then log in and push:

# Example HTTPS config (skip verification)
mkdir -p /etc/containerd/certs.d/myharbor-minio.com:443
cat > /etc/containerd/certs.d/myharbor-minio.com:443/hosts.toml <<EOF
server = "https://docker.io"
[host."https://myharbor-minio.com:443"]
  capabilities = ["pull", "resolve", "push"]
  skip_verify = true
  ca = ["/etc/containerd/myharbor-minio.com/ca.crt"]
EOF

# Login
echo Harbor12345 | nerdctl login --username "admin" --password-stdin myharbor-minio.com:443

# Push image
nerdctl --insecure-registry --namespace=k8s.io push myharbor-minio.com/bigdata/nginx:nerctl

The tutorial concludes with a summary of Containerd, crictl, ctr, and nerdctl commands and invites readers to leave comments for further questions.