Guard Spec
ENVI
GitHub
Tài liệu

Triển khai

English: README.md. Nếu hai bản khác nhau, bản tiếng Anh là bản chính.

Các hướng dẫn tham khảo để chạy Guard Spec ở nơi khác ngoài laptop.

Trạng thái: template tham khảo, maintainer chưa kiểm chứng. Cộng đồng đã thử: chưa. Nếu bạn triển khai theo các hướng dẫn này, hãy mở một issue hoặc một pull request kể lại điều gì chạy được và điều gì không. Xem CONTRIBUTING.md.

Hướng dẫn Nội dung Trạng thái
aws.md EKS với Helm chart, hoặc ECS trên Fargate; RDS for PostgreSQL 17, Secrets Manager, ALB + ACM, CloudWatch Template, chưa thử trên AWS
gcp.md GKE Autopilot với Helm chart, hoặc Cloud Run; Cloud SQL for PostgreSQL 17, Secret Manager, HTTPS load balancer, Cloud Logging Template, chưa thử trên GCP
on-premise.md Một VM với Docker Compose, Kubernetes thuần và OpenShift, cài đặt air-gapped, reverse proxy cho TLS Template; cách dùng compose là cách README đã mô tả

Những gì maintainer đã kiểm tra khi viết các hướng dẫn này, trên một host Docker cục bộ với các image 0.1.0: các migration chạy được trên PostgreSQL 17 bằng migrate/migrate:v4.20.1, deploy/postgres/set-app-password.sh đặt được mật khẩu cho role của ứng dụng, và guard-spec-gateway-full:0.1.0 cùng guard-spec-control-plane:0.1.0 khởi động được với một UID không phải root bất kỳ (group 0) và root filesystem chỉ đọc, /readyz báo "layers":["l1","l2","l3"]. Chưa chạy thử gì riêng cho cloud.

Đọc trước

Các hướng dẫn này không lặp lại README. Chúng giả định bạn đã biết:

Mọi bản triển khai đều cần

Thành phần Ghi chú
PostgreSQL Compose và CI dùng bản 17. Hai role: một role owner chạy migration (ps trong compose) và guardspec_app, được migration 004 tạo ra không có mật khẩu. Role có phạm vi toàn cluster, nên 004 sẽ lỗi trên server đã có sẵn guardspec_app (của một database hoặc một bản cài khác): hãy cho mỗi bản cài một server riêng
Migration migrations/ của tag bản phát hành, chạy bằng migrate dưới role owner, trước khi các service khởi động. Bản thân các service không bao giờ chạy migration; Helm chart chạy khi migrations.enabled=true (một hook pre-install / pre-upgrade), nếu không thì bạn tự chạy
Mật khẩu ứng dụng GUARDSPEC_APP_PASSWORD được đặt cho guardspec_app sau mỗi lần chạy migration: bằng deploy/postgres/set-app-password.sh hoặc job dbRoles của chart
Gateway ghcr.io/guard-spec/guard-spec-gateway:0.3.0 (model được mount ở /models) hoặc -gateway-full:0.3.0 (model nằm sẵn trong image). Port 8080 cho client, 9090 cho metrics
Control plane ghcr.io/guard-spec/guard-spec-control-plane:0.3.0. Port 8081 cho API và giao diện quản trị ở /ui/, 9091 cho metrics
Secret GUARDSPEC_APP_PASSWORD (cả hai service, dưới dạng PGPASSWORD), JWT_SECRET, MFA_ENC_KEY và ADMIN_PASSWORD (control plane), mật khẩu owner (chỉ dùng cho migration), UPSTREAM_LLM_KEY / UPSTREAM_KEY_* (gateway)
TLS Các service chỉ nói HTTP thường. Hãy terminate TLS ở load balancer hoặc reverse proxy đứng trước chúng

Những điều đúng ở mọi nơi

Helm chart trên main

Chart 0.3.0 (xem mục Unreleased trong CHANGELOG) bổ sung các tính năng sau, tất cả đều tắt theo mặc định: một migration hook (migrations.enabled), một init container kéo model (models.pull, kéo vào claim hoặc vào một emptyDir riêng cho từng pod, nên nhiều replica không còn cần volume ReadWriteMany), Ingress và Routes của OpenShift, HPA, PodDisruptionBudget, topologySpreadConstraints, NetworkPolicies và một ServiceAccount có annotation cho IRSA và Workload Identity. Values tham khảo cho từng nền tảng nằm trong deploy/helm/guard-spec/examples/ (EKS, AKS, GKE, OpenShift): được render và kiểm tra schema trong CI, được job kind-e2e cài lên kind với values riêng của job, chưa kiểm chứng trên cloud. Chỗ nào hướng dẫn bên dưới dùng manifest thuần cho một trong các tính năng này, thì giờ values của chart đã làm được việc tương tự.

Registry mirror và cluster không kết nối mạng: ../airgapped.vi.md (image kèm chữ ký và attestation của cosign, model, xác minh offline, values của chart, External Secrets). Sau khi cài, kubectl exec deploy/<release>-guard-spec-gateway -c gateway -- ./doctor (image từ 0.2.0) sẽ kiểm tra database, migration, model, các lớp phát hiện, upstream và các thiết lập bảo mật.

Từ chart 0.1.1 (xem CHANGELOG): /models chỉ được mount khi có models claim (hoặc models.pull), nên guard-spec-gateway-full chạy được với models.persistence.enabled=false; gateway mặc định giới hạn bộ nhớ 2Gi; job dbRoles lấy securityContext từ values và để OpenShift tự chọn UID; và MFA_ENC_KEY có thể nằm trong existingSecret.

Patch output của chart. Helm 4 chỉ chấp nhận plugin post-renderer cho --post-renderer; một script thông thường, như Helm 3 từng cho phép, sẽ bị từ chối (plugin ... not found). Để thêm patch kustomize, hãy bọc script trong một plugin post-renderer, hoặc render rồi apply mà không qua Helm release: ghi output của helm template vào resources của một kustomization, rồi chạy kubectl kustomize <dir> | kubectl apply -f -. Khi đó các hook như dbRoles chạy như Job bình thường, không còn chạy trước các service.

Đóng góp

Nếu bạn chạy Guard Spec trên một trong các nền tảng này, một báo cáo ngắn hữu ích hơn một hướng dẫn trau chuốt: nền tảng và phiên bản, những gì bạn đã thay đổi so với hướng dẫn, và những gì bị lỗi. Hãy mở một issue hoặc một pull request vào docs/deploy/ (xem CONTRIBUTING.md; commit cần có DCO sign-off). Vấn đề bảo mật phải đi qua SECURITY.md, không bao giờ qua issue công khai.

Nguồn: docs/deploy/README.vi.md @ f26302340bf1