OKD 4.x SNO (单节点 OpenShift) 离线代理环境安装实战指南

OKD 4.x SNO (单节点 OpenShift) 离线代理环境安装实战指南

1. 引言

本文详细记录了在离线且需要 HTTP/HTTPS 代理的环境下，从零开始部署一个 OKD 4.x 单节点集群（Single Node OpenShift, SNO）的全过程。我们将涵盖从配置准备、镜像生成到节点启动，以及在此过程中遇到的各种常见问题（如代理配置、内存不足、NTP 同步失败等）的排查与解决方案。

1.1 SNO 简介

单节点 OpenShift (SNO) 是一个功能完备的 OpenShift 集群，其所有功能（包括控制平面和数据平面）都运行在单一一个节点上。它非常适合资源有限的开发环境、边缘计算场景或家庭实验室。

1.2 环境概述

• 供应节点 (Provisioning Node): 一台 Linux 服务器，用于生成安装介质和运行 oc 命令。
• SNO 节点 (SNO Node): 目标虚拟机，将运行整个 OKD 集群。
• 网络环境: 内部网络，所有出网流量必须通过指定的 HTTP/HTTPS 代理。
• OKD 版本: 4.x (具体版本取决于 openshift-install 二进制文件)

---

2. 准备工作

在供应节点上执行以下操作。

2.1 创建工作目录

mkdir /root/okd-sno
cd /root/okd-sno

2.2 下载安装工具

从 OKD 的 GitHub Release 页面 下载与您想安装版本对应的 openshift-install 和 openshift-client (oc)。

# 示例：下载二进制文件并解压
wget <openshift-install_download_url>
wget <openshift-client_download_url>

tar -xvf openshift-install-linux-*.tar.gz
tar -xvf openshift-client-linux-*.tar.gz

# 将工具移动到工作目录
mv openshift-install /root/okd-sno/
mv oc kubectl /root/okd-sno/

2.3 准备 Pull Secret 和 SSH 公钥

• Pull Secret: 从 Red Hat OpenShift Cluster Manager 获取。将其内容保存为 pull-secret.txt。
• SSH 公钥: 您的 SSH 公钥，用于在安装后登录 SNO 节点。通常位于 ~/.ssh/id_rsa.pub。

---

3. 核心配置与 ISO 生成

3.1 创建 install-config.yaml

这是安装过程的核心配置文件。

apiVersion: v1
baseDomain: okd.gwm.cn
metadata:
  name: sno
networking:
  clusterNetwork:
  - cidr: 10.128.0.0/14
    hostPrefix: 23
  networkType: OVNKubernetes
  serviceNetwork:
  - 172.30.0.0/16
  machineNetwork:
  - cidr: 192.168.179.0/24
compute:
- name: worker
  replicas: 0 # SNO 模式下 worker 副本为 0
controlPlane:
  name: master
  replicas: 1 # SNO 模式下 controlPlane 副本为 1
platform:
  none: {}
bootstrapInPlace:
  installationDisk: /dev/nvme0n1 # SNO 节点的目标安装磁盘
proxy: # 关键点：代理配置
  httpProxy: http://192.168.179.1:10808
  httpsProxy: http://192.168.179.1:10808
  noProxy: localhost,127.0.0.1,::1,.localdomain,okd.gwm.cn
pullSecret: 'PASTE_PULL_SECRET_CONTENT_HERE'
sshKey: 'PASTE_SSH_PUBLIC_KEY_HERE'

3.2 创建 agent-config.yaml

在 Agent-based 安装模式下，此文件用于指定 SNO 节点的网络细节。

apiVersion: v1alpha1
kind: AgentConfig
metadata:
  name: sno-cluster
rendezvousIP: 192.168.179.132 # SNO 节点的 IP 地址

3.3 生成 Agent ISO

运行以下命令生成引导 SNO 节点所需的 ISO 镜像。

# 确保代理环境变量已设置，以便安装程序自身可以下载资源
export HTTP_PROXY="http://192.168.179.1:10808"
export HTTPS_PROXY="http://192.168.179.1:10808"
export NO_PROXY="localhost,127.0.0.1,::1,.localdomain,okd.gwm.cn"

# 运行命令
./openshift-install agent create image --dir /root/okd-sno

成功后，您将在 /root/okd-sno 目录下看到一个 agent.x86_64.iso 文件。

