OpenShift 安裝教學：從 Local 到正式環境完整指南

OpenShift 安裝是很多人的第一道關卡。看著官方文件的前置需求清單，DNS、負載平衡器、憑證⋯⋯還沒開始就想放棄。

但其實沒那麼難。這篇教學會帶你從最簡單的本機環境開始，一路到正式生產環境的部署。如果你對 OpenShift 還不熟悉，建議先閱讀 OpenShift 完整指南。

---

安裝方式總覽

IPI vs UPI

OpenShift 有兩種主要安裝方式：

方式	全名	說明	適用場景
IPI	Installer-Provisioned Infrastructure	安裝程式自動建立基礎設施	雲端環境
UPI	User-Provisioned Infrastructure	使用者先準備好基礎設施	裸機、VMware、特殊需求

IPI 的特色：

• 最簡單，幾乎一鍵安裝
• 安裝程式會自動建立 VM、網路、負載平衡器
• 適合 AWS、Azure、GCP 等主流雲端

UPI 的特色：

• 需要先準備好所有基礎設施
• 完全控制每個環節
• 適合裸機、VMware、有特殊網路需求的環境

安裝選項總覽

選項	複雜度	用途	成本
OpenShift Local	低	本機開發測試	免費
Developer Sandbox	低	雲端學習環境	免費
IPI（雲端）	中	雲端生產環境	雲端費用 + 訂閱
UPI（裸機）	高	自建資料中心	硬體 + 訂閱
ROSA/ARO	低	託管服務	託管費用

安裝前規劃

不管哪種安裝方式，都要先想清楚：

叢集規模：

• 開發測試：3 Master + 2 Worker
• 小型生產：3 Master + 3 Worker
• 中大型生產：3 Master + 6+ Worker

網路規劃：

• Pod CIDR：預設 10.128.0.0/14
• Service CIDR：預設 172.30.0.0/16
• 不能跟現有網路衝突

DNS 規劃：

• API endpoint：api.cluster.example.com
• Ingress wildcard：*.apps.cluster.example.com

插圖：展示 OpenShift 安裝方式選擇流程。起點是「選擇安裝...

場景描述： 展示 OpenShift 安裝方式選擇流程。起點是「選擇安裝方式」，第一個判斷「目的是學習還是生產」，學習指向「OpenShift Local 或 Developer Sandbox」；生產則進入第二個判斷「使用公有雲還是自建」，公有雲指向「IPI 或 託管服務（ROSA/ARO）」，自建指向「UPI 安裝」。

視覺重點：

• 主要內容清晰呈現

必須出現的元素：

• 依據描述

需要顯示的中文字： 無

顏色調性： 專業、清晰

避免元素： 抽象圖形、齒輪

Slug: openshift-installation-decision-tree

---

環境需求

硬體需求

Control Plane 節點（每節點）：

資源	最低需求	建議配置
CPU	4 vCPU	8 vCPU
記憶體	16 GB	32 GB
儲存	100 GB SSD	200 GB SSD

Worker 節點（每節點）：

資源	最低需求	建議配置
CPU	2 vCPU	4+ vCPU
記憶體	8 GB	16+ GB
儲存	100 GB	依應用需求

Bootstrap 節點（安裝時暫用）：

• 規格同 Control Plane
• 安裝完成後可刪除

網路需求

必要連接埠：

連接埠	用途	來源
6443	Kubernetes API	所有節點、管理端
22623	Machine Config Server	節點
443	HTTPS Ingress	外部流量
80	HTTP Ingress	外部流量

節點間通訊：

• Control Plane 之間：etcd 通訊（2379-2380）
• 所有節點：OVN-Kubernetes（6081、9000-9999）

DNS 設定

DNS 是安裝成功的關鍵，很多安裝失敗都卡在這裡。

必要 DNS 記錄：

# API endpoint（指向負載平衡器或 Master）
api.cluster.example.com.      A    192.168.1.10

