📘 תיעוד 106

מדריך עזר לסביבות באירוח עצמי

מדריך עזר מלא עבור ה-runner וה-orchestrator באירוח עצמי: דגלי CLI, משתני סביבה ומדדי Prometheus.

הערה: סביבות באירוח עצמי נמצאות בבטא ציבורית בתוכניות Team ו-Enterprise. משתמש בעל תפקיד Owner מפעיל אותן על ידי הדלקת Allow self-hosted environments בדף הניהול Cloud environments. דף זה הוא מדריך עזר לדגלים ולמדדים. ראה את המדריך המהיר להגדרה ואת פריסה לסביבת ייצור למתכוני פריסת צי השרתים.

דף זה הוא מדריך עזר לשני התהליכים שאתה מריץ בתוך סביבה באירוח עצמי: ה-runner, שמבצע הפעלות ענן של Claude Code על המארחים שלך, וה-orchestrator האופציונלי לקנה מידה אוטומטי, שמפעיל יחידות runner כאשר הפעלות ממתינות בתור. לכל אחד מהם יש טבלת דגלים משלו. שניהם רצים על מארחי Linux או macOS, כפי שמניחות ברירות המחדל כגון /workspace ו-~/.claude. הרץ claude self-hosted-runner --help לקבלת הרשימה המוסמכת עבור הגרסה המותקנת אצלך.

סדרות מדדים וכמה שדות API עדיין משתמשים ב-pool עבור מה שדפים אלה מכנים סביבה (environment), שני המונחים מציינים את אותו הדבר. מזהה הסביבה הוא השדה pool_id, במבנה ccpool_...: בכל מקום שבו דפים אלה מציגים מזהה pool, הוא מציין את הסביבה. דגלי CLI ומשתני סביבה מאייתים זאת environment, כגון --environment-secret-file. צורות האיות הישנות והמיושנות עם pool עדיין עובדות, כפי שמתואר בשורה של --environment-secret-file.

#דגלי CLI עבור ה-runner

למרבית הדגלים יש משתנה סביבה תואם. כאשר שניהם מוגדרים, הדגל מקבל קדימות. דגלי משך זמן מקבלים דקות או שניות ב-CLI, אך משתנה הסביבה המשויך תמיד מוגדר במילישניות, כפי שמציינת הסיומת _MS, ועמודת ברירת המחדל מציגה את יחידת המידה של הדגל: --exit-if-unused-min 10 שקול ל-SELF_HOSTED_RUNNER_IDLE_SHUTDOWN_MS=600000, וערך Helm כגון SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS: "15" פירושו 15 מילישניות, ולא ברירת המחדל של 15 דקות.

למרבית דגלי משך הזמן יש ערך מרבי, שנבחר כדי לשמור על כל פסק זמן בתוך תקרת הטיימר של 32 סיביות בזמן הריצה, שהיא כ-24.85 ימים. הדגלים מסוג --*-min מוגבלים לתקרה של 10080 דקות, שהן 7 ימים. הדגל --drain-grace-sec מוגבל ל-604800 שניות, גם כן 7 ימים, והדגל --drain-wait-sec מוגבל ל-86400 שניות, שהן 24 שעות. הדגלים --session-stop-grace-sec ו---post-session-hook-timeout-sec אינם מוגבלים. חריגה מהתקרה מתנהגת באופן שונה בכל ממשק:

• דגל: ההפעלה נכשלת עם שגיאה.
• משתנה סביבה: ה-runner מצמיד את הערך לתקרת הטיימר במקום לדחות אותו.

#דגלי CLI עבור ה-orchestrator

פקודת המשנה self-hosted-runner orchestrator, אשר מפעילה יחידות runner לפי דרישה, מקבלת את הדגלים --api-url, --environment-secret-file, --hooks-dir, --health-port ו---log-level עם אותן ברירות מחדל כמו ה-runner, ובמקומות שבהם לדגל של ה-runner יש משתנה סביבה, עם אותו משתנה סביבה, למעט הדגל --hooks-dir שהוא דגל חובה וחייב להכיל hook מסוג spawn-runner. היא מקבלת גם דגלים ייחודיים משלה:

#דגלי SCM connector

