דלגו לתוכן

הגדרת סביבות

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

מנהל סביבת העבודה כותב הגדרה פעם אחת. לאחר מכן חברים לוחצים על התחל באזור סביבה בסרגל הצד של מרחב או PR. ההגדרות נשמרות במסד הנתונים של סביבת העבודה, ולכן ענף פיצ’ר אף פעם לא משנה את מה ש-Control Center מריץ, אף שהכלים עדיין מריצים את הקוד של אותו ענף.

  1. פתחו את הגדרות → סביבת עבודה → סביבות. רק מנהלי סביבת העבודה יכולים לשנות הגדרות, ורק בעל השרת יכול לשמור הגדרה שרצה על מארח השרת (ראו מי יכול לשמור מה).
  2. לחצו על הגדרה חדשה, ואז על הגדרה ריקה או טיוטה ממאגר. טיוטה סורקת את המאגר בחיפוש אחר קובצי compose, קובץ Procfile וסקריפטים של package.json, ואתם בודקים את התוצאה.
  3. מלאו את הטופס, או השתמשו בלשונית JSON. הדוגמאות בעמוד זה הן אותו JSON.
  4. לחצו על הרצת בדיקה. הפעולה מפעילה סביבה חד-פעמית, ממתינה עד שתהיה מוכנה ומשמידה אותה.

בשמירה, ההגדרה נבדקת בקפדנות. שדה לא מוכר, ערך מסוג שגוי או בחירה שנכתבה באיות שגוי נדחים, עם הנתיב שלהם והשם התקף הקרוב ביותר, כמו repos.app.requird: Unknown field. Did you mean "required"?. מותר $schema ברמה העליונה.

כדי לשמור הגדרה במאגר, השתמשו ב-קישור קובץ ממאגר. Control Center קורא את הקובץ רק מענף ברירת המחדל ומריץ רק את הגרסה שאושרה: על ידי מנהל סביבת עבודה, או על ידי בעל השרת כשההגדרה רצה על המארח. גרסה חדשה יותר מציגה יש עדכון זמין ולא משנה דבר עד שתאושר.

הגדרת סביבה יכולה להריץ פקודות על מארח השרת, בתור המשתמש של השרת עצמו. זו החלטה של בעל השרת, לא של תפקיד בסביבת העבודה:

  • הגדרה רצה על המארח כשיש לה מיקום על המארח, בדיקה שמריצה פקודה, או משימה מסוג provision או archive. המשימות האלה רצות בעץ העבודה של המרחב על המארח, בלי קשר למיקום.
  • רק בעל השרת יכול לשמור או לאשר הגדרה שרצה על המארח. זה כולל אישור של גרסה חדשה של קובץ מאגר מקושר. מנהל סביבת עבודה שמנסה רואה “רק בעל השרת יכול לשמור או לאשר סביבה שרצה על מארח השרת. מנהל סביבת עבודה יכול להשתמש בסביבה שרצה ב־rig.”
  • מנהל סביבת עבודה יכול לשמור ולאשר הגדרה שרצה כולה ב-rig: "placement": "rig", בלי פקודת בדיקה ובלי משימה מסוג provision או archive.
  • חברים מתחילים, עוצרים ומשתמשים בסביבות בכל מקרה.
  • הגדרה שרצה על המארח רצה רק אחרי שבעל השרת הנוכחי שמר או אישר אותה. השרת רושם את האישור הזה בעצמו ובודק אותו לפני כל התחלה, בדיקה, משימה וסנכרון של ראש בקשת משיכה. הגדרה שבעל השרת הנוכחי לא אישר, כמו הגדרה שבעל שרת קודם שמר, ממתינה תחת השורה שלה ברשימת הסביבות ובעורך. בעל השרת רואה “רצה על השרת הזה. אשרו אותה כדי לאפשר את הפעלתה.” עם אישור, שמשמר אותה ללא שינוי; כל אחד אחר רואה “רצה על השרת הזה. בעל השרת צריך לאשר אותה לפני שאפשר להפעיל אותה.”
  • סביבה שממתינה לאישור הזה אומרת “בעל השרת עדיין לא אישר את הסביבה הזו, ולכן אי אפשר להריץ אותה על השרת הזה.” בעל השרת רואה במקום זאת “עדיין לא אישרתם את הסביבה הזו. היא רצה על השרת הזה, ולכן תתחיל לאחר שתאשרו את ההגדרה שלה.” עם בדיקה ואישור, שפותח את ההגדרה.
  • טרמינלים של תהליכי הסביבה, והטרמינל שההתחלה פותחת כשהיא צריכה אתכם, רצים על מארח השרת. הקלדה באחד מהם, שינוי גודלו או סגירתו דורשים הרשאת כתיבה לכל מאגר שהמרחב חושף, שנקראת דרך הכניסה שלכם לפלטפורמת הקוד: כמו התחלת הסביבה. כל אחר לא יכול להגיע לטרמינלים האלה כלל.

