containerd/nerdctl：containerd 向け Docker 互換 CLI

nerdctl は containerd の non-core CLI である

containerd/nerdctl の README 冒頭は nerdctl: Docker-compatible CLI for containerd である。同じ UI/UX as docker、nerdctl compose up による Compose、rootless（bypass4netns、slirp オーバーヘッド無しはオプション）、Stargz / Nydus / OverlayBD の lazy-pull、ocicrypt による暗号化イメージ、IPFS による配布、cosign による署名検証を、いずれも Optional 付きで列挙する。containerd の non-core サブプロジェクト。実装言語は Go。ライセンスは Apache-2.0。

Motivation 節は、Docker に無い containerd 側の機能を試すのが目的だと書く。Docker と競合することは目的ではない。それらの機能はいずれ Docker 側にも来ると README は見込んでいる。Kubernetes クラスタのデバッグに使える可能性はあるが、第一目的ではない、とも明言する。

IPFS は完全に任意で、IPFS daemon を入れない限りホストは P2P 網に繋がらない、と README は二度注意する。star 数は採用根拠にしない。コマンドリファレンスは docs/command-reference.md、障害切り分けは docs/faq.md。

non-core という位置づけは、containerd 本体のリリースサイクルと CLI のバージョンが必ずしも同時ではない、と読む。Docker 互換を謳いながら Docker と競合しない、という文は矛盾に見えて、実際は「見た目は docker コマンド、実装は containerd の実験機能」という役割分担だ。FAQ と command-reference が別ファイルなのは、README の例だけでは全フラグをカバーしないという意味である。cosign も IPFS も既定では動かない。必要な人だけ docs を開く。

alpine の run、BuildKit、compose-wordpress 例

Basic usage はデフォルトの bridge CNI（10.4.0.0/24）で nerdctl run -it --rm alpine を示す。イメージビルドは BuildKit 経由で nerdctl build -t foo /some-dockerfile-directory、続けて nerdctl run -it --rm foo。成果物をローカルディレクトリへ出す例は nerdctl build -o type=local,dest=. /some-dockerfile-directory。Compose は nerdctl compose -f ./examples/compose-wordpress/docker-compose.yaml up。詳細は examples/compose-wordpress ディレクトリを見よ、とある。

CNI が無い状態で run すると、README が前提とする bridge 10.4.0.0/24 は出てこない。BuildKit の buildkitd が止まっていると build が落ちる。compose-wordpress 例は WordPress スタックを containerd 上で再現する教材であり、本番の WordPress 運用手順ではない。

コマンドが docker と似ているからといって、ソケットが Docker Engine を向いているわけではない。相手は containerd である。

alpine を消えるコンテナとして走らせる例は、導入直後の最小確認に向く。イメージ名 foo は教材用で、レジストリへ push する手順はこの節に無い。type=local の出力は、コンテナを上げずにビルド成果だけ欲しいときの経路だ。compose-wordpress の YAML パスを間違えると、別ディレクトリの docker-compose.yaml を Docker Compose が読む、という取り違えが起きる。相手ランタイムはあくまで nerdctl 経由の containerd である。

nerdctl-full tarball と CNI/BuildKit の切れ目

Install 節のバイナリ置き場は https://github.com/containerd/nerdctl/releases である。nerdctl run には CNI plugins が要り、v1.1.0 以降を強く推奨する。nerdctl build には BuildKit（buildkitd が稼働）が任意依存で、v0.11.0 以降を強く推奨する。古い BuildKit では nerdctl system prune のキャッシュ削除が動かない、と README は書く。rootless には RootlessKit v0.10.0 以降、推奨は v3.0.0 以降。

これらの依存は nerdctl-full-<VERSION>-<OS>-<ARCH>.tar.gz に含まれ、nerdctl-<VERSION>-<OS>-<ARCH>.tar.gz には含まれない。薄いアーカイブだけ取って run が失敗するのは、この切れ目が原因になりやすい。

Linux では brew install nerdctl が可能だが、この brew 経路は macOS 非対応と明記されている。macOS は Lima を使い brew install lima、limactl start、lima nerdctl run -d --name nginx -p 127.0.0.1:8080:80 nginx:alpine。Windows は scoop install nerdctl。Linux コンテナは WSL2 で known to work。Windows コンテナは experimental。FreeBSD は docs/freebsd.md。

薄い tarball はバイナリだけ欲しい人向け、full は run と build をすぐ試す人向け、と README はファイル名で分けている。CNI プラグインの版が 1.1.0 未満だと run が苦しい、BuildKit が 0.11.0 未満だと prune が欠ける、RootlessKit が古いと rootless が欠ける。brew で Linux に入れる経路と、macOS で Lima を挟む経路を混同すると、lima 無しの nerdctl を mac のホストで直実行して詰まる。scoop の Windows は Linux コンテナが WSL2 前提で、Windows コンテナは実験扱いだ。

--namespace k8s.io で Kubernetes コンテナを覗く

Debugging Kubernetes 節は nerdctl --namespace k8s.io ps -a でローカルの Kubernetes コンテナを列挙する。レジストリ無しでローカル Kubernetes 向けにビルドする例は nerdctl --namespace k8s.io build -t foo ... のあと、imagePullPolicy: Never の Pod マニフェストを kubectl apply する流れだ。docker save 形式または OCI のアーカイブを取り込むのは nerdctl --namespace k8s.io load < /path/to/image.tar。ログ読みは experimental で、nerdctl --namespace=k8s.io logs -f <CONTAINER ID> の例に coredns が出てくる。

