Melhores Práticas para Operadores Kubernetes

Reconciliadores idempotentes, design orientado a nível e checklist de produção para operadores.

Estas regras transformam arestas afiadas recorrentes de operadores em hábitos de revisão, portões de CI e escolhas de empacotamento que mantêm os controladores seguros em escala.

Como Usar Esta Lista

• Percorra as seções A-E durante a revisão de design antes de adicionar novos campos de API ou tipos de recursos filhos.
• Execute envtest e operator-sdk bundle validate em CI em cada tag de release.
• Habilite a eleição de líder e colete métricas de reconciliação antes de aumentar as réplicas do Deployment acima de um.
• Combine os modos de instalação do OLM e o escopo do RBAC com o menor modelo de tenência que seu produto suporta.

A - Design de Reconciliação

• Trate cada reconciliação como uma passagem completa de convergência. Compare a especificação desejada com o estado observado; nunca assuma que um único evento representa o delta completo.
• Mantenha a reconciliação idempotente. Executar duas vezes com o mesmo estado do cluster não deve criar recursos externos duplicados ou aplicar patch em filhos duas vezes.
• Retorne client.IgnoreNotFound em objetos primários excluídos. Evite métricas de erro para corridas entre a exclusão e a reconciliação final.
• Use Status().Update para condições e prontidão. Nunca aplique patch em campos de status através de Update genérico no objeto completo.
• Prefira RequeueAfter para espera esperada. Reserve erros retornados para falhas genuínas que valem a pena alertar.
• Defina referências de proprietário em todos os objetos filhos que você cria. Habilite a coleta de lixo e os watches Owns sem cola baseada apenas em rótulos.

B - API, Webhooks e CRDs

• Valide limites simples em marcadores CRD; use webhooks para regras entre campos. Mantenha as camadas OpenAPI e de admissão complementares, não duplicadas de forma inconsistente.
• Defina valores padrão para especificações ausentes em webhooks mutáveis. A reconciliação ainda deve tolerar objetos legados que não possuem novos campos.
• Use failurePolicy: Fail para validação crítica de segurança. Combine com pods de webhook HA e monitoramento de certificado.
• Aumente a versão da API em vez de quebrar nomes de campos JSON. Adicione conversão quando a versão de armazenamento mudar de forma.
• Regenere manifestos após edições de marcadores. Nunca edite manualmente config/crd/bases sem sincronizar os tipos Go.
• Exponha colunas significativas em kubectl get. Engenheiros de suporte devem ver a fase e a prontidão sem dumps YAML.

C - Ciclo de Vida, Finalizadores e Exclusão

• Adicione um finalizador antes de criar dependências externas. Bloqueie a remoção do CR até que a limpeza de bancos de dados na nuvem, DNS ou IAM seja concluída.
• Torne a limpeza idempotente. APIs de exclusão externas podem ser chamadas mais de uma vez durante tempestades de retentativas.
• Remova finalizadores apenas após a limpeza bem-sucedida. Objetos presos em Terminating sinalizam lógica de limpeza ausente.
• Use predicados para reduzir o ruído de status em objetos primários. Deixe o tráfego Owns dos filhos impulsionar as atualizações de prontidão.
• Documente o comportamento órfão para objetos filhos opcionais. Esclareça se a exclusão do CR deve excluir recursos compartilhados do cluster.

D - Testes, Observabilidade e Operações

• Espelhe o registro do Scheme de produção em testes. Tipos ausentes em envtest ocultam falhas de decodificação de produção.
• Cubra os caminhos de adição, ativo e exclusão de finalizadores em tabelas envtest ou fake client. Bugs de exclusão são incidentes de produção.
• Habilite a eleição de líder quando as réplicas puderem exceder um. Pods de espera não devem reconciliar concorrentemente.
• Exponha métricas Prometheus e alerte sobre taxas de retentativa. Picos em workqueue_retries_total precedem páginas de incidentes.
• Conecte probes de liveness e readiness a portas de saúde dedicadas. Não vincule probes a endpoints de coleta de métricas.
• Inicie o Manager com ctrl.SetupSignalHandler. Libere leases prontamente em upgrades contínuos.

E - Empacotamento, RBAC e Multi-Tenancy

• Alinhe as permissões CSV com o RBAC gerado. Instalações do OLM falham silenciosamente de forma parcial quando as regras divergem das necessidades do reconciliador.
• Desabilite modos de instalação que você não implementa. Reivindicar AllNamespaces sem RBAC de cluster bloqueia a revisão de segurança.
• Escopo de Roles para namespaces de inquilinos quando possível. Prefira OwnNamespace em vez de listar Secrets em todo o cluster para plataformas SaaS.
• Passe --leader-elect e limites de recursos no Deployment CSV. HA sem eleição duplica efeitos colaterais externos.
• Valide bundles em CI antes da publicação no catálogo. operator-sdk bundle validate captura descritores de CRD possuídos ausentes.
• Planeje saltos de upgrade para releases intermediárias ruins. Documente replaces e skips nos metadados CSV.

FAQs

Relacionado

• Escrevendo um Reconciliador: ctrl.Request & Loop de Reconciliação - padrões de reconciliação idempotentes
• Watches, Predicates, Owner References & Finalizers - segurança do ciclo de vida
• Testando Operadores com envtest & fake client - harness de teste de CI
• Eleição de Líder, Métricas & Observabilidade de Operadores - operações de produção
• Bundles OLM, Upgrades & RBAC Multi-Tenant - empacotamento e tenência

Versões de Stack: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, go fix modernizers - verifique o patch na compilação), chi (latest - verifique na compilação), gin (latest - verifique na compilação), echo (latest - verifique na compilação), google.golang.org/grpc (latest - verifique na compilação), sigs.k8s.io/controller-runtime (latest - verifique na compilação), kubebuilder (latest - verifique na compilação), tinygo (latest - verifique os alvos de placa na compilação), wazero (latest - verifique na compilação) e golangci-lint (latest - verifique o conjunto de linters na compilação).