ה-orchestrator יכול להחזיק חיבור WebSocket קבוע למישור הבקרה (control plane) של Anthropic, כך שתהליכים מקדימים להפעלה המנוהלים בענן, כגון בורר המאגרים ומפענח הענפים או ההפניות, יוכלו לגשת לשרת GitHub Enterprise Server שניתן לניתוב רק מתוך הרשת הפנימית שלך. המחבר נשאר כבוי אלא אם תגדיר את --scm-connector-host.

המחבר מבצע אימות באמצעות סוד הסביבה הקיים של ה-orchestrator ומתחבר מחדש אוטומטית: עם השהיה מעריכית חוזרת (exponential backoff) בחיבור שנותק, או השהיה קבועה של 30 שניות כאשר מישור הבקרה סוגר את החיבור מכיוון שעותק משוכפל אחר של ה-orchestrator כבר מחזיק בו.

#הגדרות משתני סביבה בלבד

הגדרות runner אלה נקראות ממשתני הסביבה בלבד ומכסות התנהגות שמרבית הפריסות משאירות בערך ברירת המחדל:

#טלמטריה

תהליכי בן של הפעלות שולחים טלמטריה תפעולית ל-Anthropic אלא אם תכבה אותה. שום קוד או תוכן מאגר אינם נשלחים. הגדר את משתני הטלמטריה בתהליך ה-runner, ה-runner מחיל אותם מחדש לאחר החלת משתני סביבה שסופקו על ידי השרת, כך שהגדרת המפעיל מקבלת תמיד קדימות.

אמצעי בקרה אחד ייחודי לסביבות באירוח עצמי: CLAUDE_CODE_BYOC_ENABLE_DATADOG=1 בוחר להפעיל מדדים תפעוליים של Datadog, אשר כבויים כברירת מחדל בסביבות באירוח עצמי. אמצעי הבקרה הכלליים של טלמטריית Claude Code, שהם DISABLE_TELEMETRY, DO_NOT_TRACK, DISABLE_ERROR_REPORTING ו-CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, חלים על תהליכי הבן של ההפעלה כפי שמתועד ב-מדריך עזר למשתני סביבה. המשתנה DISABLE_GROWTHBOOK קשור אך שונה: הגדרת DISABLE_GROWTHBOOK=1 משביתה אחזור דגלי תכונות (feature flags), והטלמטריה נשארת פעילה אלא אם מוגדר גם DISABLE_TELEMETRY.

המשתנה CLAUDE_CODE_ENABLE_TELEMETRY אינו קשור: הוא מפעיל ייצוא OpenTelemetry לאספן (collector) משלך, כפי שמתואר בסעיף ניטור, ואינו שולט בניתוחי הנתונים של Anthropic.

#נקודת קצה לבדיקת תקינות (Health endpoint)

ה-runner מגיש את GET /healthz ביציאת הבריאות שהוגדרה. התגובה היא 200 OK בכל זמן שהתהליך פועל, ללא קשר למצב שבו נמצאת לולאת הדגימה (poll loop), כך שבדיקת HTTP (probe) בנקודת קצה זו מזהה תהליך מת בלבד. גוף ה-JSON מתאר את המצב הנוכחי:

{
  "status": "ok",
  "runner_id": "ccrunner_...",
  "active_sessions": 2,
  "last_poll_at": "2026-03-31T18:04:11.220Z",
  "last_poll_age_ms": 842
}

השתמש ב-last_poll_age_ms כאות חיות בבדיקות מותאמות אישית, ערך שגדל ללא הגבלה מצביע על כך שלולאת הדגימה תקועה. גם last_poll_at וגם last_poll_age_ms הם null עד להשלמת הדגימה הראשונה.

ה-orchestrator מגיש נקודת קצה /healthz משלו ביציאת הבריאות שלו. נקודת הקצה שלו מחזירה תמיד 200, והגוף מכיל שדה connected המדווח האם הדגימה האחרונה הצליחה, בתוספת ספירת תור יצירה לפי מצב בתוך queue_counts. בצע התניית מוכנות (readiness) והתראות על פי connected ולא על פי קוד המצב.

כאשר SCM connector מוגדר, גוף ה-/healthz של ה-orchestrator מכיל גם את scm_connector_connected ואובייקט scm_connector עם connected, last_connected_at, last_error, reconnects ו-requests_forwarded. שני השדות הם null כאשר --scm-connector-host אינו מוגדר.

#מדדי Prometheus

