Debian 13基于kubeadm和containerd部署单节点kubernetes

前言

在本地虚拟机环境中使用 kubeadm 搭建 Kubernetes 集群是学习和实验的理想选择。考虑到实际应用场景中可能存在的网络限制以及镜像构建需求，本文详细记录了在完全离线环境下部署单节点 Kubernetes 集群的完整过程。通过集成 Harbor 私有镜像仓库，所有 Kubernetes 组件镜像均从本地 Harbor 实例拉取，确保部署过程的可靠性和可重复性。

本指南适用于希望在受限网络环境中快速搭建 Kubernetes 实验环境的技术人员，涵盖了从系统初始化到 Cilium 网络插件配置的全流程。

环境和版本信息

基础环境配置

• 操作系统：Debian 13 (代号 "Trixie")
• 硬件规格：4 核 CPU / 4GB 内存 / 40GB 存储空间
• 网络拓扑：单节点部署（Control Plane + Worker 合一）

软件版本清单

组件	版本	说明
Kubernetes	v1.33.7	容器编排平台
containerd	2.2.1	容器运行时
runc	1.4.0	OCI 运行时规范实现
CNI Plugins	1.9.0	容器网络接口插件
Harbor	v2.14.2	企业级容器镜像仓库
Cilium	v1.18.6	eBPF 驱动的网络和安全解决方案
Helm	3.19.5	Kubernetes 包管理器

网络规划

IP 地址	主机名	角色
192.168.0.22	deb13-k8s-node1	Kubernetes 节点
192.168.0.42	deb13-harbor	Harbor 镜像仓库

注意：本文档假设两台主机位于同一内网环境中，且网络连通性已验证。

系统初始化

在开始 Kubernetes 组件安装之前，需要对系统进行必要的初始化配置，以满足 Kubernetes 的运行要求。

1. 安装 IPVS 相关工具包

IPVS（IP Virtual Server）是 Linux 内核的负载均衡实现，Kubernetes 在 IPVS 模式下运行 kube-proxy 时需要相关工具支持。

# 仅在 Kubernetes 节点执行
sudo apt update
sudo apt install -y ipvsadm ipset

2. 配置主机名

为便于管理和识别，建议为每台主机设置有意义的主机名。

# Harbor 服务器
hostnamectl set-hostname deb13-harbor

# Kubernetes 节点
hostnamectl set-hostname deb13-k8s-node1

3. 配置本地 DNS 解析

编辑 /etc/hosts 文件，添加主机名与 IP 地址的映射关系：

cat >> /etc/hosts << EOF
192.168.0.22 deb13-k8s-node1
192.168.0.42 deb13-harbor
EOF

4. 加载必要的内核模块

Kubernetes 依赖特定的内核模块来支持容器网络功能。创建模块加载配置并立即生效：

# 创建模块加载配置文件
cat << EOF > /etc/modules-load.d/containerd.conf
overlay
br_netfilter
EOF

# 立即加载模块
sudo modprobe overlay
sudo modprobe br_netfilter

# 验证模块加载状态
lsmod | grep -E "(overlay|br_netfilter)"

5. 配置系统内核参数

调整内核参数以优化容器运行环境：

cat > /etc/sysctl.d/k8s.conf << EOF
net.ipv4.ip_forward=1
net.bridge.bridge-nf-call-ip6tables = 1
net.bridge.bridge-nf-call-iptables = 1
vm.swappiness = 0
EOF

# 应用配置
sudo sysctl --system

重要提示：如果系统启用了 swap 分区，必须在 Kubernetes 启动前将其关闭，否则 kubelet 将无法正常启动。可通过以下命令临时关闭：

sudo swapoff -a
# 永久关闭需注释 /etc/fstab 中的 swap 相关行

Harbor 私有镜像仓库部署

Harbor 作为企业级容器镜像仓库，为离线环境下的 Kubernetes 部署提供了可靠的镜像分发能力。

