Sett opp miljøer
Et miljø er den kjørende stacken til et område: tjenestene en gren trenger, isolert fra alle andre områder, synlig i sidefeltet og tilgjengelig for agenter. Pull requests får også et, fordi en PR allerede har sitt eget område.
En administrator for arbeidsområdet skriver en definisjon én gang. Medlemmer klikker deretter Start i delen Miljø i sidefeltet til et område eller en PR. Definisjoner ligger i databasen til arbeidsområdet, så en funksjonsgren endrer aldri hva Control Center kjører, selv om verktøyene fortsatt kjører koden i grenen.
Opprett en definisjon
Seksjon med tittelen «Opprett en definisjon»- Åpne Innstillinger → Arbeidsområde → Miljøer. Bare administratorer for arbeidsområdet kan endre definisjoner, og bare serverens eier kan lagre en som kjører på serverens verts (se Hvem kan lagre hva).
- Klikk Ny definisjon, og deretter Tom definisjon eller Utkast fra repo. Et utkast søker gjennom repoet etter compose-filer, en
Procfileogpackage.json-skript, og du går gjennom resultatet. - Fyll ut skjemaet, eller bruk fanen JSON. Eksemplene på denne siden er den JSON-en.
- Klikk Kjør test. Det starter et engangsmiljø, venter til det er klart og ødelegger det.
Lagring kontrollerer en definisjon strengt. Et ukjent felt, en verdi av feil type eller et feilstavet valg avvises, med stien og det nærmeste gyldige navnet, for eksempel repos.app.requird: Unknown field. Did you mean "required"?. Et $schema på øverste nivå er tillatt.
Bruk Koble til en repofil for å holde en definisjon i et repo. Control Center leser filen bare fra standardgrenen og kjører bare versjonen som er godkjent: av en administrator for arbeidsområdet, eller av serverens eier når definisjonen kjører på verten. En nyere versjon viser Oppdatering tilgjengelig og endrer ingenting før den er godkjent.
Hvem kan lagre hva
Seksjon med tittelen «Hvem kan lagre hva»En miljødefinisjon kan kjøre kommandoer på serververten som serverens egen bruker. Det er serverens eiers avgjørelse, ikke en arbeidsområderolles:
- En definisjon kjører på verten når den har vertsplassering, en kontroll som kjører en kommando, eller en
provision- ellerarchive-oppgave. Disse oppgavene kjører i områdets worktree på verten uansett plassering. - Bare serverens eier kan lagre eller godkjenne en definisjon som kjører på verten. Det inkluderer å godkjenne en ny versjon av en koblet repofil. En administrator for arbeidsområdet som prøver, ser «Bare serverens eier kan lagre eller godkjenne et miljø som kjører på serververten. En administrator for arbeidsområdet kan bruke et som kjører i en stasjon.»
- En administrator for arbeidsområdet kan lagre og godkjenne en definisjon som kjører helt i en stasjon:
"placement": "rig", ingen kontrollkommando og ingenprovision- ellerarchive-oppgave. - Medlemmer starter, stopper og bruker miljøer uansett.
- En definisjon som kjører på verten, kjører bare etter at gjeldende serverens eier har lagret eller godkjent den. Serveren registrerer godkjenningen selv og sjekker den før hver start, kontroll, oppgave og synkronisering av pull request-head. En definisjon som gjeldende eier ikke har godkjent, for eksempel en som en tidligere eier lagret, venter under sin rad i miljølisten og i editoren. Serverens eier ser «Kjører på denne serveren. Godkjenn det for å la det starte.» med Godkjenn, som lagrer den uendret; alle andre ser «Kjører på denne serveren. Serverens eier må godkjenne det før det kan starte.»
- Et miljø som holdes for den godkjenningen, sier «Serverens eier har ikke godkjent dette miljøet ennå, så det kan ikke kjøre på denne serveren.» Serverens eier ser i stedet «Du har ikke godkjent dette miljøet ennå. Det kjører på denne serveren, så det starter når du godkjenner definisjonen.» med Gjennomgå og godkjenn, som åpner definisjonen.
- Prosessterminalene til et miljø, og terminalen en start åpner når den trenger deg, kjører på serververten. Å skrive i en, endre størrelsen på den eller lukke den krever skrivetilgang til hvert repo området eksponerer, lesbart med din egen innlogging hos kodeverten: det samme som å starte miljøet. Ingen andre kan nå disse terminalene i det hele tatt.
Den minste definisjonen
Seksjon med tittelen «Den minste definisjonen»Et enkelt compose-repo trenger bare dette:
{ "contract": 1, "name": "Shop", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "components": [ { "kind": "compose", "id": "stack" } ]}Alt annet har en standardverdi: compose-filen blir funnet, alle tjenester kjører, porter tildeles, HTTP-endepunkter oppdages, og miljøet får navn etter grenen.
Komponenttyper
Seksjon med tittelen «Komponenttyper»Et miljø er en ordnet liste med komponenter. Hver komponent venter til den forrige er klar, med mindre after angir andre, og stopp skjer i motsatt rekkefølge. enabledWhen gjør en komponent avhengig av et alternativ eller en rolle, for eksempel opt.seed, !opt.seed eller repo.web. En komponent hvis rolle er valgfri og mangler i området, utelates på samme måte uten at enabledWhen trengs: den starter ikke og har verken {port.*} eller {url.*}, så en annen komponent som leser dem, gjør at starten mislykkes.
| Type | Hvem kjører den | Brukes til |
|---|---|---|
compose |
Compose-driveren i Control Center | Alle compose-filer, én per miljø |
cli |
Verktøyet ditt. Control Center kaller tilordnede verb og leser JSON | Et verktøy som eier livssyklusen, domenene og dataene sine |
process |
Control Center, i en overvåket terminaløkt | Utviklingsservere og workers |
task |
Control Center, én gang per utløser | Installasjoner, migreringer, tester |
app |
Control Center, når noen klikker Åpne | En skrivebordsapp |
task-komponenter tar en when-liste:
| Utløser | Kjører |
|---|---|
provision |
Når worktreet opprettes (se worktree-oppgaver nedenfor) |
create |
Én gang per miljø, og igjen etter en tilbakestilling |
start |
Ved hver start |
change |
Etter en synkronisering, når en endret bane samsvarer med onChange |
manual |
På forespørsel: Kjør, cc-env run <id> eller environment_run_task |
archive |
Rett før worktreet ødelegges |
En task uten noe å gjøre ved en start viser Inaktiv og utelates fra listen over trinn som vises mens miljøet starter: en manual- eller change-task, eller en create-task som allerede har kjørt.
En kommando gitt som en array er argv, så alternativverdier går aldri gjennom et skall. En streng, eller script med en array av linjer, kjører under bash -lc. Plassholdere som {name}, {branch}, {stateDir}, {repo.<role>}, {port.<key>}, {opt.<key>} og {url.<role>} utvides bare i argv. Skallkommandoer leser de samme verdiene som CC_ENV_*-variabler, for eksempel $CC_ENV_PORT_WEB. En ukjent plassholder i en komponent som deltar, stopper starten før noe kjøres.
Hver kommando og områdeterminal får også CC_ENV_NAME, CC_ENV_STATE_DIR, CC_ENV_URL, CC_SPACE_ID, CC_ENV_REPO_<ROLE> og, i PR-områder, CC_PR_NUMBER og CC_PR_IS_FORK. Med en compose-komponent får de også COMPOSE_PROJECT_NAME og COMPOSE_FILE, slik at docker compose exec i en oppgave når riktig prosjekt.
Roller og arbeidsmappe
Seksjon med tittelen «Roller og arbeidsmappe»En definisjon binder roller til repoer i arbeidsområdet, slik at én stack kan omfatte flere repoer:
"repos": { "api": { "repoId": "<api>", "anchor": true, "required": true }, "web": { "repoId": "<web>", "anchor": true }, "e2e": { "repoId": "<e2e>", "whenMissing": "useSource" }}anchor: et område kan starte miljøet når det har minst én ankerrolle. Hvis to definisjoner passer, velger den som starter.required: stacken kan ikke kjøre uten dette repoet.whenMissing: hva som skjer når området mangler rollen.addToSpacelegger til repoet på standardgrenen og er standard forrequired-roller.useSourcesender den registrerte utsjekkingen din, som du bør behandle som skrivebeskyttet.skiplar variabelen stå tom og er ellers standard.- For å starte trengs en
write-tillatelse på et ankerrepo i området og lesetilgang til alle andre bundne repoer.
En kommando kjører i den første rollen som er deklarert i repos, aldri i en annen rolle området tilfeldigvis har, så en definisjon med ett repo nevner det aldri. Enhver komponent kan overstyre det med "cwd": { "role": "e2e", "path": "packages/ui" }. Begge feltene er valgfrie. Hvis den første rollen kan mangle i et område, fordi den verken er required eller det eneste ankeret, må hver komponent oppgi sin rolle.
Porter og URL-er
Seksjon med tittelen «Porter og URL-er»Control Center tildeler vertsporter før noe starter, fra et område for hele verten (42000 til 49999 som standard, i blokker på 32). En port forblir den samme i hele miljøets levetid, og compose-porter binder bare til 127.0.0.1.
- Compose-porter trenger ingen deklarasjon. Les dem som
{port.postgres.5432}ellerCC_ENV_PORT_POSTGRES_5432. - Andre porter deklareres der de brukes, med
"port": "web"eller"ports": ["web", "hmr"], og leses som{port.web}. En prosess med port får ogsåPORTogHOST=127.0.0.1.
HTTP-endepunkter får en URL på serverens ruter, som lytter på én loopback-port:
http://<endpoint>--<name>--<project>.localhost:<router port>http://web--fix-login--shop.localhost:7355<name>er grenen som slug, ellerpr-<n>i et PR-område.<project>ernaming.project, ellers definisjonens navn.*.localhost-navn peker til loopback, så de trenger verken hosts-oppføringer eller DNS, og vertsnavnet holder informasjonskapsler adskilt mellom miljøer.- Compose-porter som svarer på HTTP oppdages, og
httppå komponenten overstyrer gjetningen. En prosess trenger"endpoint": { "role": "web", "primary": true }, som også gjør{url.web}tilgjengelig. - Bruk Åpne i Browser (VM) i nettleseren (VM).
https://web--fix-login--shop.localhost/når samme rute der. - Hele etiketten holder seg innenfor 63 tegn, så lange navn forkortes med en hash.
- To endepunkter deler ikke overordnet domene. En app som trenger én informasjonskapsel på tvers av begge, må levere dem fra ett endepunkt.
For URL-er du må registrere på forhånd, for eksempel OAuth-omdirigeringer, gir "naming": { "pool": { "names": "cc{n}", "size": 8 }, "project": "shop" } et fast sett med navn.
policy bestemmer når miljøer kjører. autoCreate er off, prSpaces eller allSpaces, idleStopMinutes er 240 som standard, followPrHead synkroniserer et PR-miljø når head flytter seg, og med maxRunning (standard 6) tilbyr Start å stoppe miljøet som ble brukt for lengst siden.
Eksempel: compose-app
Seksjon med tittelen «Eksempel: compose-app»En nettapp og Postgres fra én compose-fil, med en git-ignorert .env, migreringer og en testoppgave. seedFiles kopierer navngitte filer fra den registrerte utsjekkingen din til hvert nye worktree.
{ "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" } ]}Med healthchecks kan en tjeneste uten egen helsesjekk holde igjen neste komponent. Uten den regnes en kjørende container som klar, og migreringer kan komme før en database som fortsatt starter.
Hver start og oppdatering kjører up med --remove-orphans, slik at en tjeneste som er fjernet fra compose-filen, stopper og frigjør porten sin. Images bygges ved start og oppdatering, med mindre komponenten setter "build": false.
Eksempel: egen CLI
Seksjon med tittelen «Eksempel: egen CLI»Et oppdiktet verktøy acme som eier containerne, domenene og TLS-en sin. Control Center gir {name} og får resten fra status. Det utleder aldri vertsnavnene til et verktøy og redigerer aldri /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,statusogdestroyer påkrevd. Control Center velgercreateellerstartut fra statusen det leser. Ethvert verb kan være{ "shell": "…" }i stedet for argv.interactivenevner verbene, avcreate,startogreset, som kan be om det de trenger i en terminal. Når et slikt verb avsluttes med kode 3 for en person som trykket på Start, kjører Control Center samme verb på nytt i en terminalfane, og starten fortsetter når det avsluttes med 0. Der er betingelseninteractivesann ogCC_ENV_INTERACTIVE=1satt, slik at{ "if": "!interactive", "args": ["--json"] }beholder maskinutdata for den ikke-interaktive kjøringen. En start av en agent, eller en automatisk start, åpner aldri en terminal: miljøet viser Handling kreves og venter.- Et
destroysom feiler, fjerner likevel miljøet nårstatusderetter meldermissing, slik at et miljø verktøyet ikke lenger har, alltid kan fjernes. listlar Control Center legge merke til et miljø verktøyet har mistet. Det merkes som borte bare når navnet mangler ilist, ogstatusda siermissing. Utdata som ikke kan leses som en liste, endrer ingenting.{service}ilogsogexecmå være ett ord som ikke begynner med-, og en av tjenestene verktøyet sist rapporterte, når det rapporterte noen.statusMapleser verktøyets egen JSON med JSON-pekere, der*samsvarer med hvert element. Tilstandsregler er ordnet, og det første treffet vinner. En betingelse erpathmedequals, elleranyellernonemedwhere.keepsDataOnStop: falseslår av stopp ved inaktivitet og legger til en advarsel om datatap på Stopp. Bruk det når stopp mister data.routing.mode: "tool"kobler verktøyets vertsnavn til nettleseren (VM) og agenter. Domenet må slutte på.test,.localhosteller.internal, og en rapportert URL utenfor det forkastes.
Et verktøy du eier, kan droppe statusMap og skrive ut statuskontrakten som er beskrevet på slutten av denne siden.
Eksempel: pnpm-monorepo
Seksjon med tittelen «Eksempel: pnpm-monorepo»Bare prosesser og oppgaver, ingen containere. Nettappen finner API-et gjennom {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"] } ]}- Hver prosess er en terminalfane du kan åpne, lese og skrive i, hvis du har skrivetilgang til hvert repo i området (se Hvem kan lagre hva). Å lukke fanen stopper den ikke.
readytarhttp(en fullstendig URL),tcp(host:port) ellerlogMatch(et regulært uttrykk).restarteron-failure(standard),alwaysellernever.restartOnstarter prosessen på nytt når en endret bane samsvarer.optionsblir et skjema ved Start, ogagentDefaultgjelder kjøringer en agent starter.
Eksempel: skrivebordsapp
Seksjon med tittelen «Eksempel: skrivebordsapp»En skrivebordsapp med et byggetrinn. En app fungerer likt uansett hva den er bygd med, fordi Control Center arbeider på vindusnivå i operativsystemet og ikke trenger noen hook eller SDK i appen.
{ "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" } ]}En app starter ikke med miljøet. Noen klikker Åpne, og prepare kjører først. Bygg på nytt og åpne igjen kjører det paret på nytt. enabledWhen gjelder for appen og for prepare-oppgaven, og Åpne avvises så lenge en av dem er av. En app regnes som kjørende så lenge en prosess i prosessgruppen kjører, så en oppstarter som starter appen og avslutter, er greit. Hvis alt er borte innen omtrent 5 sekunder etter Åpne, vises appen som mislykket med de siste logglinjene. Etter det vises en ren avslutning som lukket og en krasj viser de siste logglinjene, og verken det ene eller det andre starter appen på nytt. En omstart av serveren lukker appen og starter den aldri på nytt, og stopp ved inaktivitet lar en kjørende app være i fred.
Tillatelser og begrensninger for skrivebordsapper
Seksjon med tittelen «Tillatelser og begrensninger for skrivebordsapper»- På macOS gir du Control Center Skjermopptak og Tilgjengelighet én gang i Systeminnstillinger. Serververten trenger en grafisk økt: en hodeløs server nekter å starte en app.
- Start binærfilen direkte.
open -agir appen til LaunchServices, og den forlater prosesstreet Control Center følger, slik at appen vises som mislykket rett etter oppstart. - Vinduer blir på en skjerm. macOS tar ikke opp et vindu som står utenfor alle skjermer, så en app en agent bruker, er synlig på serverens skjerm. Den trenger ikke fokus.
"isolate": "home"gir appen en privat hjemmemappe gjennomHOME,XDG_*ogCFFIXED_USER_HOME, slik at kopier fra to områder kan kjøre side om side.NSUserDefaultsisoleres ikke, så Cocoa-innstillinger og Fluttersshared_preferencesforblir delt mellom kopier.isolategjelder bare den startede prosessen. En verktøykjedestarter somflutter runtrenger den ekte hjemmemappen, så kombinerisolatemed en bygd binærfil. Har appen en egen innstilling, som--user-data-dir, bør du bruke den.- Agenter styrer vinduet med
app_use, som bare når prosesstreet til dette miljøet. En agent ser vinduet, ikke skrivebordet. Agentstarter går gjennom handlingspolicyen og spør som standard, og agentinndata stopper mens en person har kontrollen. "input": "background"(standard) sender hendelser til prosessen."foreground"aktiverer vinduet og tar over markøren.
Worktree-oppgaver
Seksjon med tittelen «Worktree-oppgaver»provision- og archive-oppgaver kjører et repos oppsett og opprydding sammen med worktreet. Ikonet på raden til et repo under Innstillinger → Arbeidsområde → Arkiv åpner definisjonen for repoet.
Disse oppgavene følger worktreet, ikke miljøet, så de kjører i områder der ingen klikker Start:
provision |
archive |
|
|---|---|---|
| Kjører | Når rollens worktree opprettes, i et hvilket som helst område | Rett før det worktreet ødelegges |
| Ved feil | Klargjøringen mislykkes og worktreet ødelegges | Registreres, blokkerer aldri sletting |
| Standard tidsavbrudd | 5 minutter | 2 minutter |
| Ser | CC_WORKSPACE_PATH, CC_ROOT_PATH, CC_SPACE_*, CC_REPO_NAME |
Det samme |
Et repo uten stack trenger bare en definisjon med oppgavene sine. Siden det ikke er noe å starte, trengs ingen ankerrolle:
{ "contract": 1, "name": "Web", "repos": { "app": { "repoId": "<id>" } }, "components": [ { "kind": "task", "id": "setup", "when": ["provision"], "script": ["pnpm install", "cp \"$CC_ROOT_PATH/.env\" .env"] } ]}- Det finnes ikke noe miljø ennå, så disse oppgavene kan ikke bruke
{name},{port.*},{url.*},{opt.*}ellerenabledWhen, og de får ikke definisjonensenv. - Bare én definisjon kan ha
provision- ogarchive-oppgaver for et repo. Andre kan fortsatt binde det til alt annet. "when": ["provision", "change"]installerer også på nytt når en låsefil endres.- En oppgave kjører for worktreet til
cwd-rollen sin, så en definisjon med flere repoer kan sette opp hvert repo for seg. - En testkjøring setter
CC_SCRIPT_TEST=1. Et nytt forsøk starter fra et rent worktree, så skriv oppgaver som tåler å kjøres på nytt.
Agenter får aldri Docker-socketen. I et område med en kvalifisert definisjon får en kjøring cc-env på sin PATH. Området kommer fra kjøringen, så en agent kan bare handle på sitt eget miljø, og hver kommando går gjennom handlingspolicyen.
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>Med en compose-komponent tillater et docker-shim også docker compose med ps, logs, exec, port, restart og top, og bare mot dette miljøets egen compose-prosjekt. Ingen flagg kan stå før verbet, og hvert verb tar en kort liste med alternativer: logs kan ikke følge, og exec tar bare -T (eller --no-tty). Alternativer som peker compose til en annen fil eller et annet prosjekt (-f, -p, --project-directory, --env-file, --profile) avvises uansett hvor de står. Alt annet avsluttes med kode 5 og «not available in Control Center agent runs».
Et repo der skills kaller repoets eget verktøy, kan fortsette med det. En agentPassthrough-blokk på en cli-komponent oppgir hvilke kommandoer agenter kan kjøre. Bare kommandoer den godkjente definisjonen oppgir, slipper gjennom, og hver av dem kjører på verten, så den bærer regelen Kjør kommandoer på verten, som spør først som standard:
"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 angir operasjonen som har policyen som gjelder. positionalName tvinger det argumentet til miljøet i dette området, nameFilter filtrerer JSON-utdata til det, og hver pathFlags-verdi må peke inn i kjøringens worktrees. En kommando som ikke samsvarer med noen regel, avsluttes med kode 5.
De samme operasjonene finnes som verktøy: environment_status, environment_up, environment_down, environment_reset, environment_destroy, environment_restart, environment_exec, environment_logs, environment_run_task, environment_launch_app og environment_stop_app. Agenter i sandkasse når portene sine direkte og miljøets vertsnavn gjennom kjøringens proxy, så be dem lese endepunkter fra environment_status i stedet for å gjette en URL.
Pull requests fra forker
Seksjon med tittelen «Pull requests fra forker»Koden i en fork-PR er ikke klarert, og ved vertsplassering kjører den som serverens OS-bruker. policy.forkPrs bestemmer hva som skjer:
| Verdi | Virkning | Standard for |
|---|---|---|
rig |
Compose-filen kjører i en VM uten spørsmål | Definisjoner med bare compose- og task-komponenter |
approval |
Hver start krever en administrator | Alle andre definisjoner |
deny |
Avvist | Ingen |
seedFileskopieres aldri for en fork, fordi de vanligvis er hemmeligheter. En compose-fil som binder en av dem, rapporterer den manglende filen med navn.provision- ogarchive-oppgaver hoppes over med mindre policyen errig, og da kjører de i VM-en.- Ved vertsplassering avvises
privileged, vertsnavnerom, en binding av Docker-socketen,devicesog bindinger utenfor områdets worktrees på en fork. I klarerte områder gir de bare en advarsel.
Rig-plassering
Seksjon med tittelen «Rig-plassering»"placement": "rig" kjører compose- og task-komponenter i en egen microVM. Definisjoner med process-, cli- eller app-komponenter er ikke kvalifisert. Compose-filen kjører uendret, uten vertens Docker-socket og uten operatørens legitimasjon, og nettverkstilgangen er begrenset til registrene bildene trenger. Worktreet monteres direkte.
- arm64-gjester. Gjester er arm64 på Apple Silicon, så bilder som bare finnes for amd64, kjører ikke.
- Private registre avvises. Gjester har ingen registerlegitimasjon, så et bilde i et register utenfor de kjente offentlige avvises før VM-en starter. Et privat repository i et offentlig register feiler når gjesten henter det.
- 16 GiB lagring. Alle bilder og volumer i stacken deler én disk på 16 GiB, og den kan ikke utvides.
- Første oppstart er treg. Bildelag er per VM, så første oppstart henter alt. En stoppet rig beholder disken.
- Basisbilder må kunne leses. En Dockerfile som oppgir basisbildet gjennom en variabel, kan ikke planlegges, fordi nettverkstilgangen fastsettes ved oppstart.
- Levetid.
policy.rigTtlHoursavslutter VM-en, som standard etter 24 timer.
Statuskontrakt for verktøyforfattere
Seksjon med tittelen «Statuskontrakt for verktøyforfattere»En cli-komponent uten statusMap forventer den opprinnelige kontrakten, cc-env/1. Verbet status skriver ut dette objektet på 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": "…" }}stateerready,starting,stopped,failedellermissing.missingfører tilcreate,stoppedogfailedfører tilstart. Rapportermissingmed avslutningskode 0: en mislykketstatusteller somfailed.- Bare
stateer nødvendig. Ukjente felt ignoreres, og utdata som ikke kan tolkes, vises som degradert, med råteksten som detalj. - En URL må være loopback,
*.localhosteller underrouting.domain, ellers forkastes den. needsRecreate: trueviser Opprett på nytt, som forkaster data. Control Center handler aldri på dette alene.- Verbet
listskriver ut en JSON-array med navn, eller med objekter med etname.
Avslutningskoder gjelder for alle verb:
| Kode | Betydning |
|---|---|
| 0 | OK |
| 3 | Et svar kreves i en terminal, for eksempel et sudo-passord. Et verb som står i interactive, kjører på nytt i en terminalfane for personen som trykket på Start. Ellers åpner Kjør i terminal en områdeterminal med command for verktøyet skrevet inn, men ikke kjørt, og Prøv på nytt prøver deretter på nytt. Control Center kjører aldri sudo og svarer aldri på en ledetekst |
| 4 | Innlogging kreves. Verktøyets command sier hvordan |
| 5 | Noe det er avhengig av, er utilgjengelig, for eksempel en containerkjøretid som ikke kjører |
| Annen | Feil |
Kodene 3, 4 og 5 er ikke feil. Miljøet viser Handling kreves og venter, og neste start tar der den forrige stoppet. En oppgave som avsluttes med en av dem, betyr det samme.
Fremdrift går til stderr som linjedelt 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"}Mens et miljø starter, lister panelet opp komponentene som starten går gjennom, hver med en spinner, en hake eller et kryss. En step-linje sier hva verktøyet gjør nå, og label vises under verktøyets egen rad; trinn gir aldri nye rader. En state for et trinn er pending, running, done eller failed, og et trinn uten state kjører. Et trinn som rapporterer på nytt under samme id (en streng eller et tall, eller samme label uten en), erstatter det det sa før, slik at et verktøy med én spinner kan beholde én id og endre label. Uten id-er følger trinnene etter hverandre: et nytt avslutter det forrige. Når kommandoen avsluttes, avsluttes et trinn som fortsatt kjører på samme måte som kommandoen.
En log-linje inneholder én linje med utdata som verktøyet pakket inn i JSON, og leses som vanlig utdata. En note-linje går til utdata for kjøringen, og en linje med "level": "warn" står også igjen på miljøet som en advarsel. En siste linje av typen error blir en strukturert feil, der command tilbys for kopiering, og de siste 12 linjene med utdata vises under message. Uten den viser Control Center de siste 20 stderr-linjene. Alt som ikke er JSON, er vanlig loggutdata.