OpenShift 4 离线安装复盘（精华版）

详细安装步骤见 OpenShift 4企业高可用集群(离线)安装实践 & Troubleshooting记录，本文重新梳理并剔除了部分不适合手机阅读的细节，总结自己对整个过程的认识，并强调一些网上资源未提及或者不够明显的地方，供大家参考。

在 OpenShift 4.2 才开始提供的离线安装上，我们尝试验证了如下内容：

• 按照 Bare Metal 方式在 non-tested platforms 环境（VMware ESXi 6.7.0，非 vSphere）成功安装部署。
• 不需依赖 DHCP，采用 OpenShift 4.1 Bare Metal Install Quickstart 中第二种 Static IPs 方式但修正了其中的错误。对于小规模集群的正式部署也建议采用这种方式。
• 不需依赖 LB，但仅仅针对试验环境确认这种方式可行。正式部署不应采用。

Reference

• 注意 OpenShift 文档和软件下载在 openshift.com 和 redhat.com 各有一套，但是后者的下载速度、内容更新、文档格式均优于前者，因此建议主要使用红帽网站，不过有些内容需要红帽账号。
• 安装过程主要参考：
  • 官方文档 Chapter 9. Installing in restricted networks 的 9.1、9.3 节。
  • 博客 OpenShift 4.1 Bare Metal Install Quickstart 及 OpenShift 4.2 Disconnected Install（但是注意 Static IPs 一节有误，以下提及）。
• 故障排除：
  • OpenShift 安装程序源码：https://github.com/openshift/installer。因此该项目的 Troubleshooting 文档和 Issues 是出问题后首先需要搜索确认的地方。
  • 红帽知识库：https://access.redhat.com/search/#/knowledgebase。尝试过程中遇到的 Static IPs 问题只有在这儿才搜到正确答案。
• Online 小工具如 Certificate Decoder、Base64 Decode and Encode、CIDR Calculator 等，辅助排查问题很方便，当然 Linux 也提供了类似命令行工具，各人自便。

Pre-installation

Prerequisites

• 根据官方文档，OpenShift 安装需依赖 DHCP、LB、DNS、HTTP Server、Mirror registry 等服务，而这些服务大多部署在自行搭建的堡垒机（bastion host）。
• 实际验证我们可以省略 DHCP、LB 的工作。对于小规模集群的正式部署我们也建议不使用 DHCP，但是 LB 是必须的。
• 对于离线安装的场景，一个正常企业环境下 Mirror registry 也应该是现成的。

Bastion host

文档多处提及了堡垒机，在此总结一下它的不同角色用途：

• 部署以上需自行搭建的依赖服务。也不一定非要挤在一起，试验过程我们也独立搭了一台 LB。
• 同步镜像外网内容。
• 制作 Ignition 配置文件。
• 作为之后部署的 OpenShift 节点机的跳板机。

HTTP Server

OpenShift 在安装过程中需要从 HTTP Server 获取两种内容：

• 安装文件：由于这类文件可以反复使用，应上载保存在企业内现成的 Public HTTP Server。
• Ignition 配置文件（用途之后说明）：由于只是在安装本集群时使用，且含有敏感信息（bootstrap.ign 中"/root/.docker/config.json"的 contents 包含 registry 用户密码），不应放在 Public HTTP Server。暂时自行搭建，但仍有后续问题（以下讨论）。

自行搭建也参考 Mirror registry 使用容器方式并挂载 Ignition 配置文件的目录，尽量简化安装步骤。

DHCP

不使用 DHCP 则需要手工指定网络配置，由于 OpenShift 4 节点机使用的 RHCOS 系统不同于以往 RHEL / CentOS 具备直观的安装向导界面，需要使用博客 OpenShift 4.1 Bare Metal Install Quickstart 提及的以下两种 Static IPs 方式：

• 针对每个节点机创建一个 Ignition 配置文件将网络信息嵌入。
• 在刚开始安装系统时手工输入引导参数指定网络配置。

第一种方式感觉繁琐，采用第二种方式但博客中的 IP 配置格式有误，参见 Set up static IP configuration for an RHCOS node（https://access.redhat.com/solutions/4531011）：

ip=<WORKER_NODE_IP>::<GATEWAY_IP>:<NETMASK>:<HOSTNAMEFQDN>:<INTERFACE_NAME>:none nameserver=<DNS_IP>

如果按博客中的格式则 DNS 在安装时起作用了但实际在安装后未写入节点机 /etc/resolv.conf。