---

4. 启动 SNO 节点并安装

4.1 启动虚拟机

将新生成的 agent.x86_64.iso 作为启动盘挂载到您的 SNO 虚拟机上，并启动。

4.2 监控第一阶段：磁盘写入

系统从 ISO 启动后，会运行一个临时的 assisted-installer 容器。我们可以通过 SSH 登录节点来监控进度。

# 登录 SNO 节点（密码是 core，如果 ISO 允许）
ssh core@192.168.179.132

# 监控 installer 日志
sudo podman logs -f assisted-installer

您会看到类似如下的磁盘写入进度：

time="2025-12-19T01:35:44Z" level=info msg="Read disk 2.3827933678403497 GiB/2.5546875 GiB (93%)\n"
time="2025-12-19T01:35:45Z" level=info msg="Read disk 2.5546875 GiB/2.5546875 GiB (100%)\n"
time="2025-12-19T01:35:46Z" level=info msg="Install complete.\n"

4.3 关键操作：退出 ISO 并重启

当您看到 Install complete 或类似的日志，并且节点自动重启时，请立即从虚拟机设置中移除 ISO 引导盘。这样可以确保下一次启动时，系统从已安装操作系统的硬盘引导。

---

5. 第二阶段：控制平面启动

5.1 监控 API Server 状态

节点从硬盘启动后，会开始部署 OpenShift 的核心组件。这个阶段，API Server (端口 6443) 还不可用。我们可以使用以下命令循环探测，直到 API 就绪。

# 在供应节点或任何有 oc 和 kubeconfig 的机器上运行
oc --kubeconfig=auth/kubeconfig get nodes

初期会返回 connection refused。这是正常的。

5.2 排错：内存不足 (Insufficient Memory)

在这一阶段，我们遇到了 oauth-openshift Pod 持续处于 Pending 状态的问题。通过 oc describe pod 命令发现，原因是 Insufficient memory。

解决方案：
SNO 对内存要求苛刻。16GB 是最低标准，但在启动阶段很容易触及瓶颈。将 SNO 虚拟机的内存从 16GB 扩展到 24GB 或 32GB，然后重启节点，是解决此问题的最有效方法。

5.3 排错：NTP 同步失败

如果安装日志提示 ntp-synced Status:failure，您可以登录 SNO 节点手动修复。

# 登录 SNO 节点
ssh core@192.168.179.132

# 强制同步时间
sudo chronyc -a makestep

# 检查同步状态
sudo chronyc tracking

在大多数情况下，即使此项检查失败，只要节点时间与现实时间大致相符，安装仍可继续。

---

6. 安装完成与访问

6.1 确认集群状态

当所有组件都稳定后，运行 oc get clusteroperators，您应该看到所有操作符的 AVAILABLE 状态为 True，PROGRESSING 和 DEGRADED 为 False。

$ oc get clusteroperators
NAME               VERSION              AVAILABLE   PROGRESSING   DEGRADED   SINCE
authentication     4.20.0-okd-scos.13   True        False         False      114m
...
console            4.20.0-okd-scos.13   True        False         False      113m
...

6.2 配置本地 DNS 解析

为了通过域名访问控制台，您需要修改本地电脑的 hosts 文件。

• 文件路径: C:\Windows\System32\drivers\etc\hosts
• 添加内容:

  192.168.179.132 api.sno.okd.gwm.cn
  192.168.179.132 console-openshift-console.apps.sno.okd.gwm.cn
  192.168.179.132 oauth-openshift.apps.sno.okd.gwm.cn
  

• 刷新 DNS 缓存: ipconfig /flushdns

对于通配符 *.apps 域名的支持，推荐使用 Acrylic DNS Proxy 等本地 DNS 代理工具。

6.3 访问 Web 控制台

一切就绪后，您可以通过浏览器访问：
https://console-openshift-console.apps.sno.okd.gwm.cn

使用 kubeadmin 用户或您后续创建的用户登录。

---

7. 总结

部署 OKD SNO，特别是在有代理的网络中，是一项挑战，但也非常有价值。关键在于仔细准备配置文件、理解安装的两个主要阶段，并学会在遇到问题时（如内存不足、NTP 同步失败）如何诊断和解决。希望这份实战指南能为您的部署提供帮助。