The delivery reef
Every command that takes a Workload to an Environment, and says what runs
O reef delivery
Todos os comandos que levam um Workload a um Environment e dizem o que está rodando
The source of truth for the commands of the delivery reef (#477, ADR 0020). #845 built the first slice: the slides still planned point to the issues that build them.
The catalog's two shortcuts live here for now: nereus workload and nereus template go into the catalog reef, whose own deck is #570 (the catalog reef in the CLI reference), which links to these slides.
A fonte da verdade dos comandos do reef delivery (#477, ADR 0020). A #845 construiu a primeira fatia: os slides ainda planejados apontam para as issues que os constroem.
Os dois atalhos do catálogo ficam aqui por enquanto: nereus workload e nereus template entram no reef catalog, cujo deck é o #570 (o reef catalog na referência do CLI), que linka estes slides.
The Nereid turns a Delivery into a Release, and Flux installs it
- kubernetes: resolves the digest, writes the
Source, theTargetand theRelease, and the Delivery'sstatus - flux: installs the
Releasein the Environment, as it does today
O Nereid transforma uma Delivery em um Release, e o Flux instala
- kubernetes: resolve o digest, escreve o
Source, oTargete oRelease, e ostatusda Delivery - flux: instala o
Releaseno Environment, como já faz hoje
One writer per field (ADR 0005): the client writes the Delivery's spec, the Nereid kubernetes writes its status, and the flux Nereid keeps writing the Release's status. The last step depends on #828 (a Release reaches its Target's Environment).
One Nereid per platform it delivers to: a destination that is not Kubernetes is another Nereid, behind another Mandate, with the same nereus workload deploy and no Release.
Um escritor por campo (ADR 0005): o cliente escreve o spec da Delivery, o Nereid kubernetes escreve o status dela, e o Nereid flux continua escrevendo o status do Release. O último passo depende do #828 (um Release chega ao Environment do seu Target).
Um Nereid por plataforma para a qual ele entrega: um destino que não é Kubernetes é outro Nereid, atrás de outro Mandate, com o mesmo nereus workload deploy e sem Release.
Where does the delivery reef come from?
De onde vem o reef delivery?
The reef, then the Nereid that delivers to Kubernetes
O reef, depois o Nereid que entrega para Kubernetes
# The delivery reef's contract$ nereus reef apply delivery \ --from-file ./reefs/delivery/✓ core/reefs/delivery created (delivery.getnereus.dev/v1alpha1) # The Nereid, with the reef's default Mandate$ nereus nereid apply kubernetes \ --reef delivery✓ core/nereids/kubernetes created validatingadmissionpolicies/controller-kubernetes-read-tokens applied (its only tokens: a Registry's read identity, for that Registry, ten minutes at most)✓ core/mandates/kubernetes created (reef: delivery, nereid: kubernetes, default) Next steps: nereus workload deploy --help
The internal-developer-platform profile installs both once #845 adds them (ADR 0014). Installing by name keeps today's form until #487 (the verb that installs a reef or a Nereid by name) closes.
O profile internal-developer-platform instala os dois quando o #845 os adicionar (ADR 0014). Instalar por nome mantém a forma de hoje até o #487 (o verbo que instala um reef ou um Nereid por nome) fechar.
How does a developer run an image in an Environment?
Como um desenvolvedor roda uma imagem em um Environment?
One command takes a Workload to an Environment
Um comando leva um Workload a um Environment
# A Workload of the catalog, in the dev Environment$ nereus workload deploy hello@dev \ --image registry.example.com/hello:a1b2c3d✓ delivery/deliveries/hello-dev created Next steps: nereus delivery get hello-dev
hello@dev is sugar for hello --environment dev (ADR 0013). The name of the Delivery is generated once, <workload>-<environment>, and never changes; a name that belongs to another pair takes a short suffix from the hash of the pair (hello-dev-x-3f9a).
The Nereid resolves the tag, never the client, so the CLI and the portal behave the same (ADR 0020). The port comes from the image's ExposedPorts, overridden in the Workload.
hello@dev é açúcar para hello --environment dev (ADR 0013). O nome da Delivery é gerado uma vez, <workload>-<environment>, e nunca muda; um nome que pertence a outro par ganha um sufixo curto do hash do par (hello-dev-x-3f9a).
O Nereid resolve a tag, nunca o cliente, para o CLI e o portal se comportarem igual (ADR 0020). A porta vem do ExposedPorts da imagem, sobrescrita no Workload.
deploy never guesses the target
O deploy nunca adivinha o destino
# A bare name could change target in silence when a second Environment appears$ nereus workload deploy hello \ --image registry.example.com/hello:a1b2c3d✗ deploy needs the target. To deploy hello, run: # to the dev Environment nereus workload deploy hello@dev --image registry.example.com/hello:a1b2c3d
deploy takes the unique name, hello@dev or hello --environment dev, and refuses a bare hello even with one Environment (ADR 0020). A refusal lists what to run (ADR 0013, ADR 0012).
O deploy aceita o nome único, hello@dev ou hello --environment dev, e recusa um hello solto mesmo com um só Environment (ADR 0020). Uma recusa lista o que rodar (ADR 0013, ADR 0012).
deploy runs what a Build pushed, by its digest
O deploy roda o que um Build publicou, pelo digest
# The image of a Build that succeeded, never a tag that may move$ nereus workload deploy hello@dev \ --build hello-a1b2c3d✓ delivery/deliveries/hello-dev created Next steps: nereus delivery get hello-dev # A Build still running is refused, with what to run$ nereus workload deploy hello@dev \ --build hello-b4c5d6e✗ build/builds/hello-b4c5d6e is Running, not Succeeded. To follow it, run: nereus build get hello-b4c5d6e
--build takes the place of --image: the CLI reads the Build's digest and its Repository's pull address, and writes <pull address>/hello@sha256:... into the Delivery. A digest is never looked up again, so the Delivery runs exactly what was built. A Build of another Workload, or one that has not succeeded, is refused.
--build substitui o --image: o CLI lê o digest do Build e o endereço de pull do seu Repository, e escreve <endereço de pull>/hello@sha256:... na Delivery. Um digest nunca é consultado de novo, então a Delivery roda exatamente o que foi construído. Um Build de outro Workload, ou que não terminou com sucesso, é recusado.
Every deploy is a new request, even with the same tag
Cada deploy é um pedido novo, mesmo com a mesma tag
# The same tag, pushed again: the unique name works too$ nereus workload deploy hello-dev \ --image registry.example.com/hello:a1b2c3d✓ delivery/deliveries/hello-dev configured Next steps: nereus delivery get hello-dev
Each deploy writes spec.requestedAt, so the same tag changes spec and reaches a re-pushed image, as Flux's reconcile.fluxcd.io/requestedAt does.
The Nereid resolves once per request: a tag that moves with no new deploy never changes what runs in silence (ADR 0020).
Cada deploy escreve spec.requestedAt, então a mesma tag muda o spec e alcança uma imagem que recebeu novo push, como faz o reconcile.fluxcd.io/requestedAt do Flux.
O Nereid resolve uma vez por pedido: uma tag que muda de lugar sem novo deploy nunca muda o que está rodando em silêncio (ADR 0020).
--dry-run shows the Delivery, with the tag as typed
O --dry-run mostra a Delivery, com a tag como foi digitada
# Changes nothing; the digest comes from the Nereid, after the deploy$ nereus workload deploy hello@dev \ --image registry.example.com/hello:a1b2c3d \ --dry-rundelivery/deliveries/hello-dev would be created workload: hello environment: dev image: registry.example.com/hello:a1b2c3d
The price of resolving in the Nereid (ADR 0020): the client cannot show the digest before the deploy. With --output yaml it prints the object, ready for apply --from-file (ADR 0013).
O preço de resolver no Nereid (ADR 0020): o cliente não consegue mostrar o digest antes do deploy. Com --output yaml ele imprime o objeto, pronto para apply --from-file (ADR 0013).
--wait brings the Nereid's reason to the terminal
O --wait traz o motivo do Nereid para o terminal
# A tag that does not exist fails after the Delivery is written$ nereus workload deploy hello@dev \ --image registry.example.com/hello:does-not-exist \ --wait✓ delivery/deliveries/hello-dev configured✗ delivery/deliveries/hello-dev not ready: The registry does not have the tag does-not-exist of the repository registry.example.com/hello. To fix it, run: # deploy a tag that exists nereus workload deploy hello@dev --image registry.example.com/hello:<tag> # A tag that exists waits for it to run$ nereus workload deploy hello@dev \ --image registry.example.com/hello:a1b2c3d \ --wait✓ delivery/deliveries/hello-dev configured✓ delivery/deliveries/hello-dev ready (sha256:9f2c1e) Next steps: nereus workload logs hello-dev
Without --wait, the reason stays in the Delivery's status, and nereus delivery get shows it. The pattern is #846 (workload logs and the CLI's follow and wait).
Sem --wait, o motivo fica no status da Delivery, e o nereus delivery get o mostra. O padrão é o #846 (workload logs e o follow e wait do CLI).
What exists, what runs, and what does it print?
O que existe, o que roda e o que isso imprime?
workload list says what the catalog has
O workload list diz o que o catálogo tem
# One row per Workload; DELIVERIES counts them, 0 means not deployed$ nereus workload listWORKLOAD OWNER TYPE AUDIENCE DELIVERIES STATUSbilling Project/shop service programs 0 Readyhello Project/hello service people 2 Ready Next steps: nereus delivery list
A shortcut of nereus catalog workload list (ADR 0016, ADR 0013). The catalog reads the Deliveries to count them and never writes them.
Um atalho de nereus catalog workload list (ADR 0016, ADR 0013). O catálogo lê as Deliveries para contá-las e nunca as escreve.
delivery list says what was deployed
O delivery list diz o que foi implantado
# One row per Workload and Environment pair$ nereus delivery listNAME WORKLOAD ENVIRONMENT DIGEST READYhello-dev hello dev sha256:9f2c1e Truehello-stage hello stage sha256:77ab40 True # The deployments of one Workload$ nereus delivery list \ --workload helloNAME WORKLOAD ENVIRONMENT DIGEST READYhello-dev hello dev sha256:9f2c1e Truehello-stage hello stage sha256:77ab40 True
nereus delivery list is the one path (owner, 2026-11-03): Delivery is the reef's default kind, so it is nereus delivery delivery list, and nereus workload adds no second path to the same table.
O nereus delivery list é o único caminho (owner, 2026-11-03): Delivery é o kind padrão do reef, então ele é nereus delivery delivery list, e o nereus workload não abre uma segunda porta para a mesma tabela.
delivery get says what runs and where
O delivery get diz o que roda e onde
# The digest running, the namespace, and the previous digest$ nereus delivery get hello-devNAME WORKLOAD ENVIRONMENT DIGEST NAMESPACE READYhello-dev hello dev sha256:9f2c1e hello-dev True Previous digest: sha256:77ab40 Next steps: nereus workload logs hello-dev
It answers gap 8 of PR #836 (make scene-golden-path), nothing says what runs. The previous digest is the only history for now; rollback and update channels are open questions in ADR 0020.
Ele responde ao gap 8 do PR #836 (make scene-golden-path), nada diz o que está rodando. O digest anterior é o único histórico por enquanto; rollback e canais de atualização são perguntas abertas no ADR 0020.
workload logs reads a Delivery by its name or its pair
O workload logs lê uma Delivery pelo nome ou pelo par
# Follow what the app prints$ nereus workload logs hello-dev \ --follow[::ffff:127.0.0.1]:53792: response:200 # A Workload in several Environments lists them and picks none$ nereus workload logs hello✗ hello runs in 2 Environments. To read one, run: # in dev nereus workload logs hello@dev # in stage nereus workload logs hello@stage
The argument rule (ADR 0020): @ looks up the pair; without it, the Delivery's name, then a Workload with a single Environment. When both match different targets, the error lists the candidates.
It reads inside the Environment, with the Environment's own kubeconfig over a port-forward: a declared Stand-in, until the group moves behind the Nereus API (ADR 0018).
A regra do argumento (ADR 0020): @ procura o par; sem ele, o nome da Delivery, depois um Workload com um só Environment. Quando os dois apontam para destinos diferentes, o erro lista os candidatos.
Ele lê dentro do Environment, com o kubeconfig do próprio Environment por um port-forward: um Stand-in declarado, até o grupo passar para trás da Nereus API (ADR 0018).
How is a Delivery kept in a file, or removed?
Como manter uma Delivery em um arquivo, ou removê-la?
A Delivery in a file resolves once
Uma Delivery em um arquivo resolve uma vez
# Write it as a file, then apply the file$ nereus workload deploy hello@dev \ --image registry.example.com/hello:a1b2c3d \ --dry-run \ --output yamlapiVersion: delivery.getnereus.dev/v1alpha1kind: Deliverymetadata: name: hello-dev # The same file again changes nothing$ nereus delivery apply \ --from-file delivery/delivery/deliveries/hello-dev unchanged
Applying the same file prints unchanged: moving to a re-pushed tag takes nereus workload deploy or a new spec.requestedAt (ADR 0020). nereus delivery create builds from flags and fails when the Delivery exists (ADR 0013). It waits for each Delivery to be Ready and brings the Nereid's reason to the terminal; --wait=false leaves right after writing.
Aplicar o mesmo arquivo imprime unchanged: ir para uma tag com novo push exige nereus workload deploy ou um novo spec.requestedAt (ADR 0020). O nereus delivery create constrói a partir de flags e falha quando a Delivery existe (ADR 0013). Ele espera cada Delivery ficar Ready e traz o motivo do Nereid para o terminal; --wait=false sai logo depois de escrever.
Deleting a Delivery takes the app out of the Environment
Apagar uma Delivery tira o app do Environment
# The Workload stays in the catalog$ nereus delivery delete hello-dev✓ delivery/deliveries/hello-dev deleted Next steps: nereus workload list
The Nereid removes the Release and the Target it wrote; the shared Repository and Source stay, since other Deliveries use them. The Workload's catalog entry is another reef's and stays too.
O Nereid remove o Release e o Target que escreveu; o Repository e o Source compartilhados ficam, porque outras Deliveries os usam. A entrada do Workload no catálogo é de outro reef e fica também.
Where do a new Workload's files come from?
De onde vêm os arquivos de um Workload novo?
A template writes files, and the catalog registers them
Um template escreve arquivos, e o catálogo os registra
# The files of a new Workload, with Copier$ nereus template render python-service \ --path ./hello \ --param name=hello✓ catalog/templates/python-service rendered at ./hello Next steps: nereus catalog apply --from-file ./hello/catalog/
A shortcut of nereus catalog template render (ADR 0016): Template is a kind of the catalog. Creating the repository stays with #279 (the repository reef). The verb is render because create makes the Template object and apply takes only files (ADR 0013).
Um atalho de nereus catalog template render (ADR 0016): Template é um kind do catálogo. Criar o repositório fica com o #279 (o reef repository). O verbo é render porque create faz o objeto Template e apply aceita só arquivos (ADR 0013).
Where the ideas came from
- Flux:
requestedAt, and aHelmReleaseon a remote cluster - Kubernetes, Images: why a digest, and not a tag
- bjw-s app-template: the curated chart
- Copier: the engine of
template render
De onde vieram as ideias
- Flux:
requestedAt, e umHelmReleaseem um cluster remoto - Kubernetes, Images: por que digest, e não tag
- bjw-s app-template: o chart curado
- Copier: o motor do
template render
The full credits are in ADR 0020 and ADR 0016. Kargo's Stage and Freight are the reference for update channels, if they come.
Os créditos completos estão no ADR 0020 e no ADR 0016. O Stage e o Freight do Kargo são a referência para canais de atualização, se vierem.