1. 准备 Harbor 安装包

从 Harbor GitHub Releases 页面下载离线安装包（约 600MB）。安装 Harbor 前需确保 Docker 和 Docker Compose 已正确安装。

2. 生成自签名 TLS 证书

由于 Harbor 强制要求 HTTPS 连接，我们需要为 Harbor 服务器生成自签名证书。创建证书生成脚本：

# 创建证书目录
mkdir -p ~/apps/harbor/certs
cd ~/apps/harbor/certs

# 创建证书生成脚本
cat > gen-harbor-crt.sh << 'EOF'
#!/bin/bash

# --- 配置参数 ---
DOMAIN="deb13-harbor"       # Harbor 域名
IP="192.168.0.42"           # Harbor 服务器内网 IP
DAYS=3650                   # 有效期 10 年

# 1. 生成私钥 (无密码)
openssl genrsa -out harbor.key 2048

# 2. 创建 OpenSSL 配置文件以包含 SAN
cat > harbor.conf << CONF_EOF
[req]
distinguished_name = req_distinguished_name
x509_extensions = v3_req
prompt = no

[req_distinguished_name]
CN = ${DOMAIN}

[v3_req]
keyUsage = critical, digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names

[alt_names]
DNS.1 = ${DOMAIN}
IP.1 = ${IP}
CONF_EOF

# 3. 生成自签名证书
openssl req -x509 -nodes -days ${DAYS} -key harbor.key -out harbor.crt -config harbor.conf -extensions v3_req

# 4. 验证证书（查看是否有 Subject Alternative Name 字段）
echo "--------------------------------------------------"
echo "证书信息验证："
openssl x509 -in harbor.crt -text -noout | grep -A 1 "Subject Alternative Name"

echo "--------------------------------------------------"
echo "生成成功！"
echo "服务端使用: harbor.crt, harbor.key"
echo "客户端 (K8s 节点) 使用: harbor.crt"
EOF

# 执行证书生成
chmod +x gen-harbor-crt.sh
./gen-harbor-crt.sh

3. 配置 Harbor

从模板文件复制并修改 Harbor 配置：

# 复制配置模板
cp harbor.yml.tmpl harbor.yml

# 修改关键配置项

主要配置项如下：

# Harbor 访问地址
hostname: 192.168.0.42

# HTTPS 配置
https:
  port: 443
  certificate: /home/rainux/apps/harbor/certs/harbor.crt
  private_key: /home/rainux/apps/harbor/certs/harbor.key

# 管理员密码（请设置强密码）
harbor_admin_password: your-harbor-password

# 数据库密码
database:
  password: your-db-password

# 数据存储路径
data_volume: /home/rainux/apps/harbor/data

# 日志配置
log:
  location: /home/rainux/apps/harbor/logs

# 启用指标监控
metric:
  enabled: true
  port: 9090
  path: /metrics

4. 启动 Harbor 服务

cd ~/apps/harbor
sudo ./install.sh

5. 初始化 Harbor 项目

通过 Web 界面访问 Harbor（https://192.168.0.42），使用配置的管理员密码登录后，创建以下两个公开项目：

• google_containers：用于存储 Kubernetes 核心组件镜像
• cilium：用于存储 Cilium 网络插件相关镜像

配置更新说明：如需修改 Harbor 配置，可执行以下命令使配置生效：

sudo ./prepare
docker-compose down -v
sudo docker-compose up -d

Containerd 容器运行时配置

Containerd 作为轻量级容器运行时，是 Kubernetes 推荐的运行时选项之一。

1. 下载必要组件

从官方 GitHub 仓库下载以下组件：

• containerd
• runc
• CNI Plugins

2. 安装 runc

# 注意：原文中的文件名可能存在笔误，应为 runc.amd64
chmod +x runc.amd64
sudo mv runc.amd64 /usr/local/bin/runc

