回到所有文章

不懂 Kubernetes 也能部署:從 Zeabur 原始碼看平台怎麼藏起 Deployment、Service 與 Ingress

想讓不懂 Kubernetes 的同事自己把服務上線?Zeabur 開源的 2.0 沒有發明新的物件模型,而是改了表單問的問題、畫面上的詞,以及出錯時的說法。從原始碼整理出七個做內部部署平台可以借的做法,以及各自的代價。

「我有一個 API 要上線,要接 PostgreSQL,還要一個對外的網址。CI 已經把映像檔推到公司的 registry 了,接下來要做什麼?」

替公司做內部部署平台,很常收到 RD 這樣問。服務最後一定是 Deployment、Service 和 Ingress,但你希望 RD 不必先學會這些,就能自己把服務上線。

Zeabur 在 2026 年 10 月開源的 2.0 是一個值得參考的例子,因為它沒有發明自己的服務模型。表單產生的是一般的 Kubernetes 物件,沒有 Zeabur 專屬的欄位;官方文件也寫明 Zeabur 沒有自己的資料庫,畫面上的專案和服務都直接從叢集讀出來,移除 Zeabur 之後,物件都還在。

所以它的抽象不在物件上,而在使用者看得到的地方:表單問什麼問題、哪些答案由平台自己查、畫面上用什麼詞、出錯時怎麼說。這篇從原始碼整理出七個做法,每個都用開頭那位 RD 的情境舉例,也寫出照著做要付出的代價。

情境是假設的。我沒有安裝執行 Zeabur,內容來自原始碼(commit d4bd01b,版本 0.1.1,仍是 pre-alpha)與官方文件,最新版本可能已經不同。原始碼與開發規範是英文,引號內的中文是我的翻譯;官方中文文件與介面文字直接引用。

1. 問使用者答得出來的問題,物件是答案的結果

把 YAML 包成表單,最直接的做法是一個欄位對應一個 Kubernetes 欄位。這樣的表單,RD 還是填不出來,因為每個欄位背後都要先懂那個物件。

Zeabur 改問 RD 答得出來的問題,第一個是「你手上有什麼」。新增選單的選項是 Docker 映像檔、從 Git 部署、上傳資料夾、Docker Compose、應用程式範本,以及各種資料庫,沒有一個叫 Deployment 或 Ingress;從 YAML 建立放在最後的 進階 裡。

RD 手上有映像檔,選 Docker 映像檔。表單接著問映像檔、名稱、連接埠,以及要不要公開網域,環境變數、磁碟區、規格等收在 更多設定。這些答案在瀏覽器裡組成一組物件:

RD 回答的問題產生的物件
映像檔、名稱Deployment
連接埠Service,以及容器的 TCP 就緒檢查
公開網域Ingress;叢集有 cert-manager 的簽發者時加上 TLS
環境變數Secret <名稱>-env
磁碟區PersistentVolumeClaim
規格:小/中/大requests 與記憶體的 limit

RD 回答的是「要不要接受連線」「要不要從外面連得到」,Service 和 Ingress 是答案的結果。連接埠留空,就是不接受連線的背景服務,只會建立 Deployment。

做不到的事,也在填表之前說。叢集還沒裝 PostgreSQL 的 operator(Zeabur 用 CloudNativePG)時,選項下方直接寫「需要先安裝 …」,點開是安裝步驟;角色權限不夠的選項照樣顯示,但無法點選,並標出哪個角色才能用。RD 不會填完一整張表,才在最後一步失敗。

問題換了,從答案產生物件的規則就得由平台維護。映像檔、Git、Compose 三個入口最後都會變成 Deployment,這套規則要共用,否則同樣的答案從不同入口進來,會得到不一樣的物件。

2. 使用者答不出來的,平台自己去查

有些問題換成白話,RD 還是答不出來:服務聽哪個連接埠?「安全性」該選哪個?Zeabur 的做法是平台自己去查,查得到就先填好。

連接埠:輸入映像檔之後,Zeabur 去 registry 讀映像檔宣告的連接埠,也就是 Dockerfile 的 EXPOSE,填進表單。公司的私有映像檔也讀得到,用 RD 填的 registry 帳密,或專案裡現有的 pull Secret。

安全性:表單只有 嚴格 與 相容 兩個選項,分別對應 Pod Security 的 restricted 與 baseline,預設值看映像檔設定的使用者。只有數字、而且不是 0 的 UID(例如 USER 1000)才預設嚴格;USER app 這種用名稱指定的使用者,即使不是 root,也預設相容。

原因在 kubelet:設了 runAsNonRoot 時,kubelet 無法從名稱判斷使用者是不是 root,會直接拒絕啟動容器。平台如果一律預設嚴格,RD 第一次部署用 USER app 的映像檔,就會撞上一個講 runAsNonRoot 的錯誤。

這兩個推斷都遵守三個原則:

  • 只填空白的欄位,「使用者自己填的值永遠優先」。
  • 讀不到不擋部署。registry 連不上時,RD 自己填連接埠就好,原始碼的說法是「部署永遠不必等它」。
  • 說出依據。表單會說明為什麼選了嚴格或相容,建立前仍能切換。

推錯比不推更糟,所以預設值要偏向不會讓第一次部署失敗的那一邊,即使那一邊沒那麼安全。

3. 替使用者做取捨,但把後果說出來

有些 Kubernetes 的限制,使用者不該需要知道,卻很容易踩到。Zeabur 把這些限制寫進產生物件的程式,讓使用者選不出會壞的組合,再用白話說出後果。

假設 RD 的 API 要保存上傳的檔案,在表單加了一個磁碟區。表單建立的是 ReadWriteOnce 的 PVC,配上預設的 RollingUpdate,新副本被排到別的 Node 時會掛不上磁碟。所以只要有磁碟區,Zeabur 就把副本數固定為 1,更新策略改成 Recreate。RD 不必知道這些,但文件寫明了後果:「更新時會先停止舊副本,再啟動新副本,這段時間服務會中斷。」

規格也是取捨。小、中、大三種規格都只設記憶體上限,沒有 CPU 上限。原始碼和文件都沒有寫理由,我的解讀是:CPU limit 會讓平均用量很低的服務在突發時被 throttle,連熟悉 Kubernetes 的人都不好查(見CPU 才用三成,為什麼還被 throttle?);記憶體用超過就會被終止,所以要有上限。

替所有人做同一個選擇,就一定有人被擋住。一個服務要兩個副本又要磁碟,在表單上做不到,只能改 YAML(第 7 節)。

4. 使用者選要接哪個資料庫,接線交給平台

開頭的 RD 還要接 PostgreSQL。連線需要的 Secret 名稱、key 和資料庫的位址,RD 不知道,平台卻都查得到:資料庫和服務在同一個專案裡,兩邊的物件它都讀得到。所以 Zeabur 不問連線字串,只問要接哪一個。

RD 建立 PostgreSQL 時就可以勾選要接上的服務,之後也能在資料庫頁按 接到服務。勾選的服務會加上 DATABASE_URL,值引用 CloudNativePG 建立的 Secret:

env:
  - name: DATABASE_URL
    valueFrom:
      secretKeyRef:
        name: <資料庫的 Secret>
        key: uri

RD 不必知道 Secret 的 key 或資料庫 Service 的 DNS 名稱,密碼也不會以明文出現在 Deployment 裡。變數名稱沿用 Railway 的慣例,MongoDB 是 MONGO_URL,Dragonfly 是 REDIS_URL。

接線的程式得跟著每個 operator 的 Secret 格式寫。PostgreSQL 直接引用 CloudNativePG 提供的完整連線字串;其他資料庫要先把密碼讀進一個變數,再用 $(變數) 組出 URL。每多支援一種資料庫,就多一種接法要維護。

5. 只翻每天會看到的詞

前面四個做法處理的是把服務建起來、接上資料庫。服務上線之後,RD 每天看的是服務頁,表單和服務頁上都會一直出現 Kubernetes 的物件。全部保留原文,RD 看不懂;全部翻譯,又會造出一套沒人認得的詞。

Zeabur 的用詞規範只替四種每天會遇到的物件取白話名稱:Pod 是副本,PersistentVolumeClaim 是磁碟,Secret 是機密變數,ConfigMap 是設定檔。其他的 kind 與欄位,例如 Deployment、replicas,都保持原樣;kind 名稱只出現在 YAML、物件頁,以及白話名稱旁的小標籤。

規範的理由是,不要發明兩邊都不用的中間詞:「專業的人會搜尋 kind,初學者會搜尋白話」。假如把 Ingress 改叫「對外入口」,熟悉 Kubernetes 的人找不到它,不熟的人也不會因此更懂。

規範裡另外兩條也可以直接拿來用:

  • 一個概念只用一個詞。「服務」指使用者部署的東西;要指 Kubernetes 的 Service 物件時,一律寫「Kubernetes Service」。
  • 能顯示真實值,就不解釋。直接顯示 api.shop.svc.cluster.local:8080 並提供複製,而不是說明私有位址是什麼。

這些規則和一張術語表一起寫在 repo 的規範文件裡。用詞要在做畫面之前定下來,等每個畫面各自翻譯完再統一,就得把所有畫面都改一遍。

6. 出錯時,翻譯錯誤,也說出誰能修

服務一出錯,Kubernetes 回報的是 CrashLoopBackOff、OOMKilled、ImagePullBackOff。平台如果只包裝了建立流程,RD 這時還是得懂 Kubernetes,或者回頭找平台團隊。

