OpenShift (OKD) 部署配置：install-config.yaml 深度解析与全场景模板

摘要：install-config.yaml 是 OpenShift 集群的基因图谱。本文从架构师视角出发，深度解剖该文件的核心字段，并分别针对 SNO (单节点边缘) 和 HA (高可用生产) 两种场景，提供基于 Bare Metal (Platform None) 的标准配置模板与网络规划指南。

适用版本：OKD 4.10+ / OpenShift 4.10+

最后更新：2026-01-15

目录

  1. 核心字段全景解析
  2. 部署模式对比
  3. 场景一：SNO 单节点配置模板
  4. 场景二：HA 高可用配置模板
  5. 网络规划详解
  6. 进阶：Ignition 配置与 Day 0 定制
  7. 安装前检查清单
  8. 故障排查与避坑指南
  9. 附录：快速参考

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 (高可用)
适用场景边缘计算、开发测试、资源受限生产环境、高可用要求
节点数量13+ 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 资源要求

组件最小配置推荐配置
CPU8 核16 核
内存32 GB64 GB
存储120 GB SSD256 GB SSD
网络1Gbps10Gbps

注意：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 IPclusterNetwork容器网络，每个 Pod 分配一个 IP严禁与物理网络冲突
Service IPserviceNetworkKubernetes Service 地址，CoreDNS 使用该网段需避开物理网络
节点 IPmachineNetwork物理节点的管理 IP，OVN 隧道基于此建立必须与实际网络匹配

5.2 IP 规划建议

假设公司内网为 10.0.0.0/8，建议使用以下网段避开冲突：

用途推荐网段说明
Pod Network172.20.0.0/14/14 可提供约 260K Pod IP
Service Network172.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 .

如果要定制，必须分步执行：

  1. 准备 install-config.yaml 和 openshift/ 目录下的定制文件
  2. 运行 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 记录检查表

记录类型主机名指向必需
Aapi.<cluster>.<domain>LB / Master 1 IP是
Aapi-int.<cluster>.<domain>LB / Master 1 IP是
A*.apps.<cluster>.<domain>Ingress LB / Worker IP是
AAAA同上 (IPv6 环境)-可选

7.3 端口要求

源 → 目标端口协议说明
Bootstrap → Master6443TCPIgnition 配置获取
Worker/Master → LB6443TCPAPI Server
LB → Master6443TCPAPI Server
LB → Master22623TCPIgnition 配置服务
任意 → Master/Worker80/443TCPIngress (HTTP/HTTPS)
Master ↔ Master2379/2380TCPEtcd
Master ↔ Master9000-9999TCPOVN 隧道

8. 故障排查与避坑指南

8.1 常见问题与解决方案

问题现象可能原因解决方案
安装卡在 “Waiting for bootstrap”Bootstrap 无法连接 Master检查网络、防火墙、DNS 配置
证书验证失败时间不同步同步 NTP 时间
镜像拉取失败Pull Secret 错误/过期重新获取 Pull Secret
x509 证书错误私有 CA 未信任配置 additionalTrustBundle
Pod 无法分配 IPPod/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. 生成 Ignitioncreate ignition-configs*.ign, auth/生成机器配置
3. 创建启动介质create ignition-configsbootstrap.ign用于 PXE/ISO
4. SNO ISOcreate imageagent.x86_64.isoSNO 启动镜像
5. 安装完成wait-for bootstrap-complete-Bootstrap 结束
6. 完全可用wait-for install-completekubeconfig集群就绪

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）的掌控能力，适合生产环境

建议：

  1. 安装前完整执行第 7 章检查清单
  2. 备份 install-config.yaml
  3. 先在测试环境验证配置
  4. 生产环境部署前进行完整架构评审

希望本文能为您构建稳定的 OpenShift 底座提供参考。

文档版本：v2.0
作者：OKD Community
许可证：CC-BY-SA 4.0

# openshift # php # 开发语言 # 云计算 # 容器 # 云原生 # k8s
Logo
AI编程社区

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

码道：用 Python + FastAPI 快速构建一个学生信息管理接口：从零到 Swagger 在线文档

在日常开发和教学中，我们经常需要一套简单、可控、能快速上手的后端接口来演示"前后端分离"、练习 Restful API 设计，或者作为前端联调的 Mock 服务。传统做法往往是搭一套完整的 Web 工程：配置数据库、编写 DAO、引入 ORM、做请求分发……一套流程下来，光环境搭建就要花去不少时间，对于想快速验证想法、或者刚入门 API 开发的同学来说，显得过于沉重。

avatar AI编程社区
cover

码道 · 寻艺——从零构建“非遗交互式对话平台“的完整实践

avatar AI编程社区

码道：从零构建学生信息管理系统 API：FastAPI 内存版 CRUD 项目全解析

FastAPI 的强大，很大程度上来自 Pydantic 的校验能力。我们写下类型声明，FastAPI 在运行时自动把它变成边界检查器。name：字符串，长度限制 1 到 50；age：整数，限制在 6 到 120 之间（ge大于等于、le小于等于）；gender：字符串，用正则限定只能是"男"“女”“其他”；email：邮箱格式字符串；grade与major：可选字段，代表班级和专业方向。

avatar AI编程社区