Biên và mạng
Một request đi từ internet tới pod thế nào, mỗi host trỏ tới Service nào, và pod nào được nói chuyện với pod nào.
Mỗi stack là một namespace, shopnexus-dev hoặc shopnexus-prod, và các host của stack đều suy ra từ giá trị domain của nó. Traefik, ingress controller đi kèm k3s, nhận mọi request và định tuyến theo header Host. Request tới Traefik bằng đường nào thì tùy chế độ biên (edge mode), tức file cấu hình k3d dùng để tạo cluster.
Chế độ biên
infra/cluster/k3d-direct.yaml và infra/cluster/k3d-behind-proxy.yaml khác nhau ở hai thứ: cách k3d map cổng, và HelmChartConfig của Traefik viết thẳng trong danh sách files: của file cấu hình, được k3s áp dụng ở lần khởi động đầu. Ở cả hai chế độ, Traefik chạy một replica, gắn cố định vào node control-plane server-0.
flowchart TB
subgraph direct["direct"]
C1["Client"] -->|":80 / :443"| H1["cổng host 80, 443<br/>@server:0:direct"]
H1 --> K1["klipper-lb trên server-0<br/>externalTrafficPolicy: Local"]
K1 --> T1["Traefik websecure<br/>TLS + ACME"]
end
subgraph proxy["behind-proxy"]
C2["Client"] -->|":443"| P2["Caddy trên host<br/>TLS"]
P2 -->|"HTTP"| H2["127.0.0.1:18080<br/>@loadbalancer"]
H2 --> L2["serverlb của k3d"]
L2 --> T2["Traefik web<br/>tin X-Forwarded-*"]
end
T1 --> I["Ingress shopnexus<br/>định tuyến theo Host"]
T2 --> IDùng direct trên máy mà cổng 80 và 443 chưa có ai giữ. Đặt ACME_EMAIL; k3d điền ${ACME_EMAIL} trong file cấu hình từ biến môi trường.
ACME_EMAIL=you@example.com k3d cluster create --config infra/cluster/k3d-direct.yaml- File cấu hình map cổng
80:80và443:443với node filterserver:0:direct. Hai cổng đi thẳng vàoserver-0, nơi Traefik chạy, và bỏ qua serverlb của k3d, một stream proxy nginx thay địa chỉ của client bằng địa chỉ của chính nó. - Service của Traefik đặt
externalTrafficPolicy: Local, nên klipper-lb chuyển kết nối cho pod Traefik trên cùng node và giữ nguyên địa chỉ nguồn. - Resolver
lelấy chứng chỉ từ Let’s Encrypt bằng challenge TLS-ALPN-01 (tlsChallenge: true), challenge này trả lời ngay trên cổng 443. Chứng chỉ nằm ở/data/acme.jsontrên một volume 128Mi. Volume đó chỉ một pod giữ được, nên Deployment dùngupdateStrategy: Recreate. - Resolver dùng thư mục production của Let’s Encrypt. Để thử với thư mục staging, có giới hạn tần suất cao hơn và chứng chỉ mà trình duyệt không chấp nhận, thêm
caServer: https://acme-staging-v02.api.letsencrypt.org/directorydướiacmetrongk3d-direct.yamltrước khi tạo cluster. - Entrypoint
webchuyển hướng sangwebsecurevớipermanent: true. HTTP thường nhận về 301. - Access log được bật (
accessLog.enabled: true).
Dùng behind-proxy khi trên host đã có một proxy giữ cổng 80 và 443. Server của tác giả chạy chế độ này, sau một Caddy dùng chung với các dự án khác.
k3d cluster create --config infra/cluster/k3d-behind-proxy.yaml- File cấu hình map cổng
127.0.0.1:18080:80với node filterloadbalancer. Chỉ chính host mới gọi được cổng 18080. - Proxy bên ngoài kết thúc TLS, chuyển hướng HTTP thường (Caddy trả 308) và gửi HTTP tới
127.0.0.1:18080. Trên server của tác giả, cấu hình proxy đó làconf.d/shopnexus.caddy, liệt kê các host của cả hai stack. - Entrypoint
webcủa Traefik tin headerX-Forwarded-*từ10.0.0.0/8,172.16.0.0/12và192.168.0.0/16, dải này bao cả mạng Docker của k3d. Traefik chuyển tiếp địa chỉ client lấy từX-Forwarded-Forcủa proxy bên ngoài xuống các pod. - Ở chế độ này Traefik không làm TLS và không chuyển hướng.
Manifest Ingress ở cả hai chế độ
Ingress của chart, shopnexus trong infra/stack/templates/ingress.yaml, chỉ ghi host và Service, không có mục tls. Ở direct, TLS đặt trên entrypoint websecure của Traefik (tls.enabled: true, certResolver: le), nên mọi route trên entrypoint đó đều có chứng chỉ cho host của mình. Ở behind-proxy, TLS kết thúc trước khi vào cluster. Chart render ra cùng một bộ manifest cho cả hai chế độ, và infra/check.sh báo lỗi nếu Ingress có thêm khóa tls.
Server tin X-Forwarded-For từ TRUSTED_PROXIES, đặt bằng mạng pod 10.42.0.0/16, là nơi request của Traefik đi ra.
Host
Helper sn.host dựng mọi host từ domain: tiền tố rỗng cho ra chính domain, có tiền tố thì cho ra <tiền tố>.<domain>. Route của console có khi console.enabled là true, và đó là giá trị mặc định.
| Host | Service | Cổng | prod | dev |
|---|---|---|---|---|
<domain> | website | 3000 | shopnexus.id.vn | dev.shopnexus.id.vn |
api.<domain> | server-api | 8080 | api.shopnexus.id.vn | api.dev.shopnexus.id.vn |
media.<domain> | rustfs | 9000 | media.shopnexus.id.vn | media.dev.shopnexus.id.vn |
docs.<domain> | docs | 80 | docs.shopnexus.id.vn | docs.dev.shopnexus.id.vn |
console.<domain> | console | 80 | console.shopnexus.id.vn | console.dev.shopnexus.id.vn |
Mọi đường dẫn của một host (/, pathType: Prefix) đều tới đúng một Service. infra/stack/tests/web_test.yaml, do infra/check.sh chạy, so danh sách host render ra của cả hai stack với các giá trị này.
Chart Traefik 41
k3s v1.37.1-k3s1, image ghi trong cả hai file cấu hình k3d, đi kèm chart Traefik 41.4.0. Schema values của chart này từ chối mọi khóa nó không biết. Bản nháp đầu của cấu hình Traefik cho direct dùng khóa cũ (ports.web.redirections, ports.websecure.tls, logs). Chart từ chối chúng, và k3s chạy Traefik với values mặc định (không ACME, không chuyển hướng, không access log) mà không resource nào báo lỗi.
Các khóa đang dùng là ports.web.http.redirections, ports.websecure.http.tls, accessLog.enabled và certificatesResolvers.le.acme.tlsChallenge. infra/check.sh lấy cấu hình Traefik ra khỏi từng file cấu hình k3d, render nó bằng helm template với chart 41.4.0 rồi tìm các tham số Traefik tương ứng:
- direct:
externalTrafficPolicy: Local,--entryPoints.websecure.http.tls.certResolver=le,--entryPoints.web.http.redirections.entryPoint.to=:443,--certificatesresolvers.le.acme.tlsChallenge=true,--accesslog=true; - behind-proxy:
--entryPoints.web.forwardedHeaders.trustedIPs=10.0.0.0/8,172.16.0.0/12,192.168.0.0/16, và không có chuyển hướng.
Script cũng ghim image k3s ở rancher/k3s:v1.37.1-k3s1. Nâng k3s lên bản mang chart Traefik khác thì check sẽ fail cho tới khi các cấu hình Traefik được render lại với chart mới.
Lưu lượng trong cluster
Mỗi chặng trong cluster đều đi tới một Service của Kubernetes, Service này cân bằng kết nối ở tầng L4 qua các pod sẵn sàng phía sau, trên bất kỳ node nào. Cluster có một node server và ba agent. Các app ưu tiên agent-1 và agent-2 (nhãn role=app), nên một Service thường trải pod của stack ra hai node.
flowchart TB T["Traefik"] --> W["website :3000"] T --> SA["server-api :8080"] T --> RF["rustfs :9000"] W -->|"API_URL"| SA SA --> S1["pod server<br/>mọi phiên bản"] S1 -->|"DATABASE_URL"| PG["postgres-rw"] S1 -->|"http://rustfs:9000"| RF S1 -->|"http://ai-gateway:4000/v1"| LL["ai-gateway"] S1 -->|"http://ai-models:8000/v1, frames"| AM["ai-models"] LL -->|"stt, embed-image"| AM S1 -->|"restate.restate-#lt;stack#gt;:8080, :9070"| R["Restate"] R -->|"HTTP/1.1, :9080"| SV["Service server theo phiên bản"] R -->|"snapshot"| RF
RestateDeploymentcủa server cho mỗi pod template một ReplicaSet và một Service riêng, rồi đăng ký Service đó với Restate. Đổi config hoặc seal lại secret làm đổi checksum trong template, nên tạo ra một phiên bản mới. Operator giữ phiên bản cũ tới khi các invocation của nó chạy xong.- Restate gọi server qua Service của từng phiên bản, cổng 9080 (
restate). Invocation bắt đầu trên phiên bản nào thì ở lại phiên bản đó. server-apichọnapp.kubernetes.io/name: server, nên bao mọi phiên bản. Lưu lượng API công khai tới bất kỳ pod server nào đang sẵn sàng.- Server gọi ingress của Restate ở
http://restate.restate-<stack>:8080và admin API ở:9070.RestateClusternằm trong namespace riêng,restate-devhoặcrestate-prod.
useHttp11: true khiến Restate gọi endpoint bằng HTTP/1.1. Với HTTP/2, Restate giữ một kết nối dài và ghép nhiều invocation trên đó, mà Service L4 cân bằng theo kết nối, nên mọi invocation có thể rơi vào cùng một pod. Với HTTP/1.1, mỗi invocation là một request riêng và được chia đều qua các pod.
NetworkPolicy
infra/stack/templates/networkpolicy.yaml đặt năm policy trong mỗi namespace của stack. default-deny-ingress chọn mọi pod và không cho gì vào, còn mỗi policy trong bốn cái kia mở cho một nguồn.
| Policy | Pod được chọn | Cho phép lưu lượng từ |
|---|---|---|
default-deny-ingress | mọi pod | không gì cả |
from-stack | mọi pod | mọi pod trong cùng namespace |
from-traefik | website, docs, console, server, rustfs | pod app.kubernetes.io/name: traefik trong kube-system |
from-cnpg | cnpg.io/cluster: postgres | namespace cnpg-system (operator CloudNativePG) |
from-restate | server, rustfs | namespace restate-<stack> |
flowchart TB
subgraph ks["kube-system"]
TR["Traefik"]
end
subgraph cnpg["cnpg-system"]
OP["Operator CNPG"]
end
subgraph rp["restate-prod"]
RS["Pod Restate"]
end
subgraph sp["shopnexus-prod"]
WEB["website, docs, console"]
SRV["server"]
RFS["rustfs"]
PG["postgres"]
LLM["ai-gateway, ai-models"]
end
subgraph sd["shopnexus-dev"]
DEV["mọi pod"]
end
TR -->|"from-traefik"| WEB
TR -->|"from-traefik"| SRV
TR -->|"from-traefik"| RFS
OP -->|"from-cnpg"| PG
RS -->|"from-restate"| SRV
RS -->|"from-restate"| RFS
SRV -->|"from-stack"| PG
SRV -->|"from-stack"| LLM
WEB -->|"from-stack"| SRV
SRV -->|"networkPeers"| RS
DEV --x|"không policy nào"| PGRestate-operator tự viết policy cho namespace của Restate dựa trên RestateCluster:
spec.security.networkPeers.ingressvà.adminchỉ cho podapp.kubernetes.io/name: servertrong namespace của stack vào cổng ingress và admin của Restate.- Pod Restate được kết nối tới các pod mang nhãn
allow.restate.dev/restate-<stack>: "true". Pod template của server và StatefulSetrustfsmang nhãn này, cho invocation và snapshot.
Quy tắc chính
from-stackkhông cónamespaceSelector, nên chỉ cho pod trong chính namespace của nó.- Không policy nào mở đường từ
shopnexus-devvàoshopnexus-prodhay theo chiều ngược lại, vàfrom-restatecủa mỗi stack chỉ ghi namespacerestate-<stack>của chính stack đó. - Egress để mở. Server gọi Firebase và FCM ở ngoài cluster, còn
ai-gatewaygọi OpenRouter. - Mọi pod trong stack gọi được
ai-gatewayvàai-modelsquafrom-stack. Chỉ server và console agent giữ virtual key củaai-gateway;ai-modelskhông có xác thực.
Bài diễn tập trong Runbook kết nối từ một pod trong shopnexus-dev tới postgres-rw.shopnexus-prod. NetworkPolicy bỏ các gói tin, nên kết nối hết thời gian chờ (timeout). Bài diễn tập được lên kế hoạch cho server thật và chưa chạy.
Bản ghi DNS
Trỏ các bản ghi A sau về máy chủ. Với prod ở shopnexus.id.vn, bốn bản ghi này phủ cả hai stack.
| Tên | Phủ |
|---|---|
@ | shopnexus.id.vn (website prod) |
* | api., media., docs., console. của prod |
*.dev | api., media., docs., console. của dev |
dev | dev.shopnexus.id.vn (website dev) |
Địa chỉ API của website và console
Website là Astro render phía server, và nó gọi API trong lúc render trang. Nó đọc API_URL lúc chạy (astro:env/server), và image đặt API_URL=http://server-api:8080/v1 trong website/Dockerfile. Tên Service ngắn được phân giải trong namespace của chính pod, nên cùng một image gọi server dev khi chạy trong shopnexus-dev và server prod khi chạy trong shopnexus-prod. Lời gọi này ở trong cluster và được from-stack cho qua.
Console là app tĩnh, gọi API từ trình duyệt. console/src/lib/api.ts lấy host của chính trang, bỏ console. ở đầu và thêm api. vào trước: trang trên console.shopnexus.id.vn gọi https://api.shopnexus.id.vn/v1, trang trên console.dev.shopnexus.id.vn gọi https://api.dev.shopnexus.id.vn/v1. VITE_API_URL thay giá trị này khi phát triển cục bộ. Request mang theo cookie (credentials: 'include'), và server nhận chúng từ CONSOLE_ORIGIN, được chart đặt là https://console.<domain>.