Bỏ qua đến nội dung
ShopNexus Docs
Trên trang này Chế độ biên 1/8

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 --> I
Từ internet tới Traefik

Dù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:80 và 443:443 với node filter server:0:direct. Hai cổng đi thẳng vào server-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 le lấ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.json trên một volume 128Mi. Volume đó chỉ một pod giữ được, nên Deployment dùng updateStrategy: 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/directory dưới acme trong k3d-direct.yaml trước khi tạo cluster.
  • Entrypoint web chuyển hướng sang websecure với permanent: 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:80 với node filter loadbalancer. 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 web của Traefik tin header X-Forwarded-* từ 10.0.0.0/8, 172.16.0.0/12 và 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-For củ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.

HostServiceCổngproddev
<domain>website3000shopnexus.id.vndev.shopnexus.id.vn
api.<domain>server-api8080api.shopnexus.id.vnapi.dev.shopnexus.id.vn
media.<domain>rustfs9000media.shopnexus.id.vnmedia.dev.shopnexus.id.vn
docs.<domain>docs80docs.shopnexus.id.vndocs.dev.shopnexus.id.vn
console.<domain>console80console.shopnexus.id.vnconsole.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
Các lời gọi trong một stack
  • RestateDeployment củ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-api chọn app.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>:8080 và admin API ở :9070. RestateCluster nằm trong namespace riêng, restate-dev hoặc restate-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.

PolicyPod được chọnCho phép lưu lượng từ
default-deny-ingressmọi podkhông gì cả
from-stackmọi podmọi pod trong cùng namespace
from-traefikwebsite, docs, console, server, rustfspod app.kubernetes.io/name: traefik trong kube-system
from-cnpgcnpg.io/cluster: postgresnamespace cnpg-system (operator CloudNativePG)
from-restateserver, rustfsnamespace 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"| PG
Các luồng được phép vào shopnexus-prod

Restate-operator tự viết policy cho namespace của Restate dựa trên RestateCluster:

  • spec.security.networkPeers.ingress và .admin chỉ cho pod app.kubernetes.io/name: server trong 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à StatefulSet rustfs mang nhãn này, cho invocation và snapshot.

Quy tắc chính

  • from-stack không có namespaceSelector, nên chỉ cho pod trong chính namespace của nó.
  • Không policy nào mở đường từ shopnexus-dev vào shopnexus-prod hay theo chiều ngược lại, và from-restate của mỗi stack chỉ ghi namespace restate-<stack> của chính stack đó.
  • Egress để mở. Server gọi Firebase và FCM ở ngoài cluster, còn ai-gateway gọi OpenRouter.
  • Mọi pod trong stack gọi được ai-gateway và ai-models qua from-stack. Chỉ server và console agent giữ virtual key của ai-gateway; ai-models khô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ênPhủ
@shopnexus.id.vn (website prod)
*api., media., docs., console. của prod
*.devapi., media., docs., console. của dev
devdev.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>.

ShopNexus Docs
EN VI