The tenancy reef
Every command of the tenancy reef: whose a thing is, as a tree of Organizations and Projects
O reef tenancy
Todos os comandos do reef tenancy: de quem é cada coisa, numa árvore de Organizations e Projects
The source of truth for the commands of the tenancy reef (#477, #569 (the tenancy reef in the CLI reference)). Every command here is an idea: none is built yet. The reef comes from ADR 0015 (tenancy: a tenancy reef whose kinds come from each instance, with one fixed shape), and #573 builds it.
Nereus is born multi-tenant (#21, Organization and nested Projects): an Organization is the boundary of people, permissions and isolation, a Project sits under an Organization or under another Project, and whatever needs to say whose a thing is points to that tree.
A fonte da verdade dos comandos do reef tenancy (#477, #569 (o reef tenancy na referência do CLI)). Todo comando aqui é uma ideia: nenhum está pronto ainda. O reef vem do ADR 0015 (tenancy: um reef tenancy cujos kinds vêm de cada instância, com uma forma fixa), e o #573 o constrói.
O Nereus nasce multi-tenant (#21, Organization e Projects aninhados): uma Organization é a fronteira de pessoas, permissões e isolamento, um Project fica sob uma Organization ou sob outro Project, e tudo o que precisa dizer de quem é uma coisa aponta para essa árvore.
The kinds come from each instance, the shape is fixed
- A node: every kind of
tenancy.getnereus.dev/v1alpha1has an optionalspec.parent: {kind, name}; one with no parent is a root - The boundary: one kind carries
tenancy.getnereus.dev/boundary: "true"; here,Organization
Os kinds vêm de cada instância, a forma é fixa
- Um nó: todo kind de
tenancy.getnereus.dev/v1alpha1tem umspec.parent: {kind, name}opcional; um sem parent é uma raiz - A fronteira: um kind leva
tenancy.getnereus.dev/boundary: "true"; aqui,Organization
This instance applies Organization and Project; another instance may apply its own kinds (departments and squads, say) from its own reefs/tenancy/, and its catalog still works, because the contract is the shape of every kind of the group, not the kind names (ADR 0015).
A Project is not a namespace: it is cluster-scoped, nests, and runs in several environments at once (Triton on the kept k3d cluster and on a pr-<n> vcluster is one Project in two namespaces). The first version has no tenancy Nereid: the API keeps the tree, as it keeps the core kinds.
Esta instância aplica Organization e Project; outra instância pode aplicar os seus próprios kinds (departamentos e squads, por exemplo) a partir do seu próprio reefs/tenancy/, e o seu catálogo continua funcionando, porque o contrato é a forma de todo kind do grupo, não os nomes dos kinds (ADR 0015).
Um Project não é um namespace: ele é cluster-scoped, se aninha, e roda em vários ambientes ao mesmo tempo (o Triton no cluster k3d mantido e num vcluster pr-<n> é um Project em dois namespaces). A primeira versão não tem Nereid de tenancy: a API guarda a árvore, como guarda os kinds do core.
Where do the tenancy kinds come from?
De onde vêm os kinds de tenancy?
The tenancy reef, with the kinds of this instance
O reef tenancy, com os kinds desta instância
# The CRDs of this instance, from its reefs/tenancy/$ nereus reef apply tenancy \ --from-file reefs/tenancy/✓ core/reefs/tenancy created (tenancy.getnereus.dev/v1alpha1: organizations, projects) Next steps: nereus tenancy organization create <organization>
The output lists the kinds the reef created, in the plural, after its group (owner, 2026-10-30, ADR 0015), a line every reef's nereus reef apply grows: here they are this instance's, read from the CRDs in reefs/tenancy/, so another instance would read departments, squads.
No Nereid and no Mandate follow: the API keeps the tree itself in the first version. A tenancy Nereid comes when the tree is synced with another system (OpenFGA tuples, Keycloak groups).
nereus tenancy appears once the reef is applied (#647): the CLI builds the group from its commands cache, which reef apply refreshes, so a cluster without the reef has no tenancy command, and every profile's nereus init applies it.
A saída lista os kinds que o reef criou, no plural, depois do seu grupo (owner, 2026-10-30, ADR 0015), uma linha que o nereus reef apply de todo reef ganha: aqui eles são os desta instância, lidos dos CRDs em reefs/tenancy/, então outra instância leria departments, squads.
Nenhuma Nereid e nenhum Mandate vêm depois: a API guarda a própria árvore na primeira versão. Uma Nereid de tenancy vem quando a árvore for sincronizada com outro sistema (tuplas do OpenFGA, grupos do Keycloak).
O nereus tenancy aparece quando o reef é aplicado (#647): o CLI constrói o grupo a partir do seu cache de comandos, que o reef apply atualiza, então um cluster sem o reef não tem comando tenancy, e o nereus init de todo perfil o aplica.
No Nereid by design: the tenancy reef is Ready with none
Nenhuma Nereid por design: o reef tenancy fica Ready sem nenhuma
# Right after a plain init: core, and the tenancy reef every profile applies$ nereus statusREEF NEREID VERSION STATUS AGEcore built-in 0.1.0 Ready 2mtenancy - - Ready 2m
A reef that needs no Nereid reads Ready, not Waiting (#651): every CRD in reefs/tenancy/ carries the annotation core.getnereus.dev/nereid: "none", so nereus status knows the API keeps the reef's objects, as it keeps core's (ADR 0015). A reef that waits for a Nereid it has not got yet still reads Waiting.
nereus status --output json says why in the row's reason: "The tenancy reef needs no Nereid: the API keeps its objects." The annotation goes on every CRD of a reef or on none; a reef with some CRDs annotated and others not is refused by nereus reef apply.
Um reef que não precisa de Nereid aparece Ready, não Waiting (#651): todo CRD em reefs/tenancy/ leva a annotation core.getnereus.dev/nereid: "none", então o nereus status sabe que a API guarda os objetos do reef, como guarda os do core (ADR 0015). Um reef que espera uma Nereid que ainda não tem continua Waiting.
O nereus status --output json diz por quê no reason da linha: "The tenancy reef needs no Nereid: the API keeps its objects." A annotation vai em todo CRD de um reef ou em nenhum; um reef com alguns CRDs anotados e outros não é recusado pelo nereus reef apply.
How does a Project find its place under an Organization?
Como um Project encontra o seu lugar sob uma Organization?
Another boundary: an Organization, the root of its tree
Outra fronteira: uma Organization, a raiz da sua árvore
# The kind with the boundary annotation takes no parent$ nereus tenancy organization create example✓ tenancy/organizations/example created Next steps: nereus tenancy organization list
nereus init already wrote Nereus's own tree (#647): its step tenancy tree applies tenancy/ right after the reef, so a fresh cluster starts with the Organization getnereus and its Projects ([apply](#apply)). organization create adds another one, here example.
The command is built from the reef's schema (ADR 0013, command conventions): nereus tenancy <kind> <verb> <name>, kinds singular, each kind with create, list, get and delete, built from the cluster's CRDs (a flag per string field of spec, such as --repository), apply for the whole group, and --dry-run on every command that changes something: its lines end in (dry run).
O nereus init já escreveu a própria árvore do Nereus (#647): o seu passo tenancy tree aplica tenancy/ logo depois do reef, então um cluster novo começa com a Organization getnereus e os seus Projects ([apply](#apply)). O organization create adiciona outra, aqui example.
O comando é construído a partir do schema do reef (ADR 0013, convenções de comando): nereus tenancy <kind> <verb> <name>, kinds no singular, cada kind com create, list, get e delete, construídos a partir dos CRDs do cluster (uma flag por campo string do spec, como --repository), apply para o grupo inteiro, e --dry-run em todo comando que muda algo: as suas linhas terminam em (dry run).
A Project under the Organization, the path from the root
Um Project sob a Organization, o caminho desde a raiz
# A repository, under the Organization$ nereus tenancy project create shop \ --parent organization/example \ --repository https://github.com/example/shop✓ tenancy/organizations/example/projects/shop created Next steps: nereus tenancy project list
The output line names the Project by its full path, parents before children (ADR 0013), as Azure's resource ids do: the CLI climbs spec.parent to the root to write it.
--parent <kind>/<name> takes a kind of the group, in the singular, and the CLI refuses a parent that does not exist; --repository is a field of this instance's Project.
A linha de saída nomeia o Project pelo seu caminho completo, pais antes dos filhos (ADR 0013), como os resource ids do Azure fazem: o CLI sobe o spec.parent até a raiz para escrevê-la.
--parent <kind>/<name> recebe um kind do grupo, no singular, e o CLI recusa um parent que não existe; --repository é um campo do Project desta instância.
A Project under another Project
Um Project sob outro Project
# A part of the shop, inside it$ nereus tenancy project create checkout \ --parent project/shop✓ tenancy/organizations/example/projects/shop/projects/checkout created Next steps: nereus tenancy project list # A parent that does not exist changes nothing$ nereus tenancy project create orphan \ --parent project/missing✗ tenancy/projects/orphan: parent Project/missing does not exist. To fix it, run: nereus tenancy project list Nothing was changed.
Nested Projects take the place of Backstage's Domain and subdomain, and a leaf Project plays the part of its System, so there is no System kind (owner, 2026-10-29, #21).
The CLI checks that the parent exists (#647), since the API cannot: the admission policy refuses a node that is its own parent and a parent of a kind outside the reef (#646), and a climb stops after 32 levels, so a loop never hangs it.
Projects aninhados tomam o lugar do Domain e do subdomain do Backstage, e um Project folha faz o papel do seu System, então não há kind System (owner, 2026-10-29, #21).
O CLI confere que o parent existe (#647), já que a API não consegue: a admission policy recusa um nó que é o próprio parent e um parent de um kind fora do reef (#646), e uma subida para depois de 32 níveis, então um ciclo nunca a trava.
Each Project with its parent, the path only in get
Cada Project com o seu parent, o caminho só no get
# One row per Project, in the tree's order$ nereus tenancy project listPROJECT PARENT REPOSITORYshop Organization/example https://github.com/example/shopcheckout Project/shop -nereus Organization/getnereus https://github.com/getnereus/nereuscore Project/nereus -docs Project/nereus -nereids Project/nereus -triton Project/nereus -
The columns are the Project, its parent as Kind/name and the kind's string fields (#569's recommendation), here its repository: a full path would make the table as wide as the tree is deep. The rows go in the tree's order, parents before children and siblings by name.
As colunas são o Project, o seu parent como Kind/name e os campos string do kind (a recomendação do #569), aqui o seu repositório: um caminho completo deixaria a tabela tão larga quanto a árvore é funda. As linhas vêm na ordem da árvore, pais antes dos filhos e irmãos por nome.
One Project in full: its path and its boundary
Um Project por inteiro: o seu caminho e a sua fronteira
# The path climbs spec.parent to the root$ nereus tenancy project get checkoutName: checkoutKind: ProjectPath: tenancy/organizations/example/projects/shop/projects/checkoutParent: Project/shopBoundary: Organization/exampleRepository: -
The boundary is the first node up the tree, the node itself included, whose kind carries the boundary annotation, found without knowing the kind names, as catalog check finds it (ADR 0015).
A fronteira é o primeiro nó subindo a árvore, o próprio nó incluído, cujo kind leva a annotation de fronteira, encontrado sem conhecer os nomes dos kinds, como o catalog check o encontra (ADR 0015).
Nereus's own tree, from files, parents before children
A própria árvore do Nereus, de arquivos, pais antes dos filhos
# The Organization and the Projects of this repository, in tenancy/: init wrote them$ nereus tenancy apply \ --from-file tenancy/tenancy/organizations/getnereus unchangedtenancy/organizations/getnereus/projects/nereus unchangedtenancy/organizations/getnereus/projects/nereus/projects/core unchangedtenancy/organizations/getnereus/projects/nereus/projects/docs unchangedtenancy/organizations/getnereus/projects/nereus/projects/nereids unchangedtenancy/organizations/getnereus/projects/nereus/projects/triton unchanged Next steps: nereus tenancy --help
apply takes files or folders of .yaml, of any kind of the group, and applies parents before children whatever the order of the files (ADR 0013), refusing a missing parent or a loop before it writes anything. apply belongs to the group, not to a kind (no project apply): the files name their kinds, and each line ends in created, configured or unchanged.
The first entries are Nereus itself (ADR 0015, dogfooding): the Organization getnereus, the Project nereus, and core, nereids, triton and docs under it. nereus init applies them in its step tenancy tree (6 created), so the same files again read unchanged.
O apply recebe arquivos ou pastas de .yaml, de qualquer kind do grupo, e aplica os pais antes dos filhos seja qual for a ordem dos arquivos (ADR 0013), recusando um parent que falta ou um ciclo antes de escrever qualquer coisa. O apply é do grupo, não de um kind (não há project apply): os arquivos nomeiam os seus kinds, e cada linha termina em created, configured ou unchanged.
As primeiras entradas são o próprio Nereus (ADR 0015, dogfooding): a Organization getnereus, o Project nereus, e core, nereids, triton e docs sob ele. O nereus init as aplica no seu passo tenancy tree (6 created), então os mesmos arquivos de novo leem unchanged.
A node with children waits for them
Um nó com filhos espera por eles
# A Project with a child is refused$ nereus tenancy project delete shop✗ tenancy/organizations/example/projects/shop has 1 child (checkout): delete it first, or it with it: nereus tenancy project delete shop --cascade --dry-run Nothing was changed.
A node with children is refused (#647): deleting it alone would leave its children pointing at nothing. The message says what holds it and what to do (ADR 0012, error messages). A node never moves: spec.parent cannot change once set (#646), so there is no "move them first". A leaf is deleted with one ✓ ... deleted line.
A node named as owner by something will be refused too (#934, a tenancy node that a catalog entry names as owner cannot be deleted): deleting it would leave the catalog and the environments pointing at nothing.
Um nó com filhos é recusado (#647): apagá-lo sozinho deixaria os seus filhos apontando para nada. A mensagem diz o que o segura e o que fazer (ADR 0012, mensagens de erro). Um nó nunca se move: o spec.parent não muda depois de definido (#646), então não há "mova-os antes". Uma folha é apagada com uma linha ✓ ... deleted.
Um nó nomeado como owner por alguma coisa também será recusado (#934, um nó da tenancy que uma entrada do catálogo nomeia como owner não pode ser apagado): apagá-lo deixaria o catálogo e os ambientes apontando para nada.
A node and everything under it, deepest first
Um nó e tudo o que está sob ele, do mais fundo primeiro
# First what it would delete$ nereus tenancy project delete shop \ --cascade \ --dry-runtenancy/organizations/example/projects/shop/projects/checkout deleted (dry run)tenancy/organizations/example/projects/shop deleted (dry run) # Then for real$ nereus tenancy project delete shop \ --cascade✓ tenancy/organizations/example/projects/shop/projects/checkout deleted✓ tenancy/organizations/example/projects/shop deleted Next steps: nereus tenancy project list
--cascade deletes everything under the node, deepest first, then the node, one line each (#647); with --dry-run it changes nothing and says what it would delete, so the refusal's next step is safe to run.
--cascade apaga tudo o que está sob o nó, do mais fundo primeiro, depois o nó, uma linha cada (#647); com --dry-run ele não muda nada e diz o que apagaria, então o próximo passo da recusa é seguro de rodar.
How does everything else say whose it is?
Como todo o resto diz de quem é?
Whatever points to the tree names its owner by kind and name
- The field:
owner: {kind, name}, a kind of the tenancy group, never an apiVersion and never a namespace - Who names it: the catalog's Workloads and Packages, an Environment, a resource Instance, a Mandate's
match
Tudo o que aponta para a árvore nomeia o seu owner por kind e nome
- O campo:
owner: {kind, name}, um kind do grupo tenancy, nunca uma apiVersion e nunca um namespace - Quem o nomeia: os Workloads e Packages do catálogo, um Environment, uma Instance de recurso, o
matchde um Mandate
One reference for every reef (ADR 0015): it replaces the spec.project of the first proposal, and a new reef that needs to say whose a thing is reuses it without learning a kind name. On the command line it is --owner <kind>/<name>, as nereus environment create a --owner project/nereus already takes ([the environment reef](environment.html#create)).
Uma referência para todo reef (ADR 0015): ela substitui o spec.project da primeira proposta, e um reef novo que precisa dizer de quem é uma coisa a reusa sem aprender um nome de kind. Na linha de comando ela é --owner <kind>/<name>, como o nereus environment create a --owner project/nereus já aceita ([o reef environment](environment.html#create)).
The current owner in the CLI's config, so --owner is optional
O owner atual na config do CLI, para o --owner ser opcional
# The node the next commands are for$ nereus config set owner project/triton✓ config: owner = Project/triton # No --owner: the output names the one used$ nereus catalog workload create api \ --type service \ --audience programs✓ catalog/workloads/api created (owner: Project/triton, type: service)
The flag wins over the config, and the output line names the owner used (owner's ask, 2026-10-30, ADR 0016), as kubectl config set-context --current --namespace and gcloud config set project do.
It came with #902 (the catalog reef's kinds and commands), where --owner is first needed, and is a core command: its reference is [nereus config set](../core.html#config-set) in the core deck (#482), next to the rest of nereus config; it is shown here for the tenancy it uses, and the catalog reef's deck (#570) links to this slide.
A flag ganha da config, e a linha de saída nomeia o owner usado (pedido do owner, 2026-10-30, ADR 0016), como o kubectl config set-context --current --namespace e o gcloud config set project fazem.
Ele chegou com o #902 (os kinds e os comandos do reef catalog), onde o --owner é preciso pela primeira vez, e é um comando do core: a sua referência é o [nereus config set](../core.html#config-set) no deck do core (#482), ao lado do resto do nereus config; ele aparece aqui pela tenancy que usa, e o deck do reef catalog (#570) aponta para este slide.