The catalog reef
Every command that says what Nereus has: what runs, what is published, and whether it holds together
O reef catalog
Todos os comandos que dizem o que o Nereus tem: o que roda, o que é publicado e se tudo se sustenta
The source of truth for the commands of the catalog reef (#477, ADR 0016). The kinds and the commands are built, with real output (#902, the catalog reef's kinds and commands); check runs in the local checks (#903, catalog check and make catalog-check); and the catalog Nereid writes status (#904, the catalog Nereid writes status).
The commands follow ADR 0013: nereus catalog <kind> <verb> <name>, kinds singular, workload the reef's default kind, --dry-run everywhere, and output lines that name the object by its full path with the owner and the type in a parenthesis.
A fonte da verdade dos comandos do reef catalog (#477, ADR 0016). Os kinds e os comandos estão prontos, com a saída real (#902, os kinds e os comandos do reef catalog); o check roda nos checks locais (#903, catalog check e make catalog-check); e o Nereid catalog escreve o status (#904, o Nereid catalog escreve o status).
Os comandos seguem o ADR 0013: nereus catalog <kind> <verbo> <nome>, kinds no singular, workload o kind padrão do reef, --dry-run em todo lugar, e linhas de saída que nomeiam o objeto pelo caminho completo, com o owner e o type entre parênteses.
Workload runs, Package is published
- Workload: what runs, with
owner,type,audience,sourceandruntime - Package: what is published, with
owner,type,registry,name,audienceandsource - WorkloadType and PackageType: configurable, a name plus the answers it fills in; the platform never reads a type's name
- Template: the files of a new entry, rendered with Copier (its slide)
Workload roda, Package é publicado
- Workload: o que roda, com
owner,type,audience,sourceeruntime - Package: o que é publicado, com
owner,type,registry,name,audienceesource - WorkloadType e PackageType: configuráveis, um nome mais as respostas que ele preenche; a plataforma nunca lê o nome de um tipo
- Template: os arquivos de uma entrada nova, escritos com o Copier (o slide dele)
There is no Component, no System and no API kind (ADR 0016): a leaf Project of the tenancy tree plays the part of the system, and an API is a Workload with an audience. A thing that runs and is published is two entries.
owner is {kind, name} in the tenancy tree (ADR 0015), and --owner <kind>/<name> is optional once [the current owner](tenancy.html#config-owner) is set.
Não há Component, System nem kind API (ADR 0016): um Project folha da árvore tenancy faz o papel do sistema, e uma API é um Workload com audience. Uma coisa que roda e é publicada são duas entradas.
owner é {kind, name} na árvore tenancy (ADR 0015), e --owner <kind>/<name> é opcional quando [o owner atual](tenancy.html#config-owner) está definido.
How does what runs get into the catalog?
Como o que roda entra no catálogo?
One apply registers the repository
Um apply registra o repositório
# The files of catalog/ are the truth; Triton already exists and is imported the same way$ nereus catalog apply \ --from-file catalog/✓ catalog/workloadtypes/controller created✓ catalog/workloadtypes/service created✓ catalog/packagetypes/cli created✓ catalog/packagetypes/image created✓ catalog/workloads/flux created (owner: Project/nereids, type: controller)✓ catalog/workloads/keycloak created (owner: Project/nereids, type: controller)✓ catalog/workloads/openbao created (owner: Project/nereids, type: controller)✓ catalog/workloads/triton created (owner: Project/triton, type: service)✓ catalog/packages/nereus created (owner: Project/core, type: cli, registry: pypi)✓ catalog/packages/openbao-image created (owner: Project/nereids, type: image, registry: oci) Next steps: nereus catalog check
apply is the group's, never a kind's (ADR 0013): it takes files or folders of .yaml and creates or updates each entry; running it again prints unchanged. The types go first, so an entry finds its type, and one entry that cannot be written refuses the whole folder. This output leaves out the other five types. The file is the truth, so the catalog Nereid (#904) will write only status.
The golden path ends here: [the template slide](#template-render) writes the files and this apply registers them (the Developer Control Plane deck links to this slide).
O apply é do grupo, nunca de um kind (ADR 0013): ele aceita arquivos ou pastas de .yaml e cria ou atualiza cada entrada; rodar de novo imprime unchanged. Os tipos vão primeiro, para uma entrada achar o seu tipo, e uma entrada que não pode ser escrita recusa a pasta inteira. Esta saída omite os outros cinco tipos. O arquivo é a verdade, então o Nereid catalog (#904) vai escrever só o status.
O golden path termina aqui: [o slide do template](#template-render) escreve os arquivos e este apply os registra (o deck Developer Control Plane linka este slide).
create writes an entry from flags
O create escreve uma entrada de flags
# No --owner: the current owner is used and named in the output$ nereus catalog workload create edge-cloudflare \ --type controller \ --audience none \ --repository https://github.com/getnereus/nereus \ --ref branch=main \ --path controllers/edge-cloudflare/ \ --dry-runcatalog/workloads/edge-cloudflare would be created (owner: Project/nereids, type: controller)Nothing changed (--dry-run). # The file to commit and apply, not the object$ nereus catalog workload create edge-cloudflare \ --type controller \ --audience none \ --ref branch=main \ --dry-run \ --output yamlapiVersion: catalog.getnereus.dev/v1alpha1kind: Workloadmetadata: name: edge-cloudflarespec: owner: kind: Project name: nereids type: controller source: ref: branch: main
--audience none is spelled audience: [] in the file: audience is required on every Workload and never comes from a type, so none says on purpose that nobody talks to it.
--ref <field>=<value> mirrors the structured field (Flux's branch, tag, semver, name, commit) and repeats (--ref branch=main --ref commit=<sha>); one string such as main is refused. --template is not here: a template writes files before the catalog ([the template slide](#template-render)).
--audience none se escreve audience: [] no arquivo: audience é obrigatório em todo Workload e nunca vem de um tipo, então none diz de propósito que ninguém fala com ele.
--ref <campo>=<valor> espelha o campo estruturado (branch, tag, semver, name, commit do Flux) e se repete (--ref branch=main --ref commit=<sha>); uma string solta como main é recusada. O --template não está aqui: um template escreve arquivos antes do catálogo ([o slide do template](#template-render)).
list searches by type
O list busca por tipo
# The catalog lists what it has, one row per Workload$ nereus catalog list \ --type serviceWORKLOAD OWNER TYPE AUDIENCE STATUStriton Project/triton service agents, people DeploymentNotFound # One entry, as the platform holds it$ nereus catalog get triton \ --output yaml
workload is the default kind, so nereus catalog list is nereus catalog workload list. STATUS is the Ready the catalog Nereid writes (#904), - while no Nereid has answered. A DELIVERIES column, read from the delivery reef and never written, comes with #845 (the delivery reef); what was deployed, one row per Workload and Environment pair, is [delivery list](delivery.html#delivery-list), and nereus workload list is [its own slide](delivery.html#workload-list).
workload é o kind padrão, então nereus catalog list é nereus catalog workload list. O STATUS é o Ready que o Nereid catalog escreve (#904), - enquanto nenhum Nereid respondeu. Uma coluna DELIVERIES, lida do reef delivery e nunca escrita, chega com o #845 (o reef delivery); o que foi implantado, uma linha por par Workload e Environment, é o [delivery list](delivery.html#delivery-list), e o nereus workload list tem [o slide dele](delivery.html#workload-list).
delete never touches what runs
O delete nunca toca no que roda
# The entry leaves the catalog; the Deployment, if any, stays$ nereus catalog delete openbao✓ catalog/workloads/openbao deleted
The catalog describes, it does not run: deleting an entry never touches the Deployment or the Nereid it names in runtime; removing a delivery is [delivery delete](delivery.html#delivery-delete).
O catálogo descreve, não executa: apagar uma entrada nunca toca o Deployment nem o Nereid que ela nomeia em runtime; remover uma delivery é o [delivery delete](delivery.html#delivery-delete).
How does what is published get into the catalog?
Como o que é publicado entra no catálogo?
A Package says where it is published
Um Package diz onde é publicado
# The same verbs, the kind in the path$ nereus catalog package create nereus \ --owner project/core \ --type cli \ --registry pypi \ --name nereus \ --audience people \ --audience programs \ --ref branch=main \ --path cli/ \ --dry-runcatalog/packages/nereus would be created (owner: Project/core, type: cli, registry: pypi)Nothing changed (--dry-run). # A registry the type does not take is refused before it is written$ nereus catalog package create base-image \ --owner project/core \ --type image \ --registry pypi \ --name base-image \ --audience programs \ --dry-run✗ catalog/packages/base-image: type image takes the registries oci, not pypi Nothing was changed.
A Package has a type, a registry and an audience; the packaging format follows from the registry and is not a field. registry takes git, oci, http, pypi, npm and maven, and a PackageType allows only some of them.
A published Package names its tag or semver range, a Workload its branch: --ref tag=v1.2.0, --ref semver=">=1.2". list, get and delete are the Workload's, with the kind in the path (nereus catalog package list).
Um Package tem type, registry e audience; o formato do pacote segue do registry e não é um campo. registry aceita git, oci, http, pypi, npm e maven, e um PackageType permite só alguns deles.
Um Package publicado nomeia sua tag ou faixa semver, um Workload o seu branch: --ref tag=v1.2.0, --ref semver=">=1.2". list, get e delete são os do Workload, com o kind no caminho (nereus catalog package list).
Which shapes does the catalog know?
Que formas o catálogo conhece?
A type is a name plus answers
Um tipo é um nome mais respostas
# The shapes of what runs, and what each one answers$ nereus catalog workload-type listTYPE RUNS TRIGGER STATUScontroller always event Readyfunction once request, event Readyjob once schedule Readyservice always request Readystatic-site always request Readyweb-app always request Readyworker always event Ready # What a Package may be, and where it may be published$ nereus catalog package-type listTYPE REGISTRIES STATUSchart oci Readycli pypi, npm, oci Readyimage oci Readylibrary pypi, npm, maven Readymodule git, oci Readyreef git, oci Ready
Types are files in catalog/workload-types/ and catalog/package-types/: a new kind of software is a new file, never a change to the reef or an ADR, as a StorageClass is a name plus the parameters its provisioner takes. Both kinds take create, get and delete like any other, and the group's apply takes their files; a type in use is not deleted, and the refusal names who uses it.
Only runs and trigger come from a type; audience never does, since "who is this for?" is the one question no type can answer. list is alphabetical, like every list.
Tipos são arquivos em catalog/workload-types/ e catalog/package-types/: um tipo novo de software é um arquivo novo, nunca uma mudança no reef ou um ADR, como uma StorageClass é um nome mais os parâmetros que seu provisioner aceita. Os dois kinds aceitam create, get e delete como qualquer outro, e o apply do grupo aceita os arquivos deles; um tipo em uso não é apagado, e a recusa nomeia quem o usa.
Só runs e trigger vêm de um tipo; audience nunca vem, pois "para quem é isto?" é a única pergunta que nenhum tipo responde. O list é alfabético, como todo list.
Does the catalog hold together?
O catálogo se sustenta?
A contradiction fails, a gap points
Contradição falha, lacuna só aponta
# Nereus's own catalog today: no contradiction, and each gap with its issue$ nereus catalog check✓ tenancy: 1 organization, 5 projects, every owner resolves✓ types: every workload type and package type resolves, every registry allowed! catalog/workloads/triton: audience people, agents, no edge reef (#470)! catalog/workloads/triton: uses nats, no messaging reef (#576)! catalog/packages/nereus: not found on pypi0 contradictions, 3 gaps # The repository's files, in the local checks before a PR; the cluster needs only the tenancy reef$ make catalog-check
check is deterministic: it joins each entry to the tenancy tree, the types, the registries and the reefs that fulfil it. With no flag it reads the entries in the cluster, so an owner orphaned by deleting its Project shows; --from-file catalog/ reads the files, with a cluster that has the tenancy reef. A gap is where the catalog tells the truth and the platform cannot fulfil it yet; it prints ! with its issue and the command passes, and it disappears once the cluster serves the reef. Only pypi is looked up: a lookup with no answer prints pypi lookup did not run, never a pass.
make catalog-check joins the local checks before a PR that touches catalog/, reefs/catalog/ or the tenancy, since CI is off. With no cluster it fails and says so.
O check é determinístico: ele junta cada entrada à árvore tenancy, aos tipos, aos registries e aos reefs que a cumprem. Sem flag, lê as entradas no cluster, então um owner órfão por ter o seu Project apagado aparece; --from-file catalog/ lê os arquivos, com um cluster que tem o reef tenancy. Uma lacuna é onde o catálogo diz a verdade e a plataforma ainda não consegue cumprir; ela imprime ! com a sua issue, o comando passa, e ela some quando o cluster serve o reef. Só o pypi é consultado: uma consulta sem resposta imprime pypi lookup did not run, nunca um sucesso.
O make catalog-check entra nos checks locais antes de um PR que toca em catalog/, reefs/catalog/ ou na tenancy, já que a CI está desligada. Sem cluster, ele falha e diz o motivo.
A contradiction fails the command
Uma contradição falha o comando
# An owner that does not exist, a registry the type does not allow, an audience missing$ nereus catalog check✗ catalog/workloads/api: owner Project/ghost does not exist✗ catalog/packages/base-image: type image takes the registries oci, not pypi✗ catalog/workloads/worker: audience is missing3 contradictions, 0 gaps # The exit code is what the local check and a script read$ echo $?1
Three things are contradictions: the file says something impossible. Anything the platform could fulfil but does not yet is a gap, and a gap never fails the command.
Três coisas são contradições: o arquivo diz algo impossível. O que a plataforma poderia cumprir mas ainda não cumpre é uma lacuna, e uma lacuna nunca faz o comando falhar.
Where do a new entry's files come from?
De onde vêm os arquivos de uma entrada nova?
A template writes, apply registers
- nereus template render: the shortcut of
nereus catalog template render, with Copier;createmakes theTemplateobject andapplytakes only files - nereus catalog apply: registers what the rendered files say, and leaves what exists
unchanged
O template escreve, o apply registra
- nereus template render: o atalho de
nereus catalog template render, com o Copier;createfaz o objetoTemplateeapplyaceita só arquivos - nereus catalog apply: registra o que os arquivos escritos dizem, e deixa o que existe como
unchanged
Template is a kind of the catalog (ADR 0016), so its commands are the catalog's; the slide that shows render with its output lives in [the delivery deck](delivery.html#template-render) and is not repeated here. Creating the repository stays with #279 (the repository reef).
Template é um kind do catálogo (ADR 0016), então os comandos dele são os do catálogo; o slide que mostra o render com a sua saída vive no [deck delivery](delivery.html#template-render) e não é repetido aqui. Criar o repositório fica com o #279 (o reef repository).
Where the ideas came from
- Backstage, System model: the repository-owned entity, without
Component - Open Application Model, workload types: the characteristics of a workload
- Kubernetes, StorageClass: a type as a name plus its answers
- Flux, GitRepository: the structured
ref
De onde vieram as ideias
- Backstage, System model: a entidade que pertence ao repositório, sem
Component - Open Application Model, workload types: as características de um workload
- Kubernetes, StorageClass: um tipo como um nome mais as suas respostas
- Flux, GitRepository: o
refestruturado
The full credits are in ADR 0016.
Os créditos completos estão no ADR 0016.