Ubuntu离线环境部署Kubernetes v1.31.3（ARM64）

子书 · 发表于 2026-3-5 13:40:00

离线ARM64环境 Kubernetes v1.31.3 部署过程记录

前言

本文基于 Ubuntu 22.04/24.04 LTS ARM64 架构，提供完全离线、无外网、无私有仓库的 Kubernetes 集群部署方案，包含完整部署流程、离线物料制备、实战踩坑问题解决。

一、部署环境要求

1.1 硬件配置

节点角色	数量	CPU	内存	磁盘	架构
Master	1	≥4核	≥8G	≥40G SSD	ARM64
Node	≥1	≥4核	≥8G	≥40G SSD	ARM64

1.2 基础约束

操作系统：Ubuntu 22.04 / 24.04 LTS ARM64
所有节点关闭 Swap
节点间网络互通，配置主机名解析
完全无外网、无镜像源

1.3 主机名与hosts配置（所有节点执行）

# 设置主机名（示例）
hostnamectl set-hostname k8s-master
hostnamectl set-hostname k8s-node01

# 配置hosts
cat >> /etc/hosts <<EOF
192.168.10.10  k8s-master
192.168.10.11  k8s-node01
EOF

二、离线物料准备

2.1 必备物料清单

1. K8s 官方二进制包（linux-arm64）
kubeadm v1.31.3
kubelet v1.31.3
kubectl v1.31.3
2. 离线依赖 deb 包（ARM64）
conntrack_1%3a1.4.8-1ubuntu1_arm64.deb（核心依赖，必装）
containerd.io_1.7.21-1_arm64.deb
runc_1.1.12-0ubuntu1~22.04_arm64.deb
cri-tools_1.26.0-00_arm64.deb
kubernetes-cni_1.26.0-00_arm64.deb
3. 离线镜像包
k8s-ixe-images-v1.31.3-arm64.tar（K8s 全套核心镜像）
pause-3.10-arm64-single.tar（单架构 pause 镜像，解决导入报错）
4. 配置文件
calico-v3.31.3-arm64.yaml（Calico 网络插件）
kubelet.service（kubelet 系统服务文件

2.2 联网机制备物料（仅执行一次）

# conntrack 官方ARM64包（清华镜像源）
https://mirrors.tuna.tsinghua.edu.cn/ubuntu-ports/pool/main/c/conntrack-tools/conntrack_1.4.8-1ubuntu1_arm64.deb

# containerd 官方包
https://download.docker.com/linux/ubuntu/dists/jammy/pool/stable/arm64/containerd.io_1.7.21-1_arm64.deb

# 1. 下载K8s官方ARM64二进制包
wget https://dl.k8s.io/v1.31.3/bin/linux/arm64/kubeadm
wget https://dl.k8s.io/v1.31.3/bin/linux/arm64/kubelet
wget https://dl.k8s.io/v1.31.3/bin/linux/arm64/kubectl

# 2. 下载离线依赖deb包（清华源+官方）
wget https://mirrors.tuna.tsinghua.edu.cn/ubuntu-ports/pool/main/c/conntrack-tools/conntrack_1.4.8-1ubuntu1_arm64.deb
wget https://download.docker.com/linux/ubuntu/dists/jammy/pool/stable/arm64/containerd.io_1.7.21-1_arm64.deb
wget https://mirrors.tuna.tsinghua.edu.cn/ubuntu-ports/pool/main/r/runc/runc_1.1.12-0ubuntu1~22.04_arm64.deb

# 3. 下载Calico配置
wget https://raw.githubusercontent.com/projectcalico/calico/v3.31.3/manifests/calico.yaml -O calico-v3.31.3-arm64.yaml

# 4. 导出单架构pause镜像（解决ctr导入报错）
ctr -n k8s.io i pull --platform linux/arm64 registry.k8s.io/pause:3.10
ctr -n k8s.io i export --platform linux/arm64 pause-3.10-arm64-single.tar registry.k8s.io/pause:3.10

# 5. 导出K8s全套离线镜像
ctr -n k8s.io i export k8s-ixe-images-v1.31.3-arm64.tar \
registry.k8s.io/kube-apiserver:v1.31.3 \
registry.k8s.io/kube-controller-manager:v1.31.3 \
registry.k8s.io/kube-scheduler:v1.31.3 \
registry.k8s.io/kube-proxy:v1.31.3 \
registry.k8s.io/pause:3.10 \
registry.k8s.io/etcd:3.5.15-0 \
registry.k8s.io/coredns/coredns:v1.11.3 \
docker.io/calico/cni:v3.31.3 \
docker.io/calico/node:v3.31.3 \
docker.io/calico/kube-controllers:v3.31.3

# 1. 下载K8s官方x86_64二进制包
wget https://dl.k8s.io/v1.31.3/bin/linux/amd64/kubeadm
wget https://dl.k8s.io/v1.31.3/bin/linux/amd64/kubelet
wget https://dl.k8s.io/v1.31.3/bin/linux/amd64/kubectl

# 2. 下载离线依赖deb包（清华源+官方）
wget https://mirrors.tuna.tsinghua.edu.cn/ubuntu/pool/main/c/conntrack-tools/conntrack_1.4.8-1ubuntu1_amd64.deb
wget https://download.docker.com/linux/ubuntu/dists/jammy/pool/stable/amd64/containerd.io_1.7.21-1_amd64.deb
wget https://mirrors.tuna.tsinghua.edu.cn/ubuntu/pool/main/r/runc/runc_1.1.12-0ubuntu1~22.04_amd64.deb

# 3. 下载Calico配置
wget https://raw.githubusercontent.com/projectcalico/calico/v3.31.3/manifests/calico.yaml -O calico-v3.31.3-amd64.yaml

# 4. 导出单架构pause镜像（解决ctr导入报错）
ctr -n k8s.io i pull --platform linux/amd64 registry.k8s.io/pause:3.10
ctr -n k8s.io i export --platform linux/amd64 pause-3.10-amd64-single.tar registry.k8s.io/pause:3.10

# 5. 导出K8s全套离线镜像
ctr -n k8s.io i export k8s-ixe-images-v1.31.3-amd64.tar \
registry.k8s.io/kube-apiserver:v1.31.3 \
registry.k8s.io/kube-controller-manager:v1.31.3 \
registry.k8s.io/kube-scheduler:v1.31.3 \
registry.k8s.io/kube-proxy:v1.31.3 \
registry.k8s.io/pause:3.10 \
registry.k8s.io/etcd:3.5.15-0 \
registry.k8s.io/coredns/coredns:v1.11.3 \
docker.io/calico/cni:v3.31.3 \
docker.io/calico/node:v3.31.3 \
docker.io/calico/kube-controllers:v3.31.3

2.3 物料传输

将所有物料拷贝至离线节点 /opt/k8s-offline/ 目录。

三、所有节点统一初始化（Master+Node）

3.1 关闭 Swap

swapoff -a
sed -i '/swap/s/^/#/' /etc/fstab

3.5 配置 containerd

3.2 加载内核模块

cat > /etc/modules-load.d/containerd.conf <<EOF
overlay
br_netfilter
EOF
modprobe overlay
modprobe br_netfilter

3.3 配置内核参数

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

3.4 安装离线依赖 deb 包

cd /opt/k8s-offline
dpkg -i *.deb
apt -f install -y

3.5 部署 K8s 二进制文件

cd /opt/k8s-offline
chmod +x kubeadm kubelet kubectl
mv kubeadm kubelet kubectl /usr/local/bin/

3.6 配置 containerd

containerd config default > /etc/containerd/config.toml
sed -i 's#sandbox_image = "registry.k8s.io/pause:3.8"#sandbox_image = "registry.k8s.io/pause:3.10"#' /etc/containerd/config.toml

systemctl enable containerd
systemctl restart containerd

3.7 配置 kubelet

# 创建kubelet配置文件
cat > /var/lib/kubelet/config.yaml <<EOF
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
cgroupDriver: systemd
podInfraContainerImage: "registry.k8s.io/pause:3.10"
EOF

# 创建kubelet服务文件
cat > /etc/systemd/system/kubelet.service <<EOF
[Unit]
Description=kubelet: The Kubernetes Node Agent
Documentation=https://kubernetes.io/docs/

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

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable kubelet
systemctl restart kubelet

四、Master 节点部署

4.1 导入离线镜像

cd /opt/k8s-offline
ctr -n k8s.io images import k8s-ixe-images-v1.31.3-arm64.tar
ctr -n k8s.io images import pause-3.10-arm64-single.tar

4.2 kubeadm 初始化集群

kubeadm init \
  --kubernetes-version=v1.31.3 \
  --apiserver-advertise-address=192.168.10.10 \
  --pod-network-cidr=10.244.0.0/16 \
  --service-cidr=10.96.0.0/12 \
  --image-repository=registry.k8s.io \
  --ignore-preflight-errors=swap

保存输出的 kubeadm join 命令，用于 Node 节点加入集群

4.3 配置 kubectl

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

4.4 部署 Calico 网络

kubectl apply -f calico-v3.31.3-arm64.yaml

五、Node 节点部署

5.1 导入镜像

cd /opt/k8s-offline
ctr -n k8s.io images import k8s-ixe-images-v1.31.3-arm64.tar
ctr -n k8s.io images import pause-3.10-arm64-single.tar

5.2 加入集群

# 使用Master初始化输出的join命令
kubeadm join 192.168.10.10:6443 --token xxx \
--discovery-token-ca-cert-hash sha256:xxx

六、实战踩坑：核心问题及解决方案

问题 1：Node 节点 NotReady，calico-node 报错Failed to get sandbox image "registry.k8s.io/pause:3.8"

原因：kubelet 默认使用 pause:3.8，离线环境无法拉取，覆盖 containerd 配置。

sed -i 's#podInfraContainerImage:.*#podInfraContainerImage: "registry.k8s.io/pause:3.10"#' /var/lib/kubelet/config.yaml
systemctl restart containerd kubelet
kubectl delete pod -n kube-system calico-node-xxx

问题 2：ctr 导入镜像报错content digest not found

原因：ctr 不支持多架构镜像导入。
解决方案：必须使用--platform linux/arm64导出单架构镜像。

例如
ctr -n k8s.io images export  --platform linux/arm64  kube-proxy.tar.gz  registry.k8s.io/kube-proxy:v1.31.3

问题 3：coredns 一直 Pending

原因：未部署 CNI 网络插件。
解决方案：执行 Calico 部署命令，等待 1-2 分钟自动恢复。

七、部署验证

7.1 节点状态检查

kubectl get nodes

7.2 系统 Pod 检查

kubectl get pods -n kube-system