# API internal（指向負載平衡器或 Master）
api-int.cluster.example.com.  A    192.168.1.10

# Ingress wildcard（指向 Router）
*.apps.cluster.example.com.   A    192.168.1.20

# etcd（每個 Master 一筆）
etcd-0.cluster.example.com.   A    192.168.1.11
etcd-1.cluster.example.com.   A    192.168.1.12
etcd-2.cluster.example.com.   A    192.168.1.13

# etcd SRV records
_etcd-server-ssl._tcp.cluster.example.com. SRV 0 10 2380 etcd-0.cluster.example.com.
_etcd-server-ssl._tcp.cluster.example.com. SRV 0 10 2380 etcd-1.cluster.example.com.
_etcd-server-ssl._tcp.cluster.example.com. SRV 0 10 2380 etcd-2.cluster.example.com.

負載平衡器

需要兩個負載平衡器（或一個多 Port 的）：

API Load Balancer：

前端	後端	說明
6443	Master:6443	Kubernetes API
22623	Master:22623	Machine Config

Ingress Load Balancer：

前端	後端	說明
443	Worker:443	HTTPS 流量
80	Worker:80	HTTP 流量

---

OpenShift Local 安裝

OpenShift Local（前身 CodeReady Containers, CRC）是最快上手 OpenShift 的方式。

系統需求

資源	需求
CPU	4+ 核心
記憶體	9+ GB（建議 16 GB）
儲存	35+ GB
作業系統	macOS、Windows、Linux

下載安裝

Step 1：取得 Pull Secret

1. 前往 console.redhat.com
2. 登入 Red Hat 帳號（免費註冊）
3. 下載 Pull Secret 檔案

Step 2：下載 OpenShift Local

從同一頁面下載適合你作業系統的版本。

Step 3：安裝與設定

# macOS / Linux
tar -xvf crc-linux-amd64.tar.xz
sudo mv crc-linux-*-amd64/crc /usr/local/bin/

# 設定（會下載 VM 映像檔，約 4GB）
crc setup

# 啟動
crc start

系統會問你 Pull Secret，貼上剛才下載的內容。

存取叢集

啟動完成後：

# 查看登入資訊
crc console --credentials

# 輸出範例：
# To login as a regular user, run 'oc login -u developer -p developer https://api.crc.testing:6443'.
# To login as an admin, run 'oc login -u kubeadmin -p xxxxx-xxxxx-xxxxx-xxxxx https://api.crc.testing:6443'.

# 開啟 Web Console
crc console

常用指令

# 查看狀態
crc status

# 停止
crc stop

# 刪除（重新開始）
crc delete

# 調整資源
crc config set memory 16384
crc config set cpus 6

OpenShift Local 限制

• 單節點，無法測試多節點功能
• 不支援 Operator Hub 全部內容
• 不適合跑重負載
• 每次啟動需要幾分鐘

---

IPI 安裝（雲端）

IPI 是雲端環境最推薦的安裝方式。以 AWS 為例說明流程。

AWS 前置準備

1. IAM 權限

安裝程式需要的 IAM 權限很多，建議用官方的 Policy 範本。簡化起見，可以先給 Administrator 權限測試。

2. 安裝 AWS CLI

aws configure
# 輸入 Access Key、Secret Key、Region

3. 下載安裝程式

# 從 mirror.openshift.com 下載
wget https://mirror.openshift.com/pub/openshift-v4/clients/ocp/stable/openshift-install-linux.tar.gz
tar -xvf openshift-install-linux.tar.gz
sudo mv openshift-install /usr/local/bin/

建立 install-config.yaml

# 互動式建立設定檔
openshift-install create install-config --dir=my-cluster

系統會問你：

• SSH Public Key（用於 Debug 登入節點）
• Platform（選 AWS）
• Region
• Base Domain（如 example.com）
• Cluster Name（如 my-cluster）
• Pull Secret

生成的 install-config.yaml 範例：

apiVersion: v1
baseDomain: example.com
metadata:
  name: my-cluster
