nerdctl README

The project's README from github.com/containerd/nerdctl. As one markdown file: README.md.

[⬇️ Download] [📖 Command reference] [❓FAQs & Troubleshooting] [📚 Additional documents]

nerdctl: Docker-compatible CLI for containerd

logo

nerdctl is a Docker-compatible CLI for containerd.

✅ Same UI/UX as docker

✅ Supports Docker Compose (nerdctl compose up)

✅ [Optional] Supports rootless mode, without slirp overhead (bypass4netns)

✅ [Optional] Supports lazy-pulling (Stargz, Nydus, OverlayBD)

✅ [Optional] Supports encrypted images (ocicrypt)

✅ [Optional] Supports P2P image distribution (IPFS) (*1)

✅ [Optional] Supports container image signing and verifying (cosign)

nerdctl is a non-core sub-project of containerd.

*1: P2P image distribution (IPFS) is completely optional. Your host is NOT connected to any P2P network, unless you opt in to install and run IPFS daemon.

Examples

Basic usage

To run a container with the default bridge CNI network (10.4.0.0/24):

# nerdctl run -it --rm alpine

To build an image using BuildKit:

# nerdctl build -t foo /some-dockerfile-directory
# nerdctl run -it --rm foo

To build and send output to a local directory using BuildKit:

# nerdctl build -o type=local,dest=. /some-dockerfile-directory

To run containers from docker-compose.yaml:

# nerdctl compose -f ./examples/compose-wordpress/docker-compose.yaml up

See also ./examples/compose-wordpress.

Debugging Kubernetes

To list local Kubernetes containers:

# nerdctl --namespace k8s.io ps -a

To build an image for local Kubernetes without using registry:

# nerdctl --namespace k8s.io build -t foo /some-dockerfile-directory
# kubectl apply -f - <<EOF
apiVersion: v1
kind: Pod
metadata:
  name: foo
spec:
  containers:
    - name: foo
      image: foo
      imagePullPolicy: Never
EOF

To load an image archive (docker save format or OCI format) into local Kubernetes:

# nerdctl --namespace k8s.io load < /path/to/image.tar

To read logs (experimental):

# nerdctl --namespace=k8s.io ps -a
CONTAINER ID    IMAGE                                                      COMMAND                   CREATED          STATUS    PORTS    NAMES
...
e8793b8cca8b    registry.k8s.io/coredns/coredns:v1.9.3                     "/coredns -conf /etc…"    2 minutes ago    Up                 k8s://kube-system/coredns-787d4945fb-mfx6b/coredns
...

# nerdctl --namespace=k8s.io logs -f e8793b8cca8b
[INFO] plugin/reload: Running configuration SHA512 = 591cf328cccc12bc490481273e738df59329c62c0b729d94e8b61db9961c2fa5f046dd37f1cf888b953814040d180f52594972691cd6ff41be96639138a43908
CoreDNS-1.9.3
linux/amd64, go1.18.2, 45b0a11
...

Rootless mode

To launch rootless containerd:

$ containerd-rootless-setuptool.sh install

To run a container with rootless containerd:

$ nerdctl run -d -p 8080:80 --name nginx nginx:alpine

See ./docs/rootless.md.

Install

Binaries are available here: https://github.com/containerd/nerdctl/releases

In addition to containerd, the following components should be installed:

These dependencies are included in nerdctl-full-<VERSION>-<OS>-<ARCH>.tar.gz, but not included in nerdctl-<VERSION>-<OS>-<ARCH>.tar.gz.

Brew

On Linux systems you can install nerdctl via brew:

brew install nerdctl

This is currently not supported for macOS. The section below shows how to install on macOS using brew.

macOS

Lima project provides Linux virtual machines for macOS, with built-in integration for nerdctl.

$ brew install lima
$ limactl start
$ lima nerdctl run -d --name nginx -p 127.0.0.1:8080:80 nginx:alpine

Windows

Install with Scoop:

scoop install nerdctl

Regarding compatibility, note that:

FreeBSD

See ./docs/freebsd.md.

Docker

To run containerd and nerdctl inside Docker:

docker build -t nerdctl .
docker run -it --rm --privileged nerdctl

Motivation

The goal of nerdctl is to facilitate experimenting the cutting-edge features of containerd that are not present in Docker (see below).

Note that competing with Docker is not the goal of nerdctl. Those cutting-edge features are expected to be eventually available in Docker as well.

Also, nerdctl might be potentially useful for debugging Kubernetes clusters, but it is not the primary goal.

Features present in nerdctl but not present in Docker

Major:

Minor:

Trivial:

Features implemented in nerdctl ahead of Docker

Similar tools

Developer guide

