DOCSEARCHbyAlgolia
Submit Docs

nerdctl Documentation

repository·main·Indexed 27 days ago

https://github.com/containerd/nerdctl

nerdctl is a Docker-compatible CLI for containerd that provides a familiar UI/UX while enabling access to advanced containerd features such as lazy-pulling, image encryption, and Kubernetes namespace debugging. It supports BuildKit for image building, Docker Compose for orchestration, and rootless mode via RootlessKit.

Tokens
38.9K
Snippets
105
Records
233
Agent score
94%

What's inside nerdctl

  1. Build nerdctl from source

    main

    To build nerdctl, use the provided Makefile. Using make is recommended over go build because it correctly populates the version string, allowing nerdctl -v to work correctly.

    After building, you can install the binary to your system using sudo make install.

    make
sudo make install

  2. Sign container images with cosign during push

    main

    You can sign container images while pushing them to a registry using the nerdctl push command with the --sign flag. This requires the cosign executable to be in your $PATH and nerdctl >= 0.15.

    Keyless Signing

    Use Keyless mode to sign images without managing local key pairs. This uses ephemeral keys and certificates via Fulcio and Rekor.

    Key-pair Signing

    To sign using a local key pair, generate keys with cosign generate-key-pair and provide the private key using the --cosign-key flag.

    # Sign the image with Keyless mode
$ nerdctl push --sign=cosign devopps/hello-world

# Sign the image and store the signature in the registry using a local key
$ nerdctl push --sign=cosign --cosign-key cosign.key devopps/hello-world

  3. Use `pkg/store` for persistent data storage in nerdctl development

    main

    If you are developing features for nerdctl that require storing persistent information (e.g., metadata, lifecycle info), use the pkg/store package. This package provides a storage abstraction designed to handle filesystem-based storage reliably, specifically addressing challenges like incomplete writes and concurrency.

    Key Guarantees:

    • Atomic Writes: Uses a temporary file and the rename syscall to ensure writes are atomic. This prevents corrupted files in the event of an application crash or interrupted write.
      • Note: Atomic writes change the inode. If a file is mounted inside a container, an atomic write will not propagate changes to the container.
    • Concurrency Safety: Provides mechanisms to handle concurrency between goroutines and between distinct binary invocations using filesystem locks (flock).

    Important Implementation Rules:

    • Manual Locking Required: The core store API does not lock automatically. You must manage locks yourself to ensure atomicity across multiple operations (e.g., checking if a resource exists before creating it).
    • Locking Scope: Always lock the smallest possible segment. A store should only lock resources under the specific namespace being manipulated to avoid global performance bottlenecks.
    • Safety Checks: Methods that require a lock will fail loudly if a lock is not detected.

  5. Build Nydus images using `nerdctl image convert`

    main

    You can convert OCI or Docker format v2 images into Nydus images using the nerdctl image convert command.

    Prerequisites

    Conversion Workflow

    1. Convert: Run the conversion command specifying the path to the nydus-image binary.
    2. Push: Since converted images cannot be run directly, you must push the converted image to a registry.
    3. Pull & Unpack: Use nerdctl --snapshotter nydus image pull to unpack the image into the Nydus snapshotter before running it.

    Command Syntax

    Use the following flags:

    • --nydus: Enables Nydus conversion.
    • --oci: Specifies OCI format.
    • --nydus-builder-path <path>: The filesystem path to the nydus-image binary.
    nerdctl image convert --nydus --oci --nydus-builder-path <the_path_of_nydus_image_binary> <source_image> <target_image>

  7. Perform development tasks with Tigron

    main

    Use the following make commands to manage dependencies, format code, and run tests within the Tigron environment:

    • Update dependencies: make up
    • Format code (re-order imports, gofmt, go mod tidy, etc.): make fix
    • Run linters: make lint
    • Run tests: make test
    # Update dependencies
make up

# Re-order imports, gofmt, go mod tidy, etc
make fix

# Ensure linters are happy
make lint

# Run tests
make test

  9. Configure container networking with CNI

    main

    nerdctl uses CNI (Container Network Interface) plugins for container networking. You can specify a network using the --network or --net option when running containers.

    Default Networks:

    • Linux: The default network is bridge.
    • Windows: The default network is nat.

    Supported Basic CNI Plugins (Linux):

    • bridge
    • portmap
    • firewall
    • tuning

  10. Set up CernVM-FS Snapshotter for lazy-pulling

    main

    CernVM-FS Snapshotter is a containerd snapshotter plugin that enables lazy-pulling by assembling container image layers into a stacked file system.

    Prerequisites

    1. Install the cvmfs-snapshotter remote snapshotter plugin.
    2. Configure /etc/containerd/config.toml to use the snapshotter and define the communication endpoint.
    3. (Optional) Configure a custom CernVM-FS repository in /etc/containerd-cvmfs-grpc/config.toml.
    4. Start the required services.

    Configuration Steps

    1. Configure containerd

    Add the following to /etc/containerd/config.toml to instruct containerd to use the cvmfs-snapshotter and set the gRPC proxy plugin address:

    [plugins."io.containerd.grpc.v1.cri".containerd]
    snapshotter = "cvmfs-snapshotter"
    disable_snapshot_annotations = false

[proxy_plugins]
    [proxy_plugins.cvmfs]
        type = "snapshot"
        address = "/run/containerd-cvmfs-grpc/containerd-cvmfs-grpc.sock"

    2. Configure CernVM-FS Repository

    The default repository is unpacked.cern.ch. To use a different repository, add the following to /etc/containerd-cvmfs-grpc/config.toml:

    repository = "myrepo.mydomain"

    3. Start Services

    Launch both containerd and cvmfs-snapshotter using systemd:

    systemctl start containerd cvmfs-snapshotter

  11. Push images to Amazon ECR

    main

    After creating a repository in the AWS ECR console, tag your image with the ECR endpoint and push it.

    $ nerdctl tag hello-world <AWS_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com/<REPO>
$ nerdctl push <AWS_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com/<REPO>