README
¶
Lepton
lepton is an experimental containerd cli.
Requires:
- containerd 2.0+
- golang 1.23+
- cni plugins 1.6+
- cgroup v2 (see https://rootlesscontaine.rs/getting-started/common/cgroup2/)
Project goals
- provide a ready-to-use library to easily build cli and applications communicating with containerd
- provide a reference cli implementation, comparable to the docker cli or to nerdctl
- primary focus is on stability and code quality, not on features
Detailed relationship with nerdctl, and current status
Nerdctl objective is to provide a fully docker compatible experience with many advanced or experimental additional features. As a mature project, it is also conservatively (and rightfully) focused on backward compatibility.
Lepton departs from this in a few important ways:
- docker cli compatibility is best-effort, and will be broken where it makes sense
- before 1.0, there should be no expectation of backward compatibility - API will change, and only the latest versions of dependencies will be supported
- lepton is departing from the way nerdctl is storing data
- the current filesystem layout of nerdctl needs a rehaul
- lepton is removing support for unstable or otherwise experimental, or lesser used features
- this is meant to reduce maintenance burden, simplify code and increase quality
Furthermore, lepton overarching priority is to provide a clean SDK for people who want to author their own stuff, specifically with more expressive and cleaner error management, better storage abstractions, better performance, and better concurrency management.
Lepton started in 2024 as a private project, and was reset as a friendly fork of nerdctl, 14th of December 2024, from https://github.com/containerd/nerdctl/commit/7e97f0618ceb160b044e95810e17fccf21fea3df
As such, a large fraction of its codebase is indeed coming from https://github.com/containerd/nerdctl (copyright The Containerd Authors, licensed under the Apache License, see NOTICE).
Lepton is regularly cherry-picking changes from nerdctl, and conversely, so far, about 100k lines of code have been contributed back from lepton to nerdctl.
Unlike nerdctl, lepton does not support (and has removed from its codebase):
- freebsd
- stargz (partly)
- cvmfs
- overlaybd
- nydus
- IPFS
- cgroup v1
Also, lepton does not explicitly support and does not test anymore (might still work):
- containerd pre v2 (v1.7, v1.6)
- ubuntu 22.04 and earlier
So far, besides removal of unsupported code, lepton has been focused on cleanup, reviewing and moving "library" packages up into https://github.com/farcloser/go-containers, and UX review and sanity.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
leptonic
|
|
|
identifiers
Package identifiers provides common validation for identifiers and keys across containerd.
|
Package identifiers provides common validation for identifiers and keys across containerd. |
|
store
Package store provides a concurrency-safe lightweight storage solution with a simple interface.
|
Package store provides a concurrency-safe lightweight storage solution with a simple interface. |
|
Package pkg provides non-CLI packages.
|
Package pkg provides non-CLI packages. |
|
annotations
Package annotations defines OCI annotations
|
Package annotations defines OCI annotations |
|
containerdutil
Package containerdutil provides "caching" versions of containerd native snapshotter and content store.
|
Package containerdutil provides "caching" versions of containerd native snapshotter and content store. |
|
dnsutil/hostsstore
Package hostsstore provides the interface for /var/lib/nerdctl/<ADDRHASH>/etchosts Prioritizes simplicity over scalability.
|
Package hostsstore provides the interface for /var/lib/nerdctl/<ADDRHASH>/etchosts Prioritizes simplicity over scalability. |
|
imgutil/pull
Package pull forked from https://github.com/containerd/containerd/blob/v1.4.3/cmd/ctr/commands/content/fetch.go
|
Package pull forked from https://github.com/containerd/containerd/blob/v1.4.3/cmd/ctr/commands/content/fetch.go |
|
imgutil/push
Package push derived from https://github.com/containerd/containerd/blob/v1.4.3/cmd/ctr/commands/images/push.go
|
Package push derived from https://github.com/containerd/containerd/blob/v1.4.3/cmd/ctr/commands/images/push.go |
|
inspecttypes/dockercompat
Package dockercompat mimics `docker inspect` objects.
|
Package dockercompat mimics `docker inspect` objects. |
|
labels
Package labels defines labels that are set to containerd containers as labels.
|
Package labels defines labels that are set to containerd containers as labels. |
|
labels/k8slabels
Package k8slabels defines Kubernetes container labels
|
Package k8slabels defines Kubernetes container labels |
|
logging
Forked from https://github.com/kubernetes/kubernetes/blob/cc60b26dee4768e3c5aa0515bbf4ba1824ad38dc/staging/src/k8s.io/cri-client/pkg/logs/logs_other.go Copyright The Kubernetes Authors.
|
Forked from https://github.com/kubernetes/kubernetes/blob/cc60b26dee4768e3c5aa0515bbf4ba1824ad38dc/staging/src/k8s.io/cri-client/pkg/logs/logs_other.go Copyright The Kubernetes Authors. |
|
mountutil/volumestore
Package volumestore allows manipulating containers' volumes.
|
Package volumestore allows manipulating containers' volumes. |
|
namestore
Package namestore provides a simple store for containers to exclusively acquire and release names.
|
Package namestore provides a simple store for containers to exclusively acquire and release names. |
|
ocihook/state
Package state provides a store to retrieve and save container lifecycle related information This is typically used by oci-hooks for information that cannot be retrieved / updated otherwise Specifically, the state carries container start time, and transient information about possible failures during hook events processing.
|
Package state provides a store to retrieve and save container lifecycle related information This is typically used by oci-hooks for information that cannot be retrieved / updated otherwise Specifically, the state carries container start time, and transient information about possible failures during hook events processing. |
|
resolvconf
Package resolvconf provides utility code to query and update DNS configuration in /etc/resolv.conf originally from https://github.com/moby/moby/blob/6014c1e29dc34dffa77fb5749cc3281c1b4854ac/libnetwork/resolvconf/resolvconf.go
|
Package resolvconf provides utility code to query and update DNS configuration in /etc/resolv.conf originally from https://github.com/moby/moby/blob/6014c1e29dc34dffa77fb5749cc3281c1b4854ac/libnetwork/resolvconf/resolvconf.go |
|
testutil/portlock
portlock provides a mechanism for containers to acquire and release ports they plan to expose, and a wait mechanism This allows tests dependent on running containers to always parallelize without having to worry about port collision with any other test Note that this does NOT protect against trying to use a port that is already used by an unrelated third-party service or container Also note that *generally* finding a free port is not easy: - to just "listen" and see if it works won't work for containerized services that are DNAT-ed (plus, that would be racy) - inspecting iptables instead (or in addition to) may work for containers, but this depends on how networking has been set (and yes, it is also racy) Our approach here is optimistic: tests are responsible for calling Acquire and Release
|
portlock provides a mechanism for containers to acquire and release ports they plan to expose, and a wait mechanism This allows tests dependent on running containers to always parallelize without having to worry about port collision with any other test Note that this does NOT protect against trying to use a port that is already used by an unrelated third-party service or container Also note that *generally* finding a free port is not easy: - to just "listen" and see if it works won't work for containerized services that are DNAT-ed (plus, that would be racy) - inspecting iptables instead (or in addition to) may work for containers, but this depends on how networking has been set (and yes, it is also racy) Our approach here is optimistic: tests are responsible for calling Acquire and Release |
Click to show internal directories.
Click to hide internal directories.