Dựng một cluster
Từ một máy trống đến hai stack dev và prod chạy trên k3d, theo đúng thứ tự mà các file trong infra/ cần.
Bài hướng dẫn này đưa một bản fork của repo umbrella thành một cluster k3d tên shopnexus chạy hai stack: dev trong shopnexus-dev và prod trong shopnexus-prod. Bạn chạy ba lệnh: k3d cluster create với một file cấu hình trong infra/cluster/ tạo cluster, và k3s cài Argo CD vào đó; go -C infra run ./cmd/seal ghi các secret; còn Hurl chạy infra/smoke.hurl để kiểm tra kết quả. Argo CD cài và đồng bộ mọi thứ còn lại từ bản fork của bạn.
Trước khi bắt đầu
- Một máy Linux có địa chỉ IP công khai và đủ bộ nhớ trống cho hai stack. Kế hoạch dựng hệ thống của tác giả dừng lại để cân nhắc khi còn dưới 6 GB khả dụng.
- Docker. Lệnh seal cũng dùng Docker để chạy image server sinh khóa.
- k3d. Cluster được dựng bằng k3d v5.9.0; server của tác giả chạy v5.8.3. Cả hai file cấu hình trong
infra/cluster/,k3d-direct.yamlvàk3d-behind-proxy.yaml, ghim image noderancher/k3s:v1.37.1-k3s1. - kubectl (đã thử với v1.37.2), Helm (v4.3.1) và kubeseal (0.41.2).
- Go, để chạy lệnh seal trong
infra/cmd/seal.infra/go.modyêu cầu Go 1.27. - Hurl, để chạy smoke test trong
infra/smoke.hurl. - yq (v4.54.1) và plugin Helm helm-unittest (v1.2.1), chỉ
infra/check.shcần, để kiểm tra chart trước khi bạn push một thay đổi. Cài plugin bằnghelm plugin install https://github.com/helm-unittest/helm-unittest --version v1.2.1 --verify=false. - Một tên miền mà bạn quản lý được DNS, và một tài khoản GitHub để chứa bản fork.
Thứ tự khởi động
flowchart TD up["k3d cluster create<br/>--config infra/cluster/k3d-#lt;mode#gt;.yaml"] --> k3d["Cluster k3d shopnexus<br/>+ cấu hình edge của Traefik"] k3d --> argo["Argo CD<br/>(Helm chart 10.11.7)"] argo --> root["Application root"] root --> w0["Wave 0: platform<br/>cnpg, sealed-secrets,<br/>restate-operator, image-updater"] w0 --> w1["Wave 1: stack-dev, stack-prod,<br/>ImageUpdater shopnexus"] w1 --> w2["Wave 2: ai-dev, ai-prod"] w1 -->|"ComparisonError:<br/>chưa có sealed secret"| seal["cmd/seal dev, cmd/seal prod<br/>commit và push"] seal --> sm1["Wave -1 của stack<br/>Namespace restate-#lt;stack#gt;"] sm1 --> s0["Wave 0 của stack<br/>postgres, rustfs, SealedSecret"] s0 --> s1["Wave 1 của stack<br/>migrate, objectstore-init,<br/>RestateCluster"] s1 --> s2["Wave 2 của stack<br/>server, website, docs,<br/>console, Ingress"] s2 --> a0["Wave 0 của ai-#lt;stack#gt;<br/>ai-gateway, ai-models"] a0 --> a1["Wave 1 của ai-#lt;stack#gt;<br/>ai-gateway-keys"]
Application root đồng bộ infra/platform và infra/argocd từ bản fork của bạn. Wave 0 của nó cài bốn operator của platform, wave 1 tạo mỗi stack một Application, và wave 2 tạo ai-dev và ai-prod. Mỗi Application của stack render Helm chart trong infra/stack và áp dụng nó theo các wave riêng. ai-<stack> render chart trong chart/ của repo ai vào cùng namespace khi Application của stack đã Healthy, nên Postgres của stack đã có database litellm.
Các bước
-
Fork repo và trỏ cấu hình về bản fork
Fork
shopnexus/shopnexustrên GitHub rồi clone bản fork về máy. Argo CD đọc bản fork mà không dùng thông tin đăng nhập, nên bản fork phải ở chế độ public.Đặt
repoURLthành URL clone của bản fork trong hai file:infra/argocd/root.yaml, có hai chỗ, một choinfra/platformvà một choinfra/argocd;infra/argocd/stacks.yaml, một chỗ trongstack-devvà một chỗ trongstack-prod.
infra/argocd/ai.yamlđọc repoai,https://github.com/shopnexus/ai.git, một chỗ trongai-devvà một chỗ trongai-prod. Trỏ nó về bản forkaicủa bạn nếu bạn sửa hub.Đặt
domaintronginfra/stack/values-dev.yamlvàinfra/stack/values-prod.yaml. Giá trị gốc làdev.shopnexus.id.vnvàshopnexus.id.vn; giữ nguyên cấu trúc đó, với dev nằm dưới prod một nhãn.ai-gatewaycủa mỗi stack gửi mọi lời gọi mô hình tới mô hình mà alias của nó ghi tronggateway.aliasesởchart/values.yamlcủa repoai, phần lớn trên OpenRouter, nên mỗi stack cần một khóa OpenRouter. Ngân sách theo ngày của từng key nằm tronginfra/argocd/ai.yaml. Nếu bạn tự build image, đổi các tênghcr.io/shopnexus/*tronginfra/stack/values.yaml,infra/argocd/stacks.yamlvàimagescủa chartai, và đặt các package GHCR ở chế độ public.Commit và push lên
main.Bạn sẽ thấy URL clone của mình trên mọi dòng
repoURL:Terminalgrep -n repoURL infra/argocd/*.yaml -
Tạo bản ghi DNS
Tạo bốn bản ghi A trỏ về IP công khai của máy. Lấy
example.comlàm tên miền prod:Bản ghi Phủ @example.com, website prod*api.,media.,docs.vàconsole.example.com*.devapi.dev.,media.dev.,docs.dev.vàconsole.dev.example.comdevdev.example.com, website devKhi đã có
*.dev, bản ghi*không còn phủdev.example.com, nên website dev cần bản ghidevriêng (trang Biên và mạng giải thích lý do).Bạn sẽ thấy IP của máy cho cả website dev lẫn một host bên dưới nó:
Terminaldig +short dev.example.com dig +short api.dev.example.com -
Tạo cluster bằng k3d
Chọn chế độ biên.
directđể Traefik trong cluster giữ cổng 80 và 443 và lấy chứng chỉ từ Let’s Encrypt.behind-proxydành cho máy đã có một proxy khác giữ các cổng đó; khi ấy Traefik nghe ở127.0.0.1:18080và proxy lo phần TLS. Máy mới dùngdirect. Server của tác giả dùngbehind-proxy, đứng sau một Caddy dùng chung.ACME_EMAILlà bắt buộc; k3d điền${ACME_EMAIL}trong file cấu hình từ biến môi trường. Traefik lấy chứng chỉ từ server production của Let’s Encrypt.TerminalACME_EMAIL=you@example.com k3d cluster create --config infra/cluster/k3d-direct.yamlĐể thử với server staging của Let’s Encrypt, có giới hạn tần suất cao hơn và chứng chỉ mà trình duyệt không tin, thêm
caServer: https://acme-staging-v02.api.letsencrypt.org/directorydướiacmetronginfra/cluster/k3d-direct.yamltrước khi tạo cluster. k3d chép cấu hình Traefik vào cluster lúc tạo cluster, nên sửa file về sau không đến được cluster đang chạy.Traefik trả lời thử thách TLS-ALPN-01 trên cổng 443, nên cổng 443 phải mở ra internet. Cổng 80 chuyển hướng sang HTTPS bằng mã 301. Trang Biên và mạng có ánh xạ cổng và các thiết lập Traefik của chế độ này.
Terminalk3d cluster create --config infra/cluster/k3d-behind-proxy.yamlProxy trên máy host kết thúc TLS và chuyển HTTP thường đến
127.0.0.1:18080. Traefik tin các headerX-Forwarded-*đến từ địa chỉ private. Khối Caddy trên server của tác giả liệt kê mọi host của cả hai stack:/etc/caddy/conf.d/shopnexus.caddyshopnexus.id.vn, api.shopnexus.id.vn, console.shopnexus.id.vn, media.shopnexus.id.vn, docs.shopnexus.id.vn, dev.shopnexus.id.vn, api.dev.shopnexus.id.vn, console.dev.shopnexus.id.vn, media.dev.shopnexus.id.vn, docs.dev.shopnexus.id.vn { request_body { max_size 50MB } reverse_proxy 127.0.0.1:18080 }Thay các tên bằng tên miền của bạn, chạy
caddy validate --adapter caddyfile --config <file>rồi reload Caddy. Proxy phải giữ nguyên headerHost, vàreverse_proxymặc định làm vậy: một lượt upload presigned lênmedia.được ký cho đúng host đó. Caddy chuyển hướng HTTP thường bằng mã 308.Cluster có một node server và ba agent, với ánh xạ cổng của chế độ biên.
agent-0mang nhãnrole=stateful, cònagent-1vàagent-2mangrole=app. Danh sáchfiles:của file cấu hình đặt ba manifest vào thư mục manifests của k3s trên node server, và k3s áp dụng chúng ở lần khởi động đầu:- Một
HelmChartConfigcấu hình lại Traefik đi kèm k3s. Nó được viết thẳng trong file cấu hình k3d của từng chế độ. infra/cluster/argocd.yaml, mộtHelmChartcủa k3s cài chartargo-cd, phiên bản 10.11.7, vào namespaceargocd. Phần values của nó thêm kiểm tra health cho Application; thiếu nó,rootsẽ không chờ platform healthy rồi mới khởi động các stack.infra/argocd/root.yaml. k3s thử lại file này cho đến khi các CRD của Argo CD tồn tại. Từ đó Argo CD quản lý luôn file đó.
Khi node server khởi động lại, k3s áp dụng lại bản
root.yamlmà nó nhận lúc tạo cluster. Nếu file trong git đã đổi từ đó, cơ chế self-heal của Argo CD đưa bản trong git trở lại trong vòng vài phút.Bạn sẽ thấy
roottrong danh sách khi Argo CD đã lên:Terminalkubectl -n argocd get applications - Một
-
Đọc những gì Argo CD hiển thị
Terminalkubectl -n argocd get applicationsSau vài phút, bốn Application của platform là
cnpg,sealed-secrets,restate-operatorvàimage-updaterở trạng thái Synced và Healthy.stack-devvàstack-prodhiện Unknown kèm một ComparisonError:infra/stack/secrets/dev/ holds no sealed secrets: run go -C infra run ./cmd/seal dev, commit and pushLỗi này nằm trong dự tính. Chart trong
infra/stack/templates/secrets.yamltừ chối render khiinfra/stack/secrets/<stack>/chưa có SealedSecret nào, vì stack không thể chạy thiếu chúng. Lúc này các secret chưa thể có:kubesealmã hóa bằng chứng chỉ của controller Sealed Secrets, và controller đó vừa lên ở wave 0 một phút trước. Cả hai Application của stack thử lại, với thời gian chờ tăng dần từ 30 giây đến 5 phút, cho đến khi các file đã niêm phong có mặt trong git.Để vào giao diện web, chuyển tiếp một cổng và đọc mật khẩu admin ban đầu:
Terminalkubectl -n argocd port-forward svc/argocd-server 8080:443 kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath='{.data.password}' | base64 -d -
Niêm phong các secret
Chạy lệnh seal một lần cho mỗi stack, từ thư mục gốc của umbrella. Lệnh cần Docker, Go và một context kubectl trỏ vào cluster này; k3d đã đặt nó làm context hiện tại.
Terminalgo -C infra run ./cmd/seal devLần chạy đầu chép
infra/stack/secrets/example.envthànhinfra/stack/secrets/dev.envvới quyền 600 và sinh mọi khóa stack cần, điền thẳng vào dòngKEY=còn trống hoặc thêm một dòng mới: khóa JWT, khóa console và khóa ký của Restate (từ/envgentrong image server), khóa RustFS, master key và mật khẩu database của gateway, và virtual key của server và console agent. Khóa riêng của Restate nằm ởdev.restate.pembên cạnh. Rồi lệnh dừng:seal: .../infra/stack/secrets/dev.env: set OPENROUTER_API_KEYMở
dev.envvà điền các giá trị mà lệnh không tự sinh được:Biến dev prod OPENROUTER_API_KEYbắt buộc bắt buộc FCM_CREDENTIALStùy chọn; để trống thì thông báo đẩy chỉ được ghi log thay vì gửi đi bắt buộc; APP_ENV=prodkhông chấp nhận giá trị trống, và lệnh seal cho prod cũng vậyOPENROUTER_API_KEYlà khóa OpenRouter của stack,ai-gatewaygửi nó cho mọi alias trên OpenRouter; hãy đặt cho khóa một hạn mức credit theo ngày trên OpenRouter.FCM_CREDENTIALSlà JSON của một service account Firebase, mã hóa base64.Chạy lại lệnh cho dev, rồi hai lần cho prod:
Terminalgo -C infra run ./cmd/seal dev go -C infra run ./cmd/seal prod # tạo prod.env rồi dừng go -C infra run ./cmd/seal prod # sau khi điền prod.envLần chạy thứ hai giữ các khóa đã có trong
<stack>.env, nên niêm phong đúng những giá trị đó. Mỗi lần chạy thành công ghi bốn SealedSecret vàoinfra/stack/secrets/<stack>/:server-secrets.yaml,restate-secrets.yaml,litellm-secrets.yamlvàlitellm-db.yaml. Commit và push chúng:Terminalgit add infra/stack/secrets/dev infra/stack/secrets/prod git commit -m "infra: sealed secrets for dev and prod" git pushCác file
.envvà.pembị git bỏ qua và chỉ nằm trên máy.Sau mỗi lần chạy thành công, bạn sẽ thấy
sealed into .../infra/stack/secrets/<stack>; commit and push. -
Theo dõi các sync wave
Argo CD nhận bản push ở lần poll repo tiếp theo. Để nó xem ngay:
Terminalkubectl -n argocd annotate application stack-dev argocd.argoproj.io/refresh=normal kubectl -n argocd annotate application stack-prod argocd.argoproj.io/refresh=normalSau đó mỗi stack đồng bộ theo các wave từ -1 tới 2, rồi
ai-<stack>của nó theo wave 0 và 1, như sơ đồ ở trên. Argo CD chờ một wave healthy rồi mới bắt đầu wave sau. Trang Postgres, Restate và RustFS liệt kê mọi resource của từng wave.Terminalkubectl -n argocd get applications -w kubectl -n shopnexus-prod get pods -o wide kubectl -n restate-prod get pods -o wideBạn sẽ thấy
stack-dev,stack-prod,ai-devvàai-prodở trạng thái Synced và Healthy. Dev chạy mỗi thứ một bản. Prod chạy ba pod server trênagent-1vàagent-2, hai pod Postgres trên hai node khác nhau và ba pod Restate trên ba node khác nhau. -
Chạy smoke test
infra/smoke.hurlgửi request đến mọi host công khai của một stack. Thêm--insecurenếu chứng chỉ đến từ staging của Let’s Encrypt.Terminalhurl --test --continue-on-error --variable domain=dev.example.com infra/smoke.hurl hurl --test --continue-on-error --variable domain=example.com infra/smoke.hurlFile kiểm tra
https://<domain>/,https://api.<domain>/healthzvà/readyz,https://docs.<domain>/,https://console.<domain>/vàhttps://media.<domain>/healthtrả 200, vàhttp://api.<domain>/healthztrả về chuyển hướng sang HTTPS (301 từ Traefik, 308 từ Caddy).--continue-on-errorchạy đủ bảy request kể cả khi một request thất bại, nên báo cáo liệt kê mọi host lỗi.Bạn sẽ thấy file được báo là thành công và mã thoát 0.
-
Mở console
Console ở
console.<domain>cần một tài khoản nhân viên, và cluster mới chưa có tài khoản nào. API và console chỉ tạo được moderator; admin đầu tiên được tạo bằng lệnhconsoletrong một pod server:Terminalkubectl -n shopnexus-prod exec -it $(kubectl -n shopnexus-prod get pod -l app.kubernetes.io/name=server -o name | head -1) -- \ /console create-admin --email you@example.com --name "Your Name"Lệnh in ra
created admin you@example.com (<id>)và một mật khẩu tạm. Mởhttps://console.example.comvà đăng nhập bằng mật khẩu đó. Console yêu cầu đặt mật khẩu mới, rồi đăng ký một ứng dụng xác thực TOTP. Chạy cùng lệnh đó trongshopnexus-devcho console của dev.Bạn sẽ thấy trang chính của console. Trang Runbook có các lệnh
consolecòn lại.
Gỡ bỏ
k3d cluster delete shopnexusLệnh này xóa mọi node, volume và database trong cluster, kể cả khóa của controller Sealed Secrets. Các SealedSecret trong git chỉ mở được trên một cluster mới nếu bạn khôi phục khóa đó từ bản sao lưu trước khi niêm phong lại; trang Secret có quy trình. Nếu không có khóa, chạy lệnh seal với cluster mới, lệnh dùng lại các khóa trong <stack>.env, rồi commit các SealedSecret mới.