The edge reef
Every command of the edge reef: domains, zones and routes, in the order a person types them
O reef edge
Todos os comandos do reef edge: domínios, zonas e rotas, na ordem em que uma pessoa os digita
The source of truth for the commands of the edge reef. Every command, built or only imagined, is here first; the tag after each label says whether it is built, planned (with the issue that builds it) or an idea.
The reef is refined in #470 (the edge reef publishes a reef's endpoint at a hostname); its domains in #475 (a godaddy Nereid that changes a domain at its registrar).
A fonte da verdade dos comandos do reef edge. Todo comando, pronto ou só imaginado, está aqui primeiro; a etiqueta depois de cada rótulo diz se ele está pronto, planejado (com a issue que o constrói) ou se é uma ideia.
O reef é refinado no #470 (o reef edge publica o endpoint de um reef num hostname); os seus domínios no #475 (uma Nereid godaddy que muda um domínio na registradora).
What comes before the first domain?
O que vem antes do primeiro domínio?
One command applies the edge reef, with its first kind, Route
Um comando aplica o reef edge, com o seu primeiro kind, Route
# Apply the edge reef$ nereus reef apply edge✓ core/reefs/edge 0.1.0 created Next steps: nereus edge --help nereus nereid apply <nereid> --reef edge
The reef comes first, with no tool behind it. Its first kind is Route (a hostname that reaches the platform, #1949); Zone (who answers for the domain's names, #1960), Domain (where the registrar sends the domain, #475) and Record (a CNAME or an A entry) come later.
O reef vem primeiro, sem ferramenta por trás. O seu primeiro kind é Route (um hostname que chega à plataforma, #1949); Zone (quem responde pelos nomes do domínio, #1960), Domain (para onde a registradora manda o domínio, #475) e Record (uma entrada CNAME ou A) vêm depois.
The cloudflare Nereid runs the tunnel its Mandate names
A Nereid cloudflare roda o túnel que o seu Mandate nomeia
# Apply the cloudflare Nereid to the edge reef$ nereus nereid apply cloudflare \ --reef edge✓ core/nereids/cloudflare created, Ready Next steps: nereus mandate create cloudflare --reef edge --nereid cloudflare --param tunnel=<tunnel> --param credentialsSecret=edge/<secret> --default nereus edge route create <name> --hostname <hostname> # Its Mandate: the named tunnel and its credentials, a secret of the secrets reef$ nereus mandate create cloudflare \ --reef edge \ --nereid cloudflare \ --param tunnel=nereus \ --param credentialsSecret=edge/cloudflare-tunnel \ --default✓ core/mandates/cloudflare created (reef: edge, nereid: cloudflare, default)
The Nereid runs cloudflared for the Mandate's named tunnel (#1949), its credentials bound from the secrets reef, so the cluster needs no kubectl apply and no open terminal. With the Mandate's apiTokenSecret, it also makes each Route's CNAME through Cloudflare's API (#1950) and the zone (#1960); with it and no credentialsSecret, it gets the tunnel itself, adopting the one of that name or creating it, its credentials sealed into the vault edge as edge/cloudflared-<mandate> (#1961). It binds secrets of the vault edge alone, which nereid apply makes and its admission policy holds it to (#1967): a secret of another vault is SecretOutsideVault. An azure-dns Nereid may take its place later, by swapping the Mandate; the commands stay the same.
A Nereid roda o cloudflared do túnel nomeado do Mandate (#1949), com as credenciais vindas do reef secrets, então o cluster não precisa de kubectl apply nem de terminal aberto. Com o apiTokenSecret do Mandate, ela também faz o CNAME de cada Route pela API da Cloudflare (#1950) e a zona (#1960); com ele e sem credentialsSecret, ela obtém o próprio túnel, adotando o de mesmo nome ou criando-o, com as credenciais seladas no vault edge como edge/cloudflared-<mandate> (#1961). Ela vincula só secrets do vault edge, que o nereid apply cria e a sua admission policy impõe (#1967): um secret de outro vault é SecretOutsideVault. Uma Nereid azure-dns pode tomar o seu lugar depois, trocando o Mandate; os comandos continuam os mesmos.
The godaddy Nereid talks to the registrar, through its Mandate
A Nereid godaddy fala com a registradora, pelo seu Mandate
# Apply the godaddy Nereid to the edge reef$ nereus nereid apply godaddy \ --reef edge✓ core/nereids/godaddy created, Ready Next steps: nereus mandate create godaddy --reef edge --nereid godaddy # Bind it to the reef$ nereus mandate create godaddy \ --reef edge \ --nereid godaddy✓ core/mandates/godaddy created Next steps: nereus edge domain list --at-registrar --mandate godaddy
The API never names the registrar (ADR 0002): a Domain says which nameservers it delegates to, and the Mandate picks godaddy. Another registrar's Nereid takes its place by swapping the Mandate.
A API nunca nomeia a registradora (ADR 0002): um Domain diz para quais nameservers delega, e o Mandate escolhe godaddy. A Nereid de outra registradora toma o seu lugar trocando o Mandate.
Who answers for the domain's names?
Quem responde pelos nomes do domínio?
A zone gives the domain the nameservers that will answer for it
Uma zona dá ao domínio os nameservers que vão responder por ele
# Delegate the domain to the platform$ nereus edge zone create getnereus.dev \ --mandate cloudflare✓ edge/zones/getnereus.dev created, waiting for its delegation nameservers: ada.ns.cloudflare.com, bob.ns.cloudflare.com point the registrar of getnereus.dev at them; the zone turns Active once Cloudflare sees it Next steps: nereus edge zone get getnereus.dev # Every zone and whether its delegation arrived$ nereus edge zone listNAME MANDATE STATUS NAMESERVERSgetnereus.dev cloudflare Pending ada.ns.cloudflare.com, bob.ns.cloudflare.com
The zone publishes its nameservers in status; Cloudflare assigns them when the zone is created. Until the registrar points to them, the zone waits.
create waits for the nameservers, never for Active: the delegation is the registrar's step. delete forgets the Zone, and the zone stays at Cloudflare (owner, 2026-11-20).
A zona publica os seus nameservers no status; o Cloudflare os atribui quando a zona é criada. Até a registradora apontar para eles, a zona espera.
create espera os nameservers, nunca o Active: a delegação é o passo da registradora. delete esquece a Zone, e a zona fica no Cloudflare (o dono, 2026-11-20).
Where does the registrar send the domain?
Para onde a registradora manda o domínio?
The registrar shows its domains, with the credentials asked for now and never stored
A registradora mostra os seus domínios, com as credenciais pedidas na hora e nunca guardadas
# What the registrar holds$ nereus edge domain list \ --at-registrar \ --mandate godaddyGoDaddy API key: ****GoDaddy API secret: ****NAME NAMESERVERS EXPIRES MANAGEDgetnereus.dev ns01.domaincontrol.com (+1) 2029-10-25 noexample.com ns01.domaincontrol.com (+1) 2029-10-25 noexample.org ns01.domaincontrol.com (+1) 2028-06-11 no Next steps: nereus edge domain get <name> --at-registrar --mandate godaddy nereus edge domain apply <name> --mandate godaddy
A list shows one nameserver and (+N) for the others; get shows them all (the owner, 2026-10-29). MANAGED says whether Nereus already looks after the domain.
The credentials are asked for at the time of use (the owner, 2026-10-29); keeping them in the secrets reef is decided in #475. The GoDaddy Domains API may be closed to small accounts: #475 checks it first.
Uma lista mostra um nameserver e (+N) para os outros; get mostra todos (o dono, 2026-10-29). MANAGED diz se o Nereus já cuida do domínio.
As credenciais são pedidas na hora do uso (o dono, 2026-10-29); guardá-las no reef secrets é decidido no #475. A API de domínios da GoDaddy pode estar fechada para contas pequenas: o #475 verifica isso primeiro.
Nereus takes the domain and sends it to the zone's nameservers
O Nereus assume o domínio e o manda para os nameservers da zona
# Delegate getnereus.dev to the zone$ nereus edge domain apply getnereus.dev \ --nameservers-from zone/getnereus.dev \ --mandate godaddy✓ domain/getnereus.dev created Next steps: nereus edge domain get getnereus.dev --watch
--nameservers-from zone/<name> takes the nameservers the zone publishes; --nameservers <ns1>,<ns2> writes them by hand, for a zone outside Nereus.
--nameservers-from zone/<nome> usa os nameservers que a zona publica; --nameservers <ns1>,<ns2> os escreve à mão, para uma zona fora do Nereus.
The list shows the domains Nereus looks after
A lista mostra os domínios de que o Nereus cuida
# What Nereus looks after$ nereus edge domain listNAME MANDATE NAMESERVERS DELEGATEDgetnereus.dev godaddy ada.ns.cloudflare.com (+1) True Next steps: nereus edge domain get getnereus.dev
Without --at-registrar, the list shows the Domain objects, the ones Nereus looks after. The nameservers are examples; Cloudflare assigns the real ones.
Sem --at-registrar, a lista mostra os objetos Domain, os de que o Nereus cuida. Os nameservers são exemplos; o Cloudflare atribui os reais.
One domain shows every detail, its nameservers one per line
Um domínio mostra todos os detalhes, os nameservers um por linha
# Every detail of one domain$ nereus edge domain get getnereus.devName: getnereus.devMandate: godaddyDelegated: TrueExpires: 2029-10-25Nameservers: ada.ns.cloudflare.com bob.ns.cloudflare.com (from zone/getnereus.dev) Next steps: nereus edge domain get getnereus.dev --watch
Nameservers are always a list, one per line (the owner, 2026-10-29), and the line under them says where they came from.
Os nameservers são sempre uma lista, um por linha (o dono, 2026-10-29), e a linha embaixo deles diz de onde vieram.
How does a reef's endpoint get a name?
Como o endpoint de um reef ganha um nome?
A route makes a hostname reach the platform
Uma rota faz um hostname chegar à plataforma
# Carry Triton's hostname through the tunnel$ nereus edge route create triton \ --hostname triton.getnereus.dev✓ edge/routes/triton created, Ready: https://triton.getnereus.dev Next steps: nereus edge route get triton # Every hostname the platform answers$ nereus edge route listNAME HOSTNAME ENDPOINT MANDATE READY URLauth auth.getnereus.dev - cloudflare True https://auth.getnereus.devportal portal.getnereus.dev - cloudflare True https://portal.getnereus.devtriton triton.getnereus.dev - cloudflare True https://triton.getnereus.dev
The first slice (#1949): a hostname goes to the instance's entrance, where the reefs' own routes pick the backend; it names no cluster, Service or port. With the Mandate's API token, the Nereid makes its CNAME and deletes it with the Route (#1950); without one, the record is made by hand. A reef's endpoint is named with --endpoint (#1951).
A primeira fatia (#1949): um hostname vai para a entrada da instância, onde as rotas dos próprios reefs escolhem o backend; não nomeia cluster, Service nem porta. Com o token de API do Mandate, a Nereid faz o seu CNAME e o apaga junto com a Route (#1950); sem ele, o registro é feito à mão. O endpoint de um reef é nomeado com --endpoint (#1951).
The Nereids say what they serve, never where it runs
As Nereids dizem o que servem, nunca onde rodam
# What the Nereids serve at the instance's entrance$ nereus edge endpoint listREEF ENDPOINT NEREID PROTOCOL PATHS HOSTS PUBLISHABLE PUBLISHED ROUTESmessaging mcp triton http / triton.example.com yes no - # Grant it: only an endpoint its Nereid's spec.publish names is ever published$ nereus nereid apply triton \ --publish mcp✓ core/nereids/triton unchanged, Ready✓ core/nereids/triton configured (publishes: mcp)
An endpoint is something a Nereid publishes in its status (ADR 0005, Nereids publish endpoints and commands in status), named <reef>/<endpoint> by its Nereid's first reef: never a cluster, a namespace, a Service or a port (the owner, 2026-10-29). It is published only when the Nereid marks it publishable (an admin surface is not) and its spec.publish grants it, written by nereus nereid apply --publish (#1951); --publish "" takes the grant away. An entry the Nereid CRD would refuse is dropped, never shown (ADR 0004).
Um endpoint é algo que uma Nereid publica no seu status (ADR 0005, as Nereids publicam endpoints e comandos no status), com o nome <reef>/<endpoint> pelo primeiro reef da sua Nereid: nunca um cluster, um namespace, um Service ou uma porta (o dono, 2026-10-29). Ele só é publicado quando a Nereid o marca como publicável (uma superfície de admin não é) e o seu spec.publish o concede, escrito por nereus nereid apply --publish (#1951); --publish "" retira a concessão. Uma entrada que o CRD da Nereid recusaria é descartada, nunca mostrada (ADR 0004).
A route publishes a reef's endpoint at a fixed address
Uma rota publica o endpoint de um reef num endereço fixo
# Publish Triton's MCP endpoint$ nereus edge route create triton \ --hostname triton.example.com \ --endpoint messaging/mcp✓ edge/routes/triton created, Ready: https://triton.example.com Next steps: nereus edge route get triton # Not granted: the Route stays, and says what is missing$ nereus edge route create docs \ --hostname docs.example.com \ --endpoint messaging/admin✗ timed out after 120s waiting for edge/routes/docs to be Ready (Ready: NotPublishable: <its Nereid's message>); it is left as it is: see 'nereus edge route get docs'
Triton is the first use (the Triton roadmap, step 1). The cloudflare Nereid carries the hostname only when the endpoint is publishable, granted by its Nereid's spec.publish and served on that hostname; otherwise the Route's Ready says why: NoEndpoint, NotPublishable, NotPublished, NotServed or Ambiguous (#1951). The endpoint is fixed once created, as the Mandate.
O servidor MCP do Tritão é o primeiro uso (o roadmap do Tritão, passo 1). A Nereid cloudflare só leva o hostname quando o endpoint é publicável, concedido pelo spec.publish da sua Nereid e servido naquele hostname; senão o Ready da Route diz o porquê: NoEndpoint, NotPublishable, NotPublished, NotServed ou Ambiguous (#1951). O endpoint fica fixo depois de criado, como o Mandate.