nix-snapshotter

[![Go 参考][go-reference-badge]][go-reference] [![CI][ci-badge]][ci] [![Go 报告卡][go-report-card-badge]][go-report-card]

为 [containerd][containerd] 带来对 [Nix][nix] 包的原生理解。

主要特性 • 快速入门 • 安装 • [架构][architecture] • 贡献

</div>

主要特性

软件包直接来自 Nix 存储，而不是下载镜像层。
可以从 Nix 二进制缓存获取包或即时构建。
向后兼容现有的非 Nix 镜像。
Nix-snapshotter 层可以与普通层交错使用。
提供 [CRI][cri] 镜像服务，允许 Kubernetes 从 Nix 存储"拉取镜像"，使您无需 Docker 注册表即可运行容器。
完全声明式的 Kubernetes 资源，其中镜像引用是 Nix 存储路径。

Nix 是一个包管理器/构建系统，它完全理解每个包的构建和运行时依赖。Nix 包存储在一个全局哈希路径中，如：/nix/store/s66mzxpvicwk07gjbjfw9izjfa797vsw-hello-2.12.1。包通常遵循 FHS 约定，所以 Nix 包通常是包含其他目录（如 bin、share 等）的目录。例如，hello 二进制文件可以通过 /nix/store/s66mzxpvicwk07gjbjfw9izjfa797vsw-hello-2.12.1/bin/hello 访问。

运行时依赖（包括 glibc）也在 /nix/store 中，因此它真正具有完整的依赖图。以 hello 为例，完整的闭包如下：

/nix/store/3n58xw4373jp0ljirf06d8077j15pc4j-glibc-2.37-8
/nix/store/fz2c8qahxza5ygy4yvwdqzbck1bs3qag-libidn2-2.3.4
/nix/store/q7hi3rvpfgc232qkdq2dacmvkmsrnldg-libunistring-1.1
/nix/store/ryvnrp5n6kqv3fl20qy2xgcgdsza7i0m-xgcc-12.3.0-libgcc
/nix/store/s66mzxpvicwk07gjbjfw9izjfa797vsw-hello-2.12.1

如果检查其 ELF 数据，您确实可以看到它链接到了那个特定的 glibc：

$ readelf -d /nix/store/s66mzxpvicwk07gjbjfw9izjfa797vsw-hello-2.12.1/bin/hello | grep runpath
 0x000000000000001d (RUNPATH)            Library runpath: [/nix/store/3n58xw4373jp0ljirf06d8077j15pc4j-glibc-2.37-8/lib]

这意味着包含该闭包的根文件系统足以运行 hello，即使它是动态链接的。这类似于包含静态编译的 go 二进制文件的最小镜像，或者像 [distroless][distroless] 那样利用 [Bazel][bazel] 达到相同效果。

</details>

快速入门

尝试这个的最简单方法是运行一个预先配置好的 NixOS 虚拟机。

[!注意] 您需要安装 [Nix][nix]，并启用 [flake 支持][nix-flake] 和 [统一 CLI][nix-command]，这些在 [Determinate Nix 安装程序][nix-installer] 中是预先启用的。
<details> <summary>不安装 Nix 也可尝试</summary>
如果您安装了 [docker][docker] 或其他 OCI 运行时，可以运行 docker run --rm -it nixpkgs/nix-flakes：
nix run github:pdtpartners/nix-snapshotter#vm
</details>

nix run "github:pdtpartners/nix-snapshotter#vm"
nixos login: root # (按 Ctrl-a 然后 x 退出)
Password: root

# 使用 nix-snapshotter 运行 `pkgs.hello` 镜像
nerdctl run ghcr.io/pdtpartners/hello

# 使用 kubernetes 和 nix-snapshotter 运行 `pkgs.redis` 镜像
kubectl apply -f /etc/kubernetes/redis/

# 等待几秒钟...
watch kubectl get pods

# 然后 kubernetes 服务将准备好将端口 30000 转发到 redis pod，
# 所以您可以使用 `ping` 命令测试它
redis-cli -p 30000 ping

或者您可以尝试在无根模式下运行：

nix run "github:pdtpartners/nix-snapshotter#vm-rootless"
nixos login: rootless # (按 Ctrl-a 然后 x 退出)
Password: rootless

# 目前还不支持使用无根 k3s containerd 的 `nerdctl run`
# 参见：https://github.com/containerd/nerdctl/issues/2831
#
# 如果不需要无根 kubernetes，`nerdctl run` 确实可以与无根
# containerd + nix-snapshotter 一起工作。

# 使用 kubernetes 和 nix-snapshotter 运行 `pkgs.redis` 镜像
kubectl apply -f /etc/kubernetes/redis/

# 等待几秒钟...
watch kubectl get pods

# 然后 kubernetes 服务将准备好将端口 30000 转发到 redis pod，
# 所以您可以使用 `ping` 命令测试它
redis-cli -p 30000 ping

安装

提供了 [NixOS][nixos] 和 [Home Manager][home-manager] 模块，方便安装。

[!重要] 至少需要 nixpkgs 23.05+