另外这种方式也有问题，就是无法拷贝粘贴的话手工输入大量文本极易出错，但因为本来在此处就有不少输入、额外并未多出太多，勉强可以接受。

LB

省略 LB 纯粹是为了试验环境省事，主要做法是借助 DNS 将：

• api 先指向 bootstrap 后指向 master01（切换时机见官方文档对 LB 的调整）。
• *.apps 指向 worker01。

经实际验证无问题，但明显也失去了高可用，而且如果不调整反向域名配置还容易把节点机的 hostname 搞乱，对不熟练的人虽然省去了 LB 搭建但可能干扰更大。

DNS

DNS 配置参考博客 OpenShift 4.1 Bare Metal Install Quickstart：

https://github.com/openshift-tigerteam/guides/tree/master/ocp4

如果不搭建 LB 则需要删除 api 的反向记录。

Mirror

既然是 Installing in restricted networks，对于一个正常的企业环境，内部镜像应该是现成的最不需要自行搭建的，但是 OpenShift 4 安装程序对镜像的使用却不是通常的方式：

• 在配置 quay.io 的内部镜像后，尝试调整安装程序使用该镜像但仍然报错，提示需要 quay.io/openshift-release-dev/ocp-v4.0-art-dev 镜像，而 https://quay.io/organization/openshift-release-dev 项下只有 ocp-release 却没有 ocp-v4.0-art-dev。
• 在之后的试验中可以发现相应的镜像是在 oc adm release mirror 时生成。

虽然无法使用正常的镜像方式，但如果企业内部有现成、规范的（如 HTTPS、docker 2.2 spec-compliant）的镜像服务，我们主要的工作并不是像文档指示的那样搭建 Mirror registry，而仅仅完成官方文档的 9.1.5. Mirroring the OpenShift Container Platform image repository 即可；且暂时可省略 9.1.6. Using sample imagestreams in a restricted network installation，不影响主要的安装，但记住可能对安装成功后的部分功能有影响。

Mirroring 后可以使用以下命令确认是否生成相应镜像：

podman login registry.example.com:5000
podman image pull registry.example.com:5000/ocp4/openshift4:etcd

至于为什么 etcd 是一个 tag 未得到文档提示，完全是从部署的 Mirror registry 内部找线索时发现：

[root@bastion tags]# pwd
/opt/registry/data/docker/registry/v2/repositories/ocp4/openshift4/_manifests/tags
[root@bastion tags]# ls -d *etcd*etcd  kube-etcd-signer-server

另外注意如果按照文档部署 Mirror registry 容器，这个应用貌似有 Bug，遇到过多次刚开始验证正常、但过一段时间就停止服务的状况，只能重启解决，这个会影响之后的安装。

总之 OpenShift 4 的离线安装主要折腾在这一步，很不理解为什么不是常规的通过镜像代理获取 Image、而非要通过特定程序来生成 Image？如果不这么折腾，那么对于正常的企业环境，其实离线安装和在线安装的工作量就没什么差别，Maven、YUM 等等等等不都是简单配置内部镜像就搞定了么。

大致的猜测是有些内容不能静态获取、必须动态生成？追踪过相应程序：

https://github.com/openshift/oc/blob/openshift-clients-4.2.0-201910041700/pkg/cli/admin/release/mirror.go

但没深入。无论如何，从最终用户的感觉来看太折腾了，且无法利用以往的排错手段。

Installing

Ignition config

到这一步开始了正式安装。记录自己在这一步遇到的坑：

