Secret
Các stack nhận khóa qua Sealed Secrets thế nào. Mọi khóa lệnh seal ghi ra, Secret mà khóa nằm trong và ai đọc nó, các file cần sao lưu, cách đổi khóa và khôi phục trên một cluster mới.
Khóa của một stack nằm trong hai file bị git bỏ qua, trên máy chạy lệnh seal: infra/stack/secrets/<stack>.env và infra/stack/secrets/<stack>.restate.pem. Lệnh seal, infra/cmd/seal, mã hóa chúng bằng chứng chỉ công khai của controller Sealed Secrets và ghi kết quả thành các SealedSecret vào infra/stack/secrets/<stack>/, thư mục được commit. Chỉ controller, bên trong cluster, mới biến chúng trở lại thành Secret.
flowchart TB env["dev.env / prod.env<br/>+ .restate.pem<br/>(git bỏ qua)"] --> seal["infra/cmd/seal"] cert["chứng chỉ của controller"] -.->|"kubeseal lấy về"| seal seal --> yaml["infra/stack/secrets/#lt;stack#gt;/*.yaml<br/>SealedSecret, được commit"] yaml -->|"git push"| argo["Argo CD<br/>stack-dev, stack-prod"] argo --> ss["resource SealedSecret"] ss --> ctrl["sealed-secrets-controller<br/>kube-system"] ctrl -->|"giải mã"| sec["Secret"] sec --> pods["server, rustfs, ai-gateway,<br/>Restate, Job"]
Mô hình Sealed Secrets
Application sealed-secrets (infra/platform/sealed-secrets.yaml, chart 2.22.0) chạy controller trong kube-system với tên sealed-secrets-controller, là tên mà kubeseal tìm. Lần khởi động đầu, controller tạo một cặp khóa và giữ nó trong một Secret gắn nhãn sealedsecrets.bitnami.com/sealed-secrets-key. kubeseal mã hóa bằng nửa công khai; nửa bí mật không bao giờ rời cluster.
Lệnh seal gọi kubeseal không có --scope, nên mỗi SealedSecret dùng scope mặc định strict: nó chỉ giải mã được dưới đúng tên và namespace của nó. Một SealedSecret chép sang stack kia sẽ không mở được ở đó.
Chart lấy mọi file trong infra/stack/secrets/<stack>/. Khi thư mục rỗng, việc render thất bại với infra/stack/secrets/<stack>/ holds no sealed secrets: run go -C infra run ./cmd/seal <stack>, commit and push, và Application của stack hiện lỗi đó cho tới khi các file tới.
Lệnh seal làm gì
Chạy lệnh từ thư mục gốc của umbrella:
go -C infra run ./cmd/seal dev|prod [-dry-run]-C infra đặt infra/ làm thư mục làm việc, nên các đường dẫn mặc định tính từ đó. -dir đặt thư mục secret (mặc định stack/secrets), -example đặt file mẫu (mặc định stack/secrets/example.env) và -image đặt image server chạy /envgen (mặc định ghcr.io/shopnexus/server:main). Cờ có thể đứng trước hoặc sau tên stack. Thêm một đối số thừa thì lệnh in cách dùng và thoát với mã 2.
-
Tạo file .env
Ở lần chạy đầu,
/envgenchépinfra/stack/secrets/example.envthành<stack>.envvới mode 600. Ở các lần sau, nó thêm những biếnexample.envcó mà<stack>.envthiếu, với giá trị trong example. -
Sinh các khóa còn thiếu
Với mỗi khóa tự sinh chưa có giá trị trong
<stack>.env, lệnh tạo một khóa. Khóa JWT, khóa console và khóa Restate đến từ/envgentrong image server (-image), chạy trong Docker. Các khóa còn lại là byte ngẫu nhiên từcrypto/randcủa Go, mã hóa hex. Cả hai cách đều điền vào dòngKEY=rỗng tại chỗ và nối thêm dòng còn thiếu. -
Kiểm tra giá trị của người vận hành
Lệnh dừng với
seal: .../<stack>.env: set OPENROUTER_API_KEYkhi giá trị đó còn rỗng. Với prod, lệnh dừng khiFCM_CREDENTIALScòn rỗng, kèmprod needs FCM_CREDENTIALS (APP_ENV=prod refuses to only log pushes). -
Seal bốn Secret
Lệnh tự dựng từng Secret, chuyển qua
kubeseal --format yaml, và ghiserver-secrets.yaml,restate-secrets.yaml,litellm-secrets.yamlcùnglitellm-db.yamlvàoinfra/stack/secrets/<stack>/.kubeseallấy chứng chỉ từ cluster mà kubectl đang trỏ tới. Lệnh kết thúc bằngsealed into .../infra/stack/secrets/<stack>; commit and push.
Lần chạy thứ hai thấy mọi khóa đã có và seal đúng các giá trị cũ. kubeseal mã hóa với một session key ngẫu nhiên mới mỗi lần, nên các file đã seal vẫn thay đổi.
Các khóa
| Khóa | Do ai tạo | Secret | Ai đọc |
|---|---|---|---|
JWT_KEY_ID | /envgen: k và giờ UTC, ví dụ k20261104120000 | server-secrets | server |
JWT_PRIVATE_KEY | /envgen: base64 của một seed Ed25519 32 byte | server-secrets | server, dùng để ký access token |
CONSOLE_KEY | /envgen: base64 của 32 byte ngẫu nhiên | server-secrets | server, suy ra từ nó khóa niêm phong TOTP và khóa HMAC dùng khi khóa đăng nhập |
RESTATE_IDENTITY_KEY | /envgen: khóa công khai, publickeyv1_… | server-secrets | server, từ chối request của Restate không ký bằng khóa bí mật tương ứng |
<stack>.restate.pem | /envgen: khóa bí mật Ed25519 | restate-secrets dưới tên private.pem | Restate (requestSigningPrivateKey) |
OBJECT_STORE_ACCESS_KEY | 12 byte ngẫu nhiên, hex | server-secrets; restate-secrets dưới tên AWS_ACCESS_KEY_ID | server, RustFS (RUSTFS_ACCESS_KEY), snapshot của Restate |
OBJECT_STORE_SECRET_KEY | 24 byte ngẫu nhiên, hex | server-secrets; restate-secrets dưới tên AWS_SECRET_ACCESS_KEY | server, RustFS (RUSTFS_SECRET_KEY), snapshot của Restate |
LLM_API_KEY | sk- và 24 byte ngẫu nhiên, hex | server-secrets | server; Job ai-gateway-keys đăng ký nó làm key server-llm |
STT_API_KEY | sk- và 24 byte ngẫu nhiên, hex | server-secrets | server; Job ai-gateway-keys đăng ký nó làm key server-stt |
EMBED_INDEX_API_KEY | sk- và 24 byte ngẫu nhiên, hex | server-secrets | server, khi index tin đăng; Job ai-gateway-keys đăng ký nó làm key server-embed-index |
EMBED_SEARCH_API_KEY | sk- và 24 byte ngẫu nhiên, hex | server-secrets | server, khi embed câu truy vấn; Job ai-gateway-keys đăng ký nó làm key server-embed-search |
LITELLM_MASTER_KEY | sk- và 24 byte ngẫu nhiên, hex | litellm-secrets | ai-gateway, Job ai-gateway-keys |
LITELLM_DB_PASSWORD | 24 byte ngẫu nhiên, hex | litellm-db dưới tên password, với username: litellm | CloudNativePG (managed role litellm), ai-gateway |
OPENROUTER_API_KEY | bạn: khóa OpenRouter của stack, có hạn mức credit theo ngày đặt trên OpenRouter | litellm-secrets | ai-gateway, cho mọi alias trên OpenRouter |
FCM_CREDENTIALS | bạn: JSON của một service account Firebase, mã hóa base64 | server-secrets | server, để gửi push |
FCM_CREDENTIALS có thể để rỗng trên dev, nơi server ghi push ra log thay vì gửi. APP_ENV=prod từ chối giá trị rỗng, nên lệnh seal cho prod cũng vậy. OPENROUTER_API_KEY bắt buộc trên cả hai stack.
server-secrets, litellm-secrets và litellm-db nằm trong shopnexus-<stack>. restate-secrets nằm trong restate-<stack>, namespace của RestateCluster. Các Job migrate, objectstore-init và objectstore-init-snapshots chạy image server với cùng môi trường, nên cũng nhận mọi khóa của server-secrets.
CloudNativePG tạo thêm một Secret, postgres-app, có uri là DATABASE_URL của server. JWT_PREVIOUS_KEY_ID và JWT_PREVIOUS_PUBLIC_KEY là chuỗi rỗng trong infra/stack/env/server.env, file mà chart đưa vào ConfigMap server-env và docker-compose.yml ở gốc đọc bằng env_file.
Các file cần sao lưu
| File | Chứa gì | Mất nó thì |
|---|---|---|
infra/stack/secrets/dev.env, prod.env | mọi khóa trong bảng trên, ở dạng rõ | một lần seal lại sinh khóa mới. CONSOLE_KEY mới làm mọi TOTP secret đã lưu không đọc được nữa; khóa JWT mới từ chối các access token phát ra trước nó, trong tối đa 15 phút sống của chúng |
infra/stack/secrets/dev.restate.pem, prod.restate.pem | khóa ký bí mật của Restate | /envgen dừng, và lệnh seal in thông báo của nó sau envgen in <image>: <stack>.env has RESTATE_IDENTITY_KEY but <stack>.restate.pem is missing: restore <stack>.restate.pem from the backup |
| khóa của controller | khóa bí mật mở được mọi SealedSecret trong git | các SealedSecret đã commit không mở được trên cluster mới; bạn seal lại từ các file .env và .pem |
Xuất khóa của controller bằng:
kubectl -n kube-system get secret -l sealedsecrets.bitnami.com/sealed-secrets-key -o yaml > sealed-secrets-key.yamlGiữ năm file trong một trình quản lý mật khẩu hoặc một chỗ lưu khác không nằm trên máy này.
Khi cluster còn chạy, các giá trị đã giải mã cũng nằm trong Secret của nó, ví dụ kubectl -n shopnexus-prod get secret server-secrets -o yaml và kubectl -n restate-prod get secret restate-secrets -o yaml. Từ đó có thể dựng lại một file .env bị mất trước khi cluster mất theo.
Quyền file
/envgen tạo <stack>.env và <stack>.restate.pem với mode 600, chạy trong Docker bằng uid và gid của bạn, nên các file thuộc về bạn. Sau đó lệnh seal đặt <stack>.env về mode 600 ở mỗi lần chạy, việc này cũng sửa một file cũ còn ở 644, và ghi file lại với mode đó. Người dùng khác trên máy không đọc được hai file này. .helmignore của chart loại secrets/*.env và secrets/*.pem khỏi chart, và .gitignore của umbrella bỏ qua chúng; chỉ example.env được theo dõi.
Chạy thử
-dry-run in bốn Secret ở dạng rõ, dưới dạng JSON, ra stdout thay vì seal. Nó không cần cluster và không cần kubeseal, nên cho thấy lệnh seal sẽ seal gì trước khi controller tồn tại.
Nó vẫn cần Docker, vẫn tạo <stack>.env, sinh các khóa còn thiếu và dừng khi OPENROUTER_API_KEY rỗng, như một lần chạy thật. Đầu ra chứa mọi khóa ở dạng rõ; đừng dán nó vào ticket hay khung chat.
Đổi một khóa
-
Xóa dòng
Xóa cả dòng của khóa trong
<stack>.env, kể cả tên. Một dòngKEY=rỗng cũng được: lệnh seal ghi giá trị mới vào chính dòng đó. Với khóa JWT, xóa cảJWT_KEY_IDlẫnJWT_PRIVATE_KEY:/envgenghi cả cặp khi thiếu một trong hai. -
Seal lại và push
Terminalgo -C infra run ./cmd/seal prod git add infra/stack/secrets/prod git commit -m "infra: rotate <key> in prod" git push -
Khởi động lại pod Restate nếu cần
Argo CD apply các SealedSecret mới, controller cập nhật các Secret, và các workload trong bảng dưới khởi động lại tự động hoặc bằng tay, như bảng ghi.
| Workload | Khi seal lại |
|---|---|
server (RestateDeployment) | một phiên bản mới khởi động, vì template pod mang checksum/secrets, mã băm của mọi file trong infra/stack/secrets/<stack>/ |
| RustFS (StatefulSet) | khởi động lại, qua cùng checksum/secrets |
ai-gateway (Deployment, Application ai-<stack>) | giữ giá trị cũ cho tới khi chạy kubectl -n shopnexus-<stack> rollout restart deploy/ai-gateway; nó không mang checksum của secret của stack |
migrate, objectstore-init, objectstore-init-snapshots, ai-gateway-keys | vốn chạy ở mỗi lần sync Application của chúng |
pod Restate (RestateCluster) | giữ giá trị cũ cho tới khi khởi động lại; chart không gắn checksum lên chúng |
Mỗi khóa có tác dụng riêng:
LLM_API_KEYmới làmai-gateway-keyscập nhật khóa cũ thất bại rồi tạo khóa mới ở lần syncai-<stack>kế tiếp. Virtual key cũ vẫn nằm trong database của gateway cho tới khi bạn xóa nó ở đó.LITELLM_DB_PASSWORDmới được CloudNativePG đặt cho rolelitellm; khởi động lạiai-gatewaybằng tay để nó dùng mật khẩu mới.- Cặp khóa object store mới tới RustFS và server qua checksum, nhưng chỉ tới bộ ghi snapshot của Restate khi các pod Restate khởi động lại. Việc đổi chúng trên một volume RustFS đã có dữ liệu chưa được thử.
CONSOLE_KEYkhông đổi được mà không mất dữ liệu. Server không có thiết lập khóa trước cho nó, và các TOTP secret trong Postgres được niêm phong bằng một khóa suy ra từ nó.
Khóa Restate
Khóa bí mật trong restate-secrets và khóa công khai trong server-secrets phải khớp nhau. Một pod server từ chối mọi request ký bằng khóa khác. Trong lúc đổi khóa, hai khóa đổi vào hai thời điểm khác nhau: phiên bản server mới khởi động với khóa công khai mới qua checksum, còn các pod Restate ký bằng khóa bí mật cũ cho tới khi khởi động lại. Request từ Restate tới phiên bản mới thất bại trong khoảng đó, và phiên bản server cũ, đang được rút, từ chối khóa mới sau khi Restate khởi động lại.
Lệnh seal từ chối một .env có RESTATE_IDENTITY_KEY trong khi thiếu file .pem. Không có kiểm tra này, một lần khôi phục quên file .pem sẽ sinh cặp khóa mới và đổi khóa ngoài ý muốn. Để đổi có chủ đích, xóa dòng RESTATE_IDENTITY_KEY và file .pem, chạy lệnh seal, push, rồi khởi động lại từng pod Restate một:
kubectl -n restate-prod get pods -l app.kubernetes.io/name=restate
kubectl -n restate-prod delete pod <một pod>Chỉ xóa dòng thì vẫn giữ khóa cũ: /envgen dùng lại file .pem đang có và ghi lại khóa công khai của nó. Việc đổi khóa Restate có chủ đích chưa được thử trên cluster.
Khóa JWT
Server kiểm access token bằng JWT_KEY_ID, và trong lúc đổi khóa còn bằng JWT_PREVIOUS_KEY_ID với JWT_PREVIOUS_PUBLIC_KEY. Hai biến khóa trước được đặt cùng nhau hoặc không đặt, và ID trước phải khác ID hiện tại. Access token sống 15 phút, nên khóa trước phải ở lại ít nhất 15 phút sau khi khóa mới có hiệu lực.
Trong cluster, chart cố định cả hai biến khóa trước là chuỗi rỗng trong server-env, và lệnh seal không seal chúng. Vì vậy muốn đổi mà không mất phiên thì phải sửa trước: thêm JWT_PREVIOUS_KEY_ID và JWT_PREVIOUS_PUBLIC_KEY vào danh sách khóa của server-secrets trong infra/cmd/seal/main.go. Pod đọc server-secrets sau server-env, và Kubernetes ưu tiên nguồn envFrom đứng sau, nên giá trị đã seal ghi đè giá trị rỗng. Để lấy khóa công khai cũ từ seed cũ trong <stack>.env:
seed=$(grep -m1 '^JWT_PRIVATE_KEY=' infra/stack/secrets/prod.env | cut -d= -f2-)
{ printf '302e020100300506032b657004220420' | xxd -r -p; base64 -d <<<"$seed"; } \
| openssl pkey -inform DER -pubout -outform DER | tail -c 32 | base64Ghi ID cũ và khóa công khai đó thành JWT_PREVIOUS_KEY_ID và JWT_PREVIOUS_PUBLIC_KEY, xóa hai dòng JWT_KEY_ID và JWT_PRIVATE_KEY cũ, seal lại và push. Sau 15 phút, xóa hai dòng khóa trước và seal lại lần nữa.
Khôi phục trên cluster mới
Các SealedSecret trong git mở lại được khi controller mới có khóa cũ.
-
Tạo cluster
Chạy
k3d cluster createvớiinfra/cluster/k3d-direct.yamlhoặcinfra/cluster/k3d-behind-proxy.yamlnhư trong Dựng một cluster, và chờsealed-secretsSynced và Healthy. -
Apply khóa cũ
Bỏ các trường mà cluster cũ đặt, rồi apply:
Terminalyq 'del(.items[].metadata.resourceVersion, .items[].metadata.uid, .items[].metadata.creationTimestamp)' \ sealed-secrets-key.yaml | kubectl apply -f - -
Khởi động lại controller
Controller nạp khóa lúc khởi động.
Terminalkubectl -n kube-system rollout restart deployment sealed-secrets-controllerGiờ nó mở được SealedSecret làm bằng khóa cũ và bằng khóa nó tạo ở lần khởi động đầu.
-
Khôi phục các file dạng rõ
Chép
dev.env,prod.env,dev.restate.pemvàprod.restate.pemtrở lạiinfra/stack/secrets/và chạychmod 600trên chúng, để lần seal sau giữ nguyên khóa.
Không có khóa của controller thì seal lại với controller mới.
-
Tạo cluster
Tạo cluster bằng
k3d cluster createvà chờsealed-secretsHealthy. -
Khôi phục các file dạng rõ
Chép bốn file trở lại
infra/stack/secrets/với mode 600. Khôi phục mỗi file.pemcùng file.envcủa nó; lệnh seal dừng nếu thiếu một file. -
Seal lại và push
Terminalgo -C infra run ./cmd/seal dev go -C infra run ./cmd/seal prod git add infra/stack/secrets/dev infra/stack/secrets/prod git commit -m "infra: reseal for the new cluster" git pushLệnh seal dùng lại mọi khóa trong các file
.env, nên các stack nhận đúng các khóa cũ dưới bản mã mới.
Sau khi seal lại theo tab thứ hai, hãy sao lưu khóa của controller mới, vì các SealedSecret trong git giờ được seal bằng nó.
Quy tắc chính
<stack>.envvà<stack>.restate.pemkhông bao giờ được commit. Chỉ YAML đã seal tronginfra/stack/secrets/<stack>/được commit.<stack>.env,<stack>.restate.pemvà khóa của controller được sao lưu ra ngoài máy chủ sau mỗi lần thay đổi.CONSOLE_KEYcố định suốt đời database của một stack.- File
.pemđược khôi phục cùng file.envcủa nó. Khóa Restate chỉ được đổi có chủ đích, bằng cách xóa cả dòng lẫn file. - Khóa JWT được đổi với khóa cũ nằm trong
JWT_PREVIOUS_KEY_IDvàJWT_PREVIOUS_PUBLIC_KEYít nhất 15 phút. - Khóa được đổi trong
<stack>.envrồi seal lại. Secret sửa tay trong cluster bị ghi đè ở lần seal lại tiếp theo.
Xử lý sự cố
kubeseal: error: cannot fetch certificate
kubeseal tới controller qua kubectl context hiện tại. Kiểm tra kubectl config current-context trỏ tới cluster k3d và kubectl -n kube-system get deploy sealed-secrets-controller đã ready.
SealedSecret không thành Secret
Đọc status của nó và log của controller:
kubectl -n shopnexus-prod get sealedsecret server-secrets -o jsonpath='{.status.conditions}'
kubectl -n kube-system logs deploy/sealed-secrets-controller --tail=50no key could decrypt secret nghĩa là các file được seal cho controller của một cluster khác. Khôi phục khóa của controller đó, hoặc seal lại với controller này.
Server báo thiếu hoặc sai một biến
Lúc khởi động, server nêu tên mọi biến nó thiếu. Kiểm tra khóa có trong danh sách khóa của server-secrets trong infra/cmd/seal/main.go và có giá trị trong <stack>.env, rồi seal lại. RESTATE_IDENTITY_KEY phải bắt đầu bằng publickeyv1_.