למאגר compose פשוט מספיק זה:

{
"contract": 1,
"name": "Shop",
"repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } },
"components": [ { "kind": "compose", "id": "stack" } ]
}

לכל השאר יש ברירת מחדל: קובץ ה-compose מתגלה, כל השירותים רצים, פורטים מוקצים, נקודות קצה של HTTP מזוהות והסביבה נקראת על שם הענף.

סביבה היא רשימה מסודרת של רכיבים. כל רכיב ממתין שהקודם יהיה מוכן, אלא אם after מציין אחרים, והעצירה מתבצעת בסדר הפוך. enabledWhen מתנה רכיב באפשרות או בתפקיד, למשל opt.seed, !opt.seed או repo.web. רכיב שהתפקיד שלו אופציונלי ואינו קיים במרחב מושמט באותו אופן, בלי צורך ב-enabledWhen: הוא לא מתחיל ואין לו {port.*} או {url.*}, ולכן רכיב אחר שקורא אותם נכשל בהתחלה.

סוג מי מריץ אותו שימוש
compose מנהל ה-compose של Control Center כל קובץ compose, אחד לכל סביבה
cli הכלי שלכם. Control Center קורא לפעלים ממופים וקורא JSON כלי שמנהל בעצמו מחזור חיים, דומיינים ונתונים
process Control Center, בסשן מסוף מפוקח שרתי פיתוח ו-workers
task Control Center, פעם אחת לכל טריגר התקנות, מיגרציות, בדיקות
app Control Center, כשמישהו לוחץ על הפעלת האפליקציה אפליקציית שולחן עבודה

רכיבי task מקבלים רשימת when:

טריגר מתי רץ
provision כשעץ העבודה נוצר (ראו משימות עץ עבודה בהמשך)
create פעם אחת לכל סביבה, ושוב אחרי איפוס
start בכל הפעלה
change אחרי סנכרון, כשנתיב שהשתנה תואם ל-onChange
manual לפי בקשה: הרצה, cc-env run <id> או environment_run_task
archive ממש לפני השמדת עץ העבודה

משימה שאין לה מה לעשות בהפעלה מציגה את הסטטוס לא פעיל ואינה מופיעה ברשימת השלבים שמוצגת בזמן שהסביבה מתחילה: משימה מסוג manual או change, או משימה מסוג create שכבר רצה.

פקודה שניתנת כמערך היא argv, ולכן ערכי אפשרויות אף פעם לא עוברים דרך מעטפת. מחרוזת, או script עם מערך שורות, רצה תחת bash -lc. מצייני מיקום כמו {name}, {branch}, {stateDir}, {repo.<role>}, {port.<key>}, {opt.<key>} ו-{url.<role>} מורחבים רק ב-argv. פקודות מעטפת קוראות את אותם ערכים כמשתני CC_ENV_*, כמו $CC_ENV_PORT_WEB. מציין מיקום לא מוכר ברכיב שמשתתף בסביבה עוצר את ההתחלה לפני שמשהו רץ.

כל פקודה ומסוף מרחב מקבלים גם CC_ENV_NAME, CC_ENV_STATE_DIR, CC_ENV_URL, CC_SPACE_ID, CC_ENV_REPO_<ROLE>, ובמרחבי PR גם CC_PR_NUMBER ו-CC_PR_IS_FORK. עם רכיב compose הם מקבלים גם COMPOSE_PROJECT_NAME ו-COMPOSE_FILE, כך ש-docker compose exec במשימה מגיע לפרויקט הנכון.

תפקידים ותיקיית עבודה

קטע בשם “תפקידים ותיקיית עבודה”

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

"repos": {
"api": { "repoId": "<api>", "anchor": true, "required": true },
"web": { "repoId": "<web>", "anchor": true },
"e2e": { "repoId": "<e2e>", "whenMissing": "useSource" }
}
  • anchor: מרחב יכול להפעיל את הסביבה כשיש בו לפחות תפקיד עוגן אחד. אם שתי הגדרות תואמות, מי שמפעיל בוחר.
  • required: הסטאק לא יכול לרוץ בלי מאגר זה.
  • whenMissing: מה קורה כשהתפקיד חסר במרחב. addToSpace מוסיף את המאגר בענף ברירת המחדל שלו והוא ברירת המחדל לתפקידי required. useSource מעביר את ה-checkout הרשום שלכם, שיש להתייחס אליו כקריאה בלבד. skip משאיר את המשתנה לא מוגדר והוא ברירת המחדל בשאר המקרים.
  • הפעלה דורשת הרשאת write על מאגר עוגן במרחב וגישת קריאה לכל מאגר קשור אחר.

פקודה רצה בתפקיד הראשון המוצהר ב-repos, ולא בתפקיד אחר שיש למרחב במקרה, ולכן הגדרה של מאגר אחד לא מזכירה זאת. כל רכיב יכול לעקוף זאת עם "cwd": { "role": "e2e", "path": "packages/ui" }. שני השדות אופציונליים. כשייתכן שהתפקיד הראשון חסר במרחב, כי הוא אינו required וגם לא העוגן היחיד, כל רכיב חייב לציין את התפקיד שלו.

Control Center מקצה פורטים של המארח לפני שמשהו מופעל, מטווח משותף לכל המארח (42000 עד 49999 כברירת מחדל, בבלוקים של 32). פורט נשאר זהה לאורך כל חיי הסביבה, ופורטים של compose נקשרים רק ל-127.0.0.1.

  • פורטים של compose לא דורשים הצהרה. קראו אותם כ-{port.postgres.5432} או CC_ENV_PORT_POSTGRES_5432.
  • פורטים אחרים מוצהרים במקום השימוש, עם "port": "web" או "ports": ["web", "hmr"], ונקראים כ-{port.web}. תהליך עם פורט מקבל גם PORT ו-HOST=127.0.0.1.

נקודות קצה של HTTP מקבלות כתובת URL בנתב של השרת, שמאזין על פורט loopback אחד:

http://<endpoint>--<name>--<project>.localhost:<router port>
http://web--fix-login--shop.localhost:7355
  • <name> הוא הענף כ-slug, או pr-<n> במרחב PR. <project> הוא naming.project, ואחרת שם ההגדרה.
  • שמות *.localhost מצביעים על loopback, ולכן אינם דורשים רשומות hosts או DNS, ושם המארח מפריד עוגיות בין סביבות.
  • פורטים של compose שעונים ב-HTTP מזוהים, ו-http על הרכיב עוקף את הניחוש. תהליך צריך "endpoint": { "role": "web", "primary": true }, שגם מאפשר את {url.web}.
  • בדפדפן (VM), השתמשו ב-פתיחה ב-Browser (VM). שם https://web--fix-login--shop.localhost/ מגיע לאותו נתיב.
  • התווית כולה נשארת בגבול 63 תווים, ולכן שמות ארוכים מקוצרים בעזרת גיבוב.
  • לשתי נקודות קצה אין דומיין אב משותף. אפליקציה שצריכה עוגייה אחת לשתיהן חייבת להגיש אותן מנקודת קצה אחת.

לכתובות URL שיש לרשום מראש, כמו הפניות OAuth, "naming": { "pool": { "names": "cc{n}", "size": 8 }, "project": "shop" } נותן קבוצת שמות קבועה.

policy קובע מתי סביבות רצות. autoCreate הוא off, prSpaces או allSpaces, ברירת המחדל של idleStopMinutes היא 240, followPrHead מסנכרן סביבת PR כשה-head זז, ועם maxRunning (ברירת מחדל 6) התחל מציע לעצור את הסביבה שלא הייתה בשימוש הכי הרבה זמן.

אפליקציית ווב ו-Postgres מקובץ compose אחד, עם .env ש-git מתעלם ממנו, מיגרציות ומשימת בדיקות. seedFiles מעתיק קבצים בשם מה-checkout הרשום שלכם לכל עץ עבודה חדש.

{
"contract": 1,
"name": "Shop",
"repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } },
"naming": { "project": "shop" },
"seedFiles": [".env"],
"components": [
{ "kind": "compose", "id": "stack",
"services": ["postgres", "web"],
"healthchecks": { "postgres": ["pg_isready", "-U", "postgres"] } },
{ "kind": "task", "id": "migrate", "when": ["create", "change"],
"onChange": ["db/migrations/**"],
"command": "docker compose exec -T web bin/migrate" },
{ "kind": "task", "id": "test", "when": ["manual"],
"command": "docker compose exec -T web bin/test" }
]
}

healthchecks מאפשר לשירות בלי בדיקת תקינות משלו לעכב את הרכיב הבא. בלעדיו, קונטיינר רץ נחשב מוכן, ומיגרציות עלולות להקדים מסד נתונים שעדיין עולה.

כל התחלה ורענון מריצים את up עם --remove-orphans, כך ששירות שהוסר מקובץ compose נעצר ומשחרר את הפורט שלו. התמונות נבנות בהתחלה ובריענון, אלא אם הרכיב מגדיר "build": false.

כלי בדיוני acme שמנהל בעצמו קונטיינרים, דומיינים ו-TLS. Control Center מספק את {name} ולומד את כל השאר מ-status. הוא אף פעם לא גוזר שמות מארחים של כלי ולא עורך את /etc/hosts.

{
"contract": 1,
"name": "Acme",
"repos": {
"server": { "repoId": "<server>", "anchor": true, "required": true },
"web": { "repoId": "<web>", "anchor": true }
},
"routing": { "mode": "tool", "domain": "acme.test", "upstream": "127.0.0.1:443",
"tls": true, "caFile": "~/.acme/tls/ca.crt" },
"components": [
{ "kind": "cli", "id": "acme",
"verbs": {
"create": ["acme", "env", "create", "{name}",
{ "if": "!interactive", "args": ["--json"] },
{ "if": "repo.web", "args": ["--web-dir", "{repo.web}"] }],
"start": ["acme", "env", "start", "{name}"],
"stop": ["acme", "env", "stop", "{name}"],
"destroy": ["acme", "env", "destroy", "{name}", "--yes"],
"reset": ["acme", "env", "reset-db", "{name}"],
"status": ["acme", "env", "status", "{name}", "--json"],
"list": ["acme", "env", "ls", "--json"],
"logs": ["acme", "env", "logs", "{name}",
{ "if": "service", "args": ["{service}"] },
"--tail", "{tail}",
{ "if": "follow", "args": ["--follow"] }],
"exec": ["acme", "env", "exec", "{name}", "{service}", "{command}"]
},
"interactive": ["create"],
"keepsDataOnStop": false,
"statusMap": {
"state": [
{ "when": { "path": "/status/ready", "equals": true }, "state": "ready" },
{ "when": { "none": "/status/containers", "where": { "state": "running" } },
"state": "stopped" },
{ "when": { "path": "/status/phase", "equals": "failed" }, "state": "failed" },
{ "state": "starting" }
],
"detail": "phase: {/status/phase}",
"warnings": [
{ "when": { "path": "/status/dnsWorking", "equals": false },
"message": "Not resolvable on this host" }
],
"endpoints": [
{ "role": "app", "label": "App", "url": "/urls/app", "primary": true },
{ "role": "db", "hostPort": "/ports/db" }
],
"services": "/status/containers/*/service",
"list": "/*/slug",
"missingErrorCodes": ["env.not-found"]
} }
]
}
  • create, status ו-destroy הם חובה. Control Center בוחר ב-create או ב-start לפי הסטטוס שהוא קורא. כל פועל יכול להיות { "shell": "…" } במקום argv.
  • interactive מציין אילו פועלים, מתוך create, start ו-reset, יכולים לבקש את מה שהם צריכים בטרמינל. כשפועל כזה יוצא עם קוד 3 עבור מי שלחץ התחל, Control Center מריץ את אותו פועל שוב בלשונית טרמינל, וההתחלה ממשיכה אחרי שהוא יוצא עם קוד 0. שם התנאי interactive הוא אמת ו-CC_ENV_INTERACTIVE=1 מוגדר, ולכן { "if": "!interactive", "args": ["--json"] } שומר על הפלט המכונה עבור הצינור. התחלה על ידי סוכן, או התחלה אוטומטית, לעולם לא פותחת טרמינל: הסביבה מציגה נדרשת פעולה וממתינה.
  • destroy שנכשל עדיין מסיר את הסביבה כש-status מדווח אחר כך missing, כך שסביבה שהכלי כבר אינו מחזיק תמיד ניתנת להסרה.
  • list מאפשר ל-Control Center לזהות סביבה שהכלי איבד. הסביבה מסומנת כנעלמה רק כשהשם שלה חסר מ-list ו-status אז מחזיר missing. פלט שאי אפשר לקרוא כרשימה לא משנה דבר.
  • {service} ב-logs וב-exec חייב להיות מילה אחת שלא מתחילה ב--, ואחד השירותים שהכלי דיווח עליהם בפעם האחרונה שדיווח על שירותים.
  • statusMap קורא את ה-JSON של הכלי עם מצביעי JSON, כאשר * תואם לכל פריט. כללי המצב מסודרים וההתאמה הראשונה מנצחת. תנאי הוא path עם equals, או any או none עם where.
  • keepsDataOnStop: false מכבה עצירה בחוסר פעילות ומוסיף ל-עצור אזהרה על אובדן נתונים. הגדירו זאת כשעצירה מאבדת נתונים.
  • routing.mode: "tool" מחבר את שמות המארחים של הכלי לדפדפן (VM) ולסוכנים. הדומיין חייב להסתיים ב-.test, .localhost או .internal, וכתובת URL מדווחת מחוץ לו נזרקת.

כלי משלכם יכול לוותר על statusMap ולהדפיס את חוזה הסטטוס שמתואר בסוף העמוד.

רק תהליכים ומשימות, בלי קונטיינרים. אפליקציית הווב מוצאת את ה-API דרך {url.api}.

{
"contract": 1,
"name": "Monorepo",
"repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } },
"naming": { "project": "mono" },
"options": [ { "key": "seed", "type": "bool", "default": true, "agentDefault": false } ],
"components": [
{ "kind": "task", "id": "install", "when": ["provision", "change"],
"onChange": ["pnpm-lock.yaml"],
"command": ["pnpm", "install", "--frozen-lockfile"] },
{ "kind": "process", "id": "api", "label": "API", "port": "api",
"cwd": { "path": "apps/api" },
"command": ["pnpm", "dev"],
"endpoint": { "role": "api" },
"ready": { "http": "http://127.0.0.1:{port.api}/health", "timeout": 120 },
"restartOn": ["pnpm-lock.yaml"] },
{ "kind": "task", "id": "seed", "when": ["create"], "enabledWhen": "opt.seed",
"cwd": { "path": "apps/api" },
"command": ["pnpm", "db:seed"] },
{ "kind": "process", "id": "web", "label": "Dev server", "port": "web",
"cwd": { "path": "apps/web" },
"env": { "API_URL": "{url.api}" },
"command": ["pnpm", "dev", "--port", "{port.web}", "--host", "127.0.0.1"],
"endpoint": { "role": "web", "primary": true },
"ready": { "http": "http://127.0.0.1:{port.web}/" } },
{ "kind": "task", "id": "lint", "when": ["manual"], "command": ["pnpm", "lint"] }
]
}
  • כל תהליך הוא לשונית מסוף שאפשר לפתוח, לקרוא ולהקליד בה, אם יש לכם הרשאת כתיבה לכל מאגר במרחב (ראו מי יכול לשמור מה). סגירת הלשונית לא עוצרת אותו.
  • ready מקבל http (כתובת URL מלאה), tcp (host:port) או logMatch (ביטוי רגולרי). restart הוא on-failure (ברירת המחדל), always או never. restartOn מפעיל מחדש את התהליך כשנתיב שהשתנה תואם.
  • options הופכות לטופס ב-התחל, ו-agentDefault חל על הרצות שסוכן מפעיל.

דוגמה: אפליקציית שולחן עבודה

קטע בשם “דוגמה: אפליקציית שולחן עבודה”

אפליקציית שולחן עבודה עם שלב בנייה. אפליקציה עובדת אותו דבר בכל טכנולוגיה, כי Control Center פועל ברמת החלונות של מערכת ההפעלה ולא צריך hook או SDK באפליקציה.

{
"contract": 1,
"name": "Studio",
"repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } },
"components": [
{ "kind": "task", "id": "build", "when": ["manual"], "command": ["pnpm", "build"] },
{ "kind": "app", "id": "desktop", "label": "Studio", "prepare": "build",
"command": ["dist/mac-arm64/Studio.app/Contents/MacOS/Studio"],
"isolate": "home" }
]
}

אפליקציה לא מופעלת עם הסביבה. מישהו לוחץ על הפעלת האפליקציה, ו-prepare רץ קודם. בנייה והפעלה מחדש מריץ את הצמד הזה שוב. enabledWhen חל על האפליקציה ועל משימת ה-prepare שלה, ו-הפעלת האפליקציה נדחית כל עוד אחד מהם כבוי. אפליקציה נחשבת רצה כל עוד תהליך כלשהו בקבוצת התהליכים שלה רץ, כך שמפעיל שמתחיל את האפליקציה ויוצא לא מזיק. אם הכול נעלם תוך כ-5 שניות מ-הפעלת האפליקציה, האפליקציה מוצגת ככושלת עם שורות היומן האחרונות שלה. לאחר מכן, יציאה נקייה מוצגת כסגורה וקריסה מציגה את שורות היומן האחרונות, ואף אחד מהם לא מפעיל אותה מחדש. הפעלה מחדש של השרת סוגרת את האפליקציה ולעולם לא מפעילה אותה מחדש, ועצירה בחוסר פעילות לא נוגעת באפליקציה רצה.

הרשאות ומגבלות של אפליקציות שולחן עבודה

קטע בשם “הרשאות ומגבלות של אפליקציות שולחן עבודה”
  • ב-macOS, העניקו ל-Control Center פעם אחת הקלטת מסך ונגישות בהגדרות המערכת. מארח השרת צריך סשן גרפי: שרת ללא ממשק מסרב להפעיל אפליקציה.
  • הפעילו את הקובץ הבינארי ישירות. open -a מעביר את האפליקציה ל-LaunchServices והיא עוזבת את עץ התהליכים ש-Control Center עוקב אחריו, כך שהאפליקציה מוצגת ככושלת מיד אחרי ההפעלה.
  • חלונות נשארים על מסך. macOS לא לוכד חלון שנמצא מחוץ לכל המסכים, ולכן אפליקציה שסוכן משתמש בה גלויה על מסך השרת. היא לא צריכה מיקוד.
  • "isolate": "home" נותן לאפליקציה תיקיית בית פרטית דרך HOME, XDG_* ו-CFFIXED_USER_HOME, כך שעותקים משני מרחבים יכולים לרוץ זה לצד זה. NSUserDefaults לא מבודד, ולכן העדפות Cocoa ו-shared_preferences של Flutter נשארות משותפות בין עותקים.
  • isolate חל רק על התהליך שהופעל. משגר של שרשרת כלים כמו flutter run צריך את תיקיית הבית האמיתית, ולכן שלבו את isolate עם קובץ בינארי בנוי. אם לאפליקציה יש הגדרה משלה, כמו --user-data-dir, העדיפו אותה.
  • סוכנים מפעילים את החלון עם app_use, שמגיע רק לעץ התהליכים של הסביבה הזו. סוכן רואה את החלון, לא את שולחן העבודה. הפעלות של סוכנים עוברות דרך מדיניות הפעולות ושואלות כברירת מחדל, וקלט הסוכן נעצר בזמן שאדם מחזיק בשליטה.
  • "input": "background" (ברירת המחדל) שולח אירועים לתהליך. "foreground" מפעיל את החלון ומשתלט על הסמן.

משימות provision ו-archive מריצות את ההתקנה והפירוק של מאגר יחד עם עץ העבודה שלו. הסמל בשורה של מאגר ב-הגדרות → סביבת עבודה → מאגרים פותח את ההגדרה של המאגר.

המשימות האלה עוקבות אחרי עץ העבודה, לא אחרי הסביבה, ולכן רצות גם במרחבים שבהם איש לא לוחץ על התחל:

provision archive
רץ כשעץ העבודה של התפקיד נוצר, בכל מרחב ממש לפני השמדת אותו עץ עבודה
בכישלון ההקצאה נכשלת ועץ העבודה מושמד נרשם, אף פעם לא חוסם מחיקה
זמן קצוב ברירת מחדל 5 דקות 2 דקות
רואה CC_WORKSPACE_PATH, CC_ROOT_PATH, CC_SPACE_*, CC_REPO_NAME אותו דבר

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

{
"contract": 1,
"name": "Web",
"repos": { "app": { "repoId": "<id>" } },
"components": [
{ "kind": "task", "id": "setup", "when": ["provision"],
"script": ["pnpm install", "cp \"$CC_ROOT_PATH/.env\" .env"] }
]
}
  • עדיין אין סביבה, ולכן המשימות האלה לא יכולות להשתמש ב-{name}, {port.*}, {url.*}, {opt.*} או enabledWhen, והן לא מקבלות את ה-env של ההגדרה.
  • רק הגדרה אחת יכולה להחזיק משימות provision ו-archive של מאגר. אחרות עדיין יכולות לקשור אותו לכל דבר אחר.
  • "when": ["provision", "change"] גם מתקין מחדש כשקובץ נעילה משתנה.
  • משימה רצה עבור עץ העבודה של תפקיד ה-cwd שלה, ולכן הגדרה מרובת מאגרים יכולה להגדיר כל מאגר בנפרד.
  • הרצת בדיקה מגדירה CC_SCRIPT_TEST=1. ניסיון חוזר מתחיל מעץ עבודה נקי, אז כתבו משימות שעומדות בהרצה חוזרת.

סוכנים אף פעם לא מקבלים את שקע Docker. במרחב עם הגדרה מתאימה, הרצה מקבלת cc-env ב-PATH שלה. המרחב נגזר מההרצה, ולכן סוכן יכול לפעול רק על הסביבה שלו, וכל פקודה עוברת דרך מדיניות הפעולות.

חלון מסוף
cc-env status
cc-env up
cc-env down
cc-env reset
cc-env destroy
cc-env restart <process>
cc-env logs <name>
cc-env exec <service> -- <cmd>
cc-env run <task> -- <args>

עם רכיב compose, shim של docker מאפשר גם docker compose עם ps, logs, exec, port, restart ו-top, ורק מול פרויקט compose של הסביבה הזו עצמה. אסור דגלים לפני הפועל, ולכל פועל יש רשימה קצרה של אפשרויות: logs לא יכול לעקוב אחר הפלט, ו-exec מקבל רק -T (או --no-tty). אפשרויות שמפנות את compose לקובץ או לפרויקט אחר (-f, -p, --project-directory, --env-file, --profile) נדחות בכל מקום שבו הן מופיעות. כל השאר מסתיים בקוד 5 וב-“not available in Control Center agent runs”.

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

"agentPassthrough": {
"binary": "acme",
"allow": [
{ "argv": ["env", "ls"], "maps": "status", "nameFilter": true },
{ "argv": ["env", "status|url"], "maps": "status", "positionalName": 2 },
{ "argv": ["env", "create"], "maps": "up", "positionalName": 2,
"pathFlags": ["--web-dir"], "denyFlags": ["--force"] },
{ "argv": ["env", "logs"], "maps": "logs", "positionalName": 2,
"denyFlags": ["--follow"] }
]
}

maps מציין את הפעולה שהמדיניות שלה חלה. positionalName כופה על הארגומנט הזה את הסביבה של המרחב, nameFilter מסנן אליה את פלט ה-JSON, וכל ערך pathFlags חייב להיפתר בתוך עצי העבודה של ההרצה. פקודה שלא תואמת אף כלל מסתיימת בקוד 5.

אותן פעולות קיימות ככלים: environment_status, environment_up, environment_down, environment_reset, environment_destroy, environment_restart, environment_exec, environment_logs, environment_run_task, environment_launch_app ו-environment_stop_app. סוכנים בארגז חול מגיעים לפורטים שלהם ישירות ולשמות המארחים של הסביבה דרך ה-proxy של ההרצה, אז בקשו מהם לקרוא נקודות קצה מ-environment_status במקום לנחש כתובת URL.

קוד של PR מ-fork אינו מהימן, ובמיקום על המארח הוא רץ כמשתמש מערכת ההפעלה של השרת. policy.forkPrs קובע מה קורה:

ערך השפעה ברירת מחדל עבור
rig קובץ ה-compose רץ ב-VM בלי שאלה הגדרות עם רכיבי compose ו-task בלבד
approval כל הפעלה דורשת מנהל כל שאר ההגדרות
deny נדחה אף אחת
  • seedFiles אף פעם לא מועתקים ל-fork, כי בדרך כלל אלה סודות. קובץ compose שקושר אחד מהם מדווח על הקובץ החסר בשמו.
  • משימות provision ו-archive מדולגות אלא אם המדיניות היא rig, ואז הן רצות ב-VM.
  • במיקום על המארח, privileged, מרחבי שמות של המארח, קישור של שקע Docker, devices וקישורים מחוץ לעצי העבודה של המרחב נדחים ב-fork. במרחבים מהימנים הם רק מזהירים.

"placement": "rig" מריץ רכיבי compose ו-task ב-microVM ייעודי. הגדרות עם רכיבי process, cli או app אינן מתאימות. קובץ ה-compose רץ ללא שינוי, בלי שקע Docker של המארח ובלי אישורי המפעיל, וגישת הרשת מוגבלת לרישומים שהתמונות שלו צריכות. עץ העבודה מחובר בזמן אמת.

  • אורחי arm64. האורחים הם arm64 ב-Apple Silicon, ולכן תמונות amd64 בלבד לא ירוצו.
  • רישומים פרטיים נדחים. לאורחים אין אישורי רישום, ולכן תמונה ברישום מחוץ לציבוריים המוכרים נדחית לפני שה-VM עולה. מאגר פרטי ברישום ציבורי נכשל כשהאורח מושך אותו.
  • אחסון של 16 GiB. כל התמונות והכרכים של הסטאק חולקים דיסק אחד של 16 GiB, ואי אפשר להגדיל אותו.
  • העלייה הראשונה איטית. שכבות התמונה הן לכל VM, ולכן העלייה הראשונה מושכת הכול. rig שנעצר שומר על הדיסק שלו.
  • תמונות בסיס חייבות להיות קריאות. קובץ Dockerfile שמציין את תמונת הבסיס דרך משתנה לא ניתן לתכנון, כי גישת הרשת נקבעת בעלייה.
  • משך חיים. policy.rigTtlHours מסיים את ה-VM, כברירת מחדל אחרי 24 שעות.

חוזה סטטוס למחברי כלים

קטע בשם “חוזה סטטוס למחברי כלים”

רכיב cli בלי statusMap מצפה לחוזה המקורי, cc-env/1. הפועל status מדפיס את האובייקט הזה ל-stdout:

{
"state": "ready",
"detail": "migrations applied, HTTP 200",
"endpoints": [
{ "role": "app", "label": "App", "url": "https://fix-login.acme.test", "primary": true },
{ "role": "postgres", "label": "Postgres", "hostPort": 49213 }
],
"services": ["server", "postgres"],
"needsRecreate": false,
"error": { "code": "post-start-failed", "message": "…", "hint": "…", "command": "…" }
}
  • state הוא ready, starting, stopped, failed או missing. missing מוביל ל-create, ו-stopped ו-failed מובילים ל-start. דווחו על missing עם קוד יציאה 0: status שנכשל נחשב failed.
  • רק state נדרש. שדות לא מוכרים מתעלמים מהם, ופלט שאי אפשר לנתח מוצג כמדורדר, עם הטקסט הגולמי כפירוט.
  • כתובת URL חייבת להיות loopback, *.localhost או תחת routing.domain, אחרת היא נזרקת.
  • needsRecreate: true מציג את יצירה מחדש, שזורק נתונים. Control Center אף פעם לא פועל על כך בעצמו.
  • הפועל list מדפיס מערך JSON של שמות, או של אובייקטים עם name.

קודי יציאה חלים על כל פועל:

קוד משמעות
0 תקין
3 נדרשת תשובה בטרמינל, למשל סיסמת sudo. פועל הרשום ב-interactive רץ שוב בלשונית טרמינל למי שלחץ התחל. אחרת, הרצה במסוף פותח מסוף מרחב עם ה-command של הכלי מוקלד אך לא מורץ, ואז נסה שוב מנסה שוב. Control Center אף פעם לא מריץ sudo ואף פעם לא עונה לבקשה.
4 נדרשת כניסה לחשבון. ה-command של הכלי מציין כיצד
5 משהו שממנו הוא תלוי אינו זמין, כמו זמן ריצה של קונטיינרים שלא פועל
אחר כישלון

קודים 3, 4 ו-5 אינם כישלונות. הסביבה מציגה נדרשת פעולה וממתינה, וההתחלה הבאה ממשיכה מהנקודה שבה ההתחלה הקודמת נעצרה. משימה שיוצאת עם אחד מהם משמעה אותו דבר.

התקדמות נשלחת ל-stderr כ-JSON מופרד בשורות:

{"type":"step","id":"images","label":"Pull images","state":"running"}
{"type":"log","stream":"stdout","line":"postgres Pulled"}
{"type":"step","id":"images","label":"Pulled 4 images","state":"done"}
{"type":"note","level":"warn","message":"Hosts entries stayed behind after destroy"}
{"type":"error","code":"hosts-missing","message":"Add the hosts entry","hint":"Needs sudo","command":"sudo acme hosts add fix-login"}

בזמן שסביבה מתחילה, החלונית מציגה את הרכיבים שההפעלה עוברת דרכם, ולכל אחד מהם ספינר, סימון V או X. שורת step מתארת מה הכלי עושה עכשיו, וה-label שלה מופיע מתחת לשורה של הכלי עצמו; שלבים לעולם אינם מוסיפים שורות. ה-state של שלב הוא pending, running, done או failed, ושלב בלי state נחשב כפועל. שלב שמדווח שוב תחת אותו id (מחרוזת או מספר, או תחת אותו label בלי מזהה) מחליף את מה שאמר קודם, ולכן כלי עם ספינר אחד יכול לשמור על id אחד ולשנות את ה-label. בלי מזהים, השלבים באים זה אחרי זה: שלב חדש מסיים את הקודם. כשהפקודה יוצאת, שלב שעדיין רץ מסתיים כפי שהפקודה הסתיימה.

שורת log מכילה שורת פלט אחת שהכלי עטף ב-JSON, ונקראת כפלט רגיל. שורת note הולכת לפלט ההרצה, ושורה עם "level": "warn" נשארת גם על הסביבה כאזהרה. שורה אחרונה מסוג error הופכת לשגיאה מובנית, ו-command מוצע להעתקה, ו-12 השורות האחרונות של הפלט מופיעות מתחת ל-message שלה. בלעדיה Control Center מציג את 20 שורות ה-stderr האחרונות. כל מה שאינו JSON הוא פלט יומן רגיל.