הגדרת סביבות
סביבה היא הסטאק הפועל של מרחב אחד: השירותים שענף צריך, מבודדים מכל שאר המרחבים, גלויים בסרגל הצד ונגישים לסוכנים. גם בקשות משיכה מקבלות סביבה, כי ל-PR כבר יש מרחב משלו.
מנהל סביבת העבודה כותב הגדרה פעם אחת. לאחר מכן חברים לוחצים על התחל באזור סביבה בסרגל הצד של מרחב או PR. ההגדרות נשמרות במסד הנתונים של סביבת העבודה, ולכן ענף פיצ’ר אף פעם לא משנה את מה ש-Control Center מריץ, אף שהכלים עדיין מריצים את הקוד של אותו ענף.
יצירת הגדרה
קטע בשם “יצירת הגדרה”- פתחו את הגדרות → סביבת עבודה → סביבות. רק מנהלי סביבת העבודה יכולים לשנות הגדרות, ורק בעל השרת יכול לשמור הגדרה שרצה על מארח השרת (ראו מי יכול לשמור מה).
- לחצו על הגדרה חדשה, ואז על הגדרה ריקה או טיוטה ממאגר. טיוטה סורקת את המאגר בחיפוש אחר קובצי compose, קובץ
Procfileוסקריפטים שלpackage.json, ואתם בודקים את התוצאה. - מלאו את הטופס, או השתמשו בלשונית JSON. הדוגמאות בעמוד זה הן אותו JSON.
- לחצו על הרצת בדיקה. הפעולה מפעילה סביבה חד-פעמית, ממתינה עד שתהיה מוכנה ומשמידה אותה.
בשמירה, ההגדרה נבדקת בקפדנות. שדה לא מוכר, ערך מסוג שגוי או בחירה שנכתבה באיות שגוי נדחים, עם הנתיב שלהם והשם התקף הקרוב ביותר, כמו 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 וגם לא העוגן היחיד, כל רכיב חייב לציין את התפקיד שלו.
פורטים וכתובות URL
קטע בשם “פורטים וכתובות URL”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) התחל מציע לעצור את הסביבה שלא הייתה בשימוש הכי הרבה זמן.
דוגמה: אפליקציית compose
קטע בשם “דוגמה: אפליקציית compose”אפליקציית ווב ו-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.
דוגמה: CLI מותאם
קטע בשם “דוגמה: CLI מותאם”כלי בדיוני 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 ולהדפיס את חוזה הסטטוס שמתואר בסוף העמוד.
דוגמה: מונוריפו pnpm
קטע בשם “דוגמה: מונוריפו pnpm”רק תהליכים ומשימות, בלי קונטיינרים. אפליקציית הווב מוצאת את ה-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 statuscc-env upcc-env downcc-env resetcc-env destroycc-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.
בקשות משיכה מ-forks
קטע בשם “בקשות משיכה מ-forks”קוד של PR מ-fork אינו מהימן, ובמיקום על המארח הוא רץ כמשתמש מערכת ההפעלה של השרת. policy.forkPrs קובע מה קורה:
| ערך | השפעה | ברירת מחדל עבור |
|---|---|---|
rig |
קובץ ה-compose רץ ב-VM בלי שאלה | הגדרות עם רכיבי compose ו-task בלבד |
approval |
כל הפעלה דורשת מנהל | כל שאר ההגדרות |
deny |
נדחה | אף אחת |
seedFilesאף פעם לא מועתקים ל-fork, כי בדרך כלל אלה סודות. קובץ compose שקושר אחד מהם מדווח על הקובץ החסר בשמו.- משימות
provisionו-archiveמדולגות אלא אם המדיניות היאrig, ואז הן רצות ב-VM. - במיקום על המארח,
privileged, מרחבי שמות של המארח, קישור של שקע Docker,devicesוקישורים מחוץ לעצי העבודה של המרחב נדחים ב-fork. במרחבים מהימנים הם רק מזהירים.
מיקום ב-rig
קטע בשם “מיקום ב-rig”"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 הוא פלט יומן רגיל.