DEV Community: Pedro Oliveira

Reconciliation Loop: Como o Kubernetes implementa infraestrutura declarativa

Pedro Oliveira — Wed, 19 Aug 2026 23:16:31 +0000

Ao meu ver, uma das maiores qualidades é o que faz o Kubernetes ser
a ferramenta padrão quando se fala de operar infraestrutura em larga escala,
seja ela em um cloud provider ou rodando on premisse é a sua abordagem
na implementação de infraestrutura declarativa. O que faz com que seja usada por organizações
de inúmeros tamanhos e áreas de atuação que desejam entregar uma plataforma de tecnologia
que seja confiável e atenda inúmeros casos de uso

Hoje, no mundo das ferramentas de infraestrutura como código (IaC) existem
duas abordagens principais para a implementação do conceito:

Infraestrutura Imperativa: Nessa abordagem, é necessário especificar as etapas e comandos exatos para provisionar e orquestrar recursos
Infraestrutura Declarativa: Ao contrário da forma imperativa, aqui o foco não está em como provisionar e orquestrar mas sim onde o ponto final da infraestrutura

Além disso, para garantir que o estado declarado no arquivo YAML,
ou outra linguagem de configuração, seja mantido ao longo do tempo,
os sistemas de orquestração historicamente adotavam abordagens baseadas em
Polling (varreduras periódicas) ou Edge-Triggered (reação a eventos pontuais):

Modelo Baseado em Eventos (Edge-Triggered / Polling): O sistema depende da entrega perfeita de notificações de eventos ou de consultas periódicas (polling). Se uma notificação de "falha de Pod" for perdida devido a uma oscilação na rede, a plataforma perde o contexto e a infraestrutura se mantém em um estado inconsistente.
Modelo Baseado no Estado Atual (Level-Triggered): Em vez de se focar no evento que passou, o Kubernetes se baseia no estado presente. Ele utiliza uma conexão contínua (Watch) para capturar alterações, mas a decisão do que fazer é tomada comparando a foto atual da infraestrutura com o estado desejado.

É exatamente a implementação desse modelo Level-Triggered que chamamos de
Reconciliation Loop.

Durante esse artigo, tentarei explicar o funcionamento dessa abordagem através
de um controller feito com kubebuilder (um framework Go para operator Kubernetes)
que apresenta uma mensagem sempre que um Pod é criado ou deletado

O motor por trás do Loop: Informers, Cache e WorkQue

Para implementar a abordagem Level-Triggered na prática sem sobrecarregar
o kube-apiserver, a biblioteca controller-runtime (base do Kubebuilder)
utiliza uma arquitetura baseada em três pilares fundamentais:
Informer, Cache Local e WorkQueue.

1. Informer: Escutando a API em Tempo Real

Em vez de fazer requisições periódicas (polling) para saber se algo mudou,
o controller utiliza o Informer. Ele estabelece uma conexão HTTP de
streaming de longa duração (Watch) com o apiserver.

No código Go de exemplo, esse registro é feito de forma declarativa dentro
do SetupWithManager:

Watches(&corev1.Pod{}, &handler.EnqueueRequestForObject{})

Sempre que um evento ocorre em um Pod no cluster, o apiserver notifica o
informer em tempo real.

2. Cache Local: Performance e Escalabilidade

Se em cada reconciliação, fosse preciso buscar os dados completos direto no
etcd, o cluster colapsaria em larga escala. Por isso, ao receber uma
notificação, o Informer atualiza um Cache In-Memory mantendo localmente
dentro do processo do controller.

Quando é executada a leitura do recurso dentro da função de reconciliação:

pod := &corev1.Pod{}
err := r.Get(ctx, req.NamespacedName, pod)

Essa consulta não faz uma request ao Kubernetes; ela lê instantaneamente
do cache local mantido pelo Informer.

3. WorkQueue: Garantindo Resiliência e Desduplicação

O Informer não chama a função Reconcile() diretamente. Em vez disso, o
utilitário handler.EnqueueRequestForObject{} extrai apenas os metadados
do recurso - a chave Namespace/Name - e a insere em uma fila de trabalho
(WorkQueue)

A WorkQueue resolve três grandes problemas de engenharia:

Deduplicação: Se múltiplos eventos do mesmo Pod chegam em um curto espaço de tempo, a chave é inserida uma vez na fila, evitando execuções redundantes.
Rate Limiting e Backoff: Se a reconciliação falhar, a fila reagenda a tentativa com tempo de espera exponencial (exponential backoff)
Desacoplamento: O recebimento de eventos e processamento deles rodam de forma assíncrona.

Desmistificando o Reconcile(): O Código na Prática

Com Informer, Cache Local e WorkQueue implementadas no
SetupWithManager, a execução chega no coração de tudo: A função Reconcile().

Diferente de arquiteturas orientadas a eventos tradicionais, o parâmetro
recebido por essa função não contém o Pod inteiro e nem o tipo de evento
que ocorreu (como Create, Update ou Delete). O controller recebe apenas
a chave do recurso através do parâmetro ctrl.Request:

func (r *ExampleReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    log := logf.FromContext(ctx)

A seguir, vamos analisar como cada bloco da função interage com os componentes
internos e onde inspecionar os logs para validar o comportamento em tempo
real

1. Leitura via Cache In-Memory e Tratamento de Exclusão

O ciclo começa obtendo o estado atual do recurso

pod := &corev1.Pod{}
    if err := r.Get(ctx, req.NamespacedName, pod); err != nil {
        if client.IgnoreNotFound(err) != nil {
            return ctrl.Result{}, err
        }
        log.Info("The pod was deleted", "name", req.Name, "namespace", req.Namespace)
        return ctrl.Result{}, nil
    }

Interação com o Cache: A chamada r.Get() consulta diretamente o Cache In-Memory mantido pelo Informer
Caso de Pod Deletado: Se o Pod foi removido do cluster, o Informer atualiza o cache local. Quando o r.Get() tenta buscar a chave req.NamespacedName, ele retorna um erro do tipo NotFound
Resposta ao WorkQueue: Ao usar client.IgnoreNotFound(err), o código reconhece que a ausência do recurso é um estado válido final. Após isso, imprime o log e retorna ctrl.Result{}, nil, sinalizando para a WorkQueue que o item foi processado com sucesso e pode ser removido da fila.

2026-08-19T17:09:45-03:00   INFO    The pod was deleted {"controller": "example", "namespace": "default", "name": "nginx", "reconcileID": "69af3331-bdd4-45c6-98dd-88eaf32f2439", "name": "nginx", "namespace": "default"}

2. Avaliação de Estado (Level-Triggered in Action)

Se o recurso foi encontrado no cache, o código prossegue para avaliar o seu
estado atual e tomar decisões

if controllerutil.ContainsFinalizer(pod, "my.domain/finalizer") {
        log.Info("Pod was deleted", "name", pod.Name, "namespace", pod.Namespace)
    } else {
        log.Info("Pod created", "name", pod.Name, "namespace", pod.Namespace)
    }

Lógica de Inspeção: Como o controller não recebe flags imperativas (como isCreate), ele deve deduzir o cenário inspecionando os metadados e o Spec/Status do Pod carregado da RAM
Uso de Finalizers: Inspecionar o array de Finalizers permite ao controller identificar se o objeto está em processo de graceful deletion ou se é uma reconciliação comum de criação/autorização

Podemos verificar esse comportamento, rodando o comando abaixo para criação
de um Pod:

kubectl run --image nginx nginx

Que vai gerar a seguinte ocorrência no log do controller

2026-08-19T19:33:07-03:00   INFO    Pod created {"controller": "example", "namespace": "default", "name": "nginx", "reconcileID": "88f9cba6-502e-481e-b5a5-c9a01b72d880", "name": "nginx", "namespace": "default"}

Se colocarmos uma label nesse Pod recém criado:

kubectl label pod nginx env=prod

A WorkQueue dispara o Reconcile() novamente

2026-08-19T19:35:53-03:00   INFO    Pod created {"controller": "example", "namespace": "default", "name": "nginx", "reconcileID": "55f7aa09-fd82-4905-b169-37b35bd1f908", "name": "nginx", "namespace": "default"}

3. Sinalizando o Fim do Loop para a WorkQueue

A instrução de encerramento do método define como a WorkQueue deve gerenciar aquela chave:

    return ctrl.Result, nil
}

O retorno da função Reconcile dita o fluxo da fila de trabalho:

ctrl.Result{}, nil: O estado desejado é atingido (ou o recurso não existe mais). A chave é removida da WorkQueue
ctrl.Result{}, err: Ocorreu uma falha. A WorkQueue retém a chave e reagenda a execução aplicando Exponential Backoff para evitar thundering herd.
ctrl.Result{RequeueAfter: 10 * time.Second}, nil: Força um re-agendamento periódico (Polling/Health-check), útil quando o controller depende de externos ao Kubernetes.

