The build reef
Every command that builds an image from a Workload's source inside the cluster
O reef build
Todos os comandos que constroem uma imagem a partir do código de um Workload dentro do cluster
The source of truth for the commands of the build reef (#848, spec 0009: the build reef's security design). #1067 builds its first slice: the verbs of Build, the buildkit Nereid, and the namespace builds (made by nereid apply) with its NetworkPolicies; #914 adds the Trigger (spec 0010), which builds a Workload on each new commit of its Mirror. The group is build.getnereus.dev/v1alpha1, cluster-scoped.
A fonte da verdade dos comandos do reef build (#848, spec 0009: o desenho de segurança do reef build). A #1067 constrói a primeira fatia: os verbos do Build, o Nereid buildkit e o namespace builds (criado pelo nereid apply) com as suas NetworkPolicies; a #914 acrescenta o Trigger (spec 0010), que constrói um Workload a cada commit novo do seu Mirror. O grupo é build.getnereus.dev/v1alpha1, com escopo de cluster.
A Build is one image, from one commit, never changed
Build:spechasworkload,commit,ownerandmandate;statushasnereid,phase,commit,image,digestandjob- Its name is the tag: the image goes to the Repository named after the Workload
- One writer per field: the person writes
spec, the Nereid writesstatus
Um Build é uma imagem, de um commit, nunca alterado
Build: ospectemworkload,commit,owneremandate; ostatustemnereid,phase,commit,image,digestejob- O nome é a tag: a imagem vai para o Repository com o nome do Workload
- Um escritor por campo: a pessoa escreve o
spec, o Nereid escreve ostatus
workload and commit never change: another commit is another Build; apply --from-file (#1545, the reefs' default apply) changes only a Build's owner and mandate, and refuses the rest. With no commit, the Nereid takes the Workload's status.source.commit once and keeps it in status.commit. The digest is the registry's answer, never what the Job wrote (spec 0009).
workload e commit nunca mudam: outro commit é outro Build; o apply --from-file (#1545, o apply padrão dos reefs) muda só o owner e o mandate de um Build, e recusa o resto. Sem commit, o Nereid pega o status.source.commit do Workload uma vez e o guarda em status.commit. O digest é a resposta do registry, nunca o que o Job escreveu (spec 0009).
create builds a Workload at the commit its Nereid read
O create constrói um Workload no commit que o Nereid leu
# Two Jobs in the namespace builds: fetch, then build and push$ nereus build create hello-1 \ --workload hellobuild/builds/hello-1 created (mandate: buildkit, nereid: buildkit) Next steps: nereus build get hello-1
nereus nereid apply buildkit makes the namespace builds, and the Nereid its NetworkPolicies before the first Job (spec 0009): no traffic but DNS, the registry, and the egress proxy builds-egress, which lets a RUN reach only the main package hosts and those the build reef's default Mandate adds with egressHosts (#1142). --commit takes a full commit (40 hexadecimal digits). A Build that exists is refused: a Build never changes. Two modes (#1120): with no BUILD_RUNTIME_CLASS, portable mode builds only the operators' Builds, and a team's ends SandboxRequired; nereus nereid apply buildkit --set BUILD_RUNTIME_CLASS=gvisor runs every build in that RuntimeClass, with builds at baseline, once a probe Pod there reports a kernel that is not its node's. The build pool (#1121): --set BUILD_NODE_POOL=builds puts every Pod of builds on the nodes labelled and tainted build.getnereus.dev/pool=builds, and no other Pod may tolerate that taint.
O nereus nereid apply buildkit cria o namespace builds, e o Nereid as suas NetworkPolicies antes do primeiro Job (spec 0009): nenhum tráfego além de DNS, o registry, e o proxy de saída builds-egress, que deixa um RUN alcançar só os principais hosts de pacotes e os que o Mandate padrão do build reef adiciona com egressHosts (#1142). O --commit aceita um commit completo (40 dígitos hexadecimais). Um Build que já existe é recusado: um Build nunca muda. Dois modos (#1120): sem BUILD_RUNTIME_CLASS, o modo portável só constrói os Builds dos operadores, e o de um time termina SandboxRequired; nereus nereid apply buildkit --set BUILD_RUNTIME_CLASS=gvisor roda todo build nessa RuntimeClass, com builds em baseline, assim que um Pod de sonda ali reporta um kernel que não é o do seu nó. O pool de builds (#1121): --set BUILD_NODE_POOL=builds põe todo Pod de builds nos nós com o label e o taint build.getnereus.dev/pool=builds, e nenhum outro Pod pode tolerar esse taint.
get shows the digest the registry answered
O get mostra o digest que o registry respondeu
# Its phase, image and digest$ nereus build get hello-1Name: hello-1Workload: helloCommit: a1b2c3d4e5f60718293a4b5c6d7e8f9012345678Owner: -Mandate: -Nereid: buildkitPhase: SucceededImage: localhost:31874/hello:hello-1Digest: sha256:3517762d3517762d3517762d3517762d3517762d3517762d3517762d3517762dJob: hello-1
A Build that waits says why in a Message line: its Workload, a commit, or a Repository with the push credential in builds (#1072). --output yaml prints the whole object.
Um Build que espera diz o porquê numa linha Message: o seu Workload, um commit, ou um Repository com a credencial de push em builds (#1072). O --output yaml imprime o objeto inteiro.
list shows every build, a line each
O list mostra cada build, uma linha cada
# The Workload, the commit, the phase and the digest$ nereus build listBUILD WORKLOAD COMMIT STATUS DIGESThello-1 hello a1b2c3d Succeeded sha256:3517762d3517hello-2 hello - Pending -
A Build with no commit yet shows -: it waits for the Workload's Nereid to read one. --sort-by .metadata.creationTimestamp lists from the oldest.
Um Build ainda sem commit mostra -: espera o Nereid do Workload ler um. O --sort-by .metadata.creationTimestamp lista do mais antigo.
A private repository is fetched with a token for that build alone
Um repositório privado é buscado com um token só daquele build
# An allow line for builds on the App's Mandate, then the Build$ nereus build get app-1Name: app-1Workload: appPhase: RunningMessage: source fetched at a1b2c3d from https://github.com/example/app with a token for example/app (contents=read)
The buildkit Nereid never holds the App's key. When an authentication Mandate's allow covers builds and the Workload's repository, it asks a Token named after the Build (ADR 0006); the github Nereid mints it into token-<build>, which only the fetch Pod mounts. The Token goes once the fetch ends. With no Mandate covering it, the fetch is anonymous; a refused Token leaves the Build Pending with the line to add.
O Nereid buildkit nunca guarda a chave do App. Quando o allow de um Mandate do reef authentication cobre builds e o repositório do Workload, ele pede um Token com o nome do Build (ADR 0006); o Nereid github o emite em token-<build>, que só o Pod do fetch monta. O Token some quando o fetch termina. Sem Mandate que o cubra, o fetch é anônimo; um Token recusado deixa o Build Pending com a linha a acrescentar.
delete removes the Build and its Job, never the image
O delete remove o Build e o seu Job, nunca a imagem
# The image it pushed stays in its Repository$ nereus build delete hello-1build/builds/hello-1 deleted Next steps: nereus build list
The Job is owned by the Build, so Kubernetes deletes it with it. A new Build of the same name waits until that Job is gone (reason OldJob).
O Job pertence ao Build, então o Kubernetes o apaga junto. Um novo Build com o mesmo nome espera esse Job sumir (motivo OldJob).
trigger create builds a Workload on each new commit of its Mirror
O trigger create constrói um Workload a cada commit novo do seu Mirror
# The Mirror nereus copies the source of the Workload triton$ nereus build trigger create triton \ --workload tritonbuild/triggers/triton created (mandate: buildkit, nereid: buildkit) Next steps: nereus build trigger get triton
A Trigger of the build reef names a Workload; its Nereid follows the scm reef's Mirror of that Workload's repository (spec 0010) and, whenever the Mirror's status.commit changes, creates the Build <trigger>-<first 7 digits of the commit>, labelled build.getnereus.dev/trigger. One Build at a time: while the last one is Pending or Running, a new commit waits (Building), so a burst of pushes builds the last one. Each Nereid writes only its own reef's objects: the forgejo Nereid keeps the Mirror's commit, the buildkit Nereid creates the Builds. --owner gives every Build that owner, checked as for nereus build create, so the gates of spec 0009 hold; --mandate names a build Mandate.
Um Trigger do reef build nomeia um Workload; o seu Nereid segue o Mirror do reef scm do repositório desse Workload (spec 0010) e, sempre que o status.commit do Mirror muda, cria o Build <trigger>-<7 primeiros dígitos do commit>, com o label build.getnereus.dev/trigger. Um Build por vez: enquanto o último está Pending ou Running, um commit novo espera (Building), então uma rajada de pushes constrói o último. Cada Nereid escreve só os objetos do seu reef: o Nereid forgejo mantém o commit do Mirror, o Nereid buildkit cria os Builds. O --owner dá esse dono a todo Build, verificado como no nereus build create, então os portões da spec 0009 valem; o --mandate nomeia um Mandate do build.
trigger list shows the commit each one saw and its last Build
O trigger list mostra o commit que cada um viu e o seu último Build
# After a push, once the Mirror pulled it$ nereus build trigger listTRIGGER WORKLOAD MIRROR COMMIT LAST BUILD STATUStriton triton nereus a1b2c3d triton-a1b2c3d Ready
The Mirror pulls on its interval, so a push becomes a Build within one interval and one pass (15 s for the forgejo Nereid). A Trigger that makes no Build says why in STATUS: NoWorkload, NoSource, NoMirror, MirrorNotReady, OtherBranch (a Mirror follows its default branch only), NameTaken or NoMandate.
O Mirror puxa no seu intervalo, então um push vira um Build dentro de um intervalo e uma passada (15 s para o Nereid forgejo). Um Trigger que não cria Build diz o porquê em STATUS: NoWorkload, NoSource, NoMirror, MirrorNotReady, OtherBranch (um Mirror segue só o seu branch padrão), NameTaken ou NoMandate.
trigger get shows the Mirror it follows and the commit it saw
O trigger get mostra o Mirror que segue e o commit que viu
# Its Mirror, branch, commit and last Build$ nereus build trigger get tritonName: tritonWorkload: tritonOwner: Project/tritonMandate: -Nereid: buildkitMirror: nereusBranch: mainCommit: a1b2c3d4e5f60718293a4b5c6d7e8f9012345678Last Build: triton-a1b2c3dStatus: Ready
A Trigger that waits says why in a Message line, with the command to run. Commit is the Mirror's commit the Trigger saw on its last pass, built or not yet. --output yaml prints the whole object.
Um Trigger que espera diz o porquê numa linha Message, com o comando a rodar. Commit é o commit do Mirror que o Trigger viu na última passada, construído ou ainda não. O --output yaml imprime o objeto inteiro.
trigger delete stops new Builds and leaves the ones it made
O trigger delete para os Builds novos e mantém os que fez
# No new Build of triton; triton-a1b2c3d stays$ nereus build trigger delete tritonbuild/triggers/triton deleted; the Builds it created stay Next steps: nereus build trigger list
A Trigger never deletes a Build: each one stays, with its image, until nereus build delete. --dry-run says what would go and changes nothing.
Um Trigger nunca apaga um Build: cada um fica, com a sua imagem, até o nereus build delete. O --dry-run diz o que sairia e não muda nada.
Where the ideas came from
- BuildKit: the builder, rootless
- crane: the push, with no shell
- Flux image automation: a controller that follows a source and acts on a new revision, the Trigger's shape
De onde vieram as ideias
- BuildKit: o builder, rootless
- crane: o push, sem shell
- Flux image automation: um controller que segue uma fonte e age numa revisão nova, a forma do Trigger
The full reasoning is in spec 0009 (the build reef's security design) and spec 0010 (the Trigger: a new commit on a Mirror builds a Workload).
O raciocínio completo está na spec 0009 (o desenho de segurança do reef build) e na spec 0010 (o Trigger: um commit novo num Mirror constrói um Workload).