Home Manager

<details> <summary>Flake</summary>

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    home-manager = {
      url = "github:nix-community/home-manager";
      inputs.nixpkgs.follows = "nixpkgs";
    };
    nix-snapshotter = {
      url = "github:pdtpartners/nix-snapshotter";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { nixpkgs, home-manager, nix-snapshotter, ... }: {
    homeConfigurations.myuser = home-manager.lib.homeManagerConfiguration {
      pkgs = import nixpkgs { system = "x86_64-linux"; };
      modules = [
        {
          home = {
            username = "myuser";
            homeDirectory = "/home/myuser";
            stateVersion = "23.11";
          };

          programs.home-manager.enable = true;

          # 让 home-manager 自动启动 systemd 用户服务。
          # 最终将成为新的默认设置。
          systemd.user.startServices = "sd-switch";
        }
        ({ pkgs, ... }: {
          # (1) 导入 home-manager 模块。
          imports = [ nix-snapshotter.homeModules.default ];

(2) 添加覆盖层。

注意：如果使用 NixOS 和 home-manager.useGlobalPkgs = true，则需要

在 NixOS 级别添加覆盖层。

nixpkgs.overlays = [ nix-snapshotter.overlays.default ];

(3) 启用服务。

virtualisation.containerd.rootless = { enable = true; nixSnapshotterIntegration = true; }; services.nix-snapshotter.rootless = { enable = true; };

(4) 添加 containerd CLI，如 nerdctl。

home.packages = [ pkgs.nerdctl ]; }) ]; }; }; }

</details>

<details>
<summary>非 flake</summary>

