Manager, Client y Scheme de controller-runtime

Cada operador Go de producción se centra en un Manager de controller-runtime que comparte cachés y hooks de ciclo de vida entre reconciliadores, webhooks y endpoints de salud.

El Client tipado y el Scheme son los dos objetos que los reconciliadores usan en cada bucle.

Resumen

El Manager inicia cachés de informadores, expone GetClient() y GetScheme(), y se ejecuta hasta SIGTERM.

El Client realiza Get/List/Create/Update/Patch/Delete contra objetos de Kubernetes, prefiriendo lecturas de caché para tipos observados.

El Scheme registra tus tipos Go de CRD más los tipos de API principales para que el mapeador REST pueda decodificar objetos no estructurados en structs.

El arranque ocurre una vez en cmd/main.go; los reconciliadores reciben dependencias a través de campos de struct.

Receta

Tarjeta de receta de referencia rápida, lista para copiar y pegar.

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

Cuándo usar esto:

• Al iniciar cualquier operador de kubebuilder o controller-runtime
• Al compartir una caché entre múltiples reconciliadores en un solo proceso
• Al habilitar métricas, sondeos de salud y elección de líder en un solo lugar
• Al registrar webhooks de admisión en el mismo servidor HTTP que las métricas

Ejemplo de Trabajo

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 en producción
        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)
    }
}

Lo que esto demuestra:

• init() registra tipos de API integrados y personalizados en un Scheme compartido.
• Las opciones del Manager conectan métricas, sondeos y elección de líder opcional.
• Los reconciliadores reciben el Client y el Scheme del Manager, no clientes client-go crudos.
• mgr.Start se bloquea hasta SIGINT/SIGTERM a través de SetupSignalHandler.

Análisis Profundo

Cómo Funciona

• El Manager construye un cliente delegante: las lecturas golpean la caché del informador compartido; las escrituras van directamente al servidor de API.
• AddToScheme vincula cada tipo Go a su GroupVersionKind para decodificar watches y listas.
• SetupWithManager en un reconciliador registra For(), Owns() y Watches() con el constructor de controladores del Manager.
• RESTMapper dentro del Manager resuelve Guestbook a webapp.example.com/v1, Kind=Guestbook para llamadas genéricas a la API.

Opciones del Manager de un Vistazo

Client vs Raw client-go

Notas de Go

// Usa APIReader cuando debas omitir la caché (lecturas críticas de consistencia)
apiReader := mgr.GetAPIReader()
 
// Operadores con ámbito de namespace: restringe la caché en las opciones del Manager
ctrl.Options{
    Cache: cache.Options{
        DefaultNamespaces: map[string]cache.Config{
            "tenant-a": {},
        },
    },
}

Trampas

• Olvidar AddToScheme para tu tipo CRD - Get de reconciliación falla con "no kind is registered". Solución: llama a webappv1.AddToScheme(scheme) en init().
• Usar el Client inmediatamente antes de que las cachés se sincronicen - la primera reconciliación puede ver NotFound para objetos existentes. Solución: confía en la re-cola o usa mgr.GetCache().WaitForCacheSync(ctx).
• Elección de líder desactivada con múltiples réplicas - cada Pod reconcilia los mismos objetos, causando trabajo duplicado y carreras. Solución: habilita LeaderElection en despliegues de producción.
• Vincular métricas a :8080 sin actualizar los monitores de Servicio - Prometheus no realiza scrapeos. Solución: alinea BindAddress con los puertos de Servicio del chart y NetworkPolicy.
• Pasar un client.Client nuevo a los reconciliadores - omite la caché compartida y duplica informadores. Solución: usa siempre mgr.GetClient().
• Mezclar clientes no estructurados y tipados sin Scheme - errores de decodificación en objetos genéricos. Solución: registra todos los GVK observados en el Scheme del Manager.

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de Operadores de Kubernetes - scaffold y primera reconciliación
• Escribiendo un Reconciliador: ctrl.Request y Bucle de Reconciliación - Valores de retorno de Reconcile
• Elección de Líder, Métricas y Observabilidad de Operadores - sondeos y Prometheus
• Pruebas de Operadores con envtest y cliente fake - configuración de Scheme de prueba
• Por qué Go Domina el Ecosistema de Operadores de Kubernetes - contexto del ecosistema

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado de GC Green Tea, go fix modernizers - verificar parche en la compilación), chi (última - verificar en la compilación), gin (última - verificar en la compilación), echo (última - verificar en la compilación), google.golang.org/grpc (última - verificar en la compilación), sigs.k8s.io/controller-runtime (última - verificar en la compilación), kubebuilder (última - verificar en la compilación), tinygo (últimos objetivos de placa de verificación en la compilación), wazero (última - verificar en la compilación) y golangci-lint (último conjunto de linters de verificación en la compilación).