我這兩年在用的部署流程:從打一個 tag 到正式站的 GitOps
每個團隊的部署流程都長得不一樣,這篇是我這兩年參與的雲端專案用的那一套。開發者只做一件事,依照要去的環境推分支或打 tag。後面測試環境由 GitHub Actions 透過 SSM 直接更新主機,正式站則是 Actions 只把版號寫進 Git,由叢集裡的 ArgoCD 自己來讀。我把一個版本從打 tag 走到正式站的每一站走一遍,講每一站做什麼、拿到什麼權限,還有為什麼這樣設計。
目錄
這兩年我參與的專案,不管是能源管理還是微電網,只要是跑在雲端的,部署都是同一套做法。工具換過,細節調過,但形狀一直沒變。開發者要做的事很少,依照要去的環境推分支或打 tag,後面全部自動。
每個團隊的部署流程都長得不一樣,這篇寫的是我們這一套。它是 SRE 同事設計的,我是使用者,用了一陣子之後我把它從頭到尾弄懂了一遍,發現中間經過的每一站都有它的理由。我盡量寫成沒碰過部署的人也看得懂的樣子,照一個版本實際走的順序,從打 tag 開始,一站一站講到正式站的 Pod 更新為止。
架構的部分我之前寫過一個請求怎麼走過整套系統,這篇可以當成它的續集,講的是一個版本怎麼走。
先講幾個名詞
後面會一直用到這幾個東西,先用一兩句話講它們是什麼:
- 映像(image):把程式連同它需要的環境打包成的一個檔案,部署就是讓主機拿到新的映像再跑起來。映像會放在一個倉庫裡,我們用的是 AWS 的 ECR(Elastic Container Registry)。
- digest:每個映像除了人取的 tag 之外,還有一個由內容算出來的雜湊。tag 可以被蓋掉,digest 不會。
- GitHub Actions:GitHub 內建的自動化工具,push 或打 tag 的時候會跑一段我們寫好的流程,叫 workflow。幾個 repo 共用的流程可以抽成 reusable workflow,各 repo 只留一份很薄的呼叫檔。
- OIDC(OpenID Connect):在這裡的意思是,GitHub 幫每一次 workflow 發一張一次性的身分證明,AWS 認這張證明就發一組短時間內有效的臨時憑證。有了它,repo 裡就不用存任何 AWS 金鑰。
- SSM:AWS Systems Manager,其中的 Run Command 可以對一台 EC2 下指令,不用 ssh 進去。
- GitOps:一種做法,把「正式站應該長什麼樣」寫在 Git 裡,讓叢集自己去對齊 Git,而不是讓 CI 去推叢集。
- ArgoCD:跑在 Kubernetes 叢集裡做 GitOps 這件事的工具。它定期讀 Git,發現跟叢集不一樣就同步。
四個環境,一條版號
同一份程式碼會依序經過四個環境,DEV 給每天開發用,SIT 做功能整合,UAT 給客戶跟 PM 驗收,PROD 是正式站。觸發方式只有兩種,推分支或打 tag,tag 的尾巴決定要去哪個環境。
push 到 dev → DEV
tag vX.Y.Z-alpha.N → SIT
tag vX.Y.Z-beta.N → UAT
PR 合併進 prod,再在 prod 打 tag vX.Y.Z → PROD前三個環境各是一台 EC2,上面用 docker compose 跑整套服務,有 repo 寫入權限的人都能觸發,不用審核。正式站是 Kubernetes 叢集,多了兩道門,要先開 PR 把 uat 合併進 prod 分支,再在 prod 的 commit 上打正式版 tag。
為什麼正式站不跟測試環境一樣,一台 EC2 跑 compose 就好?測試環境要的是便宜跟好重建,一台機器、一份 compose 檔,壞了砍掉重開,更新的時候把舊容器停掉再起新的,中間斷幾秒沒有人在意。
正式站要的不一樣。更新不能斷線,誰在什麼時候上了哪一版要查得到,出錯要能退回去,而且上面跑的不只一個產品,還有幾個產品共用的服務。這些需求用 Kubernetes 加上 GitOps 來接,後面講正式站那一節會看到每一項是怎麼被滿足的。
alpha 跟 beta 後面的 N,是同一個版號的第幾次測試。SIT 或 UAT 測出問題、修完要再測一次,版號不變,把 N 加 1 就好,例如 v1.1.19-beta.1 改成 v1.1.19-beta.2。
正式版號則是把 beta 的尾巴拿掉。例如 UAT 用 v1.1.18-beta.1 驗收,確認沒問題就合併進 prod、打 v1.1.18,正式站就會自動更新。
開發者要下的指令其實就這幾行:
# DEV:推分支就會部署
git push origin dev
# SIT/UAT:在要測的 commit 上打 tag
git tag v1.1.19-alpha.1 && git push origin v1.1.19-alpha.1
git tag v1.1.19-beta.1 && git push origin v1.1.19-beta.1
# PROD:先在 GitHub 把 uat 合併進 prod,再對 prod 的最新 commit 打正式版 tag
git fetch origin
git tag v1.1.19 origin/prod && git push origin v1.1.19打完 tag 之後的事全部自動。測試環境跟正式站用同一套 GitHub Actions 樣板 build 映像,但把新版放上去的方式完全不同。下面這張圖是整套流程的全貌,後面兩節分別講橘色跟綠色那條路。
測試環境:Actions 直接去更新主機
測試環境的 workflow 很薄,大部分邏輯在共用的 reusable workflow 裡,每個產品的 repo 只留一份呼叫檔,寫清楚觸發條件跟有哪些服務。
on:
push:
branches: ['dev']
tags: ['v*-alpha*', 'v*-beta*']
permissions:
contents: read
id-token: write # 用 OIDC 跟 AWS 換臨時憑證workflow 要推映像到 ECR、要對 EC2 下指令,這些都需要 AWS 的權限。常見的做法是在 AWS 建一組長期有效的金鑰,存進 repo 的 secrets 給 workflow 用,但金鑰一外洩,拿到的人就能一直用到被發現為止。
這套流程改用 OIDC,repo 裡一把 AWS 金鑰都沒有。id-token: write 這一行是在允許 workflow 跟 GitHub 要一張身分證明,上面寫著這次是哪個 repo、哪個分支或 tag、哪個 environment 在跑。
workflow 拿這張證明去 AWS 換,AWS 確認是 GitHub 簽的、內容也對,就發一組一小時左右有效的臨時憑證,用完就失效。
每個環境在 AWS 各有一個 IAM role,權限只有那個環境需要的,dev 的 role 只能推 dev 的映像、對 dev 那台主機下指令。role 上還寫著它只相信哪一張證明,不是「這個 repo」,而是「這個 repo 的 dev environment」,像 repo:<org>/<repo>:environment:dev。
Environment 是 GitHub repo 裡的一個設定,我們有 dev、sit、uat、prod 四個。每個 environment 可以限制只有哪些分支或 tag 能用它,dev 只給 dev 分支,sit 只給 alpha tag。該環境專用的變數也放在這裡,像要部署的是哪一台主機。
這兩層加起來就是隔離。有人在 dev 分支把 workflow 改成去拿 uat 的 role,證明上寫的還是 dev environment,AWS 比對不符就不發憑證。想改成宣告 uat environment,GitHub 又會先擋下,因為 dev 分支不在 uat 的名單裡。隔離是 AWS 那一側在強制的,不是靠大家守規矩。
只 build 有改到的服務
這套系統是 monorepo,前端、API Gateway、業務服務各有自己的 Dockerfile。workflow 先有一個 plan 的 job,比對這次 push 改了哪些路徑,決定哪些服務要重 build,沒改到的就跳過。手動觸發的時候則一律全建。
接著是 build 的 matrix,每個要建的服務各自用 OIDC 換憑證、登入 ECR、build 完推上去。映像的 tag 就是版號,dev 分支的話用 commit 的 SHA。
用 SSM 對主機下指令,不用 SSH
部署的最後一步是讓主機拉新映像、重啟服務。這裡用 SSM 的 Run Command,由 runner 送一段指令給主機上的 SSM Agent 執行,送出之後輪詢結果,拿到結束碼才算完成。
比起 ssh 進主機跑腳本,SSM 不用開 22 port、不用在 CI 裡放 SSH 私鑰,誰能對哪台主機下指令由 IAM 決定,而且每次執行都有紀錄。
主機上真正做事的是 repo 自己的 scripts/deploy.sh。runner 會先把這支腳本放到主機上並比對 sha256,再依序呼叫三次,分別跑 migration、seed、主服務。腳本的核心其實很簡單,就是改 compose 裡那一行 image 再重啟:
# 備份現在的 compose,失敗時用它回滾
cp docker-compose.yml "docker-compose.yml.backup.$(date +%Y%m%d%H%M%S)"
# 只改這個服務那一行 image,其他服務維持原本的標籤
sed -i "/^\s*${SERVICE}:/,/image:/s|image:.*|image: ${IMAGE_URL}|" docker-compose.yml
docker compose pull "${SERVICE}"
docker compose stop "${SERVICE}"
docker compose up -d "${SERVICE}"migration 跟 seed 是用一次性的容器跑的,docker compose up --exit-code-from 讓容器跑完就結束,並且用它的結束碼當成功失敗的依據。前一步失敗就停住,不會接著更新主服務。
主服務拉不到映像或起不來的話,腳本會把備份的 compose 蓋回去再 up -d,等於自動退回前一版。
因為 sed 只改被部署的那個服務,沒被 build 的服務自然維持原本的標籤,不需要另外處理。同一個 repo 對同一個環境的部署會排隊,而且刻意不取消進行中的部署,因為部署到一半被砍掉會在主機上留下半殘的狀態。
正式站:Actions 只寫 Git
正式站的 workflow 只認正式版號的 tag,而且這個檔案必須存在於 prod 分支上。GitHub 打 tag 時跑的是被 tag 的那個 commit 裡的 workflow,所以檔案要先合併進 prod,tag 才會觸發它。
on:
push:
tags:
- 'v[0-9]+.[0-9]+.[0-9]+' # 不含 -alpha/-beta接下來的事情分成幾站,每一站只拿到自己需要的最小權限。
先驗證,再等核准
第一個 job 不需要任何權限,只檢查兩件事,tag 格式對不對,以及這個 commit 是不是在 prod 分支上,用的是 git merge-base --is-ancestor。任一項不符就直接失敗,核准人不會收到無效的部署請求。
第二個 job 屬於 prod 這個 environment,上面設了 required reviewers 跟 tag policy,只有 v*.*.* 格式的 tag 能用它,而且要有人按下核准才會開始跑。核准之前,它拿不到 AWS 憑證,也拿不到任何 secret。
build 映像,拿到 digest
核准之後一樣用 OIDC 換憑證,但這個 role 只能推映像到指定的 ECR,不能做別的事。build 完推上去之後,workflow 會把映像的 digest 記下來,後面要用。
這一步還有一個保護,ECR 的 tag 是可以被覆蓋的,所以同一個版號如果重跑,workflow 會先看 ECR 上有沒有這個 tag。有的話,只有確認它是同一個 commit 建出來的才沿用,否則直接失敗,不允許覆寫正式版的映像。tag 打錯了就改用下一個版號,正式站不會受影響。
機器人把版號寫進部署設定 repo
正式站要跑哪個版本、環境變數怎麼設,都寫在另一個 repo 裡,叫它部署設定 repo。這個 repo 的 prod 分支就是正式站的真相來源,也就是 GitOps 裡的那個 Git。
workflow 用一個 GitHub App 的私鑰換一張 token,有效期一小時,權限只有「寫這一個 repo 的內容」。GitHub App 可以想成一個機器人帳號,它能做什麼是一條一條勾出來的。
然後把 manifest 裡的 image 改成 <repo>:<tag>@sha256:<digest>,提交一個 commit,訊息長得像 Deploy(Prod): Update <app> to v1.1.18。
寫 tag@digest 而不是只寫 tag,是因為 tag 可以被蓋掉,digest 鎖住的是「當時 build 出來的那一份」。到這裡 GitHub 這一側的工作就結束了,它從頭到尾沒有連進正式站,只是在 Git 上留下一個 commit。
共用的 workflow 釘在固定的版本
正式站的呼叫檔引用共用 workflow 時,寫的不是分支名稱,是一個完整的 commit SHA。這樣共用樣板之後怎麼改,都不會影響正式站的部署行為,要升級的時候再手動改成新的 SHA。
另外 reusable workflow 讀不到呼叫端沒傳進來的 secret,就算 environment 裡有同名的 secret 也一樣,所以呼叫端要寫 secrets: inherit,不然 GitHub App 的私鑰會是空字串。
ArgoCD 那一側
ArgoCD 跑在另一個叢集裡,只開放辦公室的 IP,GitHub 的 runner 本來就連不進去。與其想辦法開洞,不如反過來,讓 ArgoCD 自己來讀 Git。它每 3 分鐘左右讀一次部署設定 repo 的 prod 分支,發現跟叢集現況不一樣就同步。
每個產品各有一個 ArgoCD Application,開了自動同步。同步的時候資源不是一次全上,而是分成幾波,用 annotation 標順序:
metadata:
annotations:
argocd.argoproj.io/sync-wave: '-2'migration 的 Job 是 wave -2,seed 的 Job 是 wave -1,三個服務的 Deployment 是 wave 0。數字小的先跑,前一波全部成功才跑下一波。所以 migration 一定在服務更新之前跑完,而 migration 失敗的話後面都不會動,線上還是舊版。
到了 Deployment 這一波,Kubernetes 用 rolling update,先把新版的 Pod 起來、通過健康檢查,才關掉舊版。新版起不來的話舊版會一直撐著,使用者不會斷線。
ArgoCD 的 selfHeal 是開的,有人直接在叢集上改東西,它會把東西改回 Git 裡的樣子,所以所有變更都得走 Git。prune 則是關的,設定檔被誤刪或搬走,正式站上的東西不會跟著被刪掉。
整趟走完大約 15 到 20 分鐘,build 7 到 10 分鐘,ArgoCD 偵測 3 到 6 分鐘,migration 跟服務更新 1 到 2 分鐘。前半段可以在 GitHub 的 Actions 頁面看,後半段在 ArgoCD。
三道保險,還有怎麼退回
誰能上正式站這件事,是用 GitHub 的 ruleset 管的。正式版 tag 只有產品 team 跟管理員能打,prod 分支只能走 PR。
部署設定 repo 的 prod 分支也只能走 PR,而且 PR 裡如果有人手動改了 image 的版號,會被一個檢查擋下來,只有部署機器人能寫新版號。改回舊版的 PR 可以通過,這是為了回滾留的路。
回滾的做法就是對那次 Deploy(Prod): Update … 的 commit 開 revert PR,合併之後 ArgoCD 讀到就會退回去,大約 5 分鐘。
資料庫 migration 不會自動倒退,所以版本有跑 migration 的話,打正式 tag 之前會先請 SRE 做一次資料庫快照。
只是要改一個環境變數的話不用打 tag,對部署設定 repo 的 prod 開 PR,合併就生效。只有「換版本」才需要 tag。
為什麼是這個形狀
把整套流程放在一起看,有兩個決定影響了每一站的樣子。
第一個決定是 CI 跟正式站之間沒有線。GitHub 只負責在 Git 上留下一個 commit,由正式站裡的 ArgoCD 主動來對齊 Git。GitHub 因此不需要正式站的任何憑證,正式站也不用對外開任何入口,而每一次上線都是一個查得到的 commit,誰、哪一版、哪個映像都在裡面。
第二個決定是整套流程的 repository secret 是零。AWS 憑證靠 OIDC 現換現用,GitHub App 的 token 只活一小時、只能寫一個 repo,主機那邊靠 SSM 不用 SSH key。每一站都只拿到剛好夠用的權限,哪一站出事影響的範圍都很小。
共用的邏輯放在一個樣板 repo 的 reusable workflow 裡,每個產品 repo 只留一份很薄的呼叫檔,寫觸發條件跟服務清單。
選 reusable workflow 而不是 composite action,一個實際的原因是 composite action 裡讀不到 vars,而每個環境的差異都放在 environment 的 variables 裡。
回顧
這套流程用下來,我對自己的角色很清楚。開發者要做的事只有三件,把 uat 合併進 prod、打 tag、到 Actions 頁面看它跑。版本有 migration 的話多一件,先請人做資料庫快照。
弄懂每一站之後,差別在出事的時候知道去哪裡看。build 失敗看 Actions,核准卡住找核准人,commit 進了部署設定 repo 但正式站沒動,就去 ArgoCD 看是哪一波停住。要退回也不用慌,開一個 revert PR 就好。
另一個收穫是看懂權限怎麼切,看過這套之後我才知道 CI 串 AWS 可以一把長期金鑰都不留,每一站用一次性的身分換剛好夠用的權限。這個做法不只適合正式站,自己的小專案要串 AWS 的時候也一樣用得上。
References
- About security hardening with OpenID Connect | GitHub Docs
- Reusing workflows | GitHub Docs
- Managing environments for deployment | GitHub Docs
- Making authenticated API requests with a GitHub App in a GitHub Actions workflow | GitHub Docs
- AWS Systems Manager Run Command
- Sync Phases and Waves | Argo CD
- Automated Sync Policy | Argo CD
- Pull an image by digest | Docker Docs