nerdctl is a containerd non-core sub-project, licensed under the Apache 2.0 license. As a containerd non-core sub-project, you will find the:

information in our containerd/project repository.

Compiling nerdctl from source

Run make && sudo make install.

See the header of go.mod for the minimum supported version of Go.

Using go install github.com/containerd/nerdctl/v2/cmd/nerdctl is possible, but unrecommended because it does not fill version strings printed in nerdctl version

Testing

See testing nerdctl.

Contributing to nerdctl

Lots of commands and flags are currently missing. Pull requests are highly welcome.

Please certify your Developer Certificate of Origin (DCO), by signing off your commit with git commit -s and with your real name.

Command reference

Moved to ./docs/command-reference.md

Additional documents

Configuration guide:

Basic features:

Advanced features:

Experimental features:

Implementation details:

Misc:

nerdctl (containerd/nerdctl)

Searching Database…

10.4K ·GitHub
Nerdctl
Что это такое?nerdctl — это клиент командной строки, совместимый с Docker, для containerd. Он даёт тот же интерфейс в стиле docker и при этом открывает функции, специфичные для containerd, которых нет в Docker.
Это замена docker CLI или он работает рядом с ним?Это самостоятельный бинарный файл командной строки (команда nerdctl), который напрямую работает с containerd. Его команды и флаги повторяют команды Docker, так что можно использовать, например, 'nerdctl run' или 'nerdctl compose up' вместо их аналогов из docker.
Как установить и начать пользоваться?Скачайте готовый бинарник (полный или минимальный архив tar.gz), либо установите через Homebrew в Linux, Scoop в Windows или Lima в macOS (она запускает nerdctl внутри виртуальной машины Linux). Также можно собрать из исходников командой 'make && sudo make install'.
Нужно ли, чтобы containerd уже работал, или nerdctl приносит собственный демон?nerdctl — это только клиент, ему нужен запущенный демон containerd (а для режима rootless — отдельный экземпляр containerd в rootless-режиме). Если не хочется устанавливать containerd отдельно, можно запустить containerd и nerdctl вместе внутри Docker.
На macOS и Windows работает так же, как на Linux?Полная нативная поддержка есть только в Linux. На macOS для запуска виртуальной машины Linux нужна Lima, а в Windows контейнеры Linux работают через WSL2, тогда как нативная поддержка контейнеров Windows пока экспериментальная.
Кто на самом деле будет использовать это вместо Docker?Разработчики, которые хотят опробовать новейшие возможности containerd (ленивую загрузку образов, шифрование образов, распространение через IPFS, отладку контейнеров Kubernetes), которых пока нет в Docker, и при этом сохранить знакомый интерфейс, похожий на Docker.
Если я не хочу никакой P2P-сети, IPFS включается принудительно?Нет, распространение образов через IPFS полностью необязательное. Ваш компьютер не подключается ни к какой P2P-сети, пока вы сами намеренно не установите и не запустите демон IPFS.
Могут ли контейнеры использовать GPU через nerdctl?Да, есть отдельная документация по использованию GPU внутри контейнеров, запущенных с помощью nerdctl.
Какие функции, эксклюзивные для containerd, открывает nerdctl и которых нет в Docker?Ленивую загрузку образов по требованию через снапшоттеры Stargz, Nydus, OverlayBD и SOCI, шифрование и расшифровку образов с помощью ocicrypt, подпись и проверку образов через cosign, ускоренную сеть в rootless-режиме через bypass4netns, а также подключение контейнера сразу к нескольким сетям.
Может ли nerdctl помочь отлаживать контейнеры Kubernetes?Да, с помощью nerdctl можно просматривать, собирать и загружать образы для локальных кластеров Kubernetes, а также читать логи контейнеров, так как все контейнеры Kubernetes находятся в пространстве имён containerd k8s.io.
Чем nerdctl отличается от утилит containerd ctr и crictl?В отличие от ctr и crictl, nerdctl совместим с командами Docker CLI и удобнее в использовании. Он поддерживает публикацию портов, политики перезапуска, сборку, логи и Docker Compose, чего ctr и crictl не предлагают.
Поддерживает ли nerdctl файлы Docker Compose?Да, он реализует команду 'nerdctl compose up' и связанные с ней команды, чтобы напрямую запускать файлы docker-compose.yaml через containerd.
What are similar projects?containerd, lima, skopeo, compose, podman, colima, harbor, public-image-mirror
Which topics is it in?containerd, registry, p2p, containers, compiler, orchestration, encryption, kubernetes, devops, go, command-line-tool, security
Creator
containerd
Size
15 MB
Stars
10.4K
Updated
CommitOct 16Releasev2.4.1Oct 02
Age
5y
Commits · 90 Days