Kubernetes (Helm chart)
Chart chính thức trong deploy/helm/lumibase/ chạy image đã publish
ghcr.io/khuepm/lumibase-cms trên Kubernetes: CMS API và Studio từ một
Deployment trên cùng một origin, migration chạy trước khi server khởi động,
probe trỏ vào chính các route health của server, và mức hardening mà image được
build cho nó (non-root UID 65532, root filesystem read-only, không capability).
PostgreSQL và Redis được kèm sẵn cho lần cài đầu tiên và thay bằng dịch vụ
managed khi lên production; Meilisearch là tuỳ chọn.
| Resource | Khi nào |
|---|---|
Deployment <release>-lumibase (API + Studio, role all hoặc web) | luôn luôn |
| Service, ConfigMap, Secret, ServiceAccount | luôn luôn |
| StatefulSet + Service cho PostgreSQL / Redis | postgresql.enabled / redis.enabled (mặc định bật) |
| StatefulSet + Service cho Meilisearch | meilisearch.enabled |
Deployment <release>-lumibase-worker (role worker) | worker.enabled |
Job <release>-lumibase-migrate-<hash> | migrations.mode=job |
| Ingress (TLS tuỳ chọn) | ingress.enabled |
| HorizontalPodAutoscaler, PodDisruptionBudget, NetworkPolicy | autoscaling.enabled, podDisruptionBudget.enabled, networkPolicy.enabled |
Pod helm test | tests.enabled (mặc định bật) |
Yêu cầu: Kubernetes 1.25 trở lên, Helm 3.8 trở lên (OCI registry), và một
StorageClass mặc định khi các dịch vụ kèm sẵn giữ persistence bật. Chart gọi
trực tiếp entrypoint distroless và migration runner của image, nên cần image đã
hardening ở Image đã hardening — bản release
mà chart được publish cùng, hoặc image.tag=edge cho main.
Cài đặt
Chart được publish dưới dạng OCI artifact cùng mỗi release, đánh version theo release, và image tag mặc định của nó chính là release đó:
helm install lumibase oci://ghcr.io/khuepm/charts/lumibase --version <version> \
--namespace lumibase --create-namespace \
--set publicUrl=https://cms.example.com
Từ một bản checkout, dùng đường dẫn thay thế: helm install lumibase ./deploy/helm/lumibase ….
publicUrl là giá trị duy nhất bạn bắt buộc phải đặt. Ở production server từ
chối khởi động khi thiếu CORS_ALLOWED_ORIGINS, và chart dừng việc render kèm
thông báo thay vì để pod rơi vào crash loop. Chart chấp nhận một trong các cách:
publicUrl, corsAllowedOrigins, hoặc ingress.enabled kèm host (khi đó origin
là https://<host> nếu có mục TLS liệt kê host đó, ngược lại là http://<host>).
Thử trên máy (kind, port-forward)
kind create cluster
helm install lumibase ./deploy/helm/lumibase -n lumibase --create-namespace \
--set publicUrl=http://localhost:1989 --wait --timeout 10m
kubectl -n lumibase port-forward service/lumibase 1989:80
Rồi mở http://localhost:1989/setup. Ghi chú sau khi cài in ra các bước tiếp
theo, gồm cả lệnh lấy setup token bên dưới.
Setup token
Chart đặt LUMIBASE_REQUIRE_SETUP_TOKEN=true (setup.requireToken): instance
truy cập được trước khi có ai setup nó, và nếu không có token thì ai vào /setup
trước sẽ chiếm instance. Web pod khởi động đầu tiên sinh token và in nó một lần:
kubectl -n lumibase logs -l app.kubernetes.io/instance=lumibase,app.kubernetes.io/component=cms \
--tail=-1 --prefix | grep SETUP_TOKEN=
Plaintext không được lưu, nên restart pod sẽ không in lại. Nếu mất token trước
khi setup xong, hãy xoá hash đã lưu rồi restart; lần khởi động sau in token mới
(câu lệnh là CLEAR_SETUP_TOKEN_SQL trong apps/cms/src/modules/setup/startup.ts):
kubectl -n lumibase exec statefulset/lumibase-postgresql -- \
psql -U lumibase -d lumibase -c "UPDATE lumibase_system_state SET setup_token_hash = NULL WHERE id = 'singleton';"
kubectl -n lumibase rollout restart deployment/lumibase
Secret
Secret do chart quản lý <release>-lumibase chứa JWT_SECRET, ENCRYPTION_KEY
và mật khẩu của các dịch vụ kèm sẵn. Với mỗi giá trị, thứ tự là: giá trị bạn
đặt, nếu không thì giá trị đã có trong Secret (đọc bằng lookup của Helm, nên
helm upgrade giữ nguyên nó), nếu không nữa thì sinh mới. Giá trị sinh ra không
bao giờ được ghi ngược vào values của bạn, nên không có gì bí mật lọt vào file
bạn commit.
ENCRYPTION_KEYđược sinh dưới dạng base64 chuẩn của 32 byte ngẫu nhiên, đúng dạng server chấp nhận. Key bạn tự đặt được kiểm tra ngay khi render theo cùng quy tắc (16, 24 hoặc 32 byte, padding chuẩn) — ở production server sẽ từ chối mọi dạng khác.- Secret mang annotation
helm.sh/resource-policy: keep(secrets.keepOnUninstall):helm uninstallgiữ nó lại, và cài lại với cùng tên release và namespace sẽ dùng lại nó thay vì sinh một key không đọc được dữ liệu cũ. - Sao lưu
ENCRYPTION_KEYngay sau lần cài đầu tiên (ghi chú cài đặt in sẵn lệnh). Các trường mã hoá và seed two-factor không đọc được nếu thiếu nó; xem Khoá mã hoá. - URL của dịch vụ kèm sẵn không bao giờ được lưu: pod spec chứa
postgresql://lumibase:$(LUMIBASE_HELM_POSTGRES_PASSWORD)@…, và Kubernetes điền mật khẩu từ Secret khi container khởi động.
GitOps (Argo CD, Flux) và helm template: lookup không trả về gì khi chart
được render mà không kết nối cluster, nên giá trị sinh ra sẽ đổi sau mỗi lần
sync — mỗi lần một ENCRYPTION_KEY mới. Hãy tự tạo Secret và trỏ chart vào nó:
kubectl -n lumibase create secret generic lumibase-app \
--from-literal=JWT_SECRET="$(openssl rand -base64 48)" \
--from-literal=ENCRYPTION_KEY="$(openssl rand -base64 32)"
secrets:
existingSecret: lumibase-app # key JWT_SECRET và ENCRYPTION_KEY
Điều tương tự áp dụng cho mật khẩu của dịch vụ kèm sẵn
(postgresql.auth.existingSecret, redis.auth.existingSecret), hoặc chạy
PostgreSQL và Redis bên ngoài chart.
Values cho production
publicUrl: https://cms.example.com
secrets:
existingSecret: lumibase-app
ingress:
enabled: true
className: nginx
hosts:
- host: cms.example.com
paths: [{ path: /, pathType: Prefix }]
tls:
- secretName: cms-example-com-tls
hosts: [cms.example.com]
postgresql:
enabled: false
database:
external:
existingSecret: lumibase-db # key DATABASE_URL, kèm sslmode=require
redis:
enabled: false
external:
existingSecret: lumibase-redis # key REDIS_URL
meilisearch:
external:
host: https://search.example.com
existingSecret: lumibase-search # key MEILISEARCH_API_KEY
s3:
endpoint: https://s3.eu-central-1.amazonaws.com
bucket: lumibase-media
existingSecret: lumibase-s3 # key S3_ACCESS_KEY, S3_SECRET_KEY
podDisruptionBudget:
enabled: true
networkPolicy:
enabled: true
ingressFrom:
- namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: ingress-nginx
Values và biến môi trường tương ứng
Mỗi thiết lập ánh xạ tới một biến mà image đọc; xem
Biến môi trường để biết tác dụng của từng biến.
Những biến khác đặt trong config (không bí mật, render vào ConfigMap, và thắng
các key của chính chart), extraEnv hoặc extraEnvFrom.
| Value | Biến |
|---|---|
environment | NODE_ENV (khi là production), LUMIBASE_ENV |
publicUrl (hoặc host của ingress) | LUMIBASE_PUBLIC_URL |
corsAllowedOrigins (mặc định: origin công khai) | CORS_ALLOWED_ORIGINS |
setup.requireToken | LUMIBASE_REQUIRE_SETUP_TOKEN |
studio.enabled | LUMIBASE_SERVE_STUDIO |
secrets.* | JWT_SECRET, ENCRYPTION_KEY |
postgresql.* / database.external.* | DATABASE_URL |
database.sslMode (disable với PostgreSQL kèm sẵn) | DATABASE_SSL_MODE |
database.rls, database.systemUrl.* | LUMIBASE_DB_RLS, DATABASE_SYSTEM_URL |
redis.* | REDIS_URL |
meilisearch.* | MEILISEARCH_HOST, MEILISEARCH_API_KEY |
s3.* | S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY, S3_SECRET_KEY |
cms.role, worker.enabled | LUMIBASE_PROCESS_ROLE |
worker.healthPort | LUMIBASE_WORKER_HEALTH_PORT |
migrations.mode | SKIP_MIGRATIONS, MIGRATION_MODE (init container) |
migrations.target | MIGRATE_TARGET (các runner migration và gate) |
Chart luôn đặt LUMIBASE_RUNTIME=docker và PORT=1989.
values.schema.json từ chối values sai dạng trước khi bất cứ thứ gì được render.
Migration
Hai thành phần của runner migration trong image (dist/migrate.cjs) sắp thứ
tự cho mọi mode:
- Lock.
migrate.cjs applygiữ một advisory lock PostgreSQL cấp session trong suốt quá trình apply. Key cố định:5509430018010346341, chính là các byte ASCII củaLumiBase(pg_lockshiển thị làclassid = 1282764137,objid = 1113682789). Các runner khởi động cùng lúc (nhiều web replica, pod surge, HPA scale-out, entrypoint trên hai replica) xếp hàng trên lock này: runner đầu tiên apply, mỗi runner sau đó không còn gì pending, ghi logNothing to applyvà thoát với mã 0. Postgres nhả lock khi kết nối của runner đóng, nên pod bị kill không bao giờ bỏ lại lock. Một runner chờ tối đaMIGRATION_LOCK_TIMEOUTgiây (mặc định 900) rồi báo lỗi, và Kubernetes chạy lại nó. - Gate.
migrate.cjs wait --timeout <seconds>chỉ đọc: thoát với mã 0 khi database không còn migration nào pending so với journal đóng gói trong image, poll với backoff (1 giây, nhân đôi đến 10 giây), và thoát với mã 1 khi hết thời gian (migrations.waitTimeoutSeconds, mặc định 600), sau đó Kubernetes khởi động lại init container.
migrations.mode chọn ai apply migration:
initContainer(mặc định): mỗi web pod trước tiên chạy entrypoint của image vớiMIGRATION_MODE=preflight— chờ database bằng chính cơ chế retry và backoff của entrypoint và in ra phiên bản schema — rồi chạynode /app/dist/migrate.cjs applydưới lock. Container server khởi động vớiSKIP_MIGRATIONS=true. Migration lỗi sẽ giữ pod ngoài vòng phục vụ thay vì phục vụ trên schema mới migrate một nửa, và rolling update dừng tại đó.job: một Job,<release>-lumibase-migrate-<hash>, chạy cùng preflight vàapply; web pod chỉ chạy gate. Hash lấy từ pod spec của Job, thứ mà Kubernetes không cho sửa: image hoặc thiết lập database mới tạo ra Job mới (Helm xoá Job trước đó), còn áp lại values không đổi —helm upgrade, hay một lần Argo CD sync output củahelm template— để nguyên Job đã chạy xong. VớinetworkPolicy.enabled, các dịch vụ kèm sẵn cũng nhận pod của Job.entrypoint: web pod không có init container; image tự migrate mỗi lần khởi động dưới cùng lock đó, giống trên Docker và các nền tảng one-click.none:SKIP_MIGRATIONS=trueở mọi nơi và không có gate; bạn tự chạy migration từ pipeline của mình trước khi rollout.
Worker pod không bao giờ migrate. Ở mọi mode trừ none, worker Deployment
khởi động với init container migrations-ready chạy gate, cùng image và cùng
hardening với migrator của web, nên queue consumer và scheduler không khởi
động trên schema cũ hơn schema mà image của chúng được build cho, dù là lần
cài mới hay khi nâng cấp.
Cố ý không dùng Helm hook: hook pre-install hay pre-upgrade chạy trước khi
PostgreSQL kèm sẵn và Secret của chart tồn tại, nên ở lần cài đầu tiên không
thể kết nối database; hook post-install dưới helm install --wait sẽ chờ các
web pod mà chính chúng đang chờ migration. Hook cũng không phải resource của
release, nên rollback không theo dõi chúng.
migrations.target (nâng cao) dừng lịch sử migration tại một tag, ví dụ
0029_activation_milestones, cho cả runner lẫn gate. Nó dành cho nâng cấp theo
từng bước và cho test nâng cấp trong CI; hãy để trống.
Nâng cấp khi có nhiều replica
Khi helm upgrade lên một image có migration mới, ở mode initContainer:
- Các web pod mới khởi động (nhiều nhất cùng lúc theo
cms.strategycho phép; HPA có thể thêm nữa). Mỗi pod chạy migrator của nó; lock chỉ cho đúng một pod apply, các pod khác chờ pod đó rồi không còn gì để apply. - Gate của worker pod mới thấy migration đang pending và chờ; container worker chỉ khởi động sau khi lần apply đã commit.
- Web pod và worker pod cũ tiếp tục phục vụ đến khi pod thay thế Ready, nên trong suốt quá trình rollout code cũ chạy trên schema mới. Giữ migration tương thích ngược với release trước (expand, rồi contract ở release sau), như các migration đóng gói sẵn.
Migration lỗi sẽ rollback transaction của nó, nhả lock và giữ các pod mới ở
Init: rollout dừng lại, và pod cũ tiếp tục phục vụ.
Đọc Nâng cấp trước khi đổi image.tag qua một bản
major.
Health check
| Probe | Path | Lý do |
|---|---|---|
| startup, liveness | /health | Trả 200 bất cứ khi nào process phục vụ HTTP, nên sự cố database không làm restart mọi pod. |
| readiness | /health/ready hoặc /health | /health/ready trả 503 khi bất kỳ database, cache, search, storage hay queue nào không khoẻ. |
cms.readinessPath để trống (mặc định) chỉ chọn /health/ready khi search
và object storage đều được cấu hình; ngược lại dùng /health, vì
/health/ready sẽ báo dịch vụ còn thiếu và không bao giờ ready. Đặt tường minh
để ghi đè. Worker pod probe /health và /health/ready trên worker.healthPort.
Mở rộng
cms.replicaCounthoặcautoscaling.enabled(CPU, tuỳ chọn thêm memory) mở rộng web Deployment. Scheduled job được khoá leader qua Redis, nên nhiều replica không chạy chúng hai lần.worker.enabledchuyển queue worker và scheduler sang Deployment riêng (LUMIBASE_PROCESS_ROLE=worker), và web pod chuyển sangweb.- Giới hạn realtime: trên Docker runtime, sự kiện WebSocket được phát trong
process (
packages/runtime/src/adapters/docker/realtime.ts), nên với nhiều hơn một web replica, client chỉ nhận sự kiện được publish bởi pod nó đang kết nối. Giữ một web replica nếu bạn phụ thuộc vào realtime, hoặc chấp nhận giới hạn đó. podDisruptionBudget.enabledbảo vệ web pod khi drain node.
Dịch vụ kèm sẵn
PostgreSQL (postgres:16-alpine), Redis (redis:7-alpine) và Meilisearch
(getmeili/meilisearch:v1.7, đúng các phiên bản trong docker/docker-compose.yml)
là các StatefulSet một instance đơn giản, non-root với root filesystem
read-only. Chúng không phải dependency subchart: subchart phải được tải từ chart
repository lúc cài và tự quyết lịch release cùng image của nó, còn template
trong chart này cài được offline và được review cùng chart. Chúng không có
replication và không có backup; dùng để đánh giá, còn production thì dùng dịch
vụ managed. Redis chạy với AOF persistence và noeviction, vì job BullMQ không
bao giờ được phép bị evict.
Object storage không được kèm sẵn. Không có s3.endpoint, instance vẫn khởi động
và setup vẫn hoàn tất, nhưng upload không hoạt động.
NetworkPolicy
Với networkPolicy.enabled, web pod chỉ nhận traffic trên cổng HTTP (từ
networkPolicy.ingressFrom nếu có đặt), worker không nhận gì (traffic từ chính
node của pod, nơi kubelet gửi probe, luôn được phép), còn PostgreSQL, Redis và Meilisearch kèm sẵn
chỉ nhận web pod và worker pod của release (và pod của Job migration khi
migrations.mode=job). Egress không bị giới hạn: CMS gọi
object storage, nhà cung cấp LLM và webhook.
Kiểm tra
helm test lumibase -n lumibase --logs
Pod test dùng chính Node của image release để kiểm tra, qua Service, rằng
/health trả lời, /api/v1/setup/state trả lời, và /setup phục vụ khung
Studio. Trong CI, .github/workflows/helm.yml lint chart, chạy
scripts/__tests__/helm-chart.test.mjs (test render), và
scripts/helm-kind-smoke.sh cài chart lên kind với image build từ cùng commit,
chạy helm test, upgrade, rồi kiểm tra ENCRYPTION_KEY không đổi. Sau đó nó
cài một worker và hai web replica thiếu một migration so với journal của image
rồi nâng cấp lên toàn bộ journal, kiểm tra rằng bảng migration chứa mỗi
migration đúng một lần, đúng một web pod đã apply nó, và worker chỉ khởi động
sau khi gate của nó qua; cuối cùng chuyển release sang migrations.mode=job.
Nâng cấp và gỡ cài đặt
helm upgrade lumibase oci://ghcr.io/khuepm/charts/lumibase --version <new> -n lumibase -f my-values.yaml
helm uninstall lumibase -n lumibase
helm uninstall giữ lại Secret (xem Secret) và PersistentVolumeClaim
của các StatefulSet; tự xoá chúng khi muốn bỏ dữ liệu.