Referência
Glossário
Antes de leres: nada — isto é uma referência. Mantém-na aberta ao lado de qualquer outra página.
As palavras que quem chega encontra neste repositório, com o significado que têm no Delonix — que
às vezes é mais estreito do que o significado geral no cloud native. Cada entrada aponta para o sítio
onde o termo é explicado ou implementado. Os caminhos são relativos à raiz do repositório;
file.rs::symbol nomeia um símbolo dentro desse ficheiro.
Os termos estão por ordem alfabética. Para o contexto geral, os primitivos do kernel (processos, namespaces, cgroups, descritores de ficheiro, sinais) são ensinados em Fundações de Linux, e o OCI, o CRI, o CNI e o KVM tal como o motor os usa em Introdução ao cloud native.
Adapter — Um crate em crates/adapters/ que implementa uma porta contra um mecanismo local: o
kernel (delonix-linux), o dataplane de rede (delonix-sdn), a loja OCI (delonix-oci), os
hypervisors locais de VM (delonix-vm). Um adapter pode depender de crates de fundação e de
contexto, nunca de um crate de interface. Ver: Camadas,
scripts/arch_fitness.py::LAYERS.
ADR (Architecture Decision Record) — Um ficheiro Markdown por decisão estrutural, em docs/adr/,
com o nome NNNN-title.md, escrito em inglês, antes do código. Um ADR aceite nunca é reescrito; um
ADR novo sucede-lhe. Ver: docs/adr/README.md,
Quando escrever um ADR.
Apply / plan / prune — Os três verbos da convergência declarativa. delonix plan mostra o que um
apply mudaria e não muda nada (--detailed-exitcode sai com 2 quando há alterações);
delonix apply faz convergir o manifesto; --prune remove também o que a stack possui e o manifesto
já não declara, e nunca corre por omissão. Ver: crates/contexts/delonix-stack/src/reconcile.rs::plan,
Reconciliação declarativa.
CAS (content-addressed storage) — A loja de blobs de imagens: cada blob vive em
blobs/sha256/<hex> no state root, endereçado pelo seu digest, por isso conteúdo idêntico é guardado
uma só vez. A integridade é verificada quando o conteúdo entra na loja, não quando é lido: um pull
compara o manifesto, a config e cada layer com o digest esperado (verify_manifest_digest e as
comparações de digest em crates/adapters/delonix-oci/src/registry.rs). Cas::read é uma leitura
simples de ficheiro e não volta a calcular o hash; Cas::verify volta a calculá-lo a pedido. Ver:
crates/adapters/delonix-oci/src/cas.rs::Cas,
Estado em disco.
CDI (Container Device Interface) — Uma especificação da CNCF que descreve como expor um
dispositivo (tipicamente uma GPU) a um container. O Delonix só consome specs já geradas por uma
ferramenta do fabricante e transforma-as nos mesmos mounts e nós de dispositivo que -v/--device
produzem; nunca descobre drivers sozinho. Ver: crates/adapters/delonix-linux/src/cdi.rs.
cgroup delegation — O mecanismo do cgroup v2 que deixa um utilizador sem privilégios gerir uma
sub-árvore de cgroups. Sem ele, os limites de recursos rootless (-m, --cpus) não podem ser
impostos; o motor detecta isto e recusa um limite que não conseguiria aplicar, em vez de o aceitar em
silêncio. Uma shell aberta por SSH muitas vezes não está delegada; systemd-run --user --scope -p
Delegate=yes dá uma que está. delonix system info mostra a resposta como cgroup2 delegated. Ver:
crates/adapters/delonix-linux/src/lib.rs::cgroup_limits_apply,
cgroups v2 e delegação,
Delegação de cgroup.
CNI (Container Network Interface) — O padrão de plugins que o Kubernetes usa para dar rede a um
pod. O Delonix consegue correr a cadeia de plugins CNI de um nó contra um network namespace nomeado,
que é como um sandbox de pod do CRI recebe a sua rede. Ver:
crates/adapters/delonix-sdn/src/cni.rs::attach_named_netns,
Rede de containers.
Contract (node) — A API de um nó, definida em Protocol Buffers em proto/delonix/node/v1/
(pacote delonix.node.v1), com um documento OpenAPI docs/api/openapi.yaml gerado a partir dela.
O scripts/contract_gate.py guarda a formatação, o lint, a compatibilidade com a última tag e o
OpenAPI gerado. É um contrato publicado; nenhum servidor o implementa ainda. Ver:
Em que ponto está a reestruturação,
ADR-0040.
Control process — A metade reiniciável da infra de rede rootless: o binário do motor arrancado
com os argumentos internos netns control (não é um comando para o utilizador) corre dentro dos
namespaces segurados pelo pin, escuta num socket unix de controlo 0600 (aceitando só o uid do
próprio motor) e faz os attaches, os publishes, as mudanças de firewall, o DNS e o DHCP, um pedido de
cada vez. Matá-lo não perturba os workloads a correr; o comando seguinte reinicia-o. Ver:
crates/adapters/delonix-sdn/src/infra.rs::start_control, control_loop; Holder / pin.
CRI (Container Runtime Interface) — A API gRPC que o kubelet usa para correr pods. O crate
delonix-cri (binário delonix-cri) implementa-a por cima do motor, para que um nó Kubernetes possa
usar o Delonix em vez de outro runtime. Ver: crates/interfaces/delonix-cri/,
Kubernetes.
Daemonless — Não é preciso nenhum processo residente para o motor funcionar: cada comando da CLI
faz o seu trabalho e sai. O que tem de persistir pertence ao systemd (units, timers) ou a um processo
por workload com um dono claro (o supervisor de um container, o pin de rede). Um processo residente
novo precisa de um ADR. Ver: «Identidade e fronteira do motor» no AGENTS.md,
Daemonless.
Delegated cgroup — Ver cgroup delegation.
DX_* exit class — Cada erro do motor tem uma string de código estável (DX_NOT_FOUND,
DX_INVALID_ARGUMENT, …) e corresponde a um código de saída do processo decidido a partir do tipo
do erro, nunca da sua mensagem (traduzida): por exemplo 4 = recurso inexistente, 5 = conflito. Os
scripts e os reconciliadores decidem pelo número, não pelo texto. Ver:
crates/foundation/delonix-model/src/error.rs::Error::code,
crates/foundation/delonix-model/src/exitcode.rs::for_error,
Erros.
Fitness function — Uma verificação automática de que a arquitectura ainda tem a forma que foi
decidida. Aqui é o scripts/arch_fitness.py (job de CI arch): direcção das camadas, directório =
camada, versões das dependências só na raiz, nenhum nome de consumidor no código, e os ratchets de
dívida. Ver:
Identidade e fronteiras do motor,
Regras de arquitectura.
Holder / pin — A metade de longa duração da infra de rede rootless. O binário do motor arrancado
com os argumentos internos netns pin cria um user, network e mount namespace e depois só dorme,
segurando-os; o seu pidfile mantém o nome histórico holder.pid, e todo o nsenter -t <pid> para a
infra aponta para ele. Antes da divisão em pin e processo de controlo, um único «holder» fazia os dois
trabalhos, e é por isso que as duas palavras aparecem no código. Ver:
crates/adapters/delonix-sdn/src/infra.rs::start_pin, pin_main,
crates/adapters/delonix-sdn/src/pin_userns.rs; Control process.
IPAM (IP address management) — Atribuição dos endereços dos workloads dentro do prefixo de uma
rede. O Delonix mantém um ficheiro de leases por prefixo em ipam/ no state root, e um ceifador que
só reclama um lease depois de o ter visto órfão duas vezes, separadas por um período de graça.
delonix network ipam ls lista os leases. Ver: crates/adapters/delonix-sdn/src/ipam.rs::allocate,
reap_orphan_leases; a aritmética pura de endereços está em
crates/foundation/delonix-net-rules/src/lib.rs.
Kind — O tipo de um recurso declarativo num manifesto (kind: Network, kind: Pod,
kind: VirtualMachine, …), agrupado por apiVersion (core, compute, networking, gateway,
storage, artifact, infrastructure). Os factos de cada Kind — o seu grupo, se tem namespace, se
converge, a sua forma — vivem numa só tabela. delonix api-resources imprime-a;
delonix explain <Kind> documenta os seus campos. Ver:
crates/contexts/delonix-stack/src/kinds.rs::FACTS, KindFacts.
LANG-01 — A regra de língua do código: identificadores, comentários e mensagens visíveis ao
utilizador escrevem-se em inglês; o português chega ao operador só através do catálogo de tradução
(bins/delonix-runtime-bin/data/pt.po, escolhido com --l18n pt). O scripts/lang_ratchet.py conta
o português que ainda está no código, como um ratchet. Ver:
Língua.
Layer (ADR-0040) — Um dos anéis arquitecturais a que cada crate pertence: fundação, contextos,
adapters, providers, interfaces, binários. As dependências apontam para dentro, e o directório do
crate (crates/<layer>/) tem de bater certo com a camada declarada. Não confundir com uma layer de
imagem (ver Overlay / lowerdir). Ver: Camadas,
ADR-0040.
Lowering (sugar Kinds) — Reescrever um Kind de conveniência no Kind que faz de facto o trabalho,
enquanto o manifesto é carregado, para que o resto do motor nunca o veja. Workload baixa para
Container/Pod/VirtualMachine, Dependency para NetworkPolicy; o spec.expose de uma
VirtualMachine baixa para um HTTPRoute chamado <vm>-expose (cmd/vm_expose.rs). A coluna FORM de
delonix api-resources diz em que se torna cada Kind: primary, sugar → X (baixado),
compat → X (um schema estrangeiro mantido mas compilado para X), sunset → X (ainda aplicado como
ele próprio, com sucessor anunciado), aggregate (expande-se nos documentos que contém, como o
Stack). Ver: crates/contexts/delonix-stack/src/kinds.rs::Form,
bins/delonix-runtime-bin/src/cmd/manifest.rs::load.
MCP (Model Context Protocol) — Um protocolo através do qual um cliente de IA chama ferramentas.
delonix mcp serve (crate delonix-mcp) é uma superfície de controlo local e sem inquilino,
sobre stdio: um processo em primeiro plano arrancado pelo cliente para uma sessão, confiado como o uid
local que o corre — não uma API de gestão remota. Ver: crates/interfaces/delonix-mcp/src/lib.rs,
ADR-0025.
microVM — Uma máquina virtual leve com um modelo de dispositivos mínimo, que arranca depressa,
usada onde um workload precisa do seu próprio kernel. No Delonix o hypervisor de microVMs é o Cloud
Hypervisor; o libvirt (QEMU/KVM) é o outro backend local. Um Workload com type: microvm força o
backend Cloud Hypervisor. Ver: Construir microVMs,
ADR-0006.
NoCloud seed — Um ISO pequeno com o user-data, o meta-data e o network-config do cloud-init,
anexado a uma VM para o seu primeiro arranque aplicar o hostname, as chaves SSH e a rede. O Delonix
gera um por VM, a não ser que a imagem seja um appliance que não corre cloud-init. Ver:
crates/adapters/delonix-vm/src/cloudinit.rs::generate_seed_iso,
Virtualização.
OCI (Open Container Initiative) — Os padrões para imagens de containers (image spec), para as
distribuir a partir de registos (distribution spec) e para as correr (runtime spec). O Delonix faz ele
próprio o pull, o build, o armazenamento e o push de imagens OCI. Ver: crates/adapters/delonix-oci/,
Imagens OCI.
Overlay / lowerdir — O overlayfs empilha as layers só de leitura da imagem (os lowerdirs) por
baixo de um directório upper gravável por container. O Delonix desempacota cada layer de imagem uma
só vez em layers/ e todos os containers dessa imagem partilham-nas; o directório do container tem
upper/, work/, merged/ e um ficheiro overlay-lowers que lista as layers. O mount é feito dentro
do próprio user namespace do container com a nova API de mount, uma chamada lowerdir+ por layer,
para que imagens com muitas layers não esbarrem no limite de comprimento das opções do mount(2)
clássico. Ver: crates/adapters/delonix-oci/src/overlay.rs::prepare_overlay,
crates/adapters/delonix-linux/src/lib.rs::mount_overlay_if_marked,
ADR-0037.
Port (hexagonal) — Um trait de que um caso de uso precisa e que um adapter ou provider
implementa, para que o domínio nunca nomeie um mecanismo concreto. Exemplos: VmBackend, e as portas
de compute ImageStore, StorageProvider, NetworkProvider, WorkloadRuntime. Ver:
crates/contexts/delonix-compute/src/ports.rs, launch.rs,
Traits como portas.
Provider — Um crate em crates/providers/ que implementa uma porta contra uma API de gestão
remota (hoje Proxmox VE e TrueNAS), trazendo o seu próprio cliente HTTP. Um provider novo entra como
implementação de uma porta, registado na raiz de composição — nunca como um if provider == … no
código — e precisa de um ADR. Ver: Providers,
ADR-0008, ADR-0009.
Ratchet — Um gate sobre um contador de dívida que falha quando o número sobe e também quando
desce sem a linha de base registada ter sido baixada no mesmo commit, para que o progresso fique
registado e nunca se perca. O scripts/lang_ratchet.py (português no código) e os ratchets de dívida
do scripts/arch_fitness.py funcionam assim; os dois têm --list e --update. Ver:
Regras de arquitectura.
Reconcile (3-way) — Como o plan/apply decidem o que mudar sem um ficheiro de estado. Os três
lados são o manifesto (o desejado), o que é observado no nó (o real), e a última spec aplicada,
guardada no próprio recurso na anotação delonix.io/last-applied. O terceiro lado separa «tiraste
este campo do ficheiro» (reverte-o) de «alguém definiu isto à mão» (deixa-o). Ver:
crates/contexts/delonix-stack/src/reconcile.rs,
O reconciliador declarativo.
Rootless — Correr como um utilizador sem privilégios, com privilégios só dentro dos user namespaces que o motor cria. É o caminho por omissão no Delonix («rootless-first»); root é um opt-in explícito. Ver: Namespaces Linux e operação rootless.
slirp4netns — Uma pilha de rede em espaço de utilizador que liga um network namespace rootless à
rede do host sem privilégios, e encaminha portas do host para dentro dele. O Delonix corre um único
slirp4netns para toda a infra de rede rootless, com o NAT e a publicação de portas feitos pelo
nftables dentro do namespace da infra. Ver: crates/adapters/delonix-sdn/src/infra.rs,
Rede.
Stack — O conjunto de recursos que um manifesto possui. A posse é uma label em cada recurso,
delonix.io/stack, e não um registo à parte: apply --prune e stack destroy só tocam em recursos
que a levam, e um recurso criado à mão nunca é removido por eles. Stack é também um Kind agregado
que agrupa recursos num só documento. Ver:
crates/contexts/delonix-stack/src/reconcile.rs::STACK_LABEL.
State root — O directório que guarda todo o estado do motor em ficheiros (não há base de dados):
DELONIX_ROOT quando definido, senão ~/.local/share/delonix (ou $XDG_DATA_HOME/delonix) para um
utilizador e /var/lib/delonix para root. Os sockets de rede vivem num directório de runtime à parte
(DELONIX_NET_RUNTIME_DIR). Define sempre os dois quando testas. Os registos debaixo dela são lidos,
escritos e trancados pelo adapter delonix-state. Ver:
bins/delonix-runtime-bin/src/cmd/util.rs::state_root,
crates/adapters/delonix-state/src/store.rs::Store::default_root,
Estado em disco,
Isolar o estado do motor.
subuid / subgid — Um intervalo de ids de utilizador e de grupo delegados ao teu utilizador em
/etc/subuid e /etc/subgid. Com ele, um user namespace rootless mapeia muitos ids (escritos através
do newuidmap e do newgidmap); sem ele, só o teu próprio uid é mapeado e as imagens que usam outros
utilizadores partem-se. Os ficheiros que um container escreve como um id mapeado não pertencem ao teu
uid no host, e é por isso que algumas operações voltam a entrar num namespace mapeado. Ver:
crates/adapters/delonix-sdn/src/pin_userns.rs,
Requisitos do kernel.
Supervisor — O processo que o container run -d faz fork para ser o pai real do container:
espera pelo container, regista o seu verdadeiro estado de saída (e uma razão OOMKilled), e aplica a
política --restart. Como faz fork, tem de ser arrancado a partir de um processo com uma só thread;
os servidores re-executam primeiro um delonix novo. Ver:
crates/adapters/delonix-linux/src/supervise.rs::run_supervised,
crates/adapters/delonix-linux/src/lib.rs::wait_and_record.
userns (user namespace) — O namespace Linux que mapeia ids de utilizador, dando a um processo
privilégios de root só sobre os objectos que o seu namespace possui. É a base da operação rootless, e
em Ubuntu recentes pode ser bloqueado pelo AppArmor para binários fora dos caminhos esperados. Ver:
Namespaces Linux,
AppArmor,
namespaces(7) e user_namespaces(7).
Verdict map — Um map do nftables de uma chave para um veredicto (jump, accept, …), usado para
que um pacote encontre a sua regra numa só consulta, em vez de percorrer uma regra por workload. O
Delonix usa o fwmap (endereço de um workload → a sua chain de firewall) e o netpair (um par de
bridges → uma isenção que abre uma rota entre duas redes). Ver:
crates/adapters/delonix-sdn/src/infra.rs::FWMAP, NETPAIR_MAP.
VmBackend — A porta que todo o backend de VM implementa (boot, stop, destroy, is_running,
ip, pausa e snapshots, …). O Cloud Hypervisor e o libvirt estão registados por omissão; um provider
remoto regista-se na raiz de composição. Registar não faz I/O, e a auto-detecção filtra pela
registration antes de construir seja o que for, por isso um backend remoto só se liga quando é
escolhido. Ver: crates/adapters/delonix-vm/src/lib.rs::VmBackend, register_backend,
select_backend,
Traits como portas.
Workload — Duas coisas relacionadas. kind: Workload é um Kind de açúcar com spec.type:
container|pod|vm|microvm que baixa para o Kind correspondente na altura do load
(ADR-0001). delonix workload é o grupo de comandos de
day-2 (ls, describe, stop, rm) que lista e actua sobre containers e VMs em conjunto
(ADR-0002). Ver:
crates/contexts/delonix-stack/src/kinds.rs::WORKLOAD_LOWERS_TO,
bins/delonix-runtime-bin/src/cmd/workload.rs.
Worktree — Um git worktree: um segundo directório de trabalho ligado ao mesmo repositório, no
seu próprio branch. Cada tarefa aqui tem o seu, criado a partir de origin/main num directório
persistente fora do repositório (nunca /tmp), e é removido juntamente com o seu branch no fim. Ver:
Um worktree por tarefa.
Seguinte: Visão geral e percursos de leitura — é o fim do curso; volta aos percursos de leitura por papel para escolheres o que aprofundar a seguir.