Hotdry.
归档
systems-engineering

在 NixOS 上通过声明式 Nix 模块部署最小化原生 Kubernetes 集群

利用 NixOS 的 Kubernetes 模块和 containerd，实现可重现的版本固定集群部署，集成 etcd 支持。提供配置参数和部署清单。

在现代云原生环境中，Kubernetes 作为容器编排的标准工具，已成为基础设施的核心组件。然而，传统部署方式往往涉及复杂的脚本、手动配置和版本依赖管理，容易导致环境不一致和维护难题。NixOS 作为一款声明式 Linux 发行版，通过其纯函数式包管理器 Nix 和模块系统，提供了一种革命性的解决方案：将 Kubernetes 集群的整个状态定义为纯文本配置，实现完全可重现的部署。这不仅确保了集群的版本固定，还简化了 etcd 和 containerd 的集成，使最小化原生 Kubernetes 集群的搭建变得高效可靠。

本文聚焦于在 NixOS 上部署最小化原生 Kubernetes 集群的核心观点：声明式配置是实现可重现性和原子化更新的关键。通过 NixOS 的 services.kubernetes 模块，我们可以避免 kubeadm 等工具的命令行复杂性，直接在 configuration.nix 中定义集群角色、CRI 运行时和存储后端。这种方法特别适合开发测试环境或小型生产集群，能在单节点上快速验证功能，并在多节点扩展时保持一致性。证据显示，NixOS 的 Kubernetes 模块已集成 kubeadm 作为后端，支持从 v1.20 起的版本，并通过 nixpkgs 通道固定组件版本，避免了上游 Kubernetes 发布节奏带来的兼容问题。

要落地这一观点，首先需要准备 NixOS 环境。假设您已安装 NixOS（推荐使用最新稳定通道，如 nixos-24.05），编辑 /etc/nixos/configuration.nix 文件。核心配置从启用 Kubernetes 模块开始：

{ config, pkgs, ... }:

{
  imports = [ <nixpkgs/nixos/modules/services/cluster/kubernetes/default.nix> ];

  services.kubernetes = {
    enable = true;
    roles = [ "master" "node" ];  # 单节点最小化部署，同时作为控制平面和工作节点
    masterAddress = "127.0.0.1";  # 对于单节点，使用本地地址
    clusterCidr = "10.244.0.0/16";  # Pod CIDR，Flannel 默认网络
    easyCerts = true;  # 自动生成自签名证书，适合测试；生产环境建议自定义 PKI
  };

  # 集成 containerd 作为 CRI 运行时
  virtualisation.containerd = {
    enable = true;
    settings = {
      plugins."io.containerd.grpc.v1.cri" = {
        sandbox_image = "registry.k8s.io/pause:3.9";  # Kubernetes 推荐的 pause 镜像版本
        containerd.runtimes.runc.options.SystemdCgroup = true;  # 使用 systemd cgroup 驱动，与 kubelet 一致
      };
    };
  };

  # 网络和防火墙配置
  networking.firewall.allowedTCPPorts = [ 6443 2379 2380 ];  # API Server、etcd 端口
  networking.firewall.allowedUDPPorts = [ 8472 ];  # Flannel VXLAN

  # 系统依赖
  environment.systemPackages = with pkgs; [ kubectl kubernetes ];  # 安装 kubectl 和 kubernetes 工具
}

应用配置后，运行 sudo nixos-rebuild switch 即可原子化部署。Nix 会自动下载并构建所需组件，包括 Kubernetes 二进制和 containerd，确保版本 pinned 到 nixpkgs 定义（如 Kubernetes 1.30）。这一步的关键参数包括 clusterCidr，用于定义 Pod 网络范围；若使用 Calico 等其他 CNI，可调整为相应值。证据来自 NixOS 官方模块文档，该模块通过 systemd 服务管理所有 Kubernetes 组件，如 kube-apiserver、kube-scheduler 和 kubelet，实现无缝启动。

接下来，集成 etcd 作为 Kubernetes 的后端存储。原生 Kubernetes 支持嵌入式 etcd，但为最小化部署，我们推荐外部 etcd 集群以提升可用性。在 NixOS 上，可通过 services.etcd 模块声明式配置 etcd：

services.etcd = {
  enable = true;
  listenClientUrls = [ "http://127.0.0.1:2379" "http://0.0.0.0:2379" ];
  listenPeerUrls = [ "http://0.0.0.1:2380" ];
  advertiseClientUrls = [ "http://127.0.0.1:2379" ];
  initialCluster = "default=http://127.0.0.1:2380";  # 单节点 etcd
  initialClusterToken = "etcd-cluster";  # 集群令牌
};

# 在 Kubernetes 配置中指定 etcd 服务器
services.kubernetes.apiserver.securePort = 6443;
services.kubernetes.apiserver.etcdServers = [ "https://127.0.0.1:2379" ];  # 指向本地 etcd

对于多节点扩展，将 initialCluster 扩展为 "node1=http://node1-ip:2380,node2=http://node2-ip:2380"，并在每个节点的 configuration.nix 中指定相应 listen/peer URLs。参数阈值建议：etcd 数据目录设为 /var/lib/etcd，定期快照间隔 5 分钟（通过 heartbeat-interval 和 election-timeout 调优，默认为 100ms 和 1000ms）。这一配置确保 etcd 与 containerd 无缝协作，containerd 通过 CRI 接口与 kubelet 通信，处理 Pod 生命周期。

部署后，验证集群健康是落地清单的关键步骤。运行 kubectl get nodes 检查节点状态，应显示 Ready。查看 Pod：kubectl get pods -n kube-system，确认 core-dns、etcd 等组件运行正常。若遇问题，检查日志：journalctl -u kubelet 或 journalctl -u etcd。监控要点包括：API Server 响应时间 < 1s，etcd 一致性索引递增无跳跃；使用 Prometheus 集成 NixOS 的 services.prometheus 模块监控资源使用率，阈值设为 CPU 80%、内存 90%。

回滚策略同样重要。NixOS 的世代管理允许一键回滚：sudo nixos-rebuild switch --rollback 恢复上一个配置，Kubernetes 组件随之重置，无需手动清理。风险控制：单节点模式下，etcd 单点故障风险高，生产建议至少 3 节点奇数集群；containerd 配置中启用 snapshotter = "overlayfs" 以优化存储性能，但需确保底层文件系统支持（如 ext4）。

扩展到多节点时，工作节点只需设置 roles = ["node"]; masterAddress = "master-ip"，并同步配置。CNI 插件如 Flannel 可通过 addons.flannel.enable = true; 启用，参数包括 subnetLen = 24。整个过程的参数清单总结如下：

  • Kubernetes 版本：通过 nixpkgs 固定，建议 1.28+ 以支持 containerd 1.6+。
  • Etcd 版本：3.5+，数据保留 24h。
  • Containerd 配置：sandbox_image 版本与 k8s 匹配，registry mirrors 若需加速国内访问。
  • 端口阈值：API 6443 超时 30s，etcd 心跳 250ms。
  • 资源分配：kubelet --kube-reserved-cpu=100m --kube-reserved-memory=500Mi。

这种声明式方法不仅减少了部署时间（单节点 < 10 分钟），还提升了可维护性。相比传统 Ansible 或 Helm，NixOS 确保零配置漂移。

资料来源：NixOS Manual (nixos.org/manual/nixos/unstable)，nixpkgs Kubernetes 模块源代码，以及社区指南如 CSDN 的 NixOS Kubernetes 部署教程。

查看归档