Sondas de Salud, Preparación y Actividad

Separa la actividad (¿está vivo el proceso?) de la preparación (¿puede esta instancia servir tráfico?) para que los orquestadores y balanceadores de carga se comporten correctamente durante el arranque, las interrupciones de dependencias y los despliegues.

Resumen

Las sondas de Actividad (Liveness) reinician contenedores bloqueados.

Las sondas de Preparación (Readiness) eliminan instancias de los puntos de servicio hasta que puedan manejar solicitudes.

Las sondas de Arranque (Startup) (Kubernetes 1.16+) protegen aplicaciones de inicio lento antes de que la sonda de actividad actúe.

Los manejadores de sondas deben ser rápidos, idempotentes y estar libres de middleware de autenticación que bloquee el tráfico de kubelet.

Receta

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

mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, r *http.Request) {
    w.WriteHeader(http.StatusOK)
    w.Write([]byte("ok"))
})
mux.HandleFunc("GET /readyz", func(w http.ResponseWriter, r *http.Request) {
    if depsHealthy(r.Context()) {
        w.WriteHeader(http.StatusOK)
        return
    }
    http.Error(w, "not ready", http.StatusServiceUnavailable)
})

Cuándo usar esto:

• Despliegues de Kubernetes con sondas HTTP
• Balanceadores de carga en la nube que realizan comprobaciones de estado en grupos de back-end
• Despliegues continuos que deben esperar a las migraciones antes de recibir tráfico
• Grupos de escalado automático que reemplazan instancias no saludables
• Detección de valores atípicos del Service Mesh que respetan el estado de preparación

Ejemplo de Trabajo

package main
 
import (
    "context"
    "database/sql"
    "errors"
    "log/slog"
    "net/http"
    "sync"
    "time"
 
    _ "github.com/jackc/pgx/v5/stdlib"
)
 
type App struct {
    db    *sql.DB
    ready sync.RWMutex
    isReady bool
}
 
func (a *App) setReady(v bool) {
    a.ready.Lock()
    a.isReady = v
    a.ready.Unlock()
}
 
func (a *App) checkReady() bool {
    a.ready.RLock()
    defer a.ready.RUnlock()
    return a.isReady
}
 
func (a *App) liveness(w http.ResponseWriter, r *http.Request) {
    w.WriteHeader(http.StatusOK)
    w.Write([]byte("ok"))
}
 
func (a *App) readiness(w http.ResponseWriter, r *http.Request) {
    if !a.checkReady() {
        http.Error(w, "starting", http.StatusServiceUnavailable)
        return
    }
    ctx, cancel := context.WithTimeout(r.Context(), 500*time.Millisecond)
    defer cancel()
    if err := a.db.PingContext(ctx); err != nil {
        http.Error(w, "db unavailable", http.StatusServiceUnavailable)
        return
    }
    w.WriteHeader(http.StatusOK)
    w.Write([]byte("ready"))
}
 
func (a *App) business(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte(`{"orders":[]}`))
}
 
func main() {
    db, err := sql.Open("pgx", "postgres://localhost:5432/app?sslmode=disable")
    if err != nil {
        slog.Error("db open failed", "err", err)
        return
    }
    app := &App{db: db}
 
    mux := http.NewServeMux()
    mux.HandleFunc("GET /healthz", app.liveness)
    mux.HandleFunc("GET /readyz", app.readiness)
    mux.HandleFunc("GET /orders", app.business)
 
    go func() {
        time.Sleep(2 * time.Second)
        app.setReady(true)
        slog.Info("readiness enabled")
    }()
 
    slog.Info("listening", "addr", ":8080")
    if err := http.ListenAndServe(":8080", mux); err != nil && !errors.Is(err, http.ErrServerClosed) {
        slog.Error("listen failed", "err", err)
    }
}

Lo que esto demuestra:

• La sonda de actividad devuelve 200 sin tocar PostgreSQL.
• La sonda de preparación se basa en un indicador de arranque más un PingContext acotado.
• Las rutas de negocio se mantienen separadas de las rutas de sonda.
• Las respuestas 503 indican a los balanceadores de carga que dejen de enviar tráfico.

Análisis Profundo

Cómo Funciona

• Kubelet llama a la sonda de actividad en un intervalo; los fallos repetidos reinician el contenedor.
• El controlador de Endpoints elimina los pods que fallan la preparación de los puntos de servicio.
• Los balanceadores de carga reflejan la preparación: solo enrutan a las instancias que devuelven éxito.
• Las sondas de arranque deshabilitan la sonda de actividad hasta que la aplicación finaliza la inicialización lenta.

Comparación de Sondas

Campos de Sonda HTTP de Kubernetes

Notas de Go

// Eximir las sondas de middleware de autenticación costoso
func skipProbePaths(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        switch r.URL.Path {
        case "/healthz", "/readyz", "/startupz":
            next.ServeHTTP(w, r)
            return
        }
        authMiddleware(next).ServeHTTP(w, r)
    })
}

Errores Comunes

• Comprobación de base de datos en la sonda de actividad - Un pico en la base de datos reinicia todos los pods; usa la sonda de preparación solo para comprobaciones de dependencias.
• Autenticación en /healthz - Kubelet no envía tus tokens de servicio; las sondas reciben 401 y los pods se reinician.
• Manejadores de preparación lentos - Las comprobaciones largas bloquean los hilos de kubelet y hacen que la preparación fluctúe; usa tiempos de espera cortos.
• Devolver 200 durante migraciones - El tráfico golpea una discrepancia de esquema; mantén la preparación en falso hasta que las migraciones se completen.
• Misma ruta para actividad y preparación - No puedes distinguir entre un bloqueo y un fallo de dependencia.
• Tráfico de sonda en métricas - Excluye /healthz de los paneles RED o etiqueta probe=true por separado.
• Puerto de administración solo TLS - Asegúrate de que las sondas golpeen el puerto y el esquema para los que kubelet o LB están configurados.

3730363230327c3638346f6967637c6f692e73656469756765646f63

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de Observabilidad - manejadores de salud mínimos
• Apagado y Manejo de Señales Seguros - vaciado durante despliegues
• Buenas Prácticas de net/http - lista blanca de rutas de sonda en autenticación
• Producción en Go: Logs, Métricas, Trazas y Señales - señales operacionales
• Gestión de Configuración: Env, Flags y Viper - preparación para configuración faltante

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