Nereus
A composable API platform: Reefs add the APIs, Nereids look after them, installed at runtime
Nereus
Uma plataforma de APIs componível: Reefs adicionam as APIs, Nereids cuidam delas, instalados em tempo de execução
What we want to say: the platform starts empty, and every capability arrives later as a Reef with a Nereid that looks after it.
Route: the idea, the model behind it, the first slice that runs today, and where the API is heading.
O que queremos dizer: a plataforma começa vazia, e toda capacidade chega depois como um Reef com um Nereid que cuida dele.
Roteiro: a ideia, o modelo por trás dela, a primeira fatia que roda hoje e para onde a API vai.
What changes when every capability is installed at runtime?
O que muda quando toda capacidade é instalada em tempo de execução?
nereus init prepares a cluster
Reefs come later
- Before: init installs the whole platform
- Here: a cluster, ready for Reefs
nereus init prepara um cluster
Os Reefs vêm depois
- Antes: o init instala a plataforma inteira
- Aqui: um cluster, pronto para Reefs
What we want to say: init does the least it can.
In the project this one grew from, init installed identity, the API, every controller, ingress and observability. Adding or swapping a capability meant changing init, and there was no way to run the platform with less, or with something else.
Here a platform is the set of Reefs applied to it and the Nereids that look after them, so two installations can differ in what they offer. A profile lists which ones nereus init applies (ADR 0014).
Source: docs/adr/0003-init-and-nereids-at-runtime.md.
O que queremos dizer: o init faz o mínimo possível.
No projeto de onde este nasceu, o init instalava identidade, a API, todos os controllers, ingress e observabilidade. Acrescentar ou trocar uma capacidade era mudar o init, e não havia como rodar a plataforma com menos, ou com outra coisa.
Aqui uma plataforma é o conjunto de Reefs aplicados a ela e dos Nereids que cuidam deles, então duas instalações podem oferecer coisas diferentes. Um profile lista quais o nereus init aplica (ADR 0014).
Fonte: docs/adr/0003-init-and-nereids-at-runtime.md.
A Nereid adds commands to the CLI
- Published: commands as data in its status
- Built: by the CLI at runtime
- Downloaded: no code
Um Nereid acrescenta comandos à CLI
- Publicados: comandos como dados no seu status
- Montados: pela CLI em tempo de execução
- Baixado: nenhum código
What we want to say: a new Nereid needs no new CLI release.
The Nereid describes its commands (names, arguments, help) in the status of its Nereid object. The CLI caches that description and builds the Reef's command group from it, as kubectl caches API discovery.
Nothing runs on the user's machine: a run goes to the Nereid, which runs it and returns the output.
Source: docs/adr/0004-reefs-extend-the-cli.md.
O que queremos dizer: um Nereid novo não precisa de uma versão nova da CLI.
O Nereid descreve os seus comandos (nomes, argumentos, ajuda) no status do seu objeto Nereid. A CLI guarda essa descrição em cache e monta com ela o grupo de comandos do Reef, como o kubectl faz com a descoberta da API.
Nada roda na máquina de quem usa: a execução vai para o Nereid, que roda e devolve a saída.
Fonte: docs/adr/0004-reefs-extend-the-cli.md.
All a Nereid publishes to build its commands
Tudo o que um Nereid publica para montar os comandos
3- path: [repo, add]4 help: Add a chart repository.5 arguments:6 - name: name7 help: Name of the repository.8 - name: url9 help: URL of the repository.10 examples:11 - description: add the example chart repository12 command: repo add example https://charts.example.com13- path: [repo, list]14 help: List the chart repositories.15 examples:16 - description: list the chart repositories17 command: repo list
What we want to say: two commands, with their help and examples, as data.
The reference Nereid of the first slice looks after the release Reef and publishes repo add and repo list. The CLI turns them into nereus release repo add NAME URL and nereus release repo list, with their help text and examples.
O que queremos dizer: dois comandos, com a ajuda e os exemplos, como dados.
O Nereid de referência da primeira fatia cuida do Reef release e publica repo add e repo list. A CLI transforma isso em nereus release repo add NAME URL e nereus release repo list, com o texto de ajuda e os exemplos.
Which words does the platform speak?
Que palavras a plataforma fala?
Three kinds describe a platform
- Reef: a capability, its own API group
- Nereid: the controller that looks after it
- Mandate: binds one Reef to one Nereid
Três kinds descrevem uma plataforma
- Reef: uma capacidade, com o seu API group
- Nereid: o controller que cuida dele
- Mandate: liga um Reef a um Nereid
What we want to say: the person asking names the Reef, never the tool behind it.
A Reef is a capability with its own API group: environment is environment.getnereus.dev. A Nereid is the controller that looks after one or more Reefs: vcluster today, azure-aks later, interchangeable. A Mandate binds a Reef to one Nereid and may override its target parameters; one Mandate per Reef is the default.
Kubernetes already does this for storage (PersistentVolumeClaim, StorageClass, provisioner) and for traffic (Gateway, GatewayClass, controllerName).
Source: docs/adr/0011-reefs-nereids-and-mandates.md; the layers of docs/adr/0002-conceptual-model.md.
O que queremos dizer: quem pede nomeia o Reef, nunca a ferramenta por trás dele.
Um Reef é uma capacidade com o seu API group: environment é environment.getnereus.dev. Um Nereid é o controller que cuida de um ou mais Reefs: vcluster hoje, azure-aks depois, intercambiáveis. Um Mandate liga um Reef a um Nereid e pode sobrescrever os seus parâmetros de destino; um Mandate por Reef é o padrão.
O Kubernetes já faz isso com storage (PersistentVolumeClaim, StorageClass, provisioner) e com tráfego (Gateway, GatewayClass, controllerName).
Fonte: docs/adr/0011-reefs-nereids-and-mandates.md; as camadas de docs/adr/0002-conceptual-model.md.
Every field has one writer
spec asked, status done
- spec: the API, or the CLI before it exists
- status: the Nereid
Todo campo tem um escritor
spec pedido, status feito
- spec: a API, ou a CLI enquanto ela não existe
- status: o Nereid
What we want to say: two writers on one field is a design bug.
With Nereids applied and swapped at runtime, several processes touch the same objects. When two of them write the same field, the last write wins and the bug shows up far from its cause.
Source: docs/adr/0005-one-writer-per-field.md.
O que queremos dizer: dois escritores num mesmo campo é um bug de design.
Com Nereids aplicados e trocados em tempo de execução, vários processos mexem nos mesmos objetos. Quando dois escrevem o mesmo campo, a última escrita vence e o bug aparece longe da causa.
Fonte: docs/adr/0005-one-writer-per-field.md.
The Nereid kind
The CLI writes spec, the Nereid status
O kind Nereid
A CLI escreve o spec, o Nereid o status
34 spec:35 type: object36 required: [image, reefs]37 properties:39 image:40 type: string43 reefs:44 type: array78 # person's login: which login runs the plans of its reef's Instance.79 login:80 type: string81 pattern: "^[a-z][a-z0-9-]{0,40}$"82 # The endpoints of its status the edge reef may publish (#1951, OWASP A01): the explicit grant, written by98 properties:99 type:
What we want to say: the rule is visible in the schema. spec (the image, pinned by digest, and the Reefs it looks after) is written by the CLI; status.conditions and status.commands belong to the Nereid.
O que queremos dizer: a regra aparece no schema. O spec (a imagem, fixada por digest, e os Reefs de que cuida) é escrito pela CLI; status.conditions e status.commands são do Nereid.
What can a person run today?
O que uma pessoa consegue rodar hoje?
Apply the environment Reef
The output says what's next
Aplique o Reef environment
A saída diz o que vem depois
# Apply the environment Reef$ nereus reef apply environment✓ core/reefs/environment created (environment.getnereus.dev/v1alpha1) Next steps: nereus environment --help nereus nereid apply <nereid> --reef environment
What we want to say: every command teaches the next one. The output says what changed, with kubectl's words (created, configured, unchanged, deleted), and ends with "Next steps:".
The Reef environment is a virtual cluster on the local k3d, as in the first proof of concept. It is in the profile internal-developer-platform (ADR 0014); its Nereid is still to be built, so this output is the contract, not a recording.
Source: docs/adr/0013-command-conventions.md.
O que queremos dizer: todo comando ensina o próximo. A saída diz o que mudou, com as palavras do kubectl (created, configured, unchanged, deleted), e termina com "Next steps:".
O Reef environment é um cluster virtual no k3d local, como na primeira prova de conceito. Ele está no profile internal-developer-platform (ADR 0014); o seu Nereid ainda vai ser construído, então esta saída é o contrato, não uma gravação.
Fonte: docs/adr/0013-command-conventions.md.
The vcluster Nereid's first Mandate becomes the default
O primeiro Mandate do Nereid vcluster vira o padrão
# Apply the vcluster Nereid to the environment Reef$ nereus nereid apply vcluster \ --reef environment✓ core/nereids/vcluster created, Ready, pinned to sha256:3f9c2a7e1b04: see 'nereus environment --help' core/mandates/vcluster created (reef: environment, nereid: vcluster, default) Next steps: nereus nereid list # See every Reef and the Nereid that looks after it$ nereus statusREEF NEREID VERSION STATUS AGEcore built-in 0.1.0 Ready 5menvironment vcluster 0.1.0 Ready 20ssecrets openbao 0.1.0 Ready 5m
What we want to say: the Reef stays, the Nereid is interchangeable. vcluster today on k3d; azure-aks may come later, behind the same Reef and the same commands.
Long options only, one per line: a command reads the same on a slide, in the docs and in a terminal.
nereus status is also the first tool of the MCP server, so an agent sees the same rows.
O que queremos dizer: o Reef fica, o Nereid é intercambiável. vcluster hoje no k3d; azure-aks pode vir depois, atrás do mesmo Reef e dos mesmos comandos.
Só opções longas, uma por linha: um comando se lê igual num slide, na documentação e num terminal.
nereus status também é a primeira ferramenta do servidor MCP, então um agente vê as mesmas linhas.
The first slice ends with a scene run from the CLI
- init: a k3d cluster, ready
- apply: a Reef and its Nereid
- run: the commands it published
- delete: they are gone
A primeira fatia termina com uma cena rodada pela CLI
- init: um cluster k3d, pronto
- apply: um Reef e o seu Nereid
- run: os comandos que ele publicou
- delete: eles somem
What we want to say: walking skeleton first. The thinnest slice that proves both ideas: init only prepares a cluster, and an applied Nereid extends the CLI.
The scene is test/scene, on a throwaway k3d cluster, and the walkthrough in the docs is the same scene one step per page, with the output each command really prints.
Source: docs/specs/0001-first-slice.md.
O que queremos dizer: walking skeleton primeiro. A fatia mais fina que prova as duas ideias: o init só prepara um cluster, e um Nereid aplicado estende a CLI.
A cena é o test/scene, num cluster k3d descartável, e o walkthrough da documentação é a mesma cena, um passo por página, com a saída que cada comando realmente imprime.
Fonte: docs/specs/0001-first-slice.md.
What is the API for?
Para que serve a API?
A profile lists the Reefs, Nereids and Mandates to install
- core: only the engine
- internal-developer-platform:
- authentication
- database
- environment
- metrics
- release
- secrets
Um profile lista os Reefs, Nereids e Mandates a instalar
- core: só o motor
- internal-developer-platform:
- authentication
- database
- environment
- metrics
- release
- secrets
What we want to say: Nereus is a generic engine, and the Internal Developer Platform is its first distribution.
nereus init with no profile installs core. nereus init --profile internal-developer-platform adds keycloak for authentication, cloudnative-pg for database, vcluster for environment, victoriametrics for metrics, flux for release and openbao for secrets, all open source and local.
Source: docs/adr/0014-profiles.md.
O que queremos dizer: o Nereus é um motor genérico, e a Internal Developer Platform é a sua primeira distribuição.
nereus init sem profile instala o core. nereus init --profile internal-developer-platform acrescenta keycloak para authentication, cloudnative-pg para database, vcluster para environment, victoriametrics para metrics, flux para release e openbao para secrets, tudo open source e local.
Fonte: docs/adr/0014-profiles.md.
The platform tooling landscape inspired us
Five planes, with one API in front
O platform tooling landscape nos inspirou
Cinco planos, com uma API na frente
What we want to say: this is where the idea started. The five planes come from the Platform tooling landscape of platformengineering.org; the API in front of them and its clients are what we drew on top.
The API is worth having for what crosses the Reefs. kubectl reaches the CRDs of one cluster. The CLI, a portal, an IDE reading an app.yaml and an agent all speak of Reefs, and none of them should need a kubeconfig.
Each box in a plane is a candidate Reef: Delivery is release, Identity is authentication, Data is database. The next slide shows what became of them.
Source: https://platformengineering.org/platform-tooling and docs/vision.md.
O que queremos dizer: foi daqui que a ideia partiu. Os cinco planos vêm do Platform tooling landscape do platformengineering.org; a API na frente deles e os seus clientes são o que desenhamos por cima.
A API vale pelo que atravessa os Reefs. O kubectl alcança os CRDs de um cluster. A CLI, um portal, uma IDE que lê um app.yaml e um agente falam todos de Reefs, e nenhum deles deveria precisar de um kubeconfig.
Cada caixa de um plano é um Reef candidato: Delivery é release, Identity é authentication, Data é database. O próximo slide mostra no que deram.
Fonte: https://platformengineering.org/platform-tooling e docs/vision.md.
What the profile runs today
A dashed line is not in the profile yet
O que o profile roda hoje
Linha tracejada ainda não está no profile
tenancy
The kinds Organization and Project, in every profile. No Nereid: the API keeps the objects. The commands
release · flux · flux
Turns Repository, Source, Target and Release into Flux HelmRepository and HelmRelease objects and copies their status back. A Nereid that needs a chart writes its own Release. The commands
environment · vcluster · vcluster
Each Environment is a vcluster in the current cluster, through a Release of its chart in the release reef. The commands
database · cloudnative-pg · cloudnative-pg
Releases the CloudNativePG operator once, after checking its chart's SHA-256, and looks after each Database. Keycloak keeps its realm, users and sessions in one. The commands
metrics · victoriametrics · victoriametrics
Releases the VictoriaMetrics operator through the release reef, keeps 14 days of every Nereid's metrics and the kubelets' cAdvisor, and publishes the address of the Prometheus query API.
secrets · openbao · default
The CLI encrypts a value with the public key openbao publishes. OpenBao opens it in memory and keeps it in KV v2, a new version per change; a SecretBinding makes a Kubernetes Secret from it. The commands
authentication · keycloak · keycloak
Writes its own Release of Keycloak, keeps its realm in a Database and publishes its OpenID Connect (OIDC) issuer. nereus login and the Nereus API rely on it. The commands
catalog · catalog · catalog
Says what Nereus has (what runs, what is published, whether it holds together), with nereus catalog apply, list, get, delete and check. The Nereid writes each entry's status; the profile installs it. The commands
scm · forgejo · forgejo
nereus scm mirror create <name> --from https://github.com/<owner>/<repository> copies a public repository into a Forgejo the Nereid runs in the cluster, pulled on an interval, with no App; the profile installs it, forgejo the reef's default (#1255, #1327). The commands
delivery · kubernetes · kubernetes
nereus workload deploy --image, or --build, takes a Workload to an Environment. The Nereid resolves a tag to a digest, never the client, and writes the objects of the release reef (ADR 0020). The commands
registry · zot · zot
The zot Nereid runs an open source registry in the cluster, one Repository per Workload, each with its own push credential, and reads it only for its owner (ADR 0021). The commands
build · buildkit · buildkit
Built: one Job per Build clones, builds rootless with BuildKit and pushes to the registry, and nereus workload deploy --build runs it by digest. The profile installs it, its containment proved (#1069, #1257, spec 0009). The commands
edge · cloudflare · proposed
Not built. Domains, zones and routes: a cloudflare Nereid would publish a reef's endpoint at a hostname (#577). The commands
authorization · openfga · proposed
Not built, and still being refined. The first idea: the Nereus API asks one question, whether a person may do a verb on an object, with the tenancy tree as the hierarchy. OpenFGA is the candidate named by ADR 0014 (#897).
policy · kyverno · proposed
Not built, and still being refined. The first idea: a small kind for a rule a Workload or Release must follow, common to every Nereid, and one refusal a person can see. Kyverno is the candidate named by ADR 0014, to weigh against native admission policies (#898).
tenancy
Os kinds Organization e Project, em todo profile. Sem Nereid: a API guarda os objetos. Os comandos
release · flux · flux
Transforma Repository, Source, Target e Release em objetos HelmRepository e HelmRelease do Flux e copia o status de volta. Um Nereid que precisa de um chart escreve o seu próprio Release. Os comandos
environment · vcluster · vcluster
Cada Environment é um vcluster no cluster atual, por meio de um Release do seu chart no reef release. Os comandos
database · cloudnative-pg · cloudnative-pg
Faz o release do operador CloudNativePG uma vez, depois de conferir o SHA-256 do chart, e cuida de cada Database. O Keycloak guarda num deles o realm, os usuários e as sessões. Os comandos
metrics · victoriametrics · victoriametrics
Faz o release do operador VictoriaMetrics pelo reef release, guarda 14 dias de métricas de cada Nereid e o cAdvisor dos kubelets, e publica o endereço da API de consulta do Prometheus.
secrets · openbao · default
A CLI cifra um valor com a chave pública que o openbao publica. O OpenBao o abre em memória e o guarda no KV v2, uma versão nova a cada mudança; um SecretBinding gera dele um Secret do Kubernetes. Os comandos
authentication · keycloak · keycloak
Escreve o seu próprio Release do Keycloak, guarda o realm num Database e publica o seu issuer OpenID Connect (OIDC). O nereus login e a Nereus API dependem dele. Os comandos
catalog · catalog · catalog
Diz o que o Nereus tem (o que roda, o que está publicado, se tudo se sustenta), com nereus catalog apply, list, get, delete e check. O Nereid escreve o status de cada entrada; o profile o instala. Os comandos
scm · forgejo · forgejo
nereus scm mirror create <name> --from https://github.com/<owner>/<repository> copia um repositório público para um Forgejo que o Nereid roda no cluster, atualizado num intervalo, sem App; o profile o instala, com forgejo como o padrão do reef (#1255, #1327). Os comandos
delivery · kubernetes · kubernetes
nereus workload deploy --image, ou --build, leva um Workload a um Environment. O Nereid resolve a tag para um digest, nunca o cliente, e escreve os objetos do reef release (ADR 0020). Os comandos
registry · zot · zot
O Nereid zot roda um registry open source no cluster, um Repository por Workload, cada um com a sua credencial de push, e só o lê para o seu dono (ADR 0021). Os comandos
build · buildkit · buildkit
Construído: um Job por Build clona, constrói sem root com o BuildKit e faz o push para o registry, e nereus workload deploy --build o roda pelo digest. O profile o instala, com a sua contenção provada (#1069, #1257, spec 0009). Os comandos
edge · cloudflare · proposta
Não construído. Domínios, zonas e rotas: um Nereid cloudflare publicaria o endpoint de um reef num hostname (#577). Os comandos
authorization · openfga · proposta
Não construído, ainda em refinamento. A primeira ideia: a Nereus API faz uma pergunta, se uma pessoa pode executar um verbo sobre um objeto, com a árvore do tenancy como hierarquia. O OpenFGA é o candidato citado no ADR 0014 (#897).
policy · kyverno · proposta
Não construído, ainda em refinamento. A primeira ideia: um kind pequeno para uma regra que um Workload ou Release deve seguir, comum a todo Nereid, e uma recusa que a pessoa consiga ver. O Kyverno é o candidato citado no ADR 0014, a comparar com as admission policies nativas (#898).
What we want to say: the planes are still there, and now each box has a name that runs. Every card reads top to bottom: the Reef is the API, the Nereid looks after it, the Mandate binds the two.
The order on screen: the Nereus API, the five planes one at a time, the cards that run, the dashed cards as the next steps, and the clients last. Hover a solid card for a tip; click it for the details.
The solid cards: tenancy has no Nereid, since the API keeps its objects; catalog is built, and the profile installs its Nereid; the other eight are what nereus init --profile internal-developer-platform installs today, registry and delivery among them.
The dashed cards: not in the profile yet. build with buildkit runs today with nereus nereid apply buildkit --reef build, and joins the profile once #1069 (the build reef's containment is proved) closes; edge is #577 (the edge reef with a cloudflare Nereid); each number links to its place on the board. authorization with openfga is #897 (refine the authorization reef) and policy with kyverno is #898 (refine the policy reef), both named by ADR 0014 (profiles).
The clients: the Portal has its Nereid, nereus-portal, which the profile installs behind the cluster's entrance: on a k3d cluster it answers at http://localhost:<ingress port>, and another address goes in its Mandate (#896, the profile installs the nereus-portal Nereid).
Source: cli/src/nereus/profiles.py, cli/src/nereus/local_nereids.py and docs/specs/cli/reefs.
O que queremos dizer: os planos continuam lá, e agora cada caixa tem um nome que roda. Cada cartão se lê de cima para baixo: o Reef é a API, o Nereid cuida dela, o Mandate liga os dois.
A ordem na tela: a Nereus API, os cinco planos um de cada vez, os cartões que rodam, os tracejados como próximos passos e os clientes por último. Passe o mouse num cartão sólido para ver a dica; clique para ver os detalhes.
Os cartões sólidos: o tenancy não tem Nereid, pois a API guarda os seus objetos; o catalog está construído, e o profile instala o seu Nereid; os outros oito são o que nereus init --profile internal-developer-platform instala hoje, entre eles registry e delivery.
Os cartões tracejados: ainda fora do profile. build com buildkit já roda com nereus nereid apply buildkit --reef build, e entra no profile quando o #1069 (a contenção do reef build é provada) fechar; edge é o #577 (o reef edge com um Nereid cloudflare); cada número leva ao seu lugar no board. authorization com openfga é o #897 (refinar o reef authorization) e policy com kyverno é o #898 (refinar o reef policy), ambos citados no ADR 0014 (profiles).
Os clientes: o Portal tem o seu Nereid, nereus-portal, que o profile instala atrás da entrada do cluster: num cluster k3d ele responde em http://localhost:<porta do ingress>, e outro endereço vai no seu Mandate (#896, o profile instala o Nereid nereus-portal).
Fonte: cli/src/nereus/profiles.py, cli/src/nereus/local_nereids.py e docs/specs/cli/reefs.
Thank you
Obrigado
Questions.
Perguntas.