title: “Hướng dẫn triển khai Kubernetes” description: “Tài liệu hướng dẫn triển khai AgentEye trên Kubernetes.”
Hướng dẫn này triển khai toàn bộ ngăn xếp AgentEye lên một cụm Kubernetes chuyên dụng:- ClickHouse 24.8 — kho lưu trữ phân tích chính cho sự kiện và đánh giá (StatefulSet với khối lưu trữ bền vững 100Gi). Bắt buộc: máy chủ từ chối khởi động mà không có nó.
- PostgreSQL 16 — kho lưu trữ quan hệ/siêu dữ liệu cho tổ chức, khóa API, người dùng, bảng điều khiển, truy vấn đã lưu và xác thực (StatefulSet với khối lưu trữ bền vững 50Gi)
- Redis 7.2 — bộ nhớ đệm chia sẻ tùy chọn và phần phụ trợ giới hạn tốc độ; máy chủ và bảng điều khiển sẽ hoạt động bình thường nếu nó không khả dụng
- AgentEye Server — API Rust để thu nhận sự kiện, phân tích và quản lý khóa (2 bản sao)
- AgentEye Dashboard — UI web Next.js (2 bản sao)
- AI assistant (dịch vụ agent) — trợ lý chỉ đọc tùy chọn trong bảng điều khiển trên cổng 9100; vô hoạt cho đến khi điểm cuối LLM được cấu hình
- Traefik (công khai) — bộ điều khiển ingress cho lưu lượng trạm thu thập, được bảo vệ bằng mTLS
- Traefik (bảng điều khiển) — bộ điều khiển ingress cho bảng điều khiển, chỉ VPN/danh sách cho phép IP
- cert-manager — chứng chỉ TLS và CA mTLS
- Backup CronJob — xả khoá hợp nhất hàng ngày của PostgreSQL + ClickHouse lúc 03:00 UTC
- Cert Renewal Monitor — cảnh báo khi chứng chỉ khách hàng sắp hết hạn
Điều kiện tiên quyết
Chạy từng lệnh xác minh trước khi bắt đầu. Mọi kiểm tra phải vượt qua.| Yêu cầu | Tối thiểu | Lệnh xác minh | Kết quả dự kiến |
|---|---|---|---|
| Cụm Kubernetes | 1.27+ | kubectl version | Server Version >= v1.27 |
| Kustomize (được đóng gói với kubectl) | Kustomize v1.14+ (được đóng gói trong kubectl 1.27+) | kubectl kustomize --help | In ra văn bản sử dụng |
| Helm | v3 | helm version | Version:"v3.x.x" |
| RBAC cluster-admin | — | kubectl auth can-i create namespaces | yes |
| StorageClass mặc định | — | kubectl get storageclass | Ít nhất một hàng được đánh dấu (default) |
| Hỗ trợ LoadBalancer | — | Phụ thuộc vào đám mây (EKS, GKE, AKS đều hỗ trợ theo mặc định) | — |
| GitHub PAT | — | echo $AGENTEYE_TOKEN | Không trống (xem enterprise-docs/github-token.md) |
| openssl | — | openssl version | OpenSSL 1.x hoặc 3.x |
| Bộ lưu trữ cloud | — | Dành cho sao lưu PostgreSQL + ClickHouse (S3, GCS hoặc Azure Blob) | — |
Chạy tất cả các kiểm tra cùng một lúc
Hình dạng triển khai
Điểm cuối tiêu thụ được phục vụ trên tên máy chủ mà bạn kiểm soát (ví dụ:ingest.your-company.example). cert-manager yêu cầu chứng chỉ TLS được tin cậy công khai từ Let’s Encrypt qua HTTP-01, vì vậy trạm thu thập sẽ xác minh chứng chỉ máy chủ so với kho tin cậy hệ thống, không cần ghim CA theo khách hàng.
Điểm cuối bảng điều khiển hoạt động theo cách tương tự: nó được phục vụ trên tên máy chủ thứ hai mà bạn kiểm soát (ví dụ: agenteye.your-company.example) chỉ đến bộ cân bằng tải Traefik bảng điều khiển, và cert-manager phát hành chứng chỉ Let’s Encrypt của nó qua bộ cân bằng tải đó. Các trình duyệt nhận được chứng chỉ được tin cậy mà không có cảnh báo.
Cấp phát và gia hạn chứng chỉ xác thực qua HTTP-01, vì vậy cả hai LoadBalancer phải có thể truy cập được từ Internet công khai trên cổng 80. Nếu bạn cần hạn chế IP cho bộ cân bằng tải bảng điều khiển, hãy phối hợp trình giải quyết DNS-01 với hỗ trợ trước — nếu không, việc gia hạn sẽ thất bại im lặng và chứng chỉ hết hạn.
Lấy các tệp kê khai
AGENTEYE_TOKEN của bạn.
Cấu trúc thư mục:
Giám sát sức khỏe (tùy chọn): bộ thăm dò sẵn sàng của máy chủ đã phản ánh sức khỏe Postgres + ClickHouse, và third-party/robusta/ thêm cảnh báo lỗi pod gốc Kubernetes tùy chọn cho Slack. Xem enterprise-docs/health-monitoring.md.
Giai đoạn 1 — Cơ sở hạ tầng bên thứ ba (~30 phút)
1.1 Cài đặt cert-manager
cert-manager quản lý chứng chỉ TLS cho HTTPS và CA riêng được sử dụng cho chứng chỉ khách hàng mTLS.Running — cert-manager, cert-manager-cainjector, cert-manager-webhook.
certificates.cert-manager.io, clusterissuers.cert-manager.io, issuers.cert-manager.io.
Nếu nó không thành công: Pod ở CrashLoopBackOff thường có nghĩa là CRD không được cài đặt. Chạy lại với --set crds.install=true. Nếu pod webhook không thành công trong kiểm tra sẵn sàng, chờ 30 giây và kiểm tra lại — chúng có thể mất một chút thời gian để khởi động.
1.2 Cài đặt Traefik — Bộ điều khiển tiêu thụ công khai
Thực thể Traefik này xử lý lưu lượng trạm thu thập trên LoadBalancer bên ngoài. Nó chấm dứt TLS và thực thi mTLS (xác minh chứng chỉ khách hàng) trên điểm cuối tiêu thụ.Running.
kubectl describe pod -n traefik-public <pod-name> để xem lỗi kéo hình ảnh hoặc ràng buộc tài nguyên.
1.3 Cài đặt Traefik — Bộ điều khiển bảng điều khiển
Thực thể Traefik này phục vụ bảng điều khiển trên LoadBalancer chuyên dụng, bị hạn chế bởi danh sách cho phép IP.Hai cơ chế danh sách cho phép được cung cấp cho thực thể này. Hướng dẫn này sử dụngTrước khi cài đặt, hãy chỉnh sửavalues-dashboard.yaml, giới hạn quyền truy cập bằng trườngservice.loadBalancerSourceRangesdi động. Mộtvalues-internal.yamlsong song cũng được cung cấp cho các môi trường AWS thích chú thíchservice.beta.kubernetes.io/aws-load-balancer-source-rangesthay thế. Chọn một và sử dụng nó một cách nhất quán; các bước dưới đây giả địnhvalues-dashboard.yaml.
third-party/traefik/values-dashboard.yaml để đặt các IP nguồn được phép. Trường loadBalancerSourceRanges kiểm soát IP nào có thể truy cập bảng điều khiển. Theo mặc định, nó được đặt thành 0.0.0.0/0 (tất cả IP); hạn chế nó thành VPN, văn phòng hoặc IP xuất hiện đã biết của bạn.
Danh sách cho phép một IP duy nhất
Danh sách cho phép nhiều IP
Thêm một mục trên mỗi IP hoặc khối CIDR. Hậu tố/32 khớp với một địa chỉ IPv4 duy nhất; một khối CIDR (ví dụ: /24) khớp với một phạm vi. Bạn có thể trộn các IP riêng lẻ và phạm vi tự do:
- Giữ một mục trên mỗi dòng và thêm một bình luận
#ngắn để xác định chủ sở hữu hoặc mục đích của mỗi IP; đây là những gì các nhà khai thác trong tương lai sử dụng để quyết định xem mục nhập còn cần thiết hay không. - Luôn sử dụng ký hiệu CIDR. Một IP trần như
203.0.113.10bị nhà cung cấp đám mây từ chối; hãy sử dụng203.0.113.10/32. - Đối với các phạm vi IPv6, hãy sử dụng CIDR tương đương
/128(địa chỉ duy nhất) hoặc lớn hơn, ví dụ:2001:db8::1/128. Không phải tất cả các nhà cung cấp đám mây đều hỗ trợ phạm vi nguồn IPv6; kiểm tra tài liệu LoadBalancer của nhà cung cấp của bạn. - Danh sách là HOẶC: lưu lượng được phép nếu nguồn khớp với bất kỳ mục nhập nào.
helm install dưới đây. Nếu bộ điều khiển đã được cài đặt, hãy chạy helm upgrade với các cờ tương tự hoặc vá Service lúc chạy (phần tiếp theo).
Cập nhật danh sách cho phép lúc chạy
Bạn có thể thay đổi các IP được phép mà không cần nâng cấp Helm bằng cách vá Service trực tiếp. Bản vá thay thế toàn bộ danh sách; luôn bao gồm mọi IP bạn muốn giữ, không chỉ cái mới. Để thay thế danh sách bằng một bộ IP mới:
Các bản vá lúc chạy không được giữ lại trong values-dashboard.yaml. Để giữ thay đổi trong các nâng cấp Helm trong tương lai, cũng cập nhật tệp giá trị và cam kết nó.
Sau đó, cài đặt:
Running.
1.4 Chờ LoadBalancer
Cả hai thực thể Traefik đều cần các IP bên ngoài trước khi tiếp tục.EXTERNAL-IP (không phải <pending>).
Nếu vẫn chưa giải quyết, hãy theo dõi phân công:
Ctrl+C sau khi IP xuất hiện. Phân công IP thường mất 2–5 phút.
Nếu nó không thành công: <pending> sau 10 phút thường có nghĩa là nhà cung cấp đám mây không thể cấp phát LoadBalancer. Kiểm tra: thẻ con nít (EKS yêu cầu kubernetes.io/role/elb), cấu hình VPC, hạn ngạch dịch vụ và chú thích LB nội bộ chính xác được đặt cho thực thể nội bộ.
Giai đoạn 2 — Tạo bí mật (~10 phút)
Tất cả các bí mật được tạo thủ công trước khi triển khai ứng dụng. Điều này đảm bảo các giá trị nhạy cảm không bao giờ xuất hiện trong các tệp kê khai.2.1 Tạo không gian tên
Active.
2.2 Bí mật kéo hình ảnh
Bí mật này xác thực vớighcr.io để kéo các hình ảnh vùng chứa AgentEye. Xem enterprise-docs/github-token.md để biết cách tạo PAT của bạn.
kubernetes.io/dockerconfigjson.
Kiểm tra nó (sâu) — xác minh mã thông báo có thể thực sự kéo hình ảnh không:
Sử dụng thẻ hình ảnh server được ghim trong kustomization.yaml của overlay của bạn (hiện đang v0.0.1-beta.48 trong cả lớp phủ acme được đóng gói và triển khai cơ sở). Thay thế thẻ bên dưới bằng thẻ bạn đang triển khai để kiểm tra này không trôi dạt qua các bản phát hành:
ok in trong nhật ký.
Nếu nó không thành công: ErrImagePull hoặc 401 Unauthorized có nghĩa là PAT không hợp lệ hoặc thiếu phạm vi read:packages. Kiểm tra lại enterprise-docs/github-token.md.
2.3 Thông tin đăng nhập PostgreSQL
Quan trọng: Chúng tôi sử dụng-hex(không phải-base64) để tạo mật khẩu. Đầu ra Base64 có thể chứa+,/và=khiến chuỗi kết nốiDATABASE_URLbị hỏng. Xem enterprise-docs/troubleshooting.md để biết chi tiết.
Lưu trữ POSTGRES_PASSWORD trong trình quản lý bí mật của bạn ngay lập tức. Bạn sẽ cần nó nếu bạn bao giờ khôi phục từ bản sao lưu hoặc kết nối trực tiếp với cơ sở dữ liệu.
Kiểm tra nó:
48 (24 byte hex = 48 ký tự).
2.4 Khóa API quản trị
Lưu trữ ADMIN_KEY trong trình quản lý bí mật của bạn ngay lập tức.
Kiểm tra nó:
2.5 Cấu hình xác thực (đăng nhập bảng điều khiển)
Bảng điều khiển sử dụng email + OTP cho đăng nhập người dùng. Nếu không có bí mật này, máy chủ vẫn khởi động và đường dẫn APIADMIN_KEY tiếp tục hoạt động, nhưng không có người dùng nào có thể đăng nhập thông qua UI.
Tất cả các khóa được tham chiếu là optional: true trong bản kê khai cơ sở, vì vậy các bí mật riêng phần (hoặc không có bí mật nào cả) là được; máy chủ quay lại các giá trị mặc định được ghi chép. Gói mọi thứ vào một bí mật agenteye-auth duy nhất giúp bề mặt xác thực có thể xoay trong một địa điểm.
| Khóa | Mục đích |
|---|---|
ADMIN_EMAIL | Người dùng quản trị bootstrap. Upserted ở mỗi lần khởi động với tất cả các quyền và được bảo vệ khỏi xóa/chỉnh sửa quyền thông qua bảng điều khiển. Nếu không có nó, không có quản trị viên nào được gieo và đăng nhập đầu tiên là không thể. |
ALLOWED_EMAILS | Danh sách cho phép được phân tách bằng dấu phẩy. Hỗ trợ địa chỉ chính xác (user@example.com) và ký tự đại diện miền (*@example.com). Nếu không có nó, không có người dùng nào có thể đăng nhập hoặc được tạo. |
SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, SMTP_FROM | Bộ chuyển tiếp SMTP để gửi mã OTP. Nếu SMTP_HOST không được đặt, các mã OTP sẽ được ghi vào stdout của máy chủ thay vì được gửi qua email (hữu ích cho các bài kiểm tra khởi động). Cung cấp tất cả các khóa SMTP cùng nhau để gửi email thực. |
SMTP_TLS | Một trong starttls (mặc định), tls hoặc none. |
DEFAULT_ORG_NAME, DEFAULT_ORG_SLUG | Tùy chọn. Đặt cho tổ chức default được xây dựng sẵn tên hiển thị thân thiện và slug URL để nó sống ở ví dụ /acme thay vì /default. Được áp dụng chỉ trên lần khởi động đầu tiên; khi bạn đổi tên tổ chức bằng agenteye-orgctl org rename (xem §7.6) những cái này bị bỏ qua. Slug phải là 1–40 chữ cái thường alphanumerics có gạch ngang nội bộ duy nhất. Để trống cả hai để giữ default chung chung. |
Lưu trữ thông tin xác thực SMTP trong trình quản lý bí mật của bạn.Kiểm tra nó:
2.6 Khóa cô lập tổ chức đa người thuê (tùy chọn)
Bỏ qua điều này đối với triển khai một người thuê; máy chủ chạy trên một tổ chức mặc định phát triển được xây dựng sẵn và phục vụ tổ chứcdefault duy nhất một cách tốt. Trước khi bạn tạo tổ chức thứ hai, hãy đặt một ORG_CH_SECRET mạnh, ổn định: mật khẩu ClickHouse của mỗi tổ chức được dẫn xuất dưới dạng HMAC(ORG_CH_SECRET, org_id), vì vậy mặc định phát triển được biết công khai sẽ mang lại thông tin xác thực theo tổ chức được dẫn xuất công khai. Lệnh agenteye-orgctl org create (xem §7.6 Cấp phát các tổ chức) từ chối chạy trong khi máy chủ vẫn ở mặc định phát triển được xây dựng sẵn.
secretKeyRef, vì vậy một cụm một người thuê không bao giờ tạo nó vẫn khởi động bình thường. Giữ giá trị ổn định và giống nhau trên tất cả các bản sao; quay nó vô hiệu hóa mật khẩu ClickHouse được dẫn xuất của mỗi tổ chức cho đến khi khởi động lại khỏi mục tiêu cấu hình lại các người dùng (một khởi động động với giá trị nhất quán ở khắp nơi chữa nó). Xem deploy/base/server/secret.example.yaml.
Lưu trữ ORG_CH_SECRET trong trình quản lý bí mật của bạn và đừng quay nó một cách tùy tiện.
2.7 Xác minh tất cả các bí mật
agenteye-admin-key, agenteye-auth, agenteye-image-pull, agenteye-postgres) phải có mặt trước khi tiếp tục. agenteye-org-ch-secret chỉ bắt buộc đối với triển khai đa người thuê (xem §2.6).
Giai đoạn 3 — Triển khai ứng dụng (~5 phút)
3.1 Cấu hình các tên máy chủ công khai
cert-manager cần các tên máy chủ tiêu thụ và bảng điều khiển trước khi nó có thể yêu cầu chứng chỉ Let’s Encrypt của họ. Sao chép mẫu và đặt cả hai:domain.env được gitignored; nó ở địa phương cho mỗi triển khai. Xây dựng kustomize không thành công ồn ào nếu khóa nào bị thiếu.
DNS phải phân giải trước tiên. Bạn không phải chỉ định DNS tại LB ngay bây giờ (chúng không tồn tại cho đến khi Giai đoạn 1.2 hoàn thành), nhưng cấp phát ACME ở bước 3.2 sẽ thử lại cho đến khi mỗi tên máy chủ phân giải thành LoadBalancer của nó. Bạn có thể đặt DNS ngay bây giờ (sử dụng tên máy chủ LB được nắm bắt trong Giai đoạn 1.4) hoặc tiếp tục và thêm các bản ghi trong Giai đoạn 4.
3.2 Áp dụng bản kê khai
Áp dụng cơ sở trực tiếp để cài đặt mới hoặc lớp phủ nếu bạn đã cắt một cho môi trường này (lớp phủ chỉ ghim các thẻ hình ảnh, biến env và giới hạn tài nguyên; chúng kế thừa chứng chỉ và định tuyến cơ sở):3.3 Chờ các pod
agent (trợ lý AI) và redis tùy chọn xuất hiện bên cạnh chúng; trợ lý ở vô hoạt cho đến khi bạn cung cấp điểm cuối LLM của nó (xem enterprise-docs/assistant.md), và Redis là bộ nhớ đệm tốt nhất, vì vậy không ai cần ở Sẵn sàng để nền tảng phục vụ lưu lượng truy cập.
Kiểm tra nó:
agent và redis tùy chọn cũng xuất hiện và đạt Running):
| Trạng thái Pod | Nguyên nhân có thể | Lệnh gỡ lỗi |
|---|---|---|
ImagePullBackOff | Bí mật kéo hình ảnh xấu hoặc PAT | kubectl describe pod <name> -n agenteye |
CrashLoopBackOff | Biến env xấu (ví dụ: DATABASE_URL) | kubectl logs <name> -n agenteye |
Pending | CPU/bộ nhớ không đủ hoặc không có nút | kubectl describe pod <name> -n agenteye (kiểm tra Sự kiện) |
3.4 Xác minh bộ lưu trữ
Bound:
| PVC | Dung lượng | Lưng |
|---|---|---|
postgres-data-postgres-0 | 50Gi | Kho lưu trữ quan hệ/siêu dữ liệu PostgreSQL |
clickhouse-data-clickhouse-0 | 100Gi | Kho lưu trữ phân tích sự kiện + đánh giá ClickHouse |
redis-data-redis-0 (1Gi) cũng xuất hiện cho bộ nhớ đệm tùy chọn.
Nếu nó không thành công: Pending có nghĩa là không có StorageClass nào có thể cấp phát khối lượng. Kiểm tra kubectl get storageclass và đảm bảo tồn tại một mặc định. Để sản xuất, lớp phủ khối lượng ClickHouse lên StorageClass SSD nhanh (ví dụ: gp3 trên AWS, pd-ssd trên GCP); thông lượng nén bị ảnh hưởng trên đĩa chậm.
3.5 Xác minh chứng chỉ
Ready: True:
| Tên | Công cộng | Mục đích |
|---|---|---|
mtls-ca | selfsigned | CA riêng để phát hành chứng chỉ máy khách mTLS (hiệu lực 10 năm) |
ingest-tls | letsencrypt-prod | Chứng chỉ TLS công khai cho điểm cuối tiêu thụ (90 ngày, tự động gia hạn) |
dashboard-tls | letsencrypt-prod | Chứng chỉ TLS công khai cho bảng điều khiển (90 ngày, tự động gia hạn) |
ingest-tls hoặc dashboard-tls không sẵn sàng:
kubectl describe certificate <name> -n agenteye và đọc Sự kiện. Các nguyên nhân phổ biến:
- DNS chưa chỉ đến LB. Let’s Encrypt phân giải tên máy chủ và nhấn cổng 80 để xác thực —
INGEST_DOMAINphải phân giải thành LB công khai,DASHBOARD_DOMAINthành LB bảng điều khiển. Cho đến khi CNAME/Alias lan rộng, đơn đặt hàng vẫnpending. Khi DNS đúng, cert-manager thử lại tự động (không cần xóa Chứng chỉ). - Tên máy chủ không được thay thế. Nếu
dnsNamesvẫn đọcINGEST_DOMAIN_PLACEHOLDER/DASHBOARD_DOMAIN_PLACEHOLDER, bạn đã bỏ qua bước 3.1 — tạobase/certificates/domain.envvà áp dụng lại. - Traefik bảng điều khiển không thể phục vụ thử thách (
dashboard-tlschỉ). Thực thể Traefik bảng điều khiển phải được cài đặt với tệp giá trị được đóng gói (Giai đoạn 1.2), điều này cho phép nhà cung cấp Ingress được xác định phạm vi phục vụ bộ giải quyết HTTP-01 của cert-manager. Một thực thể được cài đặt mà không có nó để thử thách không có tuyến đường và thứ tựpendingmãi mãi.
mtls-ca không sẵn sàng: cert-manager chính nó không khỏe. Kiểm tra lại các pod cert-manager từ bước 1.1.
3.6 Xác minh CronJob
| Tên | Lịch | Mục đích |
|---|---|---|
agenteye-backup | 0 3 * * * | Sao lưu Postgres + ClickHouse hàng ngày lúc 03:00 UTC |
cert-renewal-check | 0 3,15 * * * | Cảnh báo hết hạn chứng chỉ lúc 03:00 và 15:00 UTC |
3.7 Xác minh máy chủ khởi động chính xác
POSTGRES_PASSWORD chứa các ký tự không an toàn URL mà bảng DATABASE_URL. Xem enterprise-docs/troubleshooting.md.
3.8 Xác minh bảng điều khiển được kết nối với máy chủ
Ready trong đầu ra mà không có ECONNREFUSED hoặc các lỗi tương tự.
Nếu nó không thành công: Kiểm tra rằng Dịch vụ server tồn tại (kubectl get svc server -n agenteye) và AGENTEYE_SERVER_URL được đặt thành http://server:8080 trong triển khai bảng điều khiển.
Giai đoạn 4 — Quyền truy cập mạng (~5 phút)
4.1 Truy xuất địa chỉ LoadBalancer
Trên AWS EKS, LoadBalancer trả về tên máy chủ thay vì IP. Thay thếKiểm tra nó:.ipbằng.hostnametrong các lệnh trên.
4.2 Trỏ DNS tại LoadBalancer
Tạo bản ghi DNS để các tên máy chủ từbase/certificates/domain.env phân giải thành LoadBalancer của họ — INGEST_DOMAIN thành LB Traefik công khai, DASHBOARD_DOMAIN thành LB Traefik bảng điều khiển:
- AWS Route 53: Bản ghi
AcóAlias = Yes, mục tiêu = tên máy chủ LB. Đừng sử dụng A bình thường → IP; IP ELB xoay. - Bất kỳ nhà cung cấp nào khác:
CNAMEtừ tên máy chủ đến tên máy chủ LB.
$PUBLIC_IP và $INTERNAL_IP tương ứng (hoặc, trên EKS, phân giải thành cùng tên máy chủ *.elb.amazonaws.com).
Khi DNS phân giải, cert-manager hoàn thành các đơn đặt hàng ACME chưa hoàn thành từ Giai đoạn 3.5 trong vòng một phút. Chạy lại kubectl get certificates -n agenteye cho đến khi cả ingest-tls và dashboard-tls hiển thị Ready: True.
4.3 Tiếp cận điểm cuối tiêu thụ
Điểm cuối tiêu thụ công khai thực thi TLS lẫn nhau, vì vậy mỗi yêu cầu (bao gồm/health) phải trình bày chứng chỉ khách hàng. Bạn phát hành chứng chỉ khách hàng đầu tiên của bạn trong Giai đoạn 5; nếu bạn đã có cái, hãy xác minh khả năng truy cập ngay bây giờ:
{"status":"ok"}. Không cần -k — chứng chỉ máy chủ chuỗi đến CA công khai cho INGEST_DOMAIN, vì vậy nó xác thực so với kho tin cậy hệ thống. Tiếp cận điểm cuối tiêu thụ bằng tên máy chủ INGEST_DOMAIN của nó (khớp với chứng chỉ phát hành), không phải bởi IP/tên máy chủ LB thô.
Điểm cuối bảng điều khiển được phục vụ trên DASHBOARD_DOMAIN có chứng chỉ được tin cậy công khai và không phải mTLS, vì vậy không cần -k và không cần chứng chỉ khách hàng:
DASHBOARD_DOMAIN, vì vậy địa chỉ thô hiển thị sự không khớp về tên chứng chỉ.
Nếu nó không thành công: Nếu curl treo, kiểm tra rằng LB có thể truy cập được từ máy của bạn (VPN, nhóm bảo mật, quy tắc tường lửa). Lỗi bắt tay certificate required trên tên máy chủ tiêu thụ có nghĩa là không có chứng chỉ khách hàng được trình bày; hãy hoàn thành Giai đoạn 5 trước. Lỗi xác thực TLS trên tên máy chủ tiêu thụ có nghĩa là chứng chỉ máy chủ chưa hoàn thành phát hành; quay lại Giai đoạn 3.5 và giải quyết vấn đề ở đó.
Giai đoạn 5 — Phát hành chứng chỉ khách hàng mTLS (~10 phút trên cụm)
Trạm thu thập xác thực bằng hai yếu tố: chứng chỉ khách hàng (lớp vận tải, chứng minh yêu cầu đến từ một cụm được ủy quyền) và khóa API (lớp ứng dụng, chứng minh yêu cầu từ trạm thu thập có quyềnevents:add). Khóa rò rỉ vô dụng mà không có cert; cert bị đánh cắp vô dụng mà không có khóa hợp lệ.
5.1 Phát hành chứng chỉ
Mỗi cụm chạy trạm thu thập cần chứng chỉ khách hàng riêng của nó. Từ thư mục bản kê khai:<cluster-name> bằng một định danh có ý nghĩa (ví dụ: us-east-1-prod, staging).
Kiểm tra nó: Tập lệnh in ==> Done! và liệt kê các tệp đầu ra.
Ready: True.
Tệp đầu ra trong issued/<cluster-name>/:
| Tệp | Mục đích |
|---|---|
client.crt | Chứng chỉ khách hàng (hiệu lực 90 ngày) |
client.key | Khóa riêng máy khách |
ca.crt | Chứng chỉ CA để xác minh máy chủ |
collector-mtls-secret.yaml | Bí mật Kubernetes sẵn sàng áp dụng cho cụm trạm thu thập |
5.1b Phương tiện thay thế: AWS Secrets Manager
Nếu người tiêu dùng cert là một Pod Kubernetes cầnclient.crt và client.key trên đĩa — trường hợp điển hình khi bạn chạy trạm thu thập agenteye-collector dưới dạng sidecar trong pod ứng dụng của bạn — đẩy bó cert vào AWS Secrets Manager. Pod ứng dụng sau đó gắn nó qua Secrets Store CSI Driver với IRSA, và quay một vòng chứng chỉ hoàn toàn tự động.
PutSecretValue trên cùng một bí mật, vì vậy ARN và tên giữ ổn định. CSI Driver chọn phiên bản mới trên bộ xoay tiếp theo của nó và viết lại các tệp bên trong pod.
Điều kiện tiên quyết:
awsCLI v2 được xác thực cho tài khoản AWS của bạn.jqcài đặt.- Biến môi trường
AWS_REGIONđược đặt. - Quyền IAM trên danh tính người gọi của bạn (phạm vi
Resourcethànharn:aws:secretsmanager:<region>:<account>:secret:agenteye/mtls-client/*):secretsmanager:CreateSecretsecretsmanager:DescribeSecretsecretsmanager:PutSecretValuesecretsmanager:TagResource
| Bước | Hành động |
|---|---|
| 1 | Phát hành / tái trích xuất cert qua cert-manager (giống như chế độ mặc định). |
| 2 | Gọi DescribeSecret trên agenteye/mtls-client/<cluster-name> để quyết định tạo vs cập nhật. |
| 3 | Trên lần chạy đầu tiên: CreateSecret với tải trọng JSON ba khóa (client.crt, client.key, ca.crt), được gắn thẻ AgentEyeCluster=<cluster-name>. Trên các lần chạy tiếp theo: PutSecretValue để xuất bản phiên bản mới; thẻ làm mới qua TagResource. |
| 4 | Xóa issued/<cluster-name>/ chỉ sau khi tải lên thành công. Khi có lỗi, thư mục được bảo tồn để bạn thử lại. |
aws secretsmanager restore-secret --secret-id agenteye/mtls-client/<cluster-name> trước khi thử lại.
Để dây toàn bộ pod (SecretProviderClass, thiết lập IRSA, hành vi quay một vòng, gỡ lỗi) xem enterprise-docs/single-pod-deployment.md.
5.2 Xác minh chứng chỉ hoạt động
Kiểm tra chứng chỉ phát hành so với mTLS ingress:{"status":"ok"}
Nếu nó không thành công:
| Lỗi | Nguyên nhân | Khắc phục |
|---|---|---|
certificate required | Cert không được trình bày | Kiểm tra đường dẫn tệp trong lệnh curl |
bad certificate | Không khớp CA | Xác minh mtls-ca-issuer phát hành cert: kubectl describe certificate mtls-client-<name> -n agenteye |
connection refused | Tên máy chủ hoặc LB sai không có thể truy cập | Kiểm tra /etc/hosts hoặc DNS |
5.3 Gửi tới cụm trạm thu thập
Gửicollector-mtls-secret.yaml cho đội vận hành cụm trạm thu thập. Họ áp dụng nó:

