Entenda o Cache do Controller-Runtime e Evite Gargalos no API Server do Kubernetes

Para engenheiros de plataforma e desenvolvedores de Kubernetes, entender o cache do controller-runtime é crucial. Longe de ser um detalhe de implementação, ele é o motor que permite aos controladores operar em escala sem sobrecarregar o kube-apiserver. O mecanismo central é o padrão de list + watch: o controlador faz uma leitura inicial de um tipo de recurso e depois mantém um fluxo de eventos para manter sua cópia local atualizada. Isso significa que chamadas como r.Get() e r.List() dentro do seu reconciler geralmente não vão ao API server, mas leem de um cache em memória.

Essa abordagem garante leituras de baixo custo e alta performance, mas introduz o conceito de consistência eventual. Seus dados no cache podem estar ligeiramente desatualizados em relação ao estado mais recente no etcd. Componentes como Reflector (que mantém a conexão com o API server), Indexer (o armazenamento em memória) e o workqueue (fila de reconciliação que dedupilca requisições) trabalham em conjunto para gerenciar essa cópia local. Compreender a interação desses elementos é fundamental para evitar surpresas em produção, como alto consumo de memória por caches mal indexados ou comportamentos inesperados devido a leituras defasadas.

A arquitetura interna do controller-runtime evoluiu recentemente para lidar melhor com o 'staleness' (dados defasados) e a ordenação de eventos. Historicamente, o buffer entre o Reflector e o Informer usava o DeltaFIFO, que realizava deduplicação de eventos. Conforme noticiado pelo CEVIU em 1 de maio de 2026, a versão 1.36 do Kubernetes introduziu a mitigação de staleness, com um foco renovado no processamento FIFO.

A mudança mais significativa agora explicada é a substituição do DeltaFIFO pelo RealFIFO. O RealFIFO simplifica o fluxo: cada notificação do Reflector é passada em ordem, uma por uma, sem deduplicação. Isso garante que todos os estados intermediários sejam processados, embora o custo seja a remoção da deduplicação nativa a nível do informer. A deduplicação agora é movida para a workqueue do controlador, garantindo que o reconciler sempre receba uma única requisição por objeto, mas processando todos os eventos que levaram a ela.

Para quem opera e desenvolve em Kubernetes, entender as nuances do cache do controller-runtime é vital para a confiabilidade e o custo-benefício da infraestrutura. O desconhecimento pode levar a gargalos no API server, consumo excessivo de memória em controladores mal otimizados e decisões de automação baseadas em estados defasados. Dominar como os controladores leem dados e como a consistência eventual se manifesta é um pilar para a engenharia de confiabilidade de sistemas (SRE) e para o design de plataformas eficientes.

Ao compreender o funcionamento do list + watch e a transição para o RealFIFO, engenheiros podem diagnosticar problemas de performance, otimizar o uso de recursos e construir controladores mais resilientes. Isso garante que as automações do Kubernetes, o coração de muitos ambientes de DevOps, sejam robustas e evitem surpresas caras em produção, contribuindo diretamente para uma operação mais estável e previsível.