sal/src/virt/nerdctl/nerdctl-essentials.md

nerdctl Essentials

This guide provides a comprehensive overview of essential nerdctl functionality to help you get started quickly. nerdctl is a Docker-compatible CLI for containerd, with additional features specifically designed for containerd environments.

Introduction

nerdctl is a Docker-compatible CLI for containerd. It provides the same user experience as the Docker CLI (docker) but leverages the more efficient containerd container runtime. Key differences and advantages include:

• Direct integration with containerd (no extra daemon required)
• Support for containerd-specific features
• First-class support for rootless mode
• Compatibility with Docker commands
• Additional nerdctl-specific commands

Basic Configuration

nerdctl can be configured using the nerdctl.toml configuration file:

• Rootful mode: /etc/nerdctl/nerdctl.toml
• Rootless mode: ~/.config/nerdctl/nerdctl.toml

Example configuration:

debug = false
debug_full = false
address = "unix:///run/containerd/containerd.sock"
namespace = "default"
snapshotter = "overlayfs"
cgroup_manager = "systemd"
hosts_dir = ["/etc/containerd/certs.d", "/etc/docker/certs.d"]

Common configuration properties:

Property	CLI Flag	Description
address	--address, --host, -a, -H	containerd address
namespace	--namespace, -n	containerd namespace
snapshotter	--snapshotter	containerd snapshotter
cni_path	--cni-path	CNI binary directory
data_root	--data-root	Persistent state directory
insecure_registry	--insecure-registry	Allow insecure registry

Container Management

Running Containers

Run a container:

nerdctl run [OPTIONS] IMAGE [COMMAND] [ARG...]

Common options:

• -i, --interactive: Keep STDIN open
• -t, --tty: Allocate a pseudo-TTY
• -d, --detach: Run container in background
• --name: Assign a name to the container
• -p, --publish: Publish container's port to the host
• -v, --volume: Bind mount a volume
• -e, --env: Set environment variables
• --rm: Automatically remove the container when it exits
• --restart=(no|always|on-failure|unless-stopped): Restart policy
• --net, --network: Connect container to a network

Examples:

# Run an interactive container and automatically remove it when it exits
nerdctl run -it --rm alpine sh

# Run a detached container with port mapping
nerdctl run -d --name nginx -p 8080:80 nginx

# Run a container with a volume mount
nerdctl run -it --rm -v $(pwd):/data alpine ls /data

Managing Containers

List containers:

nerdctl ps [OPTIONS]

Options:

• -a, --all: Show all containers (default shows just running)
• -q, --quiet: Only display container IDs
• -s, --size: Display total file sizes

Stop a container:

nerdctl stop [OPTIONS] CONTAINER [CONTAINER...]

Start a container:

nerdctl start [OPTIONS] CONTAINER [CONTAINER...]

Remove a container:

nerdctl rm [OPTIONS] CONTAINER [CONTAINER...]

Options:

• -f, --force: Force removal of running container
• -v, --volumes: Remove anonymous volumes

View container logs:

nerdctl logs [OPTIONS] CONTAINER

Options:

• -f, --follow: Follow log output
• --since: Show logs since timestamp
• -t, --timestamps: Show timestamps
• -n, --tail: Number of lines to show from the end of logs

Execute a command in a running container:

nerdctl exec [OPTIONS] CONTAINER COMMAND [ARG...]

Options:

• -i, --interactive: Keep STDIN open
• -t, --tty: Allocate a pseudo-TTY
• -d, --detach: Detached mode
• -w, --workdir: Working directory
• -e, --env: Set environment variables

Image Management

Working with Images

List images:

nerdctl images [OPTIONS]

Options:

• -a, --all: Show all images
• -q, --quiet: Only show numeric IDs
• --digests: Show digests

Pull an image:

nerdctl pull [OPTIONS] NAME[:TAG|@DIGEST]

Options:

• --platform=(amd64|arm64|...): Pull content for specific platform
• -q, --quiet: Suppress verbose output

Push an image:

nerdctl push [OPTIONS] NAME[:TAG]

Build an image:

nerdctl build [OPTIONS] PATH

Options:

• -t, --tag: Name and optionally tag the image
• -f, --file: Name of the Dockerfile
• --build-arg: Set build-time variables
• --no-cache: Do not use cache when building

Remove an image:

nerdctl rmi [OPTIONS] IMAGE [IMAGE...]

Options:

• -f, --force: Force removal

Tag an image:

nerdctl tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]

Save an image to a tar archive:

nerdctl save [OPTIONS] IMAGE [IMAGE...]

Options:

• -o, --output: Write to a file

Load an image from a tar archive:

nerdctl load [OPTIONS]

Options:

• -i, --input: Read from a tar archive file

Network Management

Working with Networks

List networks:

nerdctl network ls [OPTIONS]

Create a network:

nerdctl network create [OPTIONS] NETWORK

Common options:

• -d, --driver=(bridge|macvlan|ipvlan): Driver to manage the network
• --subnet: Subnet in CIDR format (e.g., "10.5.0.0/16")
• --gateway: Gateway for the subnet
• --ipam-driver=(default|host-local|dhcp): IP address management driver

Remove a network:

nerdctl network rm NETWORK [NETWORK...]

Inspect a network:

nerdctl network inspect [OPTIONS] NETWORK [NETWORK...]

Prune networks:

nerdctl network prune [OPTIONS]

Network Types

nerdctl supports the following network types:

• bridge (default on Linux): Creates a bridge interface on the host
• host: Uses the host's network stack
• none: No networking
• macvlan: Connects container interfaces directly to host interfaces
• ipvlan: Similar to macvlan but shares host's IP address

Example creating a macvlan network:

nerdctl network create macnet --driver macvlan \
  --subnet=192.168.5.0/24 \
  --gateway=192.168.5.1 \
  -o parent=eth0

Volume Management

Working with Volumes

List volumes:

nerdctl volume ls [OPTIONS]

Create a volume:

nerdctl volume create [OPTIONS] [VOLUME]

Remove a volume:

nerdctl volume rm [OPTIONS] VOLUME [VOLUME...]

Inspect a volume:

nerdctl volume inspect [OPTIONS] VOLUME [VOLUME...]

Prune volumes:

nerdctl volume prune [OPTIONS]

Volume Flags for Containers

Volume-related flags when running containers:

• -v, --volume: Bind mount a volume (format: SRC:DST[:OPTIONS])
• --mount: Attach a filesystem mount to the container
• --tmpfs: Mount a tmpfs directory

Volume options:

• rw: Read/write (default)
• ro: Read-only
• rro: Recursive read-only (kernel >= 5.12)
• shared, slave, private: Non-recursive propagation
• rshared, rslave, rprivate: Recursive propagation

Examples:

# Mount a host directory
nerdctl run -it --rm -v /host/path:/container/path:ro alpine ls /container/path

# Use tmpfs
nerdctl run -it --rm --tmpfs /tmp:size=64m,exec alpine ls /tmp

Compose

nerdctl includes Docker Compose compatibility, allowing you to define and run multi-container applications.

Run Compose applications:

nerdctl compose up [OPTIONS]

Options:

• -d, --detach: Run containers in the background
• --build: Build images before starting containers
• --no-build: Don't build images, even if they're missing
• --force-recreate: Force recreation of containers

Stop Compose applications:

nerdctl compose down [OPTIONS]

Options:

• -v, --volumes: Remove named volumes and anonymous volumes

View Compose logs:

nerdctl compose logs [OPTIONS] [SERVICE...]

Other Compose commands:

• nerdctl compose build: Build service images
• nerdctl compose ps: List containers
• nerdctl compose pull: Pull service images
• nerdctl compose exec: Execute a command in a running container
• nerdctl compose restart: Restart services

Example compose.yml:

version: "3.8"
services:
  web:
    image: nginx
    ports:
      - "8080:80"
    volumes:
      - ./html:/usr/share/nginx/html
  db:
    image: postgres
    environment:
      POSTGRES_PASSWORD: example
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:

Rootless Mode

nerdctl supports rootless containers, allowing unprivileged users to create and manage containers. This provides better security isolation compared to running everything as root.

Setup Rootless Mode

1. Install required dependencies (see https://rootlesscontaine.rs/getting-started/common/)
2. Set up rootless containerd:

   containerd-rootless-setuptool.sh install
   

3. Enable lingering for your user (to keep services running after logout):

   sudo loginctl enable-linger $(whoami)
   

4. For building images, install BuildKit in rootless mode:

   containerd-rootless-setuptool.sh install-buildkit
   

When running in rootless mode, nerdctl automatically uses the appropriate socket and configuration.

Limitations and Considerations

• Resource limits require cgroup v2 and systemd
• By default, ports below 1024 cannot be published (use slirp4netns port driver or configure capabilities)
• Some file system operations might be restricted
• Network performance can be slower (consider using bypass4netns to improve performance)

Registry Authentication

nerdctl uses the same authentication configuration as Docker, located in ${DOCKER_CONFIG}/config.json (default: $HOME/.docker/config.json).

Log in to a registry:

nerdctl login [OPTIONS] [SERVER]

Options:

• -u, --username: Username
• -p, --password: Password
• --password-stdin: Take the password from stdin

Log out from a registry:

nerdctl logout [SERVER]

Registry Certificates

For private registries with custom certificates, place certificates in:

• Rootful: /etc/containerd/certs.d/<HOST:PORT>/ or /etc/docker/certs.d/<HOST:PORT>/
• Rootless: ~/.config/containerd/certs.d/<HOST:PORT>/ or ~/.config/docker/certs.d/<HOST:PORT>/

Advanced Features

GPU Support

nerdctl supports NVIDIA GPU passthrough to containers:

nerdctl run -it --rm --gpus all nvidia/cuda:12.3.1-base-ubuntu20.04 nvidia-smi

Options for --gpus:

• all: Use all available GPUs
• Custom configuration: --gpus '"capabilities=utility,compute",device=GPU-UUID'

BuildKit Integration

BuildKit provides advanced image building capabilities:

1. Set up BuildKit (different for rootful and rootless):

   # Rootless with containerd worker
   CONTAINERD_NAMESPACE=default containerd-rootless-setuptool.sh install-buildkit-containerd
   

2. Use advanced build features:

   nerdctl build --output=type=local,dest=./output --platform=linux/amd64,linux/arm64 .
   

Namespace Management

Create a namespace:

nerdctl namespace create NAMESPACE

List namespaces:

nerdctl namespace ls

Remove a namespace:

nerdctl namespace remove NAMESPACE

Security Features

nerdctl supports various security features:

• --security-opt seccomp=profile.json: Apply a seccomp profile
• --security-opt apparmor=profile: Apply an AppArmor profile
• --cap-add/--cap-drop: Add or drop Linux capabilities
• --privileged: Give extended privileges to the container