כל runner מגיש מדדי Prometheus ב-GET /metrics באותה יציאה של /healthz. סדרות עיקריות:

ה-orchestrator מגיש סדרות משלו ב-GET /metrics באותה יציאה של ה-/healthz שלו:

לצורך קנה מידה אוטומטי (autoscaling), בחר את הסדרה המתאימה לסגנון שינוי הגודל שלך והתנה אותה לפני שהיא מזינה את מנגנון ה-scaler:

• קנה מידה לפי עומק תור (Queue-depth scaling): הזן את claude_code_self_hosted_orchestrator_pool_pending_sessions לתוך ה-scaler של HPA או KEDA שלך, ולא את queue_pending_sessions.
• קנה מידה לפי קיבולת (Capacity scaling): שנה קנה מידה לפי היחס בין active_sessions של ה-runner לבין capacity.
• התניה על connected: סנן את השאילתה עם claude_code_self_hosted_orchestrator_connected == 1 לכל מופע, כך שערך ישן של עותק משוכפל מנותק לא יזין את ה-scaler.

במהלך השבתת דגימה מלאה, שבה כל העותקים המשוכפלים מנותקים, השאילתה המותנית אינה מחזירה נתונים. מנגנון HPA שומר על מספר העותקים הנוכחי במקרה של מדד חסר, אך ה-scaler של KEDA עבור Prometheus בערך ברירת המחדל שלו ignoreNullValues: "true" קורא את התוצאה הריקה כאפס ומבצע הקטנת כמות עותקים (scale in). הגדר ignoreNullValues: "false" ב-ScaledObject, באופן אופציונלי עם רצפת עותקים משוכפלים מסוג fallback.

ה-PodMonitor הבא של Prometheus Operator מכסה את שני התהליכים. הוא בוחר pods לפי התווית app.kubernetes.io/part-of: claude-code-self-hosted-runner ויציאת ה-health בעלת השם שמוגדרת על ידי המתכון ל-Kubernetes. התאם את מרחבי השמות (namespaces) לפריסה שלך:

# Example Prometheus Operator PodMonitor for the Claude Code self-hosted
# runner + orchestrator. Adjust the namespace and label selectors to match
# your deployment. Both the runner and the orchestrator serve /metrics on
# their --health-port (default 8080).
apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: claude-code-self-hosted-runner
  namespace: monitoring
spec:
  namespaceSelector:
    matchNames:
      - claude-runners
  selector:
    matchExpressions:
      
# Matches the runner Deployment from the Kubernetes recipe, plus any
      
# on-demand runner Jobs and orchestrator pods you label the same way
      
# and give a named 'health' containerPort.
      - key: app.kubernetes.io/part-of
        operator: In
        values: [claude-code-self-hosted-runner]
  podMetricsEndpoints:
    - port: health
      path: /metrics
      interval: 30s

כללי התראה לדוגמה אלה מהווים נקודת התחלה. כוונן את הספים עבור גודל צי השרתים שלך:

# Example Prometheus alert rules for the Claude Code self-hosted runner
# + orchestrator. Tune thresholds for your fleet size and SLOs.
groups:
  - name: claude-code-self-hosted-runner
    rules:
      - alert: ClaudeRunnerPollStale
        expr: claude_code_self_hosted_runner_last_poll_age_seconds > 60
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "Runner {{ $labels.pod }} has not polled in >60s"
      - alert: ClaudeRunnerVersionDrift
        expr: count(count by (version) (claude_code_self_hosted_runner_info)) > 1
        for: 30m
        labels: {severity: info}
        annotations:
          summary: "Runners are running mixed versions"
      - alert: ClaudeRunnerInitErrorsHigh
        expr: increase(claude_code_self_hosted_runner_session_init_errors_total[10m]) > 3
        for: 5m
        labels: {severity: warning}
        annotations:
          summary: "Runner {{ $labels.pod }}: >3 session init failures in 10m (checkout hook / git / token / pre-init crash)"
      - alert: ClaudeRunnerPollErrors
        expr: sum by (pod) (rate(claude_code_self_hosted_runner_poll_errors_total[5m])) > 0
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "Runner {{ $labels.pod }}: PollWork failing ({{ $value | humanize }}/s over 5m)"
      - alert: ClaudeRunnerSessionStartHookErrors
        expr: increase(claude_code_self_hosted_runner_session_start_hook_errors_total[10m]) > 3
        for: 5m
        labels: {severity: warning}
        annotations:
          summary: "Runner {{ $labels.pod }}: >3 SessionStart hook failures in 10m"

  - name: claude-code-self-hosted-orchestrator
    rules:
      - alert: ClaudeOrchestratorDisconnected
        expr: claude_code_self_hosted_orchestrator_connected == 0
        for: 2m
        labels: {severity: critical}
        annotations:
          summary: "Orchestrator {{ $labels.pod }} cannot reach the Anthropic control plane"
      - alert: ClaudeOrchestratorPollStale
        expr: claude_code_self_hosted_orchestrator_last_poll_age_seconds > 90
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "Orchestrator {{ $labels.pod }} has not polled in >90s (poll loop waits on hook execution)"
      - alert: ClaudeOrchestratorCircuitBroken
        expr: claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions > 0
        for: 1m
        labels: {severity: critical}
        annotations:
          summary: "{{ $value }} sessions circuit-broken: spawn-runner hook is repeatedly non-retryable; fix infra then retry from the Activity tab"
      - alert: ClaudeOrchestratorPollErrors
        expr: sum by (pod) (rate(claude_code_self_hosted_orchestrator_poll_errors_total[5m])) > 0
        for: 2m
        labels: {severity: warning}
        annotations:
          summary: "Orchestrator {{ $labels.pod }}: PollSpawnHints failing ({{ $value | humanize }}/s over 5m)"
      - alert: ClaudeOrchestratorSpawnHookFailing
        expr: sum by (pod) (increase(claude_code_self_hosted_orchestrator_spawn_hooks_total{result!="ok"}[5m])) > 3
        for: 5m
        labels: {severity: warning}
        annotations:
          summary: "Orchestrator {{ $labels.pod }}: >3 spawn-runner hook failures in 5m"

#העברת מדדים מתהליכי בן של הפעלה

כל הפעלה רצה בתהליך בן משלה עם מדדי OpenTelemetry משלה. כאשר ערך --capacity גדול מאחד, ה-runner משכתב את האופן שבו מדדי תהליכי הבן האלה נחשפים. הגדרת OTEL_METRICS_EXPORTER=prometheus במארח ה-runner ו-CLAUDE_CODE_ENABLE_TELEMETRY=1 בסביבת ההפעלה, למשל מתוך סקריפט המעטפת שלך או מסביבת ה-runner עצמו, שההפעלות יורשות, חושפת מחדש את מכשירי המדידה מסוג מונה ומד של כל תהליך בן בנקודת הקצה /metrics של ה-runner עצמו, לצד הסדרות של ה-runner. ה-runner משכתב את ה-exporter של תהליך הבן כדי לדחוף נתונים באמצעות OTLP למקבל של loopback בלבד ביציאת הבריאות, מתייג כל סדרה עם תוויות session_id ו-client_platform, ומסיר את הסדרות של הפעלה כאשר אותה הפעלה מסתיימת. היסטוגרמות אינן מועברות, ומדד של תהליך בן ששמו מתנגש עם הקידומת של ה-runner עצמו מושמט.

בברירת המחדל של --capacity 1, השכתוב אינו חל: תהליך הבן של ההפעלה מאזין בנקודת קצה של Prometheus משלו ביציאה 9464 כרגיל.

#סמנטיקה של מוני מחזור חיי הפעלה

המונים sessions_started_total, sessions_completed_total, sessions_failed_total ו-sessions_interrupted_total מסווגים כל הפעלה לפי האופן שבו היא הסתיימה. כל תהליך בן של הפעלה שנוצר מקדם את sessions_started_total באחד בעת היצירה, ובדיוק אחד משלושת המונים האחרים מקודם באחד בעת היציאה, כך ש-sessions_started_total פחות סכום שלושת האחרים שווה למספר תהליכי הבן של הפעלות שרצים כעת.

• completed: ההפעלה הסתיימה בצורה נקייה. זה כולל יציאה עצמאית של תהליך הבן עם קוד 0, העברת ההפעלה לארכיון או מחיקתה בעת שתהליך הבן עדיין היה מחובר, ושחרור המשבצת על ידי ה-runner כהעברה נקייה: שחרור עקב חוסר פעילות, פסק זמן של אתחול, או ביטול הקצאה (deassign) בצד השרת שלולאת הדגימה זיהתה לפני שתהליך הבן יצא. מקדם את sessions_completed_total.
• failed: תהליך הבן יצא בעצמו עם קוד שאינו אפס, בין אם עקב קריסה או כשל הגדרה לאחר היצירה. מקדם את sessions_failed_total.
• interrupted: ה-runner סיים את תהליך הבן מסיבה תפעולית שאינה הצלחה של ההפעלה ואינה תקלה של ה-runner, כגון ריקון (drain) או מנגנון השמירה על משך חיים מרבי --kill-session-after-min. הפעלה מחדש מדורגת ב-Kubernetes השולחת SIGTERM היא דוגמה אחת לריקון. מקדם את sessions_interrupted_total.

המשתנה CLAUDE_RUNNER_EXIT_REASON של ה-hook מסוג post-session אינו משתמש בסיווג זה עבור העברות נקיות. ה-hook מדווח על שחרור עקב חוסר פעילות, פסק זמן של אתחול, וביטול הקצאה בצד השרת כ-interrupted, מכיוון שמנקודת מבטו של ה-hook ה-runner הרג את תהליך הבן, בעוד שהמונים לעיל מתעדים את אותם אירועים כ-completed, מכיוון ששום דבר לא השתבש והמשבצת הוחזרה בצורה נקייה. אם תתאים קבלות מ-hook מול sessions_completed_total ישירות, תספור פחות סיומים מהמצב בפועל. השתמש ב-hook עבור ערבויות ברמת ההפעלה הבודדת ובמונים עבור שיעורים מצטברים.

בסביבת ריצה בודדת (one-shot), שבה מוגדר --capacity 1 עם ברירת המחדל --drain-grace-sec 0, כל תהליך runner יוצא רגעים ספורים לאחר סיום ההפעלה היחידה שלו. המונים sessions_completed_total, sessions_failed_total ו-sessions_interrupted_total מתקדמים רק בסיום ההפעלה, ממש לפני אותה יציאה, כך שאיסוף של Prometheus כל 15 עד 60 שניות תופס רק לעיתים רחוקות את הקידום לפני שהסדרה של ה-runner נעלמת. שלושת מוני סיום ההפעלה הללו הם המונים הסופיים שיתר סעיף זה מתייחס אליהם. המונה sessions_started_total מתקדם בעת יצירת התהליך ונשאר גלוי למשך כל חיי ההפעלה, כך שהוא מופיע באופן מהימן, אך בסביבת ריצה בודדת משמעותו קרובה יותר ל"הפעלות שרצות כעת" מאשר לספירה מצטברת.

השתמש בסדרות בטבלה זו עבור היעד המתאים במקום במונים הסופיים:

השורות orchestrator_* קיימות רק בסביבות המריצות את ה-orchestrator לפי דרישה. בצי שרתים קבוע שבו יחידות ה-runner שורדות מעבר להפעלות שלהן, עם --drain-grace-sec גדול מ-0, השתמש ב-sum(rate(claude_code_self_hosted_runner_sessions_started_total[5m])) עבור תפוקה. בצי שרתים של ריצה בודדת, לסדרה זו יש אותה בעיית חלון איסוף כמו למונים הסופיים, לכן הסתמך על ספירת ההפעלות שבתור במקום זאת. בדוק עומס ממתין בכרטיסיית Activity של הסביבה, בדף הניהול Cloud environments: יחידות ה-runner אינן מייצאות סדרה של עומק תור.

לדיווח תוצאות ברמת ההפעלה הבודדת, השתמש ב-hook מסוג post-session במקום זאת: הוא מופעל בכל סיום הפעלה שבה נוצר תהליך בן, למעט סיום פתאומי של ה-runner כגון הפקעת מכונה וירטואלית (VM preemption), בהתאם לחוזה של ה-hook עצמו.

#מה הלאה

• סביבות באירוח עצמי: מודל הסביבה, ה-runner וההפעלה, המדריך המהיר ו-פריסה לסביבת ייצור כוללים הגדרה ותפעול
• התאמה אישית של הפעלות: סקריפטים של מעטפת, סקריפטים של מחזור חיים ויחידות runner לפי דרישה
• אימות זהות ההפעלה: אסימון ההפעלה, הטענות שלו וכיצד לאמת אותו