Phát hành
Một commit trong repo thành phần tới dev như thế nào, và một bản phát hành của repo tổng quyết định prod chạy gì ra sao. Tag image, Image Updater cho dev, workflow Release, việc giữ image, và các bước để đưa lên dev, phát hành, rollback và xem phiên bản đang chạy.
Sáu repo thành phần build image: server, website, docs, console và agent cho chart của stack, và ai cho ai-models. Một lần push lên main trong repo thành phần sẽ tới dev: Argo CD Image Updater thấy digest mới của :main và ghi nó lên stack-dev hoặc ai-dev. Prod chạy một bản phát hành của repo tổng. Workflow Release (.github/workflows/release.yml trong shopnexus/shopnexus) lấy các commit mà submodule của repo tổng trỏ tới trên main, gắn tag X.Y.Z cho image của chúng, ghi bản phát hành vào infra/, rồi gắn tag vX.Y.Z cho repo tổng. Mọi image trong một bản phát hành prod có cùng một phiên bản.
flowchart TB
repo["repo thành phần<br/>server, website, docs, console, agent, ai"] -->|"push lên main"| build["build.yml<br/>GitHub Actions"]
build -->|"main, sha-#lt;commit#gt;"| ghcr[("GHCR<br/>ghcr.io/shopnexus/*")]
iu["Image Updater<br/>ImageUpdater shopnexus"] -->|"digest của :main"| ghcr
iu -->|"ghi Helm parameter"| dev["stack-dev, ai-dev"]
rel["release.yml<br/>repo tổng"] -->|"thêm X.Y.Z vào sha-#lt;commit#gt;"| ghcr
rel -->|"commit release X.Y.Z, tag vX.Y.Z"| main["main của repo tổng"]
main --> root["Application root"]
root -->|"apply infra/argocd"| prod["stack-prod ở vX.Y.Z<br/>ai-prod ở commit ai"]
root -.->|"bỏ qua spec.source.helm.parameters"| dev
dev --> devns["shopnexus-dev"]
prod --> prodns["shopnexus-prod"]Tag image
Mỗi repo thành phần có cùng một file .github/workflows/build.yml. Workflow chạy khi có push lên main và khi chạy tay (workflow_dispatch), build Dockerfile của repo một lần, và push ghcr.io/shopnexus/<repo> với hai tag. Tag phiên bản chỉ đến từ workflow Release của repo tổng, workflow này thêm tag vào một image CI đã build, không build lại.
| Ai | Khi nào | Tag |
|---|---|---|
build.yml trong repo thành phần | push lên main | main và sha-<sha đầy đủ của commit> |
release.yml trong repo tổng | một lần chạy workflow Release | X.Y.Z, trên image sha-<commit> của commit mà repo tổng trỏ tới |
Một tag vX.Y.Z trong repo thành phần không build gì và không tới prod. Các lần build của cùng một ref dùng chung một concurrency group, và lần push mới hơn hủy lần build đang chạy. Cluster pull image không cần credential, nên các package trên GHCR phải để public.
Giữ image
build.yml có một job cleanup chạy sau build, dùng dataaxiom/ghcr-cleanup-action v1.2.2. Nó giữ main và mọi tag X.Y.Z, giữ 10 image có tag khác mới nhất (các bản build sha-<commit>), và xóa image không có tag và image dở dang.
Mọi image prod từng chạy đều mang một tag X.Y.Z, nên cleanup không xóa nó. Với mỗi repo, một bản phát hành phải chọn một commit nằm trong 10 bản build mới nhất của repo đó; với commit cũ hơn, image sha-<commit> đã bị xóa và workflow Release dừng lại.
Image Updater
infra/argocd/stacks.yaml chứa một resource ImageUpdater tên shopnexus trong namespace argocd. Nó chỉ có mục cho stack-dev và ai-dev; prod không có mục nào. Chart Image Updater là 1.4.0, do Application image-updater trong infra/platform/image-updater.yaml cài.
| Application | Image được theo dõi | updateStrategy | Helm parameter được ghi |
|---|---|---|---|
stack-dev | ghcr.io/shopnexus/<thành phần>:main cho server, website, docs, console và agent | digest | images.<thành phần>.repository, images.<thành phần>.tag |
ai-dev | ghcr.io/shopnexus/ai:main | digest | images.models.repository, images.models.tag |
Nó đổi khi digest đằng sau :main thay đổi và ghi tag dưới dạng main@sha256:…. Các image khác trong values.yaml (Postgres, Restate, RustFS) được ghim ở đó và chỉ đổi qua commit. Image của gateway và curl được ghim trong chart/values.yaml của repo ai.
Parameter và Application root
Argo CD ưu tiên Helm parameter hơn file values. Trên stack-dev, khi Image Updater đã ghi images.server.tag, các dòng images.*.tag trong values-dev.yaml không còn quyết định cái gì chạy. Prod không có parameter, nên các tag trong values-prod.yaml ở tag phát hành quyết định stack-prod chạy gì.
Bản thân các Application của stack là resource của app-of-apps root (infra/argocd/root.yaml), vốn đồng bộ infra/platform và infra/argocd từ main của repo tổng với selfHeal: true. Self-heal sẽ đưa mỗi Application về đúng định nghĩa trong git và xóa các parameter trên stack-dev và ai-dev. Hai thiết lập trong root giữ chúng lại:
ignoreDifferences:
- group: argoproj.io
kind: Application
jsonPointers: [/spec/source/helm/parameters]
syncPolicy:
automated: { prune: true, selfHeal: true }
syncOptions: [RespectIgnoreDifferences=true]ignoreDifferences làm root không báo lệch ở đường dẫn đó. RespectIgnoreDifferences=true làm một lần sync để nguyên đường dẫn đó như trong cluster. Nếu chỉ có thiết lập đầu, lần sync tiếp theo của root vẫn ghi đè các parameter.
Thiết lập Argo CD
Ở lần khởi động đầu, k3s cài chart argo-cd 10.11.7 (Argo CD v3.5.7) từ infra/cluster/argocd.yaml và apply root.yaml một lần; file cấu hình k3d liệt kê cả hai file. Từ đó Argo CD quản lý root từ git. Khi node server khởi động lại, k3s apply lại bản root.yaml nó giữ, và self-heal đưa bản trong git trở lại trong vòng vài phút.
| Thiết lập | Ở đâu | Tác dụng |
|---|---|---|
automated: { prune: true, selfHeal: true } | mọi Application | commit được apply mà không cần bấm, resource bị xóa khỏi git thì bị xóa khỏi cluster, và sửa tay trong cluster bị hoàn lại |
retry: { limit: -1, backoff: { duration: 30s, factor: 2, maxDuration: 5m } } | mọi Application | lần sync lỗi được thử lại mãi, lúc đầu cách 30 giây, tối đa cách 5 phút |
| sync wave | Application platform ở wave 0; stack-dev, stack-prod và ImageUpdater ở wave 1 | các stack khởi động sau các operator |
health check Lua cho argoproj.io/Application | phần values trong argocd.yaml | root đọc health của từng Application con, nên wave 1 chờ các Application platform Healthy |
Argo CD thôi đánh giá health của resource Application từ phiên bản 1.8. Không có check Lua, root sẽ coi các Application platform là healthy ngay lập tức, và các stack sẽ khởi động trước khi CloudNativePG, Sealed Secrets và restate-operator có CRD. ImageUpdater mang SkipDryRunOnMissingResource=true, vì CRD của nó đến cùng Application image-updater trong cùng lần sync.
Bên trong một stack, mỗi lần sync chạy lại các wave của chart, kể cả các Job Sync hook migrate, objectstore-init và objectstore-init-snapshots (wave 1). Một lần sync ai-<stack> chạy Job Sync hook ai-gateway-keys (wave 1 của nó). Vì thế một image server mới chạy migration của nó trước khi các pod server mới khởi động. Bảng đầy đủ các wave, từ -1 tới 2, nằm ở trang Postgres, Restate và RustFS.
Đưa lên dev
-
Push lên main
Merge hoặc push lên
maintrong repo thành phần, ví dụserver.build.ymlbuild image và pushghcr.io/shopnexus/server:maincùngsha-<sha>.Terminalgh run watch --repo shopnexus/server -
Chờ Image Updater
Mặc định Image Updater kiểm tra registry hai phút một lần. Khi digest đằng sau
:mainđã đổi, nó ghiimages.server.taglênstack-devdưới dạngmain@sha256:….Terminalkubectl -n argocd get application stack-dev \ -o jsonpath='{range .spec.source.helm.parameters[*]}{.name}={.value}{"\n"}{end}' -
Theo dõi rollout
Argo CD đồng bộ
stack-dev.migratechạy với image mới, rồi restate-operator khởi động một phiên bản server mới bên cạnh phiên bản cũ, và phiên bản cũ chạy tiếp cho tới khi các invocation Restate của nó xong. Website, docs và console là Deployment thường và thay từng pod một.Terminalkubectl -n shopnexus-dev get rs -l app.kubernetes.io/name=serverBạn sẽ thấy một ReplicaSet mới có pod ready, và ReplicaSet cũ về 0 khi các invocation của nó xong. Trang dữ liệu mô tả cách restate-operator rút một phiên bản.
Phát hành lên prod
Một bản phát hành lấy cả sáu repo cùng lúc, ở các commit mà submodule của repo tổng trỏ tới trên main. Phiên bản có dạng X.Y.Z, không có v, và phải cao hơn tag vX.Y.Z cao nhất của repo tổng.
-
Nâng các submodule
Trong repo tổng, chuyển sáu submodule tới các commit dev đã chạy, tức là đầu nhánh
maincủa từng repo khi lần build của repo đó đã xong. Commit và push lênmaincủa repo tổng.Terminalgit switch main && git pull git submodule update --remote server website docs console agent ai git add server website docs console agent ai git commit -m "bump the components for 0.2.0" git push origin main -
Chạy workflow Release
Chạy nó từ terminal, hoặc từ tab Actions của repo tổng: Release, rồi Run workflow với phiên bản.
Terminalgh workflow run release.yml -R shopnexus/shopnexus -f version=0.2.0 gh run watch -R shopnexus/shopnexusWorkflow kiểm tra phiên bản có dạng
X.Y.Z,v0.2.0chưa tồn tại và phiên bản cao hơn bản phát hành trước. Sau đó nó kiểm traghcr.io/shopnexus/<repo>:sha-<commit>có đủ cho cả sáu repo rồi mới gắn tag cho image nào, nên một bản phát hành được gắn tag trọn vẹn hoặc không gắn gì. Nó thêm tag0.2.0vào từng image, ghi bản phát hành vào ba file, commitrelease 0.2.0trênmain, gắn tagv0.2.0cho commit đó và push cả hai.File Workflow ghi gì infra/stack/values-prod.yamlimages.<thành phần>.tag: 0.2.0choserver,website,docs,consolevàagentinfra/argocd/stacks.yamltargetRevision: v0.2.0trênstack-prodinfra/argocd/ai.yamltargetRevision: <commit ai>vàimages.models.tag: 0.2.0trênai-prodChạy
git pulltrong bản checkout repo tổng của bạn sau đó, vì workflow đã commit lênmain. -
Theo dõi stack-prod và ai-prod sync
rootapplystacks.yamlvàai.yamlmới từmain. Sau đóstack-prodrenderinfra/stackở tagv0.2.0, nên chart vàvalues-prod.yamllà của bản phát hành, cònai-prodrenderchart/của repoaiở commit ai của bản phát hành.Terminalkubectl -n argocd annotate application root argocd.argoproj.io/refresh=normal kubectl -n argocd get application stack-prod ai-prod \ -o custom-columns='NAME:.metadata.name,REVISION:.spec.source.targetRevision,SYNC:.status.sync.status,HEALTH:.status.health.status' -
Kiểm tra phiên bản mới
Terminalkubectl -n shopnexus-prod get rs -l app.kubernetes.io/name=server hurl --test --continue-on-error --variable domain=shopnexus.id.vn infra/smoke.hurlProd chạy ba pod server cho mỗi phiên bản. Bạn sẽ thấy ReplicaSet mới ở 3/3 và Hurl báo smoke test thành công.
sequenceDiagram participant Rel as release.yml participant GHCR participant Git as main của repo tổng participant Root as root participant Argo as stack-prod participant Op as restate-operator participant Restate Note over Rel: chạy với phiên bản 0.2.0 Rel->>GHCR: kiểm tra sha-#lt;commit#gt; của từng repo Rel->>GHCR: gắn tag 0.2.0 cho từng image Rel->>Git: commit release 0.2.0, tag v0.2.0 Root->>Git: đọc infra/argocd Root->>Argo: targetRevision v0.2.0 Argo->>Argo: wave 1, Job migrate Argo->>Op: wave 2, pod template mới Op->>Op: ReplicaSet và Service 0.2.0 Op->>Restate: đăng ký 0.2.0 Restate->>Op: 0.1.0 đã hết invocation Op->>Op: đưa 0.1.0 về 0
Rollback prod
Revert commit phát hành trên main của repo tổng. Bản revert đưa values-prod.yaml, stacks.yaml và ai.yaml về bản phát hành trước, nên stack-prod quay về vX.Y.Z trước đó và ai-prod quay về commit ai trước đó. Image X.Y.Z của chúng vẫn còn trên GHCR, vì cleanup giữ mọi tag phiên bản.
-
Revert commit phát hành
Terminalgit switch main && git pull git log --oneline --grep '^release ' -2 git revert <commit của release 0.2.0> infra/check.sh git push origin main -
Theo dõi sync
rootapply các Application đã revert từmain, rồistack-prodvàai-prodsync bản phát hành trước. Dùng các lệnh ở bước “Theo dõi stack-prod và ai-prod sync” phía trên.
Bản revert giữ nguyên con trỏ submodule và tag v0.2.0. Bản phát hành tiếp theo phải cao hơn 0.2.0, vì workflow so phiên bản với tag vX.Y.Z cao nhất.
Đổi một giá trị cấu hình
Thiết lập không bí mật nằm trong infra/stack/values.yaml và hai file của từng stack. Secret đi qua lệnh seal, infra/cmd/seal (Secret).
stack-dev render infra/stack ở main của repo tổng, nên dev nhận thay đổi khi push. stack-prod render nó ở tag phát hành, nên một thay đổi ở values.yaml, values-prod.yaml hay chart chỉ tới prod cùng bản phát hành tiếp theo. Định nghĩa các Application trong infra/argocd, trong đó có valuesObject của ai-prod trong ai.yaml, đến từ main qua root và tới cả hai stack khi push.
-
Sửa file values
Đổi giá trị trong
values-dev.yamlhoặcvalues-prod.yaml, ví dụserver.logLevelhoặcreplicas.server. Một giá trị trongvalues.yamláp cho cả hai stack, trừ khi file của stack đặt giá trị khác. -
Kiểm tra chart
Terminalinfra/check.shScript render chart cho cả hai stack và kiểm tra kết quả. Nó cần
helm,yqvàkubeconform, và CI chạy nó cho mọi pull request đụng tớiinfra/. -
Push lên repo tổng
Commit và push lên
main. Argo CD đọc repo hai tới ba phút một lần (timeout.reconciliation120 giây cộng tối đa 60 giây jitter, mặc định của chart). Để đồng bộ ngay:Terminalkubectl -n argocd annotate application stack-dev argocd.argoproj.io/refresh=normalVới prod, chạy một bản phát hành khi thay đổi đã nằm trên
main. -
Theo dõi rollout
Template pod của server mang
checksum/env, một mã băm của ConfigMapserver-env, nên một thiết lập của server khởi động một phiên bản server mới. Deploymentai-gatewaymangchecksum/configcho cấu hình của nó, và không mang checksum của secret của stack: sau khi seal lạilitellm-secrets, chạykubectl -n shopnexus-<stack> rollout restart deploy/ai-gateway.
Một lần kubectl edit trên resource của stack chỉ giữ tới lần self-heal tiếp theo, lúc đó resource được đưa về như trong git.
Xem phiên bản đang chạy
Bản phát hành stack-prod đang chạy, cùng commit ai và tag ai-models của ai-prod:
kubectl -n argocd get application stack-prod -o jsonpath='{.spec.source.targetRevision}{"\n"}'
kubectl -n argocd get application ai-prod \
-o jsonpath='{.spec.source.targetRevision} {.spec.source.helm.valuesObject.images.models.tag}{"\n"}'Tag image của bản phát hành đó, đọc từ git:
git show v0.2.0:infra/stack/values-prod.yaml | yq '.images'Image và digest mà từng pod chạy:
kubectl -n shopnexus-prod get pods \
-o custom-columns='POD:.metadata.name,IMAGE:.spec.containers[0].image,DIGEST:.status.containerStatuses[0].imageID'Các phiên bản server mà restate-operator giữ, cùng số pod:
kubectl -n shopnexus-prod get rs -l app.kubernetes.io/name=serverForward cổng của Argo CD server và đọc mật khẩu admin ban đầu:
kubectl -n argocd port-forward svc/argocd-server 8080:443
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath='{.data.password}' | base64 -dMở https://localhost:8080, chấp nhận chứng chỉ tự ký, và đăng nhập là admin với mật khẩu đó. Mở Application stack-prod, rồi App Details, nơi hiện target revision vX.Y.Z. Cây resource hiện từng ReplicaSet cùng các pod và image của chúng.
Quy tắc chính
- Dev đi theo
:mainbằng digest. Prod chạy một bản phát hành của repo tổng,vX.Y.Z, và mọi image trong đó có tagX.Y.Z. - Một bản phát hành lấy các commit mà submodule của repo tổng trỏ tới trên
main. Nâng chúng tới những gì dev đã chạy trước khi chạy workflow Release. - Các dòng prod trong
values-prod.yaml,stacks.yamlvàai.yamlchỉ đổi qua một bản phát hành hoặc qua việc revert một bản. - Một bản phát hành chỉ chọn được commit nằm trong 10 bản build mới nhất của mỗi repo.
- Mọi migration chạy được với phiên bản server đứng trước nó.
- Mọi thay đổi cho cluster đi qua git. Sửa tay bị self-heal hoàn lại.
Xử lý sự cố
Workflow Release báo sha-<commit> does not exist
Submodule trỏ tới một commit chưa có image trên GHCR. Hoặc build.yml của repo chưa build commit đó, hoặc cleanup đã xóa image vì nó cũ hơn 10 bản build mới nhất. Chờ lần build, hoặc nâng submodule tới một commit mới hơn, push, rồi chạy lại workflow. Lúc đó chưa image nào bị gắn tag, vì workflow kiểm tra đủ sáu image rồi mới gắn tag cho image nào.
Workflow Release không gắn tag được cho image
GITHUB_TOKEN của workflow chỉ ghi được một package khi package đó cấp quyền ghi cho repo tổng. Đây là bước làm một lần trên giao diện GitHub cho từng package trong sáu package server, website, docs, console, agent và ai: mở phần cài đặt của package, rồi Manage Actions access, thêm shopnexus/shopnexus và cho nó vai trò Write.
Workflow Release từ chối phiên bản
Phiên bản phải có dạng X.Y.Z không có v, tag vX.Y.Z của nó chưa tồn tại, và nó phải cao hơn tag vX.Y.Z cao nhất của repo tổng, kể cả một bản phát hành đã bị revert.
Prod chạy tag khác với values-prod.yaml
Kiểm tra stack-prod có Helm parameter không, vì parameter thắng file values. Một cluster từng chạy cách cũ, khi Image Updater ghi tag cho prod, có thể vẫn giữ chúng, và root không xóa chúng. Xóa chúng:
kubectl -n argocd patch application stack-prod --type json \
-p '[{"op":"remove","path":"/spec/source/helm/parameters"}]'Parameter biến mất sau một lần sync của root
root.yaml phải giữ cả mục ignoreDifferences cho /spec/source/helm/parameters lẫn RespectIgnoreDifferences=true. infra/check.sh báo lỗi khi thiếu mục đầu.
Application của stack đứng ở OutOfSync hoặc Unknown
Đọc condition bằng kubectl -n argocd get application stack-prod -o jsonpath='{.status.conditions}'. Một ComparisonError có nhắc ./cmd/seal nghĩa là infra/stack/secrets/<stack>/ chưa có SealedSecret nào. Trước bản phát hành đầu tiên, stack-prod không tìm được v0.1.0. Các lỗi khác đến từ chart; tái hiện chúng bằng infra/check.sh. Argo CD thử sync lại với backoff tối đa 5 phút, nên bản sửa trong git được nhận mà không cần bấm.