{"id":13491316,"url":"https://github.com/afbjorklund/nerdctld","last_synced_at":"2025-03-17T06:32:00.737Z","repository":{"id":37407514,"uuid":"466718067","full_name":"afbjorklund/nerdctld","owner":"afbjorklund","description":"nerdctl daemon (Docker API)","archived":false,"fork":false,"pushed_at":"2024-12-08T09:16:05.000Z","size":409,"stargazers_count":38,"open_issues_count":5,"forks_count":4,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-10T22:33:03.586Z","etag":null,"topics":["buildkit","containerd","docker","nerdctl"],"latest_commit_sha":null,"homepage":"https://github.com/containerd/nerdctl/issues/798","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/afbjorklund.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-03-06T11:33:25.000Z","updated_at":"2025-01-01T06:51:53.000Z","dependencies_parsed_at":"2023-02-19T00:01:35.903Z","dependency_job_id":"9c04cebb-743a-4bde-8ced-b8617e9019c7","html_url":"https://github.com/afbjorklund/nerdctld","commit_stats":{"total_commits":106,"total_committers":1,"mean_commits":106.0,"dds":0.0,"last_synced_commit":"636fe1b816adacd523423be5908ab407f1225ea8"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afbjorklund%2Fnerdctld","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afbjorklund%2Fnerdctld/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afbjorklund%2Fnerdctld/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afbjorklund%2Fnerdctld/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/afbjorklund","download_url":"https://codeload.github.com/afbjorklund/nerdctld/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243847061,"owners_count":20357317,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["buildkit","containerd","docker","nerdctl"],"created_at":"2024-07-31T19:00:55.555Z","updated_at":"2025-03-17T06:31:59.579Z","avatar_url":"https://github.com/afbjorklund.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# nerdctld\n\n![nerd daemon](nerdctld.png)\n\nThis is a daemon offering a `nerdctl.sock` endpoint.\n\nIt can be used with `DOCKER_HOST=unix://nerdctl.sock`.\n\n| :exclamation: Currently it mostly handles the images, for containerd k8s clusters. |\n|----------------------------------------------------------------------------------- |\n| There is some limited information about version and info, containers and volumes.  |\n\nNormally the `nerdctl` tool is a CLI-only application.\n\nA client for the `containerd` and `buildkitd` servers.\n\n\u003chttps://github.com/containerd/nerdctl\u003e\n\n\u003chttps://github.com/docker/cli\u003e `docker`\n\n## Docker API\n\nThe Docker API (REST) is available at:\n\n\u003chttps://docs.docker.com/engine/api/\u003e\n\nDocker version | API version\n--- | ---\n25.0 | 1.44\n24.0 | 1.43\n23.0 | 1.42\n... | ...\n20.10 | 1.41\n19.03 | 1.40\n18.09 | 1.39\n... | ...\n17.03 | 1.26\n1.13 | 1.25\n1.12 | 1.24\n\n## Diagram\n\n![diagram](diagram.png)\n\n* `docker.sock`\n* `nerdctl.sock`\n* `containerd.sock`\n* `buildkitd.sock`\n\n## Debugging\n\nTo start the nerdctl daemon in debugging mode:\n\n```shell\n./nerdctld --debug\n```\n\nIn another shell, you can communicate with it:\n\n```shell\nDOCKER_HOST=unix://nerdctl.sock docker version\n```\n\nYou can use cURL for talking HTTP to a Unix socket:\n\n`curl --unix-socket /var/run/docker.sock http://localhost:2375/_ping`\n\nThis can be useful to see what happens under the hood.\n\nNote: replace the socket path, with the one you want.\n\n## Running daemon\n\n### user containerd\n\n```console\n$ nerdctl version\n...\n```\n\n`systemctl --user start nerdctl.socket`\n\n```shell\nDOCKER_HOST=unix://$XDG_RUNTIME_DIR/nerdctl.sock docker version\n```\n\n### system containerd\n\n```console\n$ sudo nerdctl version\n...\n```\n\n`sudo systemctl --system start nerdctl.socket`\n\n```shell\nsudo DOCKER_HOST=unix:///var/run/nerdctl.sock docker version\n```\n\nIf you wanted to grant all users in the group \"nerdctl\" access:\n\n/etc/systemd/system/nerdctl.socket.d/10-group.conf\n\n```desktop\n[Socket]\nUMask=0007\nGroup=nerdctl\n```\n\nThis would allow access without using `sudo` (or being `root`).\n\n#### **Warning**\n\nThis `nerdctl` group grants privileges equivalent to the `root` user.\n\nCompare with the `docker` group for the docker daemon (`dockerd`):\n\n\u003chttps://docs.docker.com/engine/security/#docker-daemon-attack-surface\u003e\n\nTo run nerdctl without root privileges, see rootless (user) mode above.\n\n## BuildKit\n\nYou probably want BuildKit to use the \"containerd\" worker.\n\nInstead of the default \"OCI\" worker, which only uses runc.\n\n/etc/buildkit/buildkitd.toml\n\n```toml\n[worker.oci]\n  enabled = false\n\n[worker.containerd]\n  enabled = true\n  namespace = \"default\"\n```\n\nThis enables buildkitd to use the containerd images directly.\n\nIt also saves having to save and load images, after building.\n\nSee: \u003chttps://github.com/containerd/nerdctl/blob/main/docs/build.md\u003e\n\n## Kubernetes\n\nIn order to see the Kubernetes containers and images,\nyou will need to change the containerd \"namespace\":\n\n/etc/systemd/system/nerdctl.service.d/10-namespace.conf\n\n```desktop\n[Service]\nEnvironment=CONTAINERD_NAMESPACE=k8s.io\n```\n\nYou could also use the Kubernetes tool called `crictl`,\nand configure it to talk to the \"containerd\" runtime:\n\n/etc/crictl.yaml\n\n```yaml\nruntime-endpoint: unix:///run/containerd/containerd.sock\n```\n\n\u003chttps://github.com/kubernetes-sigs/cri-tools\u003e\n\nOne difference is that nerdctl shows the repo digest as ID,\nwhereas `crictl images` shows the image ID as the image ID:\n\n```\nREPOSITORY                                 TAG        IMAGE ID        CREATED              PLATFORM       SIZE         BLOB SIZE\nregistry.k8s.io/pause                      3.8        900118502363    About an hour ago    linux/amd64    700.0 KiB    304.0 KiB\nregistry.k8s.io/pause                      \u003cnone\u003e     900118502363    About an hour ago    linux/amd64    700.0 KiB    304.0 KiB\nregistry.k8s.io/kube-apiserver             v1.25.1    4f261d18da8d    About an hour ago    linux/amd64    125.5 MiB    32.6 MiB\nregistry.k8s.io/kube-apiserver             \u003cnone\u003e     4f261d18da8d    About an hour ago    linux/amd64    125.5 MiB    32.6 MiB\n```\n\n```\nIMAGE                                     TAG                 IMAGE ID            SIZE\nregistry.k8s.io/pause                     3.8                 4873874c08efc       311kB\nregistry.k8s.io/kube-apiserver            v1.25.1             b09a3dc327be2       34.2MB\n```\n\nAnother difference is that nerdctl shows \"pause\" containers,\nbut these sandbox images are hidden in `crictl ps` output:\n\n```\nCONTAINER ID    IMAGE                                              COMMAND                   CREATED              STATUS    PORTS    NAMES\n669b48948f93    registry.k8s.io/pause:3.8                          \"/pause\"                  About an hour ago    Up                 k8s://kube-system/kube-apiserver-lima-k8s\n8b960604e6d2    registry.k8s.io/kube-apiserver:v1.25.1             \"kube-apiserver --ad…\"    About an hour ago    Up                 k8s://kube-system/kube-apiserver-lima-k8s/kube-apiserver\n```\n\n```\nCONTAINER           IMAGE               CREATED             STATE               NAME                      ATTEMPT             POD ID              POD\n8b960604e6d29       b09a3dc327be2       About an hour ago   Running             kube-apiserver            0                   669b48948f931       kube-apiserver-lima-k8s\n```\n\n### Using nerdctld with kind\n\nWhen using `kind`, it is possible to mount the API socket.\nBut it is hard to do it as a regular file, when starting.\n\nWhat usually happens is that \"nerdctl.sock\" becomes a dir,\nand then it fails to mount the unix socket (file) over it.\n\nWorkaround: Create a subdirectory, to host the socket:\n\n```desktop\n[Socket]\nListenStream=%t/nerdctl/nerdctl.sock\n```\n\nAnd then you can mount this directory, in the kind.yaml:\n\n```yaml\nkind: Cluster\napiVersion: kind.x-k8s.io/v1alpha4\nnodes:\n- role: control-plane\n  extraMounts:\n  - hostPath: /tmp/nerdctl\n    containerPath: /run/nerdctl\n```\n\nThen it can be accessed from the host, using the path:\n\n```bash\nexport DOCKER_HOST=unix:///tmp/nerdctl/nerdctl.sock\n```\n\nMake sure to change to the `k8s.io` namespace, see above.\nAnd to use `DOCKER_BUILDKIT=0` (ironically), if building.\n\nYou probably also want to use the \"containerd\" worker:\n\n/etc/buildkit/buildkitd.toml\n\n```toml\n[worker.oci]\n  enabled = false\n[worker.containerd]\n  enabled = true\n  namespace = \"k8s.io\"\n```\n\nSo that your image is instantly available, without loading.\n\nNote: You _have_ to add a registry prefix, for Kubernetes.\n\n```bash\nDOCKER_BUILDKIT=0 docker build -t docker.io/myimage .\n```\n\nOtherwise, it will not be able to find your image later...\n\n### Using nerdctld with k3s\n\nThe containerd socket is available in a different path:\n\n```shell\nCONTAINERD_ADDRESS=unix:///run/k3s/containerd/containerd.sock\n```\n\n## Remote socket\n\nCalling the socket over `ssh:` requires a program:\n\n`docker system dial-stdio`\n\nIt is possible to replace it with a small wrapper:\n\n`socat - nerdctl.sock`\n\nBut the feature is **not** available in `nerdctl` (yet):\n\n```\nFATA[0000] unknown subcommand \"dial-stdio\" for \"system\"\n```\n\nAnd the ssh command has been hardcoded to call \"docker\":\n\n```go\nsp.Args(\"docker\", \"system\", \"dial-stdio\")\n```\n\nIncluded is a small `nerdctl` shell wrapper for `docker`.\n\nIt will forward `docker`, to `nerdctl` or `nerdctl.sock`.\n\nMake sure to set the DOCKER_HOST variable, for the user:\n\n~/.bashrc\n\n```bash\nexport DOCKER_HOST=unix:///var/run/nerdctl.sock\n```\n\nOr the rootless socket, see above for details.\n\n## Implementation\n\nThis program uses the \"Gin\" web framework for HTTP.\n\nIt and docs can be found at \u003chttps://gin-gonic.com/\u003e with some nice [examples](https://github.com/gin-gonic/examples)\n\n## Not to be implemented\n\n* buildx*     Docker Buildx\n* compose*    Docker Compose\n* node        Manage Swarm nodes\n* swarm       Manage Swarm\n\n## Implemented commands\n\n* version\n* info (system info)\n* ps (container ls)\n* inspect (container inspect)\n* logs (container logs)\n* images (image ls)\n* inspect (image inspect)\n* history (image history)\n* load (image load)\n* pull (image pull)\n* push (image push)\n* rmi (image rm)\n* save (image save)\n* tag (image tag)\n* volume ls\n* volume inspect\n* network ls\n* network inspect\n* build\n\nNote: using \"build\" requires the `buildctl` client.\n\nIt also requires a running moby `buildkitd` server.\n\n* \u003chttps://github.com/containerd/containerd\u003e\n\n* \u003chttps://github.com/moby/buildkit\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fafbjorklund%2Fnerdctld","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fafbjorklund%2Fnerdctld","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fafbjorklund%2Fnerdctld/lists"}