kubespray离线部署方案：无网络环境下的Kubernetes安装-优快云博客

kubespray离线部署方案：无网络环境下的Kubernetes安装

【免费下载链接】kubespray 项目地址: https://gitcode.com/gh_mirrors/kub/kubespray

你是否曾因严格的网络隔离政策，导致Kubernetes集群部署屡屡受阻？本文将详解如何使用Kubespray在完全离线的环境中，从零构建生产级Kubernetes集群，涵盖环境准备、资源收集、配置调整和部署验证全流程。

离线部署架构概览

离线部署需在两个环境间协同完成：在线环境（用于资源收集）和离线环境（实际部署集群）。两者通过移动存储介质传输必要文件，整体架构如下：

mermaid

核心组件包括：

文件服务器：存储Kubernetes二进制、CNI插件等静态资源
容器镜像仓库：托管所有集群所需容器镜像
操作系统仓库：提供RPM/DEB格式的系统依赖包
配置中心：通过Kubespray inventory定义离线环境参数

准备阶段：在线环境资源收集

生成部署资源清单

使用Kubespray提供的generate_list.sh脚本，生成离线部署所需的文件和镜像清单：

cd contrib/offline
./generate_list.sh

执行后将在temp目录下生成：

files.list：所有二进制文件下载链接（kubeadm、etcd等）
images.list：完整容器镜像列表（按部署配置自动生成）
*.template：变量模板文件，用于后续路径替换

下载容器镜像

通过manage-offline-container-images.sh脚本下载镜像并打包：

# 在线环境收集镜像
./manage-offline-container-images.sh create
# 生成镜像压缩包（约5-10GB，视集群规模而定）
tar -czf images.tar.gz temp/images

该脚本支持从已部署集群或镜像清单文件两种方式获取镜像，推荐使用清单文件方式：

# 从文件获取镜像列表（替代自动探测）
IMAGES_FROM_FILE=temp/images.list ./manage-offline-container-images.sh create

下载二进制文件

使用manage-offline-files.sh脚本下载所有静态文件：

./manage-offline-files.sh

脚本会自动启动临时Nginx容器验证文件可访问性，通过http://127.0.0.1:8080/检查文件完整性。关键文件包括：

Kubernetes组件：kubeadm、kubelet、kubectl（对应cluster.yml版本）
网络插件：calicoctl、cni-plugins（根据network_plugin配置）
容器运行时：containerd、runc、nerdctl（对应container-engine版本）

部署阶段：离线环境基础设施搭建

部署本地容器仓库

在离线环境启动私有镜像仓库（以Docker Registry为例）：

# 启动仓库容器
docker run -d --restart=always -p 5000:5000 --name registry registry:2
# 导入镜像到本地仓库
tar -xzf images.tar.gz
./manage-offline-container-images.sh register

默认使用5000端口，可通过REGISTRY_PORT环境变量修改。如需HTTPS，需配置TLS证书并设置DESTINATION_REGISTRY指向安全地址。

配置文件服务器

使用Nginx部署静态文件服务，目录结构需与在线环境保持一致：

# 启动文件服务器（使用离线环境IP）
docker run -d -p 8080:80 -v /path/to/downloaded/files:/usr/share/nginx/html nginx:alpine

验证文件可访问性：

curl http://<offline-server-ip>:8080/kubernetes/v1.28.0/kubeadm

配置阶段：Kubespray离线参数调整

修改Inventory配置

创建专用离线Inventory文件inventory/offline/group_vars/all/offline.yml，关键配置如下：

# 容器镜像仓库配置
registry_host: "192.168.1.100:5000"
registry_addr: "{{ registry_host }}"

# 文件服务器地址
files_repo: "http://192.168.1.100:8080"

# 覆盖所有镜像仓库前缀
kube_image_repo: "{{ registry_host }}"
gcr_image_repo: "{{ registry_host }}"
docker_image_repo: "{{ registry_host }}"
quay_image_repo: "{{ registry_host }}"

# 二进制文件下载路径
kubeadm_download_url: "{{ files_repo }}/kubernetes/{{ kube_version }}/kubeadm"
kubelet_download_url: "{{ files_repo }}/kubernetes/{{ kube_version }}/kubelet"