Zeabur 把事件與狀態整理成診斷,每個診斷都有原因、為什麼、怎麼處理,以及依據了哪些狀態與事件。假設 RD 的 API 啟動時讀不到某個環境變數就退出,中文介面會這樣說(服務名稱與次數是示意):

  • 原因:「api 反覆崩潰、重新啟動。」
  • 為什麼:「它已重新啟動 7 次。叢集每次都會再啟動它,兩次之間等得越來越久,預設最多等 5 分鐘。」
  • 處理:「錯誤訊息在重新啟動前那一次的日誌裡。」

原本的 reason 與結束碼還在,收在預設摺疊的「原始錯誤」裡。第 2 節提到的 runAsNonRoot 錯誤也會這樣翻譯:RD 把用 USER app 的映像檔改成嚴格時,看到的是「api 無法啟動:服務的安全性設為『嚴格』,但映像檔用名稱指定使用者,叢集無法確認它不是 root。」處理方式是改用數字指定使用者,或改回相容。

診斷裡最值得借的,是把「問題在哪裡」和「誰能修」拆成兩個欄位。原始碼的說明是:不能讓人把 Node 滿了或 registry 連不上,讀成自己的 bug。

情況問題在哪裡誰能修
程式以非 0 的結束碼反覆退出應用程式使用者
ResourceQuota 擋住、沒有 Node 放得下叢集叢集管理員
Node 連不到 registryregistry叢集管理員
沒設記憶體上限,Node 記憶體不足時被終止叢集使用者

最後一列說明了為什麼要拆開:記憶體不足發生在整台 Node 上,但能避免它再發生的,是替服務設定記憶體上限。只有一個欄位的話,不是把叢集的問題算到 RD 頭上,就是把 RD 能修的事推給管理員。需要管理員處理時,處理方式會以「這需要叢集管理員處理:」開頭,主要按鈕是 複製診斷,讓 RD 把整份診斷交給對的人。

網址打不開時沒有單一的錯誤可以翻譯,Zeabur 改成沿著請求的路徑,從 DNS 一路檢查到就緒的副本,指出斷在哪一段;查不到的段落,例如網域前面有 CDN,標成無法確認,不算失敗。

診斷得一種錯誤一種錯誤地寫,也不可能涵蓋所有情況。Zeabur 為此留了一種「無法解釋」的診斷,讓原始的錯誤訊息不會是畫面上唯一的說明。

7. 表單不夠用時,退回一般的 Kubernetes

抽象一定有做不到的地方。Zeabur 沒有替這些情況再發明一層,而是讓人退回一般的 Kubernetes:

  • 服務頁的幾個分頁有第二個檢視:日誌旁邊是終端機,部署紀錄旁邊是事件,設定旁邊是 YAML。
  • 表單沒有啟動指令的欄位,要改 command 與 args,就切到 YAML。需要表單以外的欄位時,按 以 YAML 編輯,目前的表單內容會一起帶過去。這些修改和表單一樣,要先經過 檢查變更。
  • 由 Helm、Argo CD 或 Flux 管理的物件,介面只能重新啟動,修改要回到原本的工具。

因為表單產生的本來就是一般的物件,退回 YAML 時看到的不是平台私有的格式。文件附了等效的 YAML,用 kubectl apply 套用的結果和表單相同。

退回 YAML,也就離開了表單的保護。第 3 節替 RD 做的取捨,例如磁碟區與副本數,在 YAML 裡就要自己負責。

結語:七個做法

回到開頭的 RD。在 Zeabur 上,RD 從頭到尾回答的是「手上有什麼」「要不要接受連線」「要不要從外面連得到」「要接哪個資料庫」,Deployment、Service、Ingress 和 Secret 都是答案的結果。出問題時,畫面告訴 RD 原因、該怎麼做,以及該由誰處理。

做內部部署平台時,可以拿這七個做法對照:

  1. 問使用者答得出來的問題,物件是答案的結果;做不到的事在填表前就說。
  2. 使用者答不出來的,平台自己去查;使用者的值優先,讀不到不擋部署,並說出依據。
  3. Kubernetes 的限制寫進產生物件的程式,替使用者做的取捨,用白話說出後果。
  4. 接資料庫時,使用者只選接哪一個,平台產生引用 Secret 的連線變數。
  5. 只翻每天會看到的詞,一個概念只用一個詞。
  6. 錯誤翻譯成原因與處理,並把「問題在哪裡」和「誰能修」分開。
  7. 表單不夠用時,退回一般的 Kubernetes,產生的始終是標準物件。

這篇只談畫面與產生物件這一側。2.0 不保存自己的狀態要付出什麼代價,以及它怎麼和 Helm、Argo CD、kubectl 共用同一批物件,是另外的題目。

參考資料

原始碼固定在 zeabur-oss/zeabur 的 commit d4bd01b,依章節列出:

繼續閱讀其他筆記