NOTE として、Kubernetes の Namespace とは無関係に、Kubernetes のコンテナはすべて containerd の k8s.io 名前空間に入る、と書いてある。kubectl get ns の名前で nerdctl --namespace を切っても、期待した Pod は出てこない。

第一目的はデバッグではない、という Motivation とこの節は両立する。クラスタ運用の主ツールを nerdctl に置き換える案内ではない。kubelet が使う runtime が containerd であるノードで、docker ps が空なのを見てから k8s.io を指定する、という使い方が README の例に近い。

docker ps が空でも、同じノードの kubelet が containerd を使っていれば k8s.io 側にコンテナがある。それがこの節の存在理由だ。imagePullPolicy: Never は、今ビルドしたタグをクラスタがレジストリへ取りに行かないための指定である。load は docker save 形式も OCI も受け付ける、と書いてある。logs -f が experimental なので、本番のログ基盤の代わりにはしない。coredns の例は出力イメージであり、自分のクラスタでも同じ CONTAINER ID になるわけではない。

Stargz と ocicrypt は Docker に無い major 機能

Features present in nerdctl but not present in Docker の Major は次である。lazy-pull は nerdctl --snapshotter=stargz|nydus|overlaybd|soci run IMAGE。暗号化は nerdctl image encrypt|decrypt SRC DST（ocicrypt / imgcrypt）。P2P 配布は nerdctl run ipfs://CID。cosign は nerdctl pull --verify=cosign と nerdctl push --sign=cosign、Compose 内の手順は docs/cosign.md。高速 rootless は nerdctl run --annotation nerdctl/bypass4netns=true。

Minor には --namespace=<NS> ps と、Docker/OCI のエクスポート（README 末尾が素材上途中で切れている）がある。IPFS は opt-in で、daemon を入れない限り P2P に接続しない、とここでも繰り返す。

これらの機能は snapshotter や別デーモンの追加導入が前提で、nerdctl バイナリ単体では完結しない。Stargz を試すなら docs/stargz.md、暗号化は docs/ocicrypt.md を README が指す。Docker Desktop の設定画面から同じスイッチは出ない。

snapshotter 名を run のたびに付けるのが README の例だ。既定の overlayfs のまま stargz 用イメージを上げても、lazy-pull にはならない。encrypt と decrypt は SRC と DST を取るサブコマンドで、通常の push とは別操作である。ipfs://CID は daemon が居るときだけ意味を持つ。bypass4netns のアノテーションは rootless のネットワーク経路を変える印で、rootful の既定には付かない。ドキュメントが切れている末尾（OCI エクスポート）は素材上不完全なので、その機能の詳細はここでは断定しない。

rootless セットアップと Docker の中で nerdctl を試す

Rootless mode 節は containerd-rootless-setuptool.sh install のあと、nerdctl run -d -p 8080:80 --name nginx nginx:alpine を例示し、docs/rootless.md へ送る。Docker の中で containerd と nerdctl を動かす例は docker build -t nerdctl . と docker run -it --rm --privileged nerdctl。特権コンテナが要る点は、この経路を CI の既定にしない理由になる。

向くのは k8s.io 名前空間で nerdctl logs -f を使いたい基盤担当と、Stargz lazy-pull を containerd で試すイメージ配信担当である。向かないのは Docker Desktop だけで足りるアプリ開発者と、CNI や BuildKit の追加導入を避けたい環境である。

確認は Releases の安定タグ（素材上 v2.3.5）または試すなら v2.4.0-beta.0 から nerdctl-full の linux 用 tarball を展開し、nerdctl run -it --rm alpine がシェルを返すこと、examples/compose-wordpress/docker-compose.yaml で compose up が起動することを見る。Kubernetes 連携を試すなら nerdctl --namespace k8s.io ps -a がノード上のコンテナ ID を列挙するか記録する。cosign と IPFS は各 docs を読んでから個別に有効化する。

rootless の install スクリプトは containerd 側のセットアップツールであり、nerdctl 本体の install とは別ファイルだ。privileged な Docker 入れ子は、手元で一気に試す近道だが、権限モデルが本番の rootless と違う。確認の順番は alpine の対話 run、compose-wordpress の up、必要なら k8s.io の ps、そのあと snapshotter だ。beta タグ v2.4.0-beta.0 を本番ノードの既定 PATH に置く理由は README に無い。安定の v2.3.5 で full アーカイブを固定する方が、日付の新しい beta より運用は単純である。

編集部の結論

Docker CLI の操作感のまま containerd の lazy-pull や k8s.io 名前空間のデバッグを試したい基盤エンジニア向けである。Docker Desktop だけで足りるアプリ開発者には向かない。GitHub Releases から nerdctl-full の tarball を取り CNI と BuildKit を揃え、nerdctl run -it --rm alpine と nerdctl compose -f examples/compose-wordpress/docker-compose.yaml up が通ることを確認してから Stargz や ocicrypt を足す。最新素材タグは v2.4.0-beta.0 と安定の v2.3.5 が並ぶので、本番には beta をそのまま置かない。

公式情報源

1. Official README
2. Project repository
3. Release notes