```nix
{ pkgs, ... }:
let
  nix-snapshotter = import (
    builtins.fetchTarball "https://github.com/pdtpartners/nix-snapshotter/archive/main.tar.gz"
  );

in {
  imports = [
    # (1) 导入 home-manager 模块。
    nix-snapshotter.homeModules.default
  ];

  # (2) 添加覆盖层。
  #
  # 注意：如果使用 NixOS 和 home-manager.useGlobalPkgs = true，则需要
  # 在 NixOS 级别添加覆盖层。
  nixpkgs.overlays = [ nix-snapshotter.overlays.default ];

  # (3) 启用服务。
  virtualisation.containerd.rootless = {
    enable = true;
    nixSnapshotterIntegration = true;
  };
  services.nix-snapshotter.rootless = {
    enable = true;
  };

  # (4) 添加 containerd CLI，如 nerdctl。
  home.packages = [ pkgs.nerdctl ];
}

</details>

NixOS

<details> <summary>Flake</summary>

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    nix-snapshotter = {
      url = "github:pdtpartners/nix-snapshotter";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { nixpkgs, nix-snapshotter, ... }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        ./hardware-configuration.nix
        ({ pkgs, ... }: {
          # (1) 导入 nixos 模块。
          imports = [ nix-snapshotter.nixosModules.default ];

          # (2) 添加覆盖层。
          nixpkgs.overlays = [ nix-snapshotter.overlays.default ];

          # (3) 启用服务。
          virtualisation.containerd = {
            enable = true;
            nixSnapshotterIntegration = true;
          };
          services.nix-snapshotter = {
            enable = true;
          };

          # (4) 添加 containerd CLI，如 nerdctl。
          environment.systemPackages = [ pkgs.nerdctl ];
        })
      ];
    };
  };
}

</details> <details> <summary>非 flake</summary>

{ pkgs, ... }:
let
  nix-snapshotter = import (
    builtins.fetchTarball "https://github.com/pdtpartners/nix-snapshotter/archive/main.tar.gz"
  );

in {
  imports = [
    ./hardware-configuration.nix
    # (1) 导入 nixos 模块。
    nix-snapshotter.nixosModules.default
  ];

  # (2) 添加覆盖层。
  nixpkgs.overlays = [ nix-snapshotter.overlays.default ];

  # (3) 启用服务。
  virtualisation.containerd = {
    enable = true;
    nixSnapshotterIntegration = true;
  };
  services.nix-snapshotter = {
    enable = true;
  };

  # (4) 添加 containerd CLI，如 nerdctl。
  environment.systemPackages = [ pkgs.nerdctl ];
}

</details>

手动安装

请参阅[手动安装文档][manual-install]。

用法

有关 Nix 接口，请参阅 package.nix。您还可以在 examples/declarative-k8s.nix 中重复上面的 asciinema 演示。

pkgs = import nixpkgs {
  overlays = [ nix-snapshotter.overlays.default ];
};

# 构建一个原生 Nix 镜像，但用于 OCI 兼容的镜像仓库。
redis = pkgs.nix-snapshotter.buildImage {
  name = "ghcr.io/pdtpartners/redis";
  tag = "latest";
  config.entrypoint = [ "${pkgs.redis}/bin/redis-server" ];
};

# 运行 "${redis.copyToRegistry {}}/bin/copy-to-registry" 将其复制到
# OCI 兼容的镜像仓库。如果目标是 DockerHub，它将尝试使用您的 Docker 凭据进行推送。

# 构建一个带有特殊镜像引用的原生 Nix 镜像。当使用 `--image-service-endpoint` 
# 指向 nix-snapshotter 运行 kubelet 时，它可以将镜像引用解析为这个 Nix 包。
redis' = pkgs.nix-snapshotter.buildImage {
  name = "redis";
  resolvedByNix = true;
  config.entrypoint = [ "${pkgs.redis}/bin/redis-server" ];
};

# 完全声明式的 Kubernetes Pod，包括镜像规范及其内容。
redisPod = pkgs.writeText "redis-pod.json" (builtins.toJSON {
  apiVersion = "v1";
  kind = "Pod";
  metadata = {
    name = "redis";
    labels.name = "redis";
  };
  spec.containers = [{
    name = "redis";
    args = [ "--protected-mode" "no" ];
    image = "nix:0${redis'}";
    ports = [{
      name = "client";
      containerPort = 6379;
    }];
  }];
});

[!注意] 如果您想了解 nix:0 是如何解析的，请查看 [Image Service][image-service] 文档。

贡献

欢迎提交任何更改的拉取请求。对于较大的更改，请考虑先开启一个问题进行讨论，以获得关于想法的反馈。

请阅读 CONTRIBUTING 以获取开发技巧和更多关于贡献指南的详细信息。

常见问题

[!重要] 要了解其背后的工作原理，请参阅 [架构][architecture] 文档以获取更多详细信息。

这与 [pkgs.dockerTools.buildImage][dockerTools] 有什么区别？

上游的 buildImage 将 Nix 包流式传输到 tarball 中，压缩它们并将其推送到 OCI 镜像仓库。由于镜像中的层数有限制，因此使用启发式方法将常用包放在一起。您的 Nix 二进制缓存和 Docker 镜像仓库 tarball 之间存在大量重复，甚至在共享包的镜像之间也会因基于启发式的分层策略而导致常见包重复。

使用 pkgs.nix-snapshotter.buildImage，containerd 原生理解 Nix 包，因此所有内容都以包粒度拉取，没有层限制。这意味着所有容器内容要么已经在您的 Nix 存储中，要么从您的 Nix 二进制缓存中获取。

</details>

我应该何时选择 rootful（普通）模式与 rootless 模式？

如果您正在运行生产服务器，最好使用 rootful 版本，因为无根容器在容器生态系统中仍处于早期阶段。然而，如果您是出于个人使用目的运行它，请先尝试无根变体。尽管不太成熟，但它是更安全的模式，因为容器运行时以非特权用户身份运行。它可以缓解潜在的容器突破漏洞，虽然不是万能的解决方案。

通常，无根模式的设置更复杂。但由于它已经作为NixOS / Home Manager模块分发，只需启用服务即可简单设置。

更多详情请参见 https://rootlesscontaine.rs。

这与[Nixery][nixery]有什么区别？

Nixery提供了一个API（以OCI注册表的形式）来动态构建基于Nix的镜像。与上游的pkgs.dockerTools.buildImage相比，它有一个[改进的分层设计][nixery-layers]，但仍然基本上是基于启发式的分层策略（见上文），因此仍然存在重复导致的低效问题。不过，Nixery完全可以开始构建nix-snapshotter镜像，这样我们就可以拥有一个能够动态构建原生Nix镜像的Docker注册表。请关注这个[Nixery问题][nixery-issue]以了解进展。

这与nix-in-docker有什么区别？

如果您在容器内运行nix（例如nixos/nix或nixpkgs/nix-flake），那么您确实是使用Nix存储获取包。但是，每个容器都将拥有自己的Nix存储，而不是在主机级别进行去重。

nix-snapshotter旨在运行在主机系统上（与containerd和/或kubelet并列），这样运行不同镜像的多个容器可以从同一个Nix存储共享底层包。

这与[nix2container][nix2container]有什么区别？

nix2container在几个方面改进了pkgs.dockerTools.buildImage。首先，它做了类似于pkgs.dockerTools.streamLayeredImage的事情，即避免将Nix层tarball写入Nix存储，而是在导出时即时构建它们，比如通过它的passthru属性copyToRegistry。这避免了不必要地将Nix层tarball写入Nix存储。

其次，它将镜像元数据和层元数据分开。这意味着更新镜像配置时，不需要重新构建层。第三，每个层的元数据都在自己的Nix包中，所以只需要重建更新的层。

最后，层元数据是一个JSON，包含Nix存储路径以及从丢弃的层tarball计算得到的摘要。这让skopeo工具只复制不存在的层，然后再次即时构建请求的层tarball。

nix2container是一个很大的改进，但仍然存在pkgs.dockerTools.buildImage部分指出的相同问题。它在Nix二进制缓存和Docker注册表之间重复数据，并且由于使用类似的基于启发式的策略，在层之间重复包。

pkgs.nix-snapshotter.buildImage具有所有相同的改进，除了我们确实将最终镜像写回Nix存储，因为它很小，并允许我们通过Nix包解析镜像清单。