完整配置示例可参考离线环境模板，需根据实际环境调整IP和端口。

配置操作系统仓库

根据节点操作系统类型，部署对应本地仓库：

CentOS/RHEL系统：

# 创建本地YUM仓库
createrepo /path/to/rpms
cat > /etc/yum.repos.d/offline.repo << EOF
[offline]
name=Offline Repo
baseurl=file:///path/to/rpms
enabled=1
gpgcheck=0
EOF

Debian/Ubuntu系统：

# 创建本地APT仓库
dpkg-scanpackages . /dev/null | gzip -9c > Packages.gz
cat > /etc/apt/sources.list.d/offline.list << EOF
deb [trusted=yes] file:///path/to/debs ./
EOF
apt update

执行部署：Kubespray离线安装

验证离线环境配置

部署前执行预检查：

ansible-playbook -i inventory/offline/hosts.yaml --tags=precheck cluster.yml

重点检查：

所有节点可访问文件服务器（8080端口）
容器运行时能拉取本地仓库镜像
操作系统仓库配置正确

执行集群部署

使用离线配置启动部署：

ansible-playbook -i inventory/offline/hosts.yaml -b cluster.yml

典型部署耗时：

单节点集群：15-20分钟
3节点控制平面+2节点工作节点：30-45分钟

如需加速部署，可设置etcd_deployment=host直接在主机部署etcd（需额外2GB内存）。

验证与维护

集群状态检查

部署完成后验证核心组件状态：

# 检查节点状态（所有节点应处于Ready状态）
kubectl get nodes
# 检查系统组件（所有Pod应处于Running状态）
kubectl get pods -n kube-system

关键验证点：

网络插件（calico/flannel）Pod正常运行
etcd集群健康（etcdctl endpoint health）
控制平面组件（kube-apiserver、kube-controller-manager）高可用

离线环境升级策略

离线升级需提前准备新版本资源：

在线环境生成新版本清单：KUBE_VERSION=v1.29.0 ./generate_list.sh
同步新文件和镜像到离线环境
更新inventory中kube_version参数
执行升级：ansible-playbook -i inventory/offline/hosts.yaml upgrade-cluster.yml

建议维护版本兼容性矩阵，避免跨版本升级（如v1.27直接升级到v1.29）。

常见问题解决

镜像拉取失败

症状：容器运行时报image pull failed
解决：

# 检查镜像仓库是否包含指定镜像
curl http://<registry-ip>:5000/v2/_catalog
# 手动导入缺失镜像
docker load -i missing-image.tar
docker tag <image-id> <registry-ip>:5000/<image-name>:<tag>
docker push <registry-ip>:5000/<image-name>:<tag>

文件下载超时

症状：ansible执行时报Connection timeout
解决：

检查files_repo参数是否正确
验证文件权限：chmod -R 755 /path/to/files
调整Nginx超时配置：proxy_connect_timeout 300s

系统依赖缺失

症状：Failed to install package错误
解决：使用yumdownloader/apt-get download在在线环境下载依赖包，补充到本地操作系统仓库。

最佳实践与优化

资源规划建议

环境类型	控制节点配置	工作节点配置	存储需求
测试环境	2C/4G/50G	4C/8G/100G	20GB（基础资源）
生产环境	4C/16G/100G	8C/32G/500G	50GB（含镜像缓存）

安全加固措施

为本地仓库配置TLS，参考Docker Registry文档
限制文件服务器访问来源：allow 192.168.1.0/24;（Nginx配置）
定期清理镜像仓库：registry garbage-collect /etc/docker/registry/config.yml

通过以上步骤，可在完全隔离的网络环境中部署生产级Kubernetes集群。关键在于严格遵循资源收集→环境配置→参数调整的流程，建议使用自动化脚本（如Ansible Role或Makefile）简化重复操作。完整离线部署示例可参考tests/files/目录下的离线测试用例配置。

【免费下载链接】kubespray 项目地址: https://gitcode.com/gh_mirrors/kub/kubespray

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考