引言

Kubernetes (k8s) 已成为容器编排的事实标准。然而，在我国部署 k8s 集群时，由于网络环境的特殊性，经常会遇到镜像拉取缓慢或失败的问题。本文将分享一套完整的 k8s 集群部署方案，从安装 containerd 容器运行时到使用 kubeadm 初始化集群，再到部署 Cilium 网络插件，详细讲解每个步骤，并提供针对国内网络环境的优化建议。
在这里插入图片描述

前提条件

  • 至少一台 Linux 服务器（推荐 Ubuntu 22.04），作为控制平面节点（master）。
  • （可选）若干台 Linux 服务器作为工作节点（worker）。
  • 所有节点能够相互通信。
  • 所有节点都已经安装好 Docker 或者 containerd, 这里我们使用 containerd.
  • 所有节点都关闭了 强制访问控制 (MAC) 系统（AppArmor|SELinux） 和 防火墙（ufw：Uncomplicated Firewall|firewalld），或者配置了相应的规则。 这一步根据实际安全要求可以放宽。

步骤 1：准备工作（所有节点）

  1. 关闭 Swap: Kubernetes 1.8+ 要求关闭 swap 分区。

    sudo swapoff -a
# 永久禁用，编辑 /etc/fstab 文件，注释掉包含 "swap" 的行。

    如果不关闭swap，后续kubelet可能会启动失败，也可以在kubelet的配置文件中添加--fail-swap-on=false参数来忽略swap开启的影响。

  2. 配置内核参数： 启用 IPv4 转发。

    cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.ipv4.ip_forward = 1
EOF
sudo sysctl --system
# 验证：
sysctl net.ipv4.ip_forward  # 输出应为 net.ipv4.ip_forward = 1

  3. 配置主机名解析（可选）： 如果我们的节点没有 DNS 服务器，可以在 /etc/hosts 文件中添加节点间的 IP 地址和主机名映射。

步骤 2：安装 containerd（所有节点）

containerd 是一个工业级的容器运行时，比 Docker 更轻量、更安全，也更适合 Kubernetes。

  1. 下载 containerd: 从 GitHub 下载 containerd 的二进制包（根据你的系统架构选择合适的版本，这里以 2.0.2 版本为例，但建议选择一个较新的稳定版本，比如 1.6 或 1.7 系列）：

    wget https://github.com/containerd/containerd/releases/download/v2.0.2/containerd-2.0.2-linux-amd64.tar.gz #请根据需求更改版本
    • 国内镜像加速 (可选)： 如果 GitHub 下载速度慢，可以使用国内镜像： 
      使用github proxy
wget https://ghproxy.com/https://github.com/containerd/containerd/releases/download/v2.0.2/containerd-2.0.2-linux-amd64.tar.gz

  2. 解压 containerd:

    sudo tar Cxzvf /usr/local containerd-2.0.2-linux-amd64.tar.gz

  3. 创建 containerd systemd 服务文件：

    cat <<EOF | sudo tee /etc/systemd/system/containerd.service
[Unit]
Description=containerd container runtime
Documentation=https://containerd.io
After=network.target local-fs.target

[Service]
ExecStartPre=-/sbin/modprobe overlay
ExecStart=/usr/local/bin/containerd

Type=notify
Delegate=yes
KillMode=process
Restart=always
RestartSec=5

# Having non-zero Limit*s causes performance problems due to accounting overhead
# in the kernel. We recommend using cgroups to do container-local accounting.
LimitNPROC=infinity
LimitCORE=infinity
LimitNOFILE=infinity

# Comment TasksMax if your systemd version does not supports it.
# Only systemd 226 and above support this version.
TasksMax=infinity
OOMScoreAdjust=-999

[Install]
WantedBy=multi-user.target
EOF

  4. 启动并启用 containerd:

    sudo systemctl daemon-reload
sudo systemctl enable --now containerd
sudo systemctl status containerd # 检查状态

  5. 配置 containerd (可选，但推荐):

    生成默认配置文件：

    sudo mkdir -p /etc/containerd
containerd config default | sudo tee /etc/containerd/config.toml

    修改配置文件 /etc/containerd/config.toml：

    • 修改 sandbox_image: 将 sandbox_image 改为国内镜像源（例如阿里云）：

      [plugins."io.containerd.grpc.v1.cri"]
  sandbox_image = "registry.aliyuncs.com/google_containers/pause:3.9" # 注意版本号
      • 注意： 不同镜像仓库的 pause 镜像版本号可能不同，你需要根据实际情况调整。

    • (可选, 强烈建议)配置镜像加速:

    ```toml
[plugins."io.containerd.grpc.v1.cri".registry.mirrors]
  [plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
    endpoint = ["https://<your-mirror-address>"] # 替换为你的镜像加速地址
```
例如，使用阿里云的镜像加速：
 ```toml
[plugins."io.containerd.grpc.v1.cri".registry.mirrors]
  [plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
    endpoint = ["https://xxxxxx.mirror.aliyuncs.com"]
  [plugins."io.containerd.grpc.v1.cri".registry.mirrors."k8s.gcr.io"]
     endpoint = ["https://registry.aliyuncs.com/google_containers"]
```
*   你需要将 `https://xxxxxx.mirror.aliyuncs.com` 替换为你自己的阿里云镜像加速地址。
*   设置 `k8s.gcr.io` 的 mirror 可以避免后续的一些镜像问题.
    • (可选) 更改cgroup driver：containerd 默认使用 systemd 作为 cgroup 驱动。如果kubelet也配置为systemd cgroup driver，则无需更改. 如果kubelet配置为cgroupfs, 则需要修改此项, 否则kubelet可能无法启动. 
      [plugins."io.containerd.grpc.v1.cri"]
   ...
  [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc]
    ...
    [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc.options]
      SystemdCgroup = true #或者 false

    重启 containerd:

    sudo systemctl restart containerd

步骤 3：安装 kubeadm, kubelet, kubectl (所有节点)

  1. 添加 Kubernetes 软件源 (以阿里云为例):

    cat <<EOF | sudo tee /etc/yum.repos.d/kubernetes.repo
[kubernetes]
name=Kubernetes
baseurl=https://mirrors.aliyun.com/kubernetes/yum/repos/kubernetes-el8-\$basearch/
enabled=1
gpgcheck=0
repo_gpgcheck=0
gpgkey=https://mirrors.aliyun.com/kubernetes/yum/doc/yum-key.gpg https://mirrors.aliyun.com/kubernetes/yum/doc/rpm-package-key.gpg
EOF
    • 注意: 如果你是 Debian/Ubuntu 系统，需要使用 apt 并配置相应的 Kubernetes apt 源。
    	sudo apt-get update && sudo apt-get install -y apt-transport-https curl
    curl -s https://mirrors.aliyun.com/kubernetes/apt/doc/apt-key.gpg | sudo apt-key add -
    sudo tee /etc/apt/sources.list.d/kubernetes.list <<EOF
    deb https://mirrors.aliyun.com/kubernetes/apt/ kubernetes-xenial main
    EOF

  2. 安装 kubeadm, kubelet, kubectl:

    # CentOS/RHEL
sudo yum install -y kubelet kubeadm kubectl --disableexcludes=kubernetes

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y kubelet kubeadm kubectl --allow-unauthenticated

  3. 启用 kubelet:

    sudo systemctl enable --now kubelet

步骤 4：初始化 Master 节点 (仅在 Master 节点执行)

  1. 预拉取镜像 (可选，但强烈推荐): 使用国内镜像源预先拉取 k8s 组件镜像，避免 kubeadm init 过程中因网络问题失败。

    kubeadm config images pull --image-repository registry.aliyuncs.com/google_containers --kubernetes-version v1.32.1
    • --image-repository: 指定国内镜像仓库。
    • --kubernetes-version: 指定 k8s 版本，与你要部署的版本一致。

  2. 初始化集群:

    sudo kubeadm init --image-repository registry.aliyuncs.com/google_containers --kubernetes-version v1.32.1 --pod-network-cidr=10.244.0.0/16
    • --image-repository: 指定国内镜像仓库。
    • --kubernetes-version: 指定 Kubernetes 版本。
    • --pod-network-cidr: 指定 Pod 网络 CIDR，需要与你选择的网络插件匹配（例如，Flannel 默认使用 10.244.0.0/16，Calico 默认使用 192.168.0.0/16）。 如果使用 Cilium，可以不指定这个参数，Cilium 会自动配置。

  3. 配置kubectl:

    按照 kubeadm init 命令的输出提示，配置 kubectl：

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

    或者，如果你是 root 用户：

    export KUBECONFIG=/etc/kubernetes/admin.conf

步骤 5：部署网络插件 (仅在 Master 节点执行)

Kubernetes 需要一个网络插件来实现 Pod 之间的通信。这里以 Cilium 为例，Cilium 是一个高性能、功能强大的网络插件，基于 eBPF 技术。

  1. 安装Cilium CLI:
CILIUM_CLI_VERSION=$(curl -s https://raw.githubusercontent.com/cilium/cilium-cli/main/stable.txt)
CLI_ARCH=amd64
if [ "$(uname -m)" = "aarch64" ]; then CLI_ARCH=arm64; fi
curl -L --fail --remote-name-all https://github.com/cilium/cilium-cli/releases/download/${CILIUM_CLI_VERSION}/cilium-linux-${CLI_ARCH}.tar.gz{,.sha256sum}
sha256sum --check cilium-linux-${CLI_ARCH}.tar.gz.sha256sum
sudo tar xzvfC cilium-linux-${CLI_ARCH}.tar.gz /usr/local/bin
rm cilium-linux-${CLI_ARCH}.tar.gz{,.sha256sum}

如果下载失败，可以使用ghproxy代理:

curl -L --fail --remote-name-all https://ghproxy.com/https://github.com/cilium/cilium-cli/releases/download/${CILIUM_CLI_VERSION}/cilium-linux-${CLI_ARCH}.tar.gz{,.sha256sum}
  1. 安装 Cilium:
cilium install --version 1.17.0 --wait # 建议安装一个较新的版本，与你的 Kubernetes 版本兼容。
  • 如果提示缺少 helm, 可以先手动安装 helm.
  1. 检查 Cilium 状态:
cilium status --wait

步骤 6：加入 Worker 节点 (在每个 Worker 节点执行)

在 Master 节点上执行 kubeadm init 后，会输出 kubeadm join 命令。在每个 Worker 节点上执行该命令，将其加入集群。

sudo kubeadm join <master-ip>:6443 --token <token> --discovery-token-ca-cert-hash sha256:<hash>
  • <master-ip>: Master 节点的 IP 地址。
  • <token>: 加入集群的令牌。
  • <hash>: CA 证书的哈希值。

步骤 7：（可选）去除 Master 节点污点
默认情况下，master节点有污点，不会被调度pod。如果希望在master节点也运行pod（例如单节点集群），可以去除污点：

kubectl taint nodes --all node-role.kubernetes.io/control-plane-

常见问题排查

  • kubelet 启动失败： 查看 kubelet 日志 (journalctl -xeu kubelet)，常见原因包括：
    • Swap 未关闭。
    • 内核参数未配置。
    • containerd 未启动或配置错误。
    • kubelet 配置文件错误（例如，/var/lib/kubelet/kubeadm-flags.env 或 /etc/systemd/system/kubelet.service.d/10-kubeadm.conf）。
  • Pod 无法启动： 查看 Pod 描述 (kubectl describe pod <pod-name> -n <namespace>)，常见原因包括：
    • 镜像拉取失败（检查镜像地址、镜像仓库认证）。
    • 网络插件未正确配置。
    • 资源不足（CPU、内存）。
  • 网络不通：
    • 检查CNI是否正常运行： kubectl get pods -n kube-system
    • 防火墙： 检查节点间防火墙是否打开了需要的端口.
    • 检查CNI配置是否正确.
  • ctr cri login 失败 (如果你的 containerd 版本较旧): 确保你使用了正确的 ctr image pull 命令和认证参数。

总结

本文提供了一套在国内环境下快速部署 Kubernetes 集群的完整方案，包括了 containerd 的安装、kubeadm 的使用、镜像仓库的配置、网络插件的部署等关键步骤。通过采用国内镜像源、预拉取镜像等优化措施，可以有效解决网络问题，提高部署效率。同时，本文也介绍了常见问题的排查方法，帮助大家快速定位和解决问题。希望这篇文章能帮助大家在国内顺利部署和使用 Kubernetes！

# kubernetes # 容器 # 云原生
Logo
魔乐社区

魔乐社区（Modelers.cn) 是一个中立、公益的人工智能社区，提供人工智能工具、模型、数据的托管、展示与应用协同服务，为人工智能开发及爱好者搭建开放的学习交流平台。社区通过理事会方式运作，由全产业链共同建设、共同运营、共同享有，推动国产AI生态繁荣发展。

更多推荐

cover

全家桶集齐！Qwen3.5四款小模型上线魔乐社区，附昇腾全套实践教程

avatar 魔乐社区

Pont - 搭建前后端之桥：高效、灵活的接口管理工具

Pont 是一款强大的数据服务层解决方案，它能够帮助开发者快速搭建前后端之间的桥梁，实现接口的高效管理和代码自动生成。无论是新手还是有经验的开发者，都能通过 Pont 轻松处理接口文档、生成类型安全的 API 代码，从而显著提升开发效率。[![Pont 工具标志](https://raw.gitcode.com/gh_mirrors/po/pont/raw/3f1b7d4bbba3fd2dda

avatar 魔乐社区

如何快速上手 hvac：HashiCorp Vault Python 客户端零基础入门指南

**hvac** 是 HashiCorp Vault 的 Python 3.X 客户端库，专为开发者提供简单高效的 Vault 交互方式。无论你是需要管理密钥、配置身份验证，还是实现安全的秘密数据存储，hvac 都能帮助你轻松搞定 Vault 的各项操作。本文将带你零基础快速入门，从安装到基础操作，让你在几分钟内即可上手使用这个强大的工具。[![hvac 客户端 Logo](https://r

avatar 魔乐社区