emptyDir event spool עובד בכל התפוצה של Kubernetes. רק הנתיב של העברת תעודה במדריך זה (AWS Secrets Manager + Secrets Store CSI Driver + IRSA) ספציפי ל-AWS / EKS. אם אתה פועל במקום אחר, שמור על עיצוב ה-pod וה-spool והחלף את מנגנון ה-secret-mount של הפלטפורמה שלך עבור Phases 2 ו-3.
מתי להשתמש בתבנית זו. בחר single-pod כאשר היישום שלך לא צריך להתקשר על פני גבול רשת כדי להגיע ל-collector (IPC בתוך pod בעל latency נמוך, חיבור חיים הדוק, בידוד pod לכל דייר). עבור צי מולטי-אפליקציה החולק collector אחד לכל node או לכל cluster, ראה enterprise-docs/kubernetes-deployment.md במקום זאת.
בהצצה
- אירועים (בתוך pod): ה-SDK של היישום שלך כותב קובצי
.jsonlל-emptyDirהמשותף ב-$AGENTEYE_HOME/events/; ה-collector sweeper קוראה אותם ומעלה. אין localhost port, אין loopback, pure shared-filesystem handoff. - תעודת mTLS (pod ← cloud): ה-Secrets Store CSI Driver מעלה את חבילת התעודה מ-Secrets Manager לתוך נפח read-only ב-
/etc/agenteye/tls/, מתוחם ל-collector container.
| צד | אחריות |
|---|---|
| Exosphere | מנפיק את תעודת הלקוח של mTLS ומעביר את החבילה לתוך חשבון AWS שלך ב-Secrets Manager תחת שם יציב. מפרסם מחדש את החבילה המחודשת לאותו secret לפני תוקף. |
| אתה | התקן את ה-Secrets Store CSI Driver, תן ל-ServiceAccount של ה-pod גישת read ל-secret דרך IRSA, והחל את manifest של ה-Pod. זהו. |
דרישות קדם
בחשבון AWS / EKS cluster שלך
-
EKS cluster עם OIDC provider משויך. אשר עם:
אם הפקודה מחזירה URL של
https://oidc.eks.…, OIDC מופעל. אם לא, שייך אחד: - Secrets Store CSI Driver ו-AWS provider מותקנים ב-cluster (ראה § Phase 2).
-
AWS CLI v2 ו-
kubectlעל תחנת העבודה שלך.
תיאום עם Exosphere
לפני שאתה פורס, Exosphere מעביר את חבילת mTLS client לתוך Secrets Manager של חשבון AWS שלך ומספק:- שם ה-secret (כנס:
agenteye/mtls-client/<your-cluster>) - אזור AWS שה-secret נמצא בו
- URL בקצה AgentEye לתצורת ה-collector
- API key של ה-collector שלך (ראה enterprise-docs/api-keys.md)
Phase 1: מה Exosphere מעביר
אתה לא יוצר את תעודת הלקוח של mTLS בעצמך. Exosphere מנפיקה אותה ומעביר את החבילה ישירות לתוך Secrets Manager של חשבון AWS שלך, כך שחומר הרשאות היחיד שכל פעם נוחת בסביבה שלך הוא ה-secret המוגמר, מוכן להעלאה. מה מגיע לחשבון שלך:| רכוש | ערך |
|---|---|
| שם Secret | agenteye/mtls-client/<cluster-name> (יציב על פני חידושים) |
| אזור | אזור AWS שציינת עבור ה-EKS cluster שלך |
| Payload | secret JSON יחיד עם שלושה מפתחות (client.crt, client.key, ו-ca.crt), כל אחד מחזיק את חומר המקודד PEM |
| תג | AgentEyeCluster=<cluster-name> |
SecretProviderClass ו-IAM policy שלך ממשיכים לעבוד ללא שינוי. עבור מחזור חיי התעודה (תוקף, קצב חידוש, התרעות תוקף) ראה enterprise-docs/kubernetes-deployment.md.
Phase 2: התקן את Secrets Store CSI Driver + AWS provider
דלג על צעד זה אם אתה כבר מריץ עומס עבודה אחר המעלה AWS secrets דרך CSI.Running עבור כל pod.
למה rotationPollInterval=1h? כאשר Exosphere מפרסם תעודה מחודשת, Secrets Manager מעודכן במקום. ה-CSI Driver קורא את ה-secret במרווח זה ויכתב מחדש את הקבצים המעלים. ה-collector קורא את קבצי התעודה פעם אחת בעת ההתחלה, כך שהוא מתחיל להציג את התעודה המחודשת רק לאחר restart של התהליך; ראה § Certificate rotation לאופן הגרימה של אחד.
Phase 3: תן ל-pod גישת read ל-secret (IRSA)
3.1 צור את IAM policy
שמור כ-agenteye-mtls-reader-policy.json:
<region>, <account-id>, ו-<cluster-name>. סיומת ה--* משוררת משדוג תו אקראי שש-תווים AWS מוסיף לכל ARN secret.
צור את ה-policy:
3.2 צור את IAM role וקשור אותו ל-ServiceAccount של ה-pod
ServiceAccount בשם agenteye-pod עם האנוטציה eks.amazonaws.com/role-arn המצביעה לתפקיד החדש.
3.3 הרשאות IAM נדרשות: סיכום
| הרשאה | טווח | למה |
|---|---|---|
secretsmanager:GetSecretValue | arn:aws:secretsmanager:<region>:<acct>:secret:agenteye/mtls-client/<cluster>-* | CSI Driver קורא את חבילת ההסמכה בכל mount + rotation tick. |
secretsmanager:DescribeSecret | זהה | CSI Driver קוראה DescribeSecret לגילוי שינויי גרסה בין polls. |
secretsmanager:PutSecretValue, secretsmanager:UpdateSecret, או secretsmanager:DeleteSecret ל-pod. ה-pod רק קורא את ה-secret; כתיבת גרסיות חדשות אליו מטופלת על ידי Exosphere כאשר התעודה מונפקת או מחודשת.
אם ה-secret מוצפן עם customer-managed KMS key (לא הדיפולט aws/secretsmanager key), גם תן:
Phase 4: פרוס את ה-Pod
4.1 SecretProviderClass
agenteye-mtls-spc.yaml:
jmesPath אומר ל-AWS provider לפצל את ה-JSON secret לשלושה קבצים נפרדים על דיסק. הציטוט ב-'"client.crt"' נדרש כי JMESPath מטפל בנקודה כ-sub-expression operator.
4.2 Pod / Deployment manifest
איך שני containers מדברים זה לזה. ה-AgentEye SDK וה-collector לא מתקשרים על פני network socket; אין local HTTP port. ה-SDK כותב batch אירועים כקבצי.jsonl לתוך $AGENTEYE_HOME/events/, וה-collector ממשיך לצפות בתיקייה זו ומעלה כל קובץ. עבור sidecar pod זה אומר:
- שני containers מעלים את אותו
emptyDirvolume ב-אותו path. - שני containers קובעים
AGENTEYE_HOMEלאותו path. - תמונת היישום שלך חייבת להיות ב-AgentEye SDK מותקן ומוגדר (ראה enterprise-docs/python-sdk.md).
כאשרAGENTEYE_HOMEלא מוגדר, גם SDK וגם collector מכריזים כברירת מחדל על~/.agenteye, ולשני containers יש בתי דירה שונים, כך שהם היו נוחתים על שתי spools נפרדות וה-handoff היה שקט נכשל. קבעAGENTEYE_HOMEלאותו explicit path ב-שני containers. §4.3 verification והשורה Troubleshooting המתאימה תופסות זה אם זה מוחמץ.
agenteye-pod.yaml (Deployment עם replicas אחד, scale כנדרש):
agenteye-collector-api-key Secret מחזיק את API key של ה-collector (ראה enterprise-docs/api-keys.md לספקת).
החל:
4.3 אשר
client.crt, client.key, ca.crt כולם נוכחים וקריאה בלבד, בבעלות משתמש ה-container.
אשר ש-shared event spool גלוי לשני containers:
AGENTEYE_HOME שונה); ראה § Troubleshooting.
בדיקת smoke end-to-end:
Done: N/N uploaded, 0 failed.. אם ה-spool ריק הוא מדפיס No pending files. ויוצא ללא אימות כלום — אז הרץ זאת רק לאחר שהיישום שלך flush לפחות אירוע אחד.
שימו לב ש-flush יוצא non-zero רק עבור setup faults מקומי: תצורה חסרה (לא URL/key resolved) או קובץ TLS cert לא קריא/unparseable (בדוק § Troubleshooting). API key לא נכון אינו משנה את קוד ה-exit — ההעלאה מקבלת 401, הקובץ מועבר ל-failed/, והפקודה עדיין מדפיסה [FAILED] … לכל קובץ בתוספת Done: 0/N uploaded, N failed. ויוצאת 0. כדי לגלות bad key או הורדת rejected, קרא את Done:/[FAILED] output או בדוק עבור קבצים נוחתים ב-$AGENTEYE_HOME/failed/, לא קוד ה-exit.
Certificate rotation
תעודת הלקוח תקף 90 ימים ומחודשת אוטומטית בערך 15 ימים לפני תוקף; Exosphere מפרסמת את הצרור המחודש באותו Secrets Manager secret. משם, הזרימה בתוך pod היא:-
ה-secret של Secrets Manager מקבל גרסה
AWSCURRENTחדשה. ARN ושם לא משתנים. -
תוך
rotationPollInterval(1 שעה כברירת מחדל; ראה § Phase 2), ה-CSI Driver קורא את הגרסה החדשה ויכתב קבצים תחת/etc/agenteye/tls/. -
ה-collector עוגן קבצי תעודה פעם אחת בעת ההתחלה, כך שהוא ממשיך להציג את התעודה הקודמת עד שהתהליך מתחדש. כדי לעבור לחומר המחודש, הפעל מחדש את ה-collector; rolling restart מספיק:
כדי להפוך זאת לאוטומטית, הוסף sidecar שצופה ב-
/etc/agenteye/tls/(לדוגמה עםinotifywait) ובהפעלת ה-rollout כאשר הקבצים משתנים.
Troubleshooting
| תסריט | סיבה סבירה | תיקיה |
|---|---|---|
Pod תקוע ב-ContainerCreating, אירועים מראים MountVolume.SetUp failed for volume "agenteye-mtls" | CSI provider לא יכול להגיע ל-Secrets Manager | בדוק IRSA קשור כראוי: kubectl describe sa agenteye-pod -n <ns> מראה את האנוטציה eks.amazonaws.com/role-arn. בדוק CloudTrail עבור AssumeRole call. |
Error: AccessDeniedException: not authorized to perform secretsmanager:GetSecretValue | IAM policy מתוחם ל-ARN לא נכון | סיומת ARN secret אקראית; השתמש ב-agenteye/mtls-client/<cluster>-* עם wildcard, לא ב-ARN מדויק. |
Error: ParameterNotFound מ-AWS provider | misMatch שם secret בין SecretProviderClass.objects[].objectName לבין ה-secret Exosphere מעביר | אשר את השם המדויק עם aws secretsmanager list-secrets --filters Key=tag-key,Values=AgentEyeCluster. |
jmesPath error, רק קובץ אחד מעלה | JMESPath syntax | הנקודות במפתחות JSON דורשות double-quoting: '"client.crt"', לא client.crt. |
Collector logs tls: bad certificate אחרי renewal | ה-CSI Driver עדיין לא עברנו על הגרסה החדשה, או ה-collector עדיין פועל עם התעודה הקודמת שהוא העל בהתחלה | אשר את הקבצים המעלים עדכנו (ls -l /etc/agenteye/tls/), ואז הפעל מחדש את ה-collector לטעינה: kubectl rollout restart deploy/my-app-with-collector -n <ns>. ראה § Certificate rotation. |
Collector container crashloops עם no such file or directory: /etc/agenteye/tls/client.crt | נפח עדיין לא מוסי בהתחלה ראשונה; startup probe חזק מדי | הוסף עיכוב ראשוני קטן או השתמש ב-init container שמחכה לקובץ להתקיים: until [ -f /etc/agenteye/tls/client.crt ]; do sleep 1; done. |
CSI Driver pod OOMKilled | דיפולט memory limits נמוך מדי עבור clusters עם הרבה SecretProviderClasses | בום --set linux.resources.limits.memory=200Mi בהתקנה של Helm. |
יישום פועל בנקיון, agenteye-collector flush דוחה No pending files., אך לוח המחוונים AgentEye שלך מראה אירועים | האפליקציה וה-collector לא חולקים את ה-event spool | בדוק ש (א) שני containers מעלים את אותו agenteye-spool emptyDir באותו path, ו (ב) שניהם קובעים AGENTEYE_HOME לאותו path. הרץ את שתי בדיקות ls /var/lib/agenteye/ מ-§ 4.3; הרשימות חייבות להתאים. |
התייחסות: קבצים על דיסק בתוך pod
ל-pod יש שני נתיבי נתונים על דיסק:חבילת תעודת mTLS: /etc/agenteye/tls/ (CSI, read-only, collector רק)
עלוי על ידי Secrets Store CSI Driver מ-AWS Secrets Manager.
| קובץ | תוכן | בשימוש על ידי collector כמו |
|---|---|---|
client.crt | PEM-encoded client certificate | AGENTEYE_TLS_CERT |
client.key | PEM-encoded private key | AGENTEYE_TLS_KEY |
ca.crt | PEM-encoded CA cert | AGENTEYE_TLS_CA (optional, רק כאשר ה-AgentEye server cert אינו publicly-trusted) |
Event spool: $AGENTEYE_HOME/ (emptyDir, shared read-write בין שני containers)
משותף דרך emptyDir volume בשם agenteye-spool.
| Path | כתוב על ידי | קרוא על ידי | מטרה |
|---|---|---|---|
$AGENTEYE_HOME/events/*.jsonl | יישום (AgentEye SDK) | Collector sweeper | Event batches ה-SDK flush, מחכה להעלאה. |
$AGENTEYE_HOME/failed/ | Collector (בהעלאה כישלון) | אתה (כאשר debugger) | JSONL קבצים ה-collector לא יכול להעלות לאחר retries. |
$AGENTEYE_HOME/config.json | אתה (optional) | Collector | Optional collector קובץ תצורה (חלופה לאנציקלופדיה vars). |
events/ ו-failed/ auto-created על ידי ה-collector בעת ההתחלה; לא initContainer צריך.
קשור docs
- enterprise-docs/collector-installation.md: אפשרויות collector binary, mTLS config reference, daemon modes.
- enterprise-docs/kubernetes-deployment.md: multi-pod deployment, cert issuance internals, lifecycle and expiry alerts.
- enterprise-docs/api-keys.md: provisioning ה-collector API key consumed על ידי ה-pod.
- enterprise-docs/troubleshooting.md: cluster-wide troubleshooting index.