platform:
  aws:
    region: ap-northeast-1
controlPlane:
  name: master
  replicas: 3
  platform:
    aws:
      type: m5.xlarge
compute:
- name: worker
  replicas: 3
  platform:
    aws:
      type: m5.large
networking:
  networkType: OVNKubernetes
  clusterNetwork:
  - cidr: 10.128.0.0/14
    hostPrefix: 23
  serviceNetwork:
  - 172.30.0.0/16
pullSecret: '{"auths":...}'
sshKey: 'ssh-rsa AAAA...'

執行安裝

# 備份 install-config.yaml（安裝會刪除它）
cp my-cluster/install-config.yaml my-cluster/install-config.yaml.bak

# 開始安裝（約 30-45 分鐘）
openshift-install create cluster --dir=my-cluster --log-level=info

安裝過程：

1. 建立 VPC、Subnet、Security Group
2. 建立 Route53 DNS 記錄
3. 建立 EC2 實例（Bootstrap → Master → Worker）
4. 等待 Bootstrap 完成
5. 等待 Operator 就緒

驗證安裝

# 設定 kubeconfig
export KUBECONFIG=my-cluster/auth/kubeconfig

# 驗證節點
oc get nodes

# 驗證 Operator
oc get clusteroperators

# 取得 Console URL
oc whoami --show-console

插圖：展示 IPI 安裝的步驟流程。從「準備 install-co...

場景描述： 展示 IPI 安裝的步驟流程。從「準備 install-config.yaml」開始，依序是「建立 Bootstrap」→「建立 Master 節點」→「Bootstrap 完成」→「建立 Worker 節點」→「Operator 初始化」→「安裝完成」。每個步驟標註預估時間。

視覺重點：

• 主要內容清晰呈現

必須出現的元素：

• 依據描述

需要顯示的中文字： 無

顏色調性： 專業、清晰

避免元素： 抽象圖形、齒輪

Slug: openshift-ipi-installation-flow

---

UPI 安裝（裸機/VMware）

UPI 安裝需要更多準備工作，但能完全控制每個環節。

基礎設施準備

1. 準備 VM 或裸機

角色	數量	規格
Bootstrap	1	4 CPU, 16GB RAM, 100GB
Master	3	4 CPU, 16GB RAM, 100GB
Worker	2+	2 CPU, 8GB RAM, 100GB

2. 設定 DNS

按前面「環境需求」章節設定所有 DNS 記錄。

3. 設定負載平衡器

可以用 HAProxy：

# /etc/haproxy/haproxy.cfg
frontend api
    bind *:6443
    default_backend api-backend

backend api-backend
    balance roundrobin
    server bootstrap 192.168.1.10:6443 check
    server master-0 192.168.1.11:6443 check
    server master-1 192.168.1.12:6443 check
    server master-2 192.168.1.13:6443 check

frontend machine-config
    bind *:22623
    default_backend machine-config-backend

backend machine-config-backend
    balance roundrobin
    server bootstrap 192.168.1.10:22623 check
    server master-0 192.168.1.11:22623 check
    server master-1 192.168.1.12:22623 check
    server master-2 192.168.1.13:22623 check

生成 Ignition 設定檔

Ignition 是 CoreOS 的初始化設定格式，告訴節點啟動時該做什麼。

# 建立 install-config.yaml
openshift-install create install-config --dir=my-cluster

# 生成 manifests
openshift-install create manifests --dir=my-cluster

# 生成 Ignition 檔案
openshift-install create ignition-configs --dir=my-cluster

會產生：

• bootstrap.ign：Bootstrap 節點用
• master.ign：Master 節點用
• worker.ign：Worker 節點用

架設 Web Server

節點需要透過 HTTP 取得 Ignition 檔案：

# 簡單起見用 Python
cd my-cluster
python3 -m http.server 8080

Bootstrap 流程

1. 啟動 Bootstrap 節點

用 RHCOS ISO 開機，在 Kernel 參數加入：

coreos.inst.install_dev=/dev/sda
coreos.inst.ignition_url=http://192.168.1.1:8080/bootstrap.ign

2. 啟動 Master 節點

同樣方式，但指向 master.ign。

3. 等待 Bootstrap 完成

openshift-install wait-for bootstrap-complete --dir=my-cluster --log-level=info

看到「Bootstrap Complete」就可以把 Bootstrap 節點從負載平衡器移除。

4. 啟動 Worker 節點

指向 worker.ign 開機。

審核 CSR

Worker 節點加入時需要審核憑證請求：

# 查看待審核的 CSR
oc get csr

# 審核全部
oc get csr -o name | xargs oc adm certificate approve

Worker 節點會送兩次 CSR（node-bootstrapper、node），都要 approve。

UPI 安裝卡關了嗎？基礎設施設定有很多眉角。預約架構諮詢，讓專家幫你解決問題。

---

安裝後設定

Web Console 存取

安裝完成後，用瀏覽器存取：

# 取得 Console URL
oc whoami --show-console

# 取得 kubeadmin 密碼
cat my-cluster/auth/kubeadmin-password

用 kubeadmin 帳號登入。

建立正式管理員帳號

kubeadmin 是臨時帳號，建議建立正式的管理員：

# 建立 HTPasswd 檔案
htpasswd -c -B -b users.htpasswd admin MySecurePassword

# 建立 Secret
oc create secret generic htpass-secret \
  --from-file=htpasswd=users.htpasswd \
  -n openshift-config

# 設定 OAuth
oc apply -f - <<EOF
apiVersion: config.openshift.io/v1
kind: OAuth
metadata:
  name: cluster
spec:
  identityProviders:
  - name: htpasswd
    type: HTPasswd
    htpasswd:
      fileData:
        name: htpass-secret
EOF

# 給 admin 叢集管理員權限
oc adm policy add-cluster-role-to-user cluster-admin admin

# 測試登入
oc login -u admin -p MySecurePassword

刪除 kubeadmin

確認新管理員可以登入後，刪除 kubeadmin：

oc delete secrets kubeadmin -n kube-system

節點標籤

為節點加上標籤，方便後續調度：

# 查看節點
oc get nodes

# 加標籤
oc label node worker-0 node-role.kubernetes.io/app=
oc label node worker-1 node-role.kubernetes.io/infra=

# 查看標籤
oc get nodes --show-labels

---

Worker Node 擴展

新增 Worker（IPI）

IPI 安裝可以透過 MachineSet 擴展：

# 查看 MachineSet
oc get machinesets -n openshift-machine-api

# 調整副本數
oc scale machineset my-cluster-worker-ap-northeast-1a \
  --replicas=4 \
  -n openshift-machine-api

新增 Worker（UPI）

UPI 需要手動加入節點：

1. 準備新的 VM/裸機
2. 用 worker.ign 開機
3. 審核 CSR

# 審核新節點的 CSR
oc get csr | grep Pending
oc adm certificate approve <csr-name>

自動擴展

設定 Cluster Autoscaler 自動擴展節點：

apiVersion: autoscaling.openshift.io/v1
kind: ClusterAutoscaler
metadata:
  name: default
spec:
  scaleDown:
    enabled: true
    delayAfterAdd: 10m
  resourceLimits:
    maxNodesTotal: 20
---
apiVersion: autoscaling.openshift.io/v1
kind: MachineAutoscaler
metadata:
  name: worker-ap-northeast-1a
  namespace: openshift-machine-api
spec:
  minReplicas: 2
  maxReplicas: 10
  scaleTargetRef:
    apiVersion: machine.openshift.io/v1beta1
    kind: MachineSet
    name: my-cluster-worker-ap-northeast-1a

---

常見安裝問題

6443 連線失敗

症狀：無法連線 API Server（port 6443）

排查：

1. 檢查 DNS：nslookup api.cluster.example.com
2. 檢查負載平衡器：確認 6443 有轉發
3. 檢查防火牆：確認 6443 有開

