Manager, Client & Scheme do controller-runtime

Todo operador Go de produção gira em torno de um Manager do controller-runtime que compartilha caches e hooks de ciclo de vida entre reconciliadores, webhooks e endpoints de saúde.

O Client tipado e o Scheme são os dois objetos que os reconciliadores usam em cada loop.

Resumo

O Manager inicia caches de informer, expõe GetClient() e GetScheme(), e executa até SIGTERM.

O Client realiza Get/List/Create/Update/Patch/Delete contra objetos Kubernetes, preferindo leituras de cache para tipos observados.

O Scheme registra seus tipos Go de CRD mais os tipos de API principais para que o mapeador REST possa decodificar objetos não estruturados em structs.

A inicialização acontece uma vez em cmd/main.go; os reconciliadores recebem dependências via campos de struct.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
    Scheme: scheme,
    Metrics: metricsserver.Options{BindAddress: ":8080"},
    HealthProbeBindAddress: ":8081",
    LeaderElection:         true,
    LeaderElectionID:       "guestbook.example.com",
})

Quando usar isso:

• Iniciando qualquer operador kubebuilder ou controller-runtime
• Compartilhando um cache entre múltiplos reconciliadores em um único processo
• Habilitando métricas, sondas de saúde e eleição de líder em um só lugar
• Registrando webhooks de admissão no mesmo servidor HTTP das métricas

Exemplo de Trabalho

package main
 
import (
    "os"
 
    appsv1 "k8s.io/api/apps/v1"
    corev1 "k8s.io/api/core/v1"
    "k8s.io/apimachinery/pkg/runtime"
    utilruntime "k8s.io/apimachinery/pkg/util/runtime"
    clientgoscheme "k8s.io/client-go/kubernetes/scheme"
    ctrl "sigs.k8s.io/controller-runtime"
    "sigs.k8s.io/controller-runtime/pkg/healthz"
    metricsserver "sigs.k8s.io/controller-runtime/pkg/metrics/server"
 
    webappv1 "example.com/guestbook-operator/api/v1"
    "example.com/guestbook-operator/internal/controller"
)
 
var scheme = runtime.NewScheme()
 
func init() {
    utilruntime.Must(clientgoscheme.AddToScheme(scheme))
    utilruntime.Must(appsv1.AddToScheme(scheme))
    utilruntime.Must(corev1.AddToScheme(scheme))
    utilruntime.Must(webappv1.AddToScheme(scheme))
}
 
func main() {
    mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
        Scheme:                 scheme,
        Metrics:                metricsserver.Options{BindAddress: "0"},
        HealthProbeBindAddress: "0",
        LeaderElection:         false, // true em produção
        LeaderElectionID:       "guestbook.example.com",
    })
    if err != nil {
        panic(err)
    }
 
    if err := (&controller.GuestbookReconciler{
        Client: mgr.GetClient(),
        Scheme: mgr.GetScheme(),
    }).SetupWithManager(mgr); err != nil {
        panic(err)
    }
 
    if err := mgr.AddHealthzCheck("healthz", healthz.Ping); err != nil {
        panic(err)
    }
    if err := mgr.AddReadyzCheck("readyz", healthz.Ping); err != nil {
        panic(err)
    }
 
    if err := mgr.Start(ctrl.SetupSignalHandler()); err != nil {
        os.Exit(1)
    }
}

O que isso demonstra:

• init() registra tipos de API embutidos e personalizados em um Scheme compartilhado
• Opções do Manager conectam métricas, sondas e eleição de líder opcional
• Reconciliadores recebem o Client e o Scheme do Manager, não clientes client-go brutos
• mgr.Start bloqueia até SIGINT/SIGTERM via SetupSignalHandler

Mergulho Profundo

Como Funciona

• O Manager constrói um cliente delegador: leituras atingem o cache do informer compartilhado; escritas vão diretamente para o servidor de API.
• AddToScheme vincula cada tipo Go ao seu GroupVersionKind para decodificar watches e listas.
• SetupWithManager em um reconciliador registra For(), Owns() e Watches() com o construtor de controller do Manager.
• RESTMapper dentro do Manager resolve Guestbook para webapp.example.com/v1, Kind=Guestbook para chamadas de API genéricas.

Opções do Manager em Destaque

Client vs Raw client-go

Notas Go

// Use APIReader quando precisar contornar o cache (leituras críticas de consistência)
apiReader := mgr.GetAPIReader()
 
// Operadores com escopo de namespace: restrinja o cache nas opções do Manager
ctrl.Options{
    Cache: cache.Options{
        DefaultNamespaces: map[string]cache.Config{
            "tenant-a": {},
        },
    },
}

Armadilhas

• Esquecer AddToScheme para seu tipo CRD - Get de reconciliação falha com "nenhum kind registrado". Correção: chame webappv1.AddToScheme(scheme) em init().
• Usar o Client imediatamente antes da sincronização dos caches - a primeira reconciliação pode ver NotFound para objetos existentes. Correção: confie em requeue ou use mgr.GetCache().WaitForCacheSync(ctx).
• Eleição de líder desativada com múltiplos réplicas - cada Pod reconcilia os mesmos objetos, causando trabalho duplicado e corridas. Correção: ative LeaderElection em Deployments de produção.
• Vincular métricas a :8080 sem atualizar os monitores de Serviço - Prometheus perde os scrapes. Correção: alinhe BindAddress com as portas de Serviço do chart e NetworkPolicy.
• Passar um client.Client novo para os reconciliadores - contorna o cache compartilhado e duplica informers. Correção: sempre use mgr.GetClient().
• Misturar clientes não estruturados e tipados sem Scheme - erros de decodificação em objetos genéricos. Correção: registre todos os GVKs observados no Manager Scheme.

Alternativas

FAQs

Relacionados

• Noções Básicas de Operadores Kubernetes - scaffold e primeira reconciliação
• Escrevendo um Reconciliador: ctrl.Request & Loop de Reconciliação - Valores de retorno da Reconciliação
• Eleição de Líder, Métricas & Observabilidade de Operadores - sondas e Prometheus
• Testando Operadores com envtest & cliente fake - configuração do Scheme de teste
• Por que Go Domina o Ecossistema de Operadores Kubernetes - contexto do ecossistema

Versões da 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 (última - verifique na compilação), gin (última - verifique na compilação), echo (última - verifique na compilação), google.golang.org/grpc (última - verifique na compilação), sigs.k8s.io/controller-runtime (última - verifique na compilação), kubebuilder (última - verifique na compilação), tinygo (última - verifique os alvos de placa na compilação), wazero (última - verifique na compilação) e golangci-lint (última - verifique o conjunto de linters na compilação).