3. 安装 CNI 插件

sudo mkdir -p /opt/cni/bin/
sudo tar xf cni-plugins-linux-amd64-v1.9.0.tgz -C /opt/cni/bin/

4. 安装 containerd

sudo tar xf containerd-2.2.1-linux-amd64.tar.gz
sudo mv bin/* /usr/local/bin/

5. 配置 containerd

生成默认配置并进行必要的修改：

# 创建 Harbor 证书目录
sudo mkdir -p /etc/containerd/certs.d/192.168.0.42/

# 生成默认配置
sudo containerd config default > /etc/containerd/config.toml

# 复制 Harbor 证书
sudo cp ~/apps/harbor/certs/harbor.crt /etc/containerd/certs.d/192.168.0.42/ca.crt

关键配置修改：

# 设置 Pod 沙箱镜像源
[plugins.'io.containerd.cri.v1.images'.pinned_images]
  sandbox = '192.168.0.42/google_containers/pause:3.10'

# 配置私有镜像仓库
[plugins.'io.containerd.cri.v1.images'.registry]
  config_path = '/etc/containerd/certs.d'

# 启用 systemd cgroup 驱动
[plugins.'io.containerd.cri.v1.runtime'.containerd.runtimes.runc.options]
  SystemdCgroup = true

6. 配置 systemd 服务

从 官方仓库 获取 service 文件：

sudo curl -o /usr/lib/systemd/system/containerd.service https://raw.githubusercontent.com/containerd/containerd/main/containerd.service

7. 启动 containerd 服务

sudo systemctl daemon-reload
sudo systemctl enable --now containerd

Kubernetes 组件部署

1. 安装 Kubernetes 二进制文件

从 Kubernetes GitHub Releases 下载 kubernetes-server-linux-amd64.tar.gz，提取核心组件：

# 解压并安装核心组件
tar xf kubernetes-server-linux-amd64.tar.gz
sudo cp kubernetes/server/bin/{kubeadm,kubelet,kubectl} /usr/local/bin/

# 验证所需镜像列表
kubeadm config images list --kubernetes-version v1.33.7

将列出的所有镜像（包括 pause、coredns、etcd 等）从官方源拉取后重新打标签并推送到 Harbor 的 google_containers 项目中。

2. 配置 kubelet systemd 服务

创建主服务文件 /usr/lib/systemd/system/kubelet.service：

[Unit]
Description=kubelet: The Kubernetes Node Agent
Documentation=https://kubernetes.io/docs/
Wants=network-online.target
After=network-online.target

[Service]
ExecStart=/usr/local/bin/kubelet
Restart=always
StartLimitInterval=0
RestartSec=10

[Install]
WantedBy=multi-user.target

3. 创建 kubeadm 配置目录

sudo mkdir -p /usr/lib/systemd/system/kubelet.service.d/

4. 配置 kubeadm drop-in 文件

创建 /usr/lib/systemd/system/kubelet.service.d/10-kubeadm.conf：

# Note: This dropin only works with kubeadm and kubelet v1.11+
[Service]
Environment="KUBELET_KUBECONFIG_ARGS=--bootstrap-kubeconfig=/etc/kubernetes/bootstrap-kubelet.conf --kubeconfig=/etc/kubernetes/kubelet.conf"
Environment="KUBELET_CONFIG_ARGS=--config=/var/lib/kubelet/config.yaml"
# This is a file that "kubeadm init" and "kubeadm join" generates at runtime, populating the KUBELET_KUBEADM_ARGS variable dynamically
EnvironmentFile=-/var/lib/kubelet/kubeadm-flags.env
# This is a file that the user can use for overrides of the kubelet args as a last resort. Preferably, the user should use
# the .NodeRegistration.KubeletExtraArgs object in the configuration files instead. KUBELET_EXTRA_ARGS should be sourced from this file.
EnvironmentFile=-/etc/sysconfig/kubelet
ExecStart=
ExecStart=/usr/local/bin/kubelet $KUBELET_KUBECONFIG_ARGS $KUBELET_CONFIG_ARGS $KUBELET_KUBEADM_ARGS $KUBELET_EXTRA_ARGS

5. 启动 kubelet 服务

sudo systemctl daemon-reload
sudo systemctl enable --now kubelet

集群初始化

1. 创建 kubeadm 配置文件

创建 kubeadm-config.yaml 配置文件：

apiVersion: kubeadm.k8s.io/v1beta4
kind: ClusterConfiguration
kubernetesVersion: v1.33.7
imageRepository: 192.168.0.42/google_containers  # 指向本地 Harbor 仓库
networking:
  podSubnet: "10.10.0.0/16"   # Cilium 默认 Pod 网段
  serviceSubnet: "10.96.0.0/12"
---
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
cgroupDriver: systemd
imageGCHighThresholdPercent: 70   # 磁盘使用率超过 70% 时开始清理镜像
imageGCLowThresholdPercent: 60    # 清理至磁盘使用率 60% 时停止
---
apiVersion: kubeproxy.config.k8s.io/v1alpha1
kind: KubeProxyConfiguration
mode: "ipvs"  # 虽然后续会使用 Cilium 替代 kube-proxy，但初始化阶段仍需配置

2. 执行集群初始化

sudo kubeadm init --config kubeadm-config.yaml --ignore-preflight-errors=ImagePull

3. 清理 kube-proxy（使用 Cilium 替代）

由于我们将使用 Cilium 作为网络解决方案，可以移除 kube-proxy：

# 删除 kube-proxy DaemonSet
kubectl delete ds kube-proxy -n kube-system

# 在所有节点清理 iptables 规则残留
sudo kube-proxy --cleanup

4. 验证初始化状态

初始化完成后，配置 kubectl 并检查集群状态：

# 配置 kubectl
mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

# 检查节点状态（此时应显示 NotReady，因为 CNI 尚未安装）
kubectl get nodes
kubectl get namespaces

Cilium 网络插件部署

Cilium 基于 eBPF 技术提供高性能的网络、安全和可观测性功能。

1. 安装 cilium-cli

从 Cilium CLI Releases 下载并安装命令行工具。

2. 准备 Cilium 镜像

将 Cilium 所需的镜像推送到 Harbor 仓库：

#!/bin/bash

set -euo pipefail

images=(
    cilium/cilium:v1.18.6
    cilium/hubble-relay:v1.18.6
    cilium/hubble-ui-backend:v0.13.3
    cilium/hubble-ui:v0.13.3
    cilium/cilium-envoy:v1.35.9-1767794330-db497dd19e346b39d81d7b5c0dedf6c812bcc5c9
    cilium/certgen:v0.3.1
    cilium/startup-script:1755531540-60ee83e
)

src_registry="quay.io"
target_registry="192.168.0.42"

for image in "${images[@]}"; do
    echo "Processing image: ${image}"
    docker pull "${src_registry}/${image}"
    docker tag "${src_registry}/${image}" "${target_registry}/${image}"
    docker push "${target_registry}/${image}"
done

3. 获取 Helm Chart

helm repo add cilium https://helm.cilium.io/
helm pull cilium/cilium --version 1.18.6
tar xf cilium-1.18.6.tgz
mv cilium cilium-chart

4. 配置 Chart Values

首先替换所有镜像源地址：

sed -i 's#quay.io#192.168.0.42#g' ./cilium-chart/values.yaml

关键配置项调整：

# 启用 kube-proxy 替代模式
kubeProxyReplacement: true

# 指定 Kubernetes API 服务器地址
k8sServiceHost: "192.168.0.22"
k8sServicePort: 6443

# 单节点部署，operator 副本数设为 1
operator:
  replicas: 1

# 启用 Hubble 可观测性组件
hubble:
  enabled: true
  relay:
    enabled: true
  ui:
    enabled: true

# 配置 IPAM CIDR 范围
ipam:
  operator:
    clusterPoolIPv4PodCIDRList:
      - "10.10.0.0/16"

镜像 Digest 注意事项 ：通过 docker pull 再 push 的方式可能导致镜像 digest 发生变化。如遇镜像拉取失败，可将 values.yaml 中的 useDigest 设置为 false。

5. 安装 Cilium

# 执行安装
cilium install --chart-directory ./cilium-chart

# 检查安装状态
cilium status

# 移除 control-plane 污点以允许 Pod 调度
kubectl taint nodes --all node-role.kubernetes.io/control-plane-

6. 验证集群状态

等待所有 Pod 正常运行后，验证集群就绪状态：

# 检查所有命名空间的 Pod 状态
kubectl get pods -A

# 验证节点状态（应显示 Ready）
kubectl get nodes

# 检查 Cilium 组件状态
cilium status --verbose

添加工作节点（扩展部署）

完成单节点集群部署后，如需扩展为多节点集群，可在新节点上执行以下步骤：

在新节点上需要先完成上面的系统初始化、Containerd配置、kube组件配置

1. 生成节点加入令牌

在 Control Plane 节点上生成 24 小时有效的加入令牌：

kubeadm token create --print-join-command

该命令将输出类似以下格式的加入命令：

kubeadm join 192.168.0.22:6443 --token <token> --discovery-token-ca-cert-hash sha256:<hash>

2. 在新节点执行加入命令

在新节点上执行上述命令，并忽略镜像预检错误：

sudo kubeadm join 192.168.0.22:6443 \
  --token <token> \
  --discovery-token-ca-cert-hash sha256:<hash> \
  --ignore-preflight-errors=ImagePull

3. 验证节点加入状态

# 检查节点列表
kubectl get nodes

# 验证 Cilium 状态
cilium status

# 清理 iptables 规则（如已禁用 kube-proxy）
sudo iptables -F

Cilium 会自动在新节点上部署代理 Pod，确保网络连通性。

私有镜像仓库认证配置

对于 Harbor 中非公开项目的镜像拉取，需要配置相应的认证机制。

方式一：Pod 级别 imagePullSecrets（推荐）

适用于需要精细化控制镜像拉取权限的场景。

1. 创建 Docker Registry Secret

kubectl create secret docker-registry harbor-pull-secret \
  --docker-server=192.168.0.42 \
  --docker-username=<your-username> \
  --docker-password=<your-password> \
  --docker-email=<your-email>

2. 在 Pod 定义中引用 Secret

apiVersion: v1
kind: Pod
spec:
  containers:
  - name: my-app
    image: 192.168.0.42/private-project/my-image:v1
  imagePullSecrets:
  - name: harbor-pull-secret

方式二：ServiceAccount 绑定（便捷方案）

适用于命名空间内所有 Pod 都需要访问私有镜像仓库的场景。

# 将 Secret 绑定到 default ServiceAccount
kubectl patch serviceaccount default -p '{"imagePullSecrets": [{"name": "harbor-pull-secret"}]}'

此配置将使该命名空间下所有新建的 Pod 自动继承镜像拉取权限。

方式三：Containerd 全局认证（实验环境适用）

在 Containerd 层面配置全局认证，适用于个人实验环境。

编辑 /etc/containerd/config.toml：

[plugins."io.containerd.grpc.v1.cri".registry.configs."192.168.0.42".auth]
  username = "your-username"
  password = "your-password"
  # 或使用 base64 编码的凭证：auth = "base64(username:password)"

安全提醒：方式三将凭据明文存储在配置文件中，不建议在生产环境中使用。

补充

相较于使用二进制方式部署，用kubeadm起码省去了手动维护证书的操作，后续添加节点也更简单些。有空整个ansible让添加节点更方便。