docs: execucao e entrada de trafego no cluster

[thnbi]

O que mudou

• ADR-0032 registrando KEDA como gatilho da escala a zero: indexadores como ScaledJob lendo o cursor de revisão, worker de notificação como Deployment com ScaledObject
• ADR-0027 corrigido em dois pontos: dizia "Job com escala a zero", e a entrada de tráfego passa de Ingress para Gateway API
• Diagrama de blocos com o grupo renomeado para "Escala a zero com KEDA" e a caixa de entrada trocada para Gateway
• Fluxogramas e casos de uso deixam de dizer "enfileira", que nomeava um mecanismo inexistente
• ADR-0032 registra como o ScaledJob evita processar o mesmo lote duas vezes: cada Job reserva um cofre com FOR UPDATE SKIP LOCKED
• ADR-0032 fica como Proposta até o KEDA ser instalado, e o ADR-0027 anota no status que foi alterado por ele

Por quê

Duas coisas estavam erradas no desenho, e as duas por falta de decisão registrada.

A escala a zero era promessa sem mecanismo. A documentação do Kubernetes define Job como tarefa
que roda até terminar e para, então alguém precisa criá-lo a cada lote, e nenhum ADR dizia quem.
O diagrama mostrava dois Jobs parados dentro de um grupo chamado "Escala a zero", como se
fossem serviços residentes esperando carga, o que não existe. O ADR-0018 rejeitou broker e o
ADR-0021 rejeitou fila dedicada, os dois condicionando a entrada a medir o custo primeiro. KEDA
lendo o cursor de revisão cabe nesse histórico sem contrariá-lo, porque continua sendo o mesmo
polling, agora feito pela plataforma.

A entrada de tráfego usava Ingress. A documentação do Kubernetes diz que "the Ingress API has
been frozen" e que o projeto recomenda Gateway no lugar dela. Gateway, GatewayClass e HTTPRoute
estão GA, e o TLS termina nos listeners do Gateway. Uma caixa "Ingress" virava três recursos com
donos distintos.

Quatro passagens diziam "enfileira a nota" ou "enfileira a notificação". Não existe fila: a
escrita avança o cursor de revisão, e a notificação é gravada como pendente.

Conferido

• Os ícones vêm do conjunto oficial kubernetes/community/icons, que o draw.io usa sem alterar
• O conjunto oficial não tem ícone de Gateway, então a caixa ficou neutra em vez de reusar o de Ingress
• O SVG renderiza no renderizador estrito, que é como o GitHub serve imagem

O que a infraestrutura da disciplina oferece

Conferido no repositório que descreve o cluster de produção:

• Gateway API v1.6.0, com gatewayClassName: cilium. O Cilium implementa o Gateway, com Envoy e kube-proxy substituído
• cert-manager com ClusterIssuer do Let's Encrypt, resolvido por gatewayHTTPRoute, então o TLS no Gateway é automático
• Longhorn para armazenamento, com StorageClass longhorn-fast
• Kubernetes v1.36, três nós em HA, pilha dupla

Isso fecha a escolha de Gateway API e mostra que não há banco gerenciado, então o PostgreSQL
roda no cluster com volume persistente. O diagrama foi corrigido, porque ele estava desenhado
fora.

KEDA não está instalado. O ADR-0032 passa a registrar isso como dependência de infraestrutura, e
descreve o alvo em vez do que roda hoje. O próprio KEDA serve as métricas do scaler de
PostgreSQL, então metrics-server não é pré-requisito. Instalar é por Helm, que já existe nas
máquinas.

Como testar

• Abrir o diagrama de blocos e conferir que a entrada diz Gateway e o grupo nomeia o KEDA
• Conferir que o ADR-0032 não contraria a rejeição de broker do ADR-0018 nem a de fila do ADR-0021
• Procurar por "enfileira" nos documentos e não achar nada
• Conferir que "Ingress" só aparece no ADR-0027 como a alternativa trocada pelo Gateway API

Auto-review (checklist)

• Descrição clara (o que/por quê/como testar)
• PR pequeno e focado
• Casos limite considerados (ex.: vazio, 0, erro)
• Evidência de teste (manual ou automatizado)

[NicolasArthurDev]

• O ADR-0032 ainda fala em fila. A Decisão diz "notificação na fila de saída", e o PR existe justamente para tirar "fila" dos documentos. Deveria ser "notificação pendente".
• A afirmação sobre metrics-server está errada. O KEDA serve as métricas do scaler de PostgreSQL pelo próprio metrics apiserver dele. O commit que corrige isso está no #28 (docs: corrige a dependencia de metrics-server na adr-0032) e deveria vir para este PR.
• Falta decidir a concorrência no ScaledJob. É a lacuna principal. O ScaledJob cria Jobs conforme o valor que a query devolve. Sem regra de quem pega qual lote, dois Jobs leem o mesmo cursor e indexam a mesma coisa duas vezes. O ADR precisa dizer como o lote é reservado, por exemplo um Job por tenant, FOR UPDATE SKIP LOCKED ou um maxReplicaCount com estratégia de escala.
• O texto da Decisão do ADR-0027 foi reescrito com status Aceita. O ADR-0018 seguiu o padrão "Substituída pelo...". Para manter o histórico, seria melhor anotar "Alterada pelo ADR-0032" no 0027.
• Status do ADR-0032. Está "Aceita", mas o próprio texto diz que descreve o alvo e não o que roda. Vale considerar "Proposta" até o KEDA ser instalado.
• Menor: o "Como testar" manda procurar "ingress" e não achar nada, mas o ADR-0027 cita Ingress de propósito.

[NicolasArthurDev]

Para aprovar: tirar "fila de saída" da Decisão do ADR-0032, trazer para cá a correção do metrics-server que está no #28 e registrar no ADR como o ScaledJob evita que dois Jobs processem o mesmo lote.

[NicolasArthurDev]

Ótimo trabalho! A reserva por cofre com FOR UPDATE SKIP LOCKED fechou bem a questão da concorrência, e as alternativas registradas (maxReplicaCount 1 e advisory lock por tenant) deixam claro por que essa foi a escolhida. O status "Proposta" e o "alterada pelo ADR-0032" no 0027 deixam o histórico fácil de seguir.

Só uma ideia para o futuro, sem bloquear: como a trava dura a transação, um cofre grande segura uma transação longa durante toda a indexação. Se isso pesar, dá para registrar depois um limite de tamanho de lote. Aprovado.