OpenShift (OKD) 部署配置：install-config.yaml 深度解析与全场景模板
·
OpenShift (OKD) 部署配置：install-config.yaml 深度解析与全场景模板
摘要：
install-config.yaml是 OpenShift 集群的基因图谱。本文从架构师视角出发，深度解剖该文件的核心字段，并分别针对 SNO (单节点边缘) 和 HA (高可用生产) 两种场景，提供基于 Bare Metal (Platform None) 的标准配置模板与网络规划指南。适用版本：OKD 4.10+ / OpenShift 4.10+
最后更新：2026-01-15
目录
- 核心字段全景解析
- 部署模式对比
- 场景一：SNO 单节点配置模板
- 场景二：HA 高可用配置模板
- 网络规划详解
- 进阶：Ignition 配置与 Day 0 定制
- 安装前检查清单
- 故障排查与避坑指南
- 附录：快速参考
1. 核心字段全景解析
无论何种部署模式，以下字段构成了集群的基础骨架。
| 字段 | 必填 | 类型 | 含义与架构影响 |
|---|---|---|---|
apiVersion |
是 | string | 固定为 v1。控制配置格式版本。 |
baseDomain |
是 | string | 集群的 DNS 根域。最终 API 地址为 api.<metadata.name>.<baseDomain>。 |
metadata.name |
是 | string | 集群标识符。建议使用简短的小写字母 (如 okd4 或 sno)。 |
platform |
是 | object | 基础设施提供商。裸机部署使用 none: {}。 |
pullSecret |
是 | string | 镜像拉取凭证。决定了集群能否下载核心组件镜像。 |
sshKey |
是 | string | 注入到节点 core 用户的公钥，是排错时的唯一通道。 |
networking |
是 | object | 网络配置，决定 Pod 和 Service 网段。 |
compute |
是 | array | 计算节点配置。 |
controlPlane |
是 | object | 控制平面节点配置（Master 节点）。 |
2. 部署模式对比
2.1 SNO vs HA 核心差异
| 特性 | SNO (单节点) | HA (高可用) |
|---|---|---|
| 适用场景 | 边缘计算、开发测试、资源受限 | 生产环境、高可用要求 |
| 节点数量 | 1 | 3+ Master，2+ Worker |
| Etcd 仲裁 | 单点 (无仲裁) | 3 节点满足多数投票 |
| Bootstrap | 内置 (bootstrapInPlace) | 独立 Bootstrap 节点 |
| 控制平面 | 混合 (Master + Worker 合一) | 独立 Master 节点 |
| 升级策略 | In-Place | 滚动升级 |
| 资源要求 | 8 核 CPU / 32GB RAM 起步 | 16 核 CPU / 64GB RAM 每节点 |
| 故障恢复 | 需完全重装 | 可替换故障节点 |
2.2 选型建议
边缘/IoT 场景 ──────────→ SNO
│
├── 带宽受限 ─────────→ SNO + 离线镜像
└── 高可用需求 ───────→ HA (3 Master)
开发/测试环境 ──────────→ SNO
│
└── 多租户隔离 ──────→ HA
生产环境 ───────────────→ HA (推荐)
│
├── 金融/医疗 ──────→ 3 Master + 3+ Worker + 独立 Etcd
└── 一般企业 ───────→ 3 Master + 2 Worker
3. 场景一：SNO 单节点配置模板
SNO (Single Node OpenShift) 适用于边缘计算、开发测试或资源受限环境。
3.1 完整配置模板
apiVersion: v1
baseDomain: example.com
metadata:
name: sno # [必填] 集群名称，仅支持小写字母和数字
platform:
none: {} # [重点] 裸机模式，不依赖云 API
bootstrapInPlace:
installationDisk: /dev/nvme0n1 # [SNO 核心] 指定系统盘，无需独立 Bootstrap 节点
networking:
networkType: OVNKubernetes # [推荐] OVN-Kubernetes 或 OpenShiftSDN
clusterNetwork:
- cidr: 10.128.0.0/14 # Pod IP 网段
hostPrefix: 23 # 每个节点分配的 Pod IP 数量 (2^(32-23) = 512)
serviceNetwork:
- 172.30.0.0/16 # Service IP 网段
machineNetwork:
- cidr: 192.168.10.0/24 # [重点] 物理节点 IP 网段
compute:
- name: worker
replicas: 0 # SNO 模式下 Worker 必须为 0
controlPlane:
name: master
replicas: 1 # Master 必须为 1
pullSecret: '{"auths":{"https://quay.io/": {"auth": "...", "email": "..."}}}'
sshKey: 'ssh-ed25519 AAAA... user@example.com'
# additionalTrustBundle: | # [可选] 私有仓库 CA 证书
# -----BEGIN CERTIFICATE-----
# ...
# -----END CERTIFICATE-----
# proxy: # [可选] 代理配置
# httpProxy: http://proxy.example.com:8080
# httpsProxy: https://proxy.example.com:443
# noProxy: .example.com,10.0.0.0/8
3.2 SNO 资源要求
| 组件 | 最小配置 | 推荐配置 |
|---|---|---|
| CPU | 8 核 | 16 核 |
| 内存 | 32 GB | 64 GB |
| 存储 | 120 GB SSD | 256 GB SSD |
| 网络 | 1Gbps | 10Gbps |
注意：SNO 模式下所有 Control Plane 和 Workload 运行在同一节点，生产环境请谨慎评估资源是否充足。
4. 场景二：HA 高可用配置模板
生产环境标准架构：3 Master + 2+ Worker。在 platform: none 模式下，需要配合外部负载均衡器 (HAProxy) 使用。
4.1 完整配置模板
apiVersion: v1
baseDomain: example.com
metadata:
name: okd-ha # 集群名称
platform:
none: {} # 意味着没有 apiVIP 字段，需自行配置 DNS 和 LB
networking:
networkType: OVNKubernetes
clusterNetwork:
- cidr: 10.128.0.0/14
hostPrefix: 23
serviceNetwork:
- 172.30.0.0/16
machineNetwork:
- cidr: 192.168.10.0/24
compute:
- name: worker
replicas: 2 # [HA 建议] 至少 2 个 Worker 承载业务
controlPlane:
name: master
replicas: 3 # [HA 核心] 必须为 3 以满足 Etcd 仲裁
pullSecret: '{"auths":{"https://quay.io/": {"auth": "...", "email": "..."}}}'
sshKey: 'ssh-ed25519 AAAA... user@example.com'
4.2 HA 架构师备忘录
| 组件 | 要求 | 说明 |
|---|---|---|
| 负载均衡 | 外部 LB (如 HAProxy) | 监听 6443/22623 转发给 Master，监听 80/443 转发给 Worker |
| DNS 解析 | api 和 api-int 指向 LB IP |
格式：api.<cluster>.<baseDomain> |
| 时钟同步 | 所有节点 NTP 同步 | 误差超过 5分钟会导致证书验证失败 |
4.3 HAProxy 配置示例
frontend api-6443
bind *:6443
mode tcp
default-backend master-6443
frontend api-int-22623
bind *:22623
mode tcp
default-backend master-22623
frontend http-80
bind *:80
mode http
default-backend worker-http
frontend https-443
bind *:443
mode tcp
default-backend worker-https
backend master-6443
mode tcp
server master1 192.168.10.11:6443 check
server master2 192.168.10.12:6443 check
server master3 192.168.10.13:6443 check
backend master-22623
mode tcp
server master1 192.168.10.11:22623 check
server master2 192.168.10.12:22623 check
server master3 192.168.10.13:22623 check
backend worker-http
mode http
server worker1 192.168.10.21:80 check
server worker2 192.168.10.22:80 check
backend worker-https
mode tcp
server worker1 192.168.10.21:443 check
server worker2 192.168.10.22:443 check
5. 网络规划详解
在裸机安装中，网络配置一旦出错，集群将无法通信且难以修复。
5.1 三大网段解析
| 网段类型 | 字段 | 用途 | 重要程度 |
|---|---|---|---|
| Pod IP | clusterNetwork |
容器网络，每个 Pod 分配一个 IP | 严禁与物理网络冲突 |
| Service IP | serviceNetwork |
Kubernetes Service 地址，CoreDNS 使用该网段 | 需避开物理网络 |
| 节点 IP | machineNetwork |
物理节点的管理 IP，OVN 隧道基于此建立 | 必须与实际网络匹配 |
5.2 IP 规划建议
假设公司内网为 10.0.0.0/8，建议使用以下网段避开冲突：
| 用途 | 推荐网段 | 说明 |
|---|---|---|
| Pod Network | 172.20.0.0/14 |
/14 可提供约 260K Pod IP |
| Service Network | 172.31.0.0/16 |
/16 可提供 65K Service IP |
| 节点网络 | 192.168.10.0/24 |
根据实际物理网络调整 |
5.3 网段冲突检测清单
安装前检查项：
□ clusterNetwork 是否与物理网络有重叠？
□ serviceNetwork 是否与物理网络有重叠？
□ machineNetwork 是否与实际节点 IP 匹配？
□ Pod/Service 网段是否被防火墙阻断？
□ MTU 值是否匹配 (推荐 1500 或 9000)？
5.4 配置示例（避开常见内网）
networking:
networkType: OVNKubernetes
clusterNetwork:
- cidr: 172.16.0.0/14 # 避开 10.x 和 192.168.x
hostPrefix: 23 # 每个节点 512 个 Pod IP
serviceNetwork:
- 172.31.0.0/16
machineNetwork:
- cidr: 10.90.0.0/24 # 根据实际物理网络填写
6. 进阶：Ignition 配置与 Day 0 定制
install-config.yaml 只能覆盖通用的集群配置。如果需要在操作系统层面进行定制（如配置 NTP、内核参数、磁盘加密），就必须介入 Ignition 生成阶段。
6.1 生成流程与"吞噬"机制
# 1. 生成 Ignition 文件 (此步会删除 install-config.yaml)
openshift-install create ignition-configs --dir .
# 产物说明：
# ├── bootstrap.ign # SNO 模式下不需要
# ├── master.ign # 控制平面配置
# ├── worker.ign # 计算节点配置
# └── auth/
# ├── kubeadmin-password # 临时 admin 密码
# └── kubeconfig # admin kubeconfig
警告：执行
create ignition-configs前，务必备份install-config.yaml！
6.2 注入自定义配置 (MachineConfig)
假设需要在安装时配置企业内部的 NTP 服务器，不能直接改 .ign 文件（它是 Base64 编码的 JSON）。正确做法是创建 MachineConfig YAML 文件，放在安装目录的 openshift/ 子目录下。
示例：注入 Chrony (NTP) 配置
在生成 Ignition 之前，创建 openshift/99-chrony.yaml：
apiVersion: machineconfiguration.openshift.io/v1
kind: MachineConfig
metadata:
labels:
machineconfiguration.openshift.io/role: master
name: 99-master-chrony
spec:
config:
ignition:
version: 3.2.0
storage:
files:
- contents:
source: data:,server%20ntp.example.com%20iburst%0Aserver%20ntp2.example.com%20iburst%0A
mode: 420
path: /etc/chrony.conf
overwrite: true
生效逻辑：执行 create ignition-configs 时，安装程序扫描 openshift/ 目录，自动将 MachineConfig 编译进对应的 .ign 文件。
6.3 常用 Day 0 定制示例
| 场景 | MachineConfig 用途 | 文件示例名 |
|---|---|---|
| NTP 配置 | 时间同步 | 99-chrony.yaml |
| 内核参数 | sysctl 调优 | 99-sysctl.yaml |
| 磁盘加密 | LUKS 加密 | 99-luks.yaml |
| 自定义 CA | 信任私有根证书 | 99-ca-cert.yaml |
| 用户配置 | 添加 SSH 用户 | 99-ssh-user.yaml |
6.4 SNO 模式下的特殊性
SNO 模式通常直接运行 create image：
openshift-install agent create image --dir .
如果要定制，必须分步执行：
- 准备
install-config.yaml和openshift/目录下的定制文件 - 运行
create image，安装程序会自动读取openshift/目录并打包进 ISO
7. 安装前检查清单
7.1 环境准备
基础设施：
□ 硬件资源满足最小要求
□ 所有节点可访问互联网或已准备离线镜像
□ 节点 BIOS/UEFI 已禁用安全启动 (Secure Boot)
□ 节点支持 UEFI 启动模式
□ 至少有 1 块 SSD 用于系统盘
网络：
□ 节点之间 2 层网络可达
□ DNS 服务器已配置 A 记录 (api, api-int, *.apps)
□ NTP 时间同步正常
□ 防火墙已放行必要端口 (见 9.2)
镜像仓库：
□ 已有有效的 Pull Secret
□ 私有仓库证书已准备 (如使用 Harbor)
□ 镜像可以正常拉取
7.2 DNS 记录检查表
| 记录类型 | 主机名 | 指向 | 必需 |
|---|---|---|---|
| A | api.<cluster>.<domain> |
LB / Master 1 IP | 是 |
| A | api-int.<cluster>.<domain> |
LB / Master 1 IP | 是 |
| A | *.apps.<cluster>.<domain> |
Ingress LB / Worker IP | 是 |
| AAAA | 同上 (IPv6 环境) | - | 可选 |
7.3 端口要求
| 源 → 目标 | 端口 | 协议 | 说明 |
|---|---|---|---|
| Bootstrap → Master | 6443 | TCP | Ignition 配置获取 |
| Worker/Master → LB | 6443 | TCP | API Server |
| LB → Master | 6443 | TCP | API Server |
| LB → Master | 22623 | TCP | Ignition 配置服务 |
| 任意 → Master/Worker | 80/443 | TCP | Ingress (HTTP/HTTPS) |
| Master ↔ Master | 2379/2380 | TCP | Etcd |
| Master ↔ Master | 9000-9999 | TCP | OVN 隧道 |
8. 故障排查与避坑指南
8.1 常见问题与解决方案
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| 安装卡在 “Waiting for bootstrap” | Bootstrap 无法连接 Master | 检查网络、防火墙、DNS 配置 |
| 证书验证失败 | 时间不同步 | 同步 NTP 时间 |
| 镜像拉取失败 | Pull Secret 错误/过期 | 重新获取 Pull Secret |
| x509 证书错误 | 私有 CA 未信任 | 配置 additionalTrustBundle |
| Pod 无法分配 IP | Pod/Service 网段冲突 | 修改 clusterNetwork |
| API Server 无法访问 | LB 配置错误 | 检查 HAProxy 配置和 DNS |
| Ignition 阶段报错 | MachineConfig 格式错误 | 验证 YAML 语法和 Ignition 版本 |
| 安装后节点 NotReady | 网络插件未启动 | 检查 OVN/Kubernetes 日志 |
8.2 代理 (Proxy) 的副作用
如果在 install-config.yaml 中配置了 proxy：
proxy:
httpProxy: http://proxy.example.com:8080
httpsProxy: https://proxy.example.com:443
noProxy: .example.com,10.0.0.0/8
后果：
- 环境变量写入节点的
/etc/profile和 Systemd - 后续安装 Operator 或 Build 镜像时，如果代理不可用，会导致诡异的超时
建议：除非必须，否则尽量在网络层（网关/路由）处理透明代理，保持集群配置纯净。
8.3 证书 (AdditionalTrustBundle)
如果使用自签名证书的私有镜像仓库（Harbor），必须注入 CA 证书：
additionalTrustBundle: |
-----BEGIN CERTIFICATE-----
MIIDrzCCApegAwIBAgIQCD5R/k3u7y...
-----END CERTIFICATE-----
否则 Ignition 阶段拉取镜像会报错：
x509: certificate signed by unknown authority
8.4 Windows 环境下的转义符
在 Windows 终端通过 SSH 传输配置时，JSON 字符串（如 PullSecret）中的引号极易被 Shell 吃掉或转义错误。
解决方案：
# 方法 1：Base64 编码传输
$ pullSecret = Get-Content pull-secret.json -Raw
$ base64 = [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($pullSecret))
# 将 base64 字符串发送给 Linux，然后在 Linux 上解码
# 方法 2：使用双引号嵌套
# 在 YAML 中：pullSecret: '{"auths":{"https://quay.io/": {"auth": "..."}}}'
# 方法 3：直接在 Linux 目标机上生成文件
scp pull-secret.json user@linux-host:/tmp/
8.5 查看安装日志
# 查看安装进度
./openshift-install --dir=<dir> wait-for bootstrap-complete
# 查看 bootstrap 日志
./openshift-install --dir=<dir> bootstrap complete
# 查看节点日志 (需 SSH 到节点)
ssh -i ~/.ssh/id_rsa core@<node-ip>
journalctl -b -u bootkube.service
journalctl -b -u kubelet.service
9. 附录：快速参考
9.1 完整字段参考
apiVersion: v1 # [必填] 版本，固定为 v1
baseDomain: example.com # [必填] DNS 根域
metadata: # [必填] 元数据
name: <cluster-name> # [必填] 集群名称
platform: # [必填] 平台配置
none: {} # 裸机配置
# vsphere: {} # vSphere 配置
# aws: {} # AWS 配置
# baremetal: {} # 裸机 (IPI)
networking: # [必填] 网络配置
networkType: OVNKubernetes # 网络插件
clusterNetwork: # Pod 网段
- cidr: 10.128.0.0/14
hostPrefix: 23
serviceNetwork: # Service 网段
- 172.30.0.0/16
machineNetwork: # 节点 IP 网段
- cidr: 192.168.10.0/24
compute: # [必填] 计算节点
- name: worker
replicas: 0 # 副本数
controlPlane: # [必填] 控制平面
name: master
replicas: 1
pullSecret: '{"auths":{...}}' # [必填] 镜像仓库密钥
sshKey: 'ssh-rsa ...' # [必填] SSH 公钥
additionalTrustBundle: | # [可选] 额外 CA 证书
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
proxy: # [可选] 代理配置
httpProxy: http://proxy.example.com:8080
httpsProxy: https://proxy.example.com:443
noProxy: .example.com,10.0.0.0/8
9.2 各阶段文件说明
| 阶段 | 命令 | 生成文件 | 说明 |
|---|---|---|---|
| 1. 准备 | - | install-config.yaml |
安装配置 (需备份) |
| 2. 生成 Ignition | create ignition-configs |
*.ign, auth/ |
生成机器配置 |
| 3. 创建启动介质 | create ignition-configs |
bootstrap.ign |
用于 PXE/ISO |
| 4. SNO ISO | create image |
agent.x86_64.iso |
SNO 启动镜像 |
| 5. 安装完成 | wait-for bootstrap-complete |
- | Bootstrap 结束 |
| 6. 完全可用 | wait-for install-complete |
kubeconfig |
集群就绪 |
9.3 常用命令速查
# 安装命令
./openshift-install create cluster --dir=<dir> # 全自动安装
./openshift-install create ignition-configs --dir=<dir> # 生成 Ignition
./openshift-install agent create image --dir=<dir> # SNO 生成 ISO
# 验证命令
./openshift-install --dir=<dir> wait-for bootstrap-complete
./openshift-install --dir=<dir> wait-for install-complete
./openshift-install --dir=<dir> graph
# 查看配置
./openshift-install --dir=<dir> print-install-config
结语
install-config.yaml 看似简单，实则牵一发而动全身。
- SNO 模式追求极致的精简与自爪，适合边缘和资源受限场景
- HA 模式考验对基础设施（DNS/LB）的掌控能力，适合生产环境
建议：
- 安装前完整执行第 7 章检查清单
- 备份
install-config.yaml - 先在测试环境验证配置
- 生产环境部署前进行完整架构评审
希望本文能为您构建稳定的 OpenShift 底座提供参考。
文档版本：v2.0
作者：OKD Community
许可证：CC-BY-SA 4.0
汇聚全球AI编程工具，助力开发者即刻编程。
更多推荐
14
0- 0
已为社区贡献5条内容
所有评论(0)