# 測試連線
curl -k https://api.cluster.example.com:6443/version

Bootstrap 失敗

症狀：卡在「Waiting for bootstrap to complete」

排查：

# SSH 進 Bootstrap 節點
ssh core@bootstrap-ip

# 查看 bootkube 日誌
journalctl -b -f -u bootkube.service

# 查看容器狀態
sudo crictl ps -a

常見原因：

• DNS 設定錯誤（最常見）
• Ignition 檔案下載失敗
• 防火牆阻擋通訊

憑證問題

症狀：節點無法加入、CSR 沒出現

排查：

# 檢查時間同步
timedatectl

# 檢查 machine-config-server
curl -k https://api-int.cluster.example.com:22623/config/worker

確保：

• 所有節點時間同步（NTP）
• api-int DNS 正確解析
• 22623 port 可連線

Operator 不健康

症狀：oc get clusteroperators 顯示 Degraded

排查：

# 查看特定 Operator 狀態
oc describe clusteroperator authentication

# 查看相關 Pod
oc get pods -n openshift-authentication

# 查看 Pod 日誌
oc logs -n openshift-authentication deployment/oauth-openshift

插圖：展示安裝問題排查流程。從「安裝失敗」開始，第一步檢查「DNS...

場景描述： 展示安裝問題排查流程。從「安裝失敗」開始，第一步檢查「DNS 是否正確」，否則修復 DNS；是則檢查「負載平衡器是否正常」，否則修復 LB；是則檢查「Ignition 是否可下載」，否則修復 Web Server；是則「檢查節點日誌找其他原因」。

視覺重點：

• 主要內容清晰呈現

必須出現的元素：

• 依據描述

需要顯示的中文字： 無

顏色調性： 專業、清晰

避免元素： 抽象圖形、齒輪

Slug: openshift-installation-troubleshooting

---

常見問題 FAQ

Q1：OpenShift Local 跟正式版有什麼差別？

OpenShift Local 是單節點的精簡版，功能完整但資源有限。主要差別：（1）只有一個節點，無法測試多節點功能；（2）某些 Operator 不支援；（3）效能受限於本機資源；（4）不適合跑生產工作負載。適合學習和開發測試。

Q2：IPI 跟 UPI 該選哪個？

雲端環境（AWS、Azure、GCP）優先選 IPI，簡單很多。UPI 適合：（1）裸機部署；（2）VMware 環境；（3）有特殊網路需求（如不能用雲端 DNS）；（4）需要完全控制基礎設施。如果沒有特殊需求，IPI 省時省力。

Q3：安裝要多久？

• OpenShift Local：首次設定約 15-20 分鐘
• IPI（雲端）：約 30-45 分鐘
• UPI（裸機）：2-4 小時（含基礎設施準備）

實際時間取決於網路速度、硬體效能、是否一次成功。

Q4：DNS 一定要自己設嗎？

IPI 在雲端環境會自動建立 DNS（用 Route53、Azure DNS 等）。UPI 則必須自己設定 DNS，這是最容易出錯的環節。建議用專門的 DNS server（如 BIND）或雲端 DNS 服務，不要用 /etc/hosts。

Q5：可以裝在單一節點嗎？

可以。OpenShift 支援 Single Node OpenShift（SNO），適合邊緣環境或資源有限的場景。但 SNO 沒有高可用性，不建議用在生產環境的核心系統。

---

OpenShift 安裝只是第一步

後續的架構設計更重要。網路規劃、儲存配置、安全設定⋯⋯每個決策都影響後續的穩定性和擴展性。

預約架構諮詢，確保你的容器平台從一開始就走對方向。

---

參考資源

• OpenShift 完整指南
• OpenShift 架構詳解
• OpenShift 版本生命週期
• OpenShift 價格分析
• OpenShift 進階功能設定
• OpenShift 學習路徑
• Red Hat OpenShift Installation Guide