• 在反复试验时，比如 install-config.yaml 所在的目录是 config，必须 rm -rf config 而不是 rm -rf config/*，后者未删除其中的隐藏文件 .openshift_install_state.json，有可能引起：x509: certificate has expired or is not yet valid。
• 在文档和博客示例中 install-config.yaml 的 cidr 配置为 10 网段，由于未细看文档理解成了节点机网段，这造成了整个过程中最莫名其妙的错误：no matches for kind MachineConfig。

Bootstrap machine

由于不使用 DHCP，相比参考文档在这一步手工输入的内容多出以下部分：

ip=<WORKER_NODE_IP>::<GATEWAY_IP>:<NETMASK>:<HOSTNAMEFQDN>:<INTERFACE_NAME>:none nameserver=<DNS_IP>

这一步最麻烦的是不得不在安装界面手工输入两三百字符的引导参数（VMware ESXi 真的不能拷贝粘贴？），因此错误也经常是由此引起，如果出错进入 emergency shell 可以首先验证网络配置：

hostname -I && ip route show && cat /etc/resolv.conf

并 ping / curl 相关服务，如果正常通常是引导参数输入错误，reboot 后重新开始。

成功安装后从堡垒机访问 bootstrap 机器，确认 6443、22623 等端口是否已启用（需等一段时间），如：

[core@bootstrap ~]$ sudo netstat -ltnp|grep 22623
tcp6 0 0 :::22623 :::* LISTEN 4466/machine-config

待服务正常后继续下一步。常见错误见以下 Troubleshooting - Error pulling image。

Master machines

步骤类似 Bootstrap machines。安装成功后确认 2379 端口是否已启用：

[core@master01 ~]$ sudo netstat -ltnp|grep 2379
tcp6       1      0 :::2379                 :::*                    LISTEN      1655/etcd

待 master 各节点机服务都正常后先不着急装 worker，继续下一步。常见错误见以下 Troubleshooting - Error pulling image，以及 etcd is unhealthy 等。

Creating the cluster

如果之前 bootstrap、master 各节点机相关服务都成功启动的话，这一步基本不出问题。

到这一步需要切换 api 的指向，部署了 LB 则在 LB 处理否则在 DNS 处理。

Worker machines

步骤类似 Bootstrap machines。无特别需要注意之处。

Logging in to the cluster

无特别需要注意之处。

Web Console

登录进去后左上角的 Administrator/Developer 选项并不代表系统、集群管理，而是应用的管理，在 OpenShift 3 的 Pod 之类的操作现在是在 Administrator 项下。

Post-installtion

OAuth

提示注意一点，添加新的 IDP 后，需要进入以下界面切换到相应的 IDP：

否则用这个 IDP 的数据检查另一个 IDP 的用户密码当然会出错。如果没有出现这个窗口可以输入 Web Console 地址自动跳转。

Registry

注意修改配置后不是马上生效，试验过程中观测有的节点机自动重启了有的有没有，未确定是否必须。

Go into production

到这一步平台安装基本就位，之后的系统管理另说，但如果是正式部署，仍然有更多需要马上考虑的情况，如文档中所涉及的堡垒机、依赖服务等，就是一个临时搭建的感觉，但对于所谓 Day 2 Operations，最典型如之后新增节点机，是否仍然需要依赖这些服务：

• HTTP Server：尝试在平台就位后新增节点机，按照之上的做法当然没问题，但显然还是从临时的 HTTP Server 获取 master.ign / worker.ign。文档未提及搭好的平台是否有其他地方提供同样数据（为什么这么想是因为之后再建 master / worker 节点时应该也需要 bootstrap.ign 的内容，既然不是从 HTTP Server 获取自然是平台内已存在），因此在正式部署时还需要一个持续、有权限控制的 HTTP Server？
• Mirror registry：显然官方文档提及的自己搭建只能是临时用途，所使用的软件也有 Bug，而即使没 Bug 也明显不是一个产品级的软件，同时考虑到还有网络权限等等，不可能作为一个公共、正式的服务。因此正规部署时就不应该用自己搭建的。
• DHCP：当然一开始就不用最好。但即使部署时用了这种方式，应该也可以在之后转为静态 IP，但奇怪的是在最早的 4.2 官方文档有这一句"After the initial boot, the machines can be configured to use static IP addresses."，最新文档却未提及？
• DNS：如果开始用自己搭建的部署，如何在正式使用时配置为企业内正式的 DNS？尝试过手工修改节点机 /etc/hosts 内容重启后自动恢复，这个符合 RHCOS 的预期，还没开始研究怎么通过 OpenShift 4 的 Machine Config 统一变更，或者说一开始就不要用临时的 DNS？
• 备份：包括跳板机的私钥以及 Ignition 配置文件。总之假定堡垒机消失也不会影响之后的运维。

Troubleshooting

What's new

相比 OCP 3 的安装及配置管理以及常用的 Debug 手段，OCP 4 有如下大的改动：

• OS - RHCOS
• Container engine - CRI-O

前者在以上章节中多有提及，后者其实也多次提到了使用 podman 操作容器而非 docker，相关内容请参考 https://blog.openshift.com/crictl-vs-podman/。

Error pulling image

在 Bootstrap、Master 各节点机安装后应该自动启用相关服务，通过检查服务端口来确认，如果观察相应端口较长时间仍未启用，执行：

sudo podman ps -a

如果没有正常运行状态的容器，可以在 journalctl 日志中搜索"pulling image"，如果出现"Error pulling image"则有以下可能：

• 在 Mirror registry 一节提到按官方文档部署的 registry 服务有可能出 Bug，需要重启。但重启 registry 服务后 bootstrap 貌似不能自动重试失败的任务，尚不清楚怎么手工启动相应程序，使用笨办法需重装解决。
• 如果更具体的出错日志类似"lookup quay.io on 10.130.250.201:53: no such host"，表示没有正常访问内部 registry 镜像。可能是 Ignition 配置的 imageContentSources - mirrors 有问题，检查由其生成的 /etc/containers/registries.conf 配置并尝试 Mirror registry 一节提到的验证命令（podman pull）。如果是 Ignition 出错需要回到那一步重新开始。

etcd is unhealthy

成功安装三台 master 后在 bootstrap 使用 journalctl -b -f -u bootkube.service 持续观察时提示：

Oct 30 09:08:14 bootstrap.example.com bootkube.sh[1804]: https://etcd-0.example.com:2379 is healthy: successfully committed proposal: took = 3.288304ms
Oct 30 09:08:14 bootstrap.example.com bootkube.sh[1804]: https://etcd-1.example.com:2379 is healthy: successfully committed proposal: took = 4.572719ms
Oct 30 09:18:14 bootstrap.example.com bootkube.sh[1804]: https://etcd-2.example.com:2379 is unhealthy: failed to connect: dial tcp 10.130.250.205:2379: connect: connection refused

在 master 节点机搜索相关日志：

[core@master03 ~]$ find /var/log -name *etcd*.log 2>/dev/null
/var/log/containers/etcd-member-master03.paas02.uat.taikangcloud.com_openshift-etcd_etcd-member-f3f94cb1b10f8a0421f70fbfcd44cf5dc280542925db01b988e3f26f312f5cb6.log

发现错误消息：

2019-10-30T09:36:51.754131911+00:00 stderr F 2019-10-30 09:36:51.753999 I | embed: rejected connection from "10.130.250.203:54534" (error "read tcp 10.130.250.205:2380->10.130.250.203:54534: use of closed network connection", ServerName "ocp4.example.com")

未找到解决办法，重装 master03 仍然出错，三台 master 全部重装后问题解决。推测是在使用 DHCP 试验的过程中配置了预期外的 IP 引起，未确定。

no matches for kind MachineConfig

成功安装三台 master 后在 bootstrap 用 journalctl -b -f -u bootkube.service 观察长时间无新输出，使用 journalctl -f 或者 journalctl -f -u bootkube -u openshift 观察有如下提示不停出现：

Nov 01 07:02:17 bootstrap.example.com openshift.sh[1812]: Executing kubectl create --filename ./99_openshift-machineconfig_master.yaml
Nov 01 07:02:18 bootstrap.example.com openshift.sh[1812]: error: unable to recognize "./99_openshift-machineconfig_master.yaml": no matches for kind "MachineConfig" in version "machineconfiguration.openshift.io/v1"

上网搜索完全未发现有提及相关问题的，非常奇怪，由于是使用 Bare Metal 方式在 VM 上安装、上述错误提及的又是 MachineConfig 相关，还以为是未验证平台的 Bug。后来反复查看安装文档，发现在 install-config.yaml 中配置 clusterNetwork 时错误理解成节点机的 IP 网段了，但修改后仍未解决，后转向 master01 日志发现了明确线索：

Nov 01 09:39:00 master01.example.com crio[1221]: 2019-11-01T09:39:00Z [error] Multus: error in invoke Delegate add - "openshift-sdn": CNI request failed with status 400: 'failed to run IPAM for d92ef9176c893dac9d8b2135741b64d7ec41eee329f707bfb053f42748af05ba: failed to run CNI IPAM ADD: failed to allocate for range 0: no IP addresses available in range set: 192.8.1.1-192.8.1.6

原因是在修改 clusterNetwork 时仅改动了 cidr 而忘了将 hostPrefix 从 29 改为 23，导致可用 IP 非常少引起故障。

Tips

补充一些在排查过程中需要注意的地方：

• 虽然日志是查错的重要线索，但是安装过程中有很多情况是等待条件就位时报的错，非常干扰，如果日志提示能够更加明确最好，比如：访问 xxx 拒绝，等待某服务启动？
• 同上，如果报的某个错误毫无头绪，很可能是在别处出错了，参见 no matches for kind MachineConfig 一节。
• 在安装过程中验证服务正常后再进入下一步，特别是 bootstrap、master 那几步，免得多走弯路。