离线环境Kubernetes集群部署实战指南

1. 离线环境K8S集群部署概述

在基础设施受限的特殊场景中，离线部署Kubernetes集群是每个运维工程师都需要掌握的硬核技能。去年我在某金融机构数据中心实施私有云项目时，就遇到过核心生产网段完全隔离的情况。与常规安装相比，离线部署需要解决三大核心问题：依赖包完整获取、镜像仓库本地化、安装流程适配改造。

典型场景包括：

• 军工、金融等安全敏感行业的物理隔离环境
• 无外网连接的生产车间或实验室
• 需要长期稳定运行的工业控制环境

2. 离线部署核心准备

2.1 资源规划清单

在开始前需要准备以下物资（以部署3节点集群为例）：

关键提示：所有节点必须确保时间同步（chrony配置），证书校验对时间敏感，误差超过5分钟会导致集群初始化失败。

2.2 依赖包离线下载

通过联网环境获取全量依赖（示例为CentOS 7）：

bash复制# 创建缓存目录
mkdir -p /opt/offline-pkgs/{docker,k8s,tools}

# 下载docker-ce全家桶
yum install --downloadonly --downloaddir=/opt/offline-pkgs/docker \
    docker-ce docker-ce-cli containerd.io

# 获取k8s基础组件
cat > /etc/yum.repos.d/kubernetes.repo <<EOF
[kubernetes]
name=Kubernetes
baseurl=https://mirrors.aliyun.com/kubernetes/yum/repos/kubernetes-el7-x86_64/
enabled=1
gpgcheck=0
EOF

yum install --downloadonly --downloaddir=/opt/offline-pkgs/k8s \
    kubeadm-1.23.5 kubelet-1.23.5 kubectl-1.23.5

# 系统工具包（注意版本兼容性）
yum install --downloadonly --downloaddir=/opt/offline-pkgs/tools \
    socat conntrack-tools ebtables ipset

2.3 镜像预拉取方案

使用kubeadm的镜像列表导出功能：

bash复制# 生成镜像清单
kubeadm config images list --kubernetes-version v1.23.5 > image-list.txt

# 编写批量拉取脚本
while read img; do
    docker pull $img
    docker save $img > /opt/offline-images/$(echo $img | awk -F/ '{print $NF}').tar
done < image-list.txt

实测发现kube-proxy镜像存在平台适配问题，建议额外拉取amd64和arm64双架构版本。

3. 本地仓库建设实战

3.1 Harbor仓库部署

采用docker-compose方式快速部署：

yaml复制version: '3'
services:
  harbor-core:
    image: goharbor/harbor-core:v2.5.3
    container_name: harbor-core
    networks:
      - harbor
    # 其他配置省略...

关键配置项：

• 必须启用https（自签名证书需提前导入所有节点）
• 存储后端建议使用本地目录（非必须NFS）
• 创建名为k8s的公开项目用于存放集群镜像

3.2 离线镜像导入

使用批量加载脚本：

bash复制for img in /opt/offline-images/*.tar; do
    docker load -i $img
    docker tag $(docker inspect --format='{{.RepoTags}}' $img | tr -d '[]') \
        harbor.local/k8s/$(basename ${img%.*})
    docker push harbor.local/k8s/$(basename ${img%.*})
done

常见报错处理：

• 证书错误：在各节点执行mkdir -p /etc/docker/certs.d/harbor.local
• 认证失败：需在/etc/docker/daemon.json配置insecure-registries

4. 集群初始化关键步骤

4.1 节点基础配置

所有节点需执行：

bash复制# 关闭swap
swapoff -a
sed -i '/swap/s/^/#/' /etc/fstab

# 加载内核模块
cat > /etc/modules-load.d/k8s.conf <<EOF
br_netfilter
ip_vs
ip_vs_rr
ip_vs_wrr
ip_vs_sh
nf_conntrack
EOF

modprobe -- $(cat /etc/modules-load.d/k8s.conf)

4.2 离线安装组件

通过本地rpm包安装：

bash复制# 安装docker
yum localinstall -y /opt/pkgs/docker/*.rpm
systemctl enable --now docker

# 安装k8s组件
yum localinstall -y /opt/pkgs/k8s/*.rpm

4.3 定制kubeadm配置

创建kubeadm-config.yaml：

yaml复制apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
imageRepository: "harbor.local/k8s"
kubernetesVersion: "v1.23.5"
networking:
  podSubnet: "10.244.0.0/16"
  serviceSubnet: "10.96.0.0/12"
controlPlaneEndpoint: "k8s-api:6443"
---
apiVersion: kubeadm.k8s.io/v1beta3
kind: InitConfiguration
nodeRegistration:
  criSocket: "unix:///var/run/containerd/containerd.sock"

初始化主节点：

bash复制kubeadm init --config=kubeadm-config.yaml --upload-certs

5. 网络方案选型与问题排查

5.1 离线安装Calico

下载Calico的manifest和镜像：

bash复制curl -O https://docs.projectcalico.org/manifests/calico.yaml
docker pull calico/cni:v3.22.2
# ...其他镜像同理

修改配置关键点：

• 将image路径改为本地仓库地址
• 调整CIDR与kubeadm配置一致
• 禁用IPIP模式（性能考虑）

5.2 典型故障处理

节点NotReady状态检查：

1. 确认kubelet服务状态
2. 检查/var/log/messages中的证书错误
3. 验证CNI插件二进制是否可执行

镜像拉取失败处理：

bash复制# 查看具体事件
kubectl describe pod -n kube-system

# 临时解决方案
docker pull harbor.local/k8s/pause:3.6
docker tag harbor.local/k8s/pause:3.6 k8s.gcr.io/pause:3.6

6. 长期维护策略

6.1 版本升级方案

1. 在联网环境下载新版本rpm包
2. 通过USB拷贝到离线环境
3. 使用kubeadm upgrade plan分步执行

6.2 备份恢复流程

关键数据备份：

bash复制# etcd快照
ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key \
  snapshot save snapshot.db

# kubeconfig备份
tar czf k8s-backup-$(date +%F).tar.gz /etc/kubernetes

在实施过程中发现，使用ansible编写自动化部署脚本能显著提高效率。这里分享一个节点校验的playbook片段：

yaml复制- name: Validate node prerequisites
  hosts: all
  tasks:
    - name: Check kernel modules
      shell: lsmod | grep -E 'br_netfilter|ip_vs'
      register: module_check
      failed_when: module_check.stdout == ""
    
    - name: Verify docker storage driver
      command: docker info | grep -i overlay
      changed_when: false

最后建议在集群稳定后，立即部署监控系统（如Prometheus离线版），我们曾因未及时发现磁盘满导致etcd异常，这个教训值得警惕。