Conclusão: A "Mágica" do Kubernetes Desmistificada

A capacidade do Kubernetes de manter clusters massivos operando de forma
resiliente não se deve a um passe de mágica, mas sim a elegância do
Reconciliation Loop e do modelo Level-Triggered.

Ao longo desse artigo, vimos que o modelo declarativo é sustentado por
componentes cirurgicamente projetados:

O Informer reage a eventos sem sobrecarregar a rede com polling.
O Cache Local In-Memory garante leituras de altíssima performance.
A WorkQueue desacopla o recebimento de eventos da execução, garantindo resiliência, deduplicação e rate-limiting.
A função Reconcile() assume a responsabilidade de comparar o estado atual (Status) com o estado desejado (Spec), agindo até que ambos convirjam.

Entender essa engrenagem é o diferencial entre encarar o Kubernetes como
um "buraco negro de arquivos YAML" e utilizá-lo como a plataforma extensível que
ele realmente é. Quando você domina o funcionamento interno do
controller-runtime, criar seus próprios CRDs e Operators para automatizar
infraestrutura torna-se uma evolução natural na sua jornada de engenharia.

Kubernetes sem Cloud Provider (Parte 2): Criando Operators em Go para automação e self-service de plataforma

Pedro Oliveira — Mon, 25 May 2026 23:37:29 +0000

Uma das maiores cargas cognitivas quando falamos em Kubernetes é a configuração dos vários componentes necessários para entregar valor real ao cluster. Em outras palavras, deparamo-nos com uma quantidade massiva de YAMLs para configurar Custom Resources (CRs), Custom Resource Definitions (CRDs), Roles e tudo o que é necessário para que um serviço tenha um Ingress com TLS, por exemplo.

Isso ficou ainda mais evidente para mim durante os meus estudos de Kubernetes sem as abstrações fornecidas pelos Cloud Providers (assunto que cobrimos na Parte 1). Para resolver esse problema, decidi aprofundar o conhecimento nas maneiras pelas quais o Kubernetes nos permite automatizar essas operações e criar abstrações self-service através de Custom Operators.

Neste artigo, vou documentar a criação de dois operators desenvolvidos em Go que fazem a ponte entre o HashiCorp Vault e os operadores de mercado External Secrets Operator e Cert-Manager:

vaultreaver: Configura a integração e os limites de segurança entre o Kubernetes e a API externa do Vault.
platform-operator: Atua como o centralizador e orquestrador de configurações dentro do cluster.

Motivação

Durante a configuração manual dos componentes responsáveis pela comunicação com o Vault, percebi um padrão repetitivo de tarefas que gerava muita fricção:

Criar uma ServiceAccount no Kubernetes.
Criar uma Vault Role para permitir a generation de tokens atrelados a essa ServiceAccount.
Criar uma política de acesso no Vault (Vault Policy) e vinculá-la à Role.

Essa operação é mandatória para que os componentes do cluster se comuniquem de forma segura com o Vault (utilizando o token JWT da ServiceAccount para se autenticarem).

Para entender a fundo a mecânica desse ecossistema, resolvi construir um operador que utilizasse esse mesmo mecanismo de autenticação nativa, mas de forma totalmente automatizada. O objetivo era esconder essa complexidade do usuário final da plataforma, automatizando todo o boilerplate de segurança e gerando os tokens necessários para as operações de cada componente.

Como tudo funciona por baixo dos panos

Nota: Para esse fluxo funcionar, o Vault já deve estar configurado previamente com o método de autenticação de Kubernetes ativo (auth/kubernetes). O nosso operador utiliza a sua própria identidade no cluster para interagir com a API do Vault e criar as novas permissões.

A configuração começa pelo vaultreaver. Ele é responsável por gerenciar o ciclo de vida dos recursos fora do cluster (na API do Vault) e recebe dois Custom Resources principais:

VaultPolicy: Declara a política de segurança com as permissões que a aplicação/componente terá dentro do Vault.
VaultKubernetesRoleBinding: Faz o vínculo (binding) da VaultPolicy com a ServiceAccount do Kubernetes e a respectiva VaultRole.

O exemplo abaixo demonstra a criação de uma permissão declarativa de leitura no path kv do Vault para um namespace de aplicação:

apiVersion: security.platform.io/v1alpha1
kind: VaultPolicy
metadata:
  name: nginx-deployment-external-secret
  namespace: nginx-apps
spec:
  policy: |
    path "kv/data/app-teste/secret-secreto" {
      capabilities = ["read"]
    }
  vaultPolicyName: nginx-deployment-external-secret-policy
---
apiVersion: security.platform.io/v1alpha1
kind: VaultKubernetesRoleBinding
metadata:
  name: nginx-deployment-external-secret
  namespace: nginx-apps
spec:
  audience: vault
  authMount: kubernetes
  boundNamespaces:
    - nginx-apps
  boundServiceAccounts:
    - nginx-deployment-external-secret
  roleName: nginx-deployment-external-secret
  tokenPolicies:
    - nginx-deployment-external-secret-policy
  tokenTTL: 1h

Depois que o vaultreaver estabelece com sucesso a ponte de segurança com o Vault, o platform-operator assume a responsabilidade pelas automações dentro do cluster.

A API do platform-operator é desenhada para ser mais ampla, aceitando contratos simplificados focados na experiência do desenvolvedor (Self-Service). O exemplo a seguir demonstra o manifesto VaultCertificate, que abstrai todo o setup necessário para provisionar TLS via Cert-Manager com o backend de PKI do Vault.
Ao receber este único CR, o operador gera dinamicamente os recursos internos:

A ServiceAccount configurada com o RBAC necessário para o fluxo de certificados.
As regras do Cert-Manager (como o ClusterIssuer ou Issuer apontando para o Vault).
O recurso final de Certificate que dispara a emissão real do certificado TLS.

apiVersion: security.platform.io/v1alpha1
kind: VaultCertificate
metadata:
  name: nginx-deployment-tls
  namespace: nginx-apps
spec:
  vaultUrl: [http://172.18.0.12:8200](http://172.18.0.12:8200)
  authPath: /v1/auth/kubernetes
  vaultRole: nginx-deployment-tls-role
  pkiPath: pki/sign/internal-dot-infra
  commonName: my-app.internal.infra
  dnsNames:
    - my-app.internal.infra
    - my-app-teste.internal.infra
  SecretName: nginx-deployment-tls
  certManagerServiceAccount: "cert-manager"
  certManagerNamespace: "cert-manager"

Da mesma forma, o operador possui controllers dedicados a simplificar o uso do ExternalSecrets, encapsulando e criando de forma automatizada o SecretStore e o ExternalSecret correspondente a partir de uma interface limpa.

Testes e Validação

Para validar o comportamento do ecossistema e garantir a idempotência dos controllers em Go, montei um laboratório completo que pode ser conferido neste repositório de demonstração:
https://github.com/pedrohro1992/homelab-app-demo

O objetivo do laboratório foi:

Garantir a automação e o provisionamento de um certificado TLS válido via Cert-Manager usando o nosso platform-operator.
Injetar credenciais sensíveis via ExternalSecrets vindas diretamente do Vault de forma totalmente declarativa.

O cenário de teste consiste no deployment de uma aplicação Nginx. Através do Ingress configurado com o TLS gerado e com o segredo resolvido pelo operador, conseguimos expor com sucesso a aplicação. Ao acessar a página de diagnóstico, é possível validar visualmente que todas as variáveis de ambiente baseadas no segredo do Vault (como o nosso VALOR_SECRET) foram injetadas perfeitamente no container em tempo de execução.

Considerações finais

Apesar de existirem diversas soluções prontas para integração entre Kubernetes e Vault, implementar esses Operators foi um excelente exercício para compreender:

Reconciliação de recursos no Kubernetes
Desenvolvimento de Operators com Kubebuilder
Fluxos de autenticação Kubernetes ↔ Vault
Automação de plataforma
Criação de abstrações de self-service

Além do aprendizado técnico, o projeto também ajudou a reduzir significativamente a complexidade operacional envolvida na configuração manual desses componentes.

Kubernetes sem Cloud Provider (Parte 1): CNI, Storage Dinâmico, Ingress e Arquitetura Terraform

Pedro Oliveira — Wed, 18 Feb 2026 02:40:16 +0000

Durante muito tempo — e ainda hoje em muitos cenários on-premises — o Kubernetes foi (e é) executado sem integrações nativas de cloud provider. Antes de EKS, GKE e AKS se tornarem padrão, era responsabilidade do operador configurar explicitamente rede, armazenamento, ingress, identidade e registry.

Este artigo é a primeira parte de uma série onde documento a construção de um cluster executando sobre Kubernetes in Docker (KinD), focando em:

Configuração de CNI (rede de pods)
Provisionamento dinâmico de storage com CSI
Configuração de Ingress
Estruturação e automação completa via Terraform

A parte de TLS com Vault e cert-manager ficará para o próximo artigo, pois ainda estou finalizando essa integração.

🎯 Motivação

Em ambientes gerenciados, temos automaticamente:

CNI integrada à VPC
Provisionamento dinâmico de discos
Load Balancers
Integrações de identidade

Mas nada disso é inerente ao Kubernetes. São componentes adicionais configurados pelo provedor.

A proposta deste projeto foi remover essas abstrações e implementar manualmente as capacidades essenciais de um cluster funcional.

Você não precisa saber mecânica para dirigir.
Mas quando o carro para no meio da estrada, esse conhecimento faz diferença.

🧱 Arquitetura do Projeto

O cluster foi criado com KinD e inicialmente não possuía:

CNI funcional
Provisionador de storage
Ingress Controller
Integrações externas

A partir disso, foram adicionados os seguintes componentes.

🌐 Rede — CNI com Calico

Para permitir comunicação entre pods e nós, foi instalado o:
Calico

Funções habilitadas:

Atribuição de IPs aos pods
Encapsulamento VXLAN
Network Policies
Comunicação inter-node

Sem CNI, pods não se comunicam — esse é o primeiro requisito real para um cluster utilizável.

💾 Storage Dinâmico — OpenEBS

Para substituir o papel que discos gerenciados fariam em cloud, implementei:

OpenEBS

Com isso foi possível:

Criar StorageClasses
Provisionar PVCs dinamicamente
Utilizar backend baseado em armazenamento local

Isso reproduz o comportamento esperado por aplicações stateful em qualquer ambiente Kubernetes.

🧠 Estrutura Terraform — Organização Modular

O repositório do módulo:

https://github.com/pedrohro1992/tf-module-kind-cluster.git

O módulo tf-module-kind-blueprint atua como um módulo agregador.

Essa técnica é conhecida como:

Root Module Composition Pattern (ou Aggregator Module Pattern)

Nesse modelo:

O módulo raiz não implementa recursos diretamente
Ele compõe módulos especializados
Centraliza variáveis e dependências
Expõe uma interface limpa para consumo Cada componente (CNI, OpenEBS, NGINX Ingress) está encapsulado em seu próprio módulo Terraform.

Vantagens arquiteturais:

Separação clara de responsabilidades
Modularidade
Reutilização
Organização escalável
Manutenção facilitada

🧩 Desafios Técnicos

Alguns pontos relevantes durante a implementação:

Coordenação entre providers (Kubernetes e Helm)
Garantia de ordem correta de dependências
Idempotência dos módulos
Encadeamento de outputs
Inicialização do provider Kubernetes apenas após cluster estar disponível

Automatizar componentes de infraestrutura dentro de um cluster recém-criado exige atenção especial ao ciclo de vida dos recursos.

⚠️ Disclaimer

Tenho um senso de humor peculiar.

O nome fictício da “empresa” usada como estudo de caso no código é:

Cacetinho-SA

Sim, há referências a isso no código.
É intencional. 😄

💽 PVC provisionado dinamicamente pelo OpenEBS

🔮 Próximos Passos

Nos próximos artigos da série:

Configuração de Identity Provider
OIDC e Workload Identity
DNS automático do Ingress com ExternalDNS
TLS automático no Ingress com:
cert-manager
HashiCorp Vault como CA
Evolução para Gateway API
Service Mesh multi-cluster com Istio
Empacotamento como Composition Function no Crossplane

(E provavelmente mais algumas ideias que surgirem no caminho.)

📌 Conclusão

Rodar Kubernetes sem cloud provider não é algo exótico — foi assim que muitos clusters rodaram por anos, e ainda rodam em ambientes bare-metal, edge e data centers privados.

Cloud providers apenas empacotam e integram:

CNI
CSI
Ingress
Identidade
PKI

Implementar manualmente essas camadas muda completamente o nível de entendimento sobre a plataforma.

Este projeto não foi apenas sobre “fazer funcionar”, mas sobre compreender o que está acontecendo por baixo das abstrações.

No próximo artigo, entro na camada de identidade e TLS — que está se mostrando um desafio interessante.