monitor de Fleet

Herramienta de diagnóstico avanzada para solucionar problemas de ampliaciones SUSE® Rancher Prime Continuous Delivery.

Descripción general

Extrae información del ciclo de vida de GitOps de SUSE® Rancher Prime Continuous Delivery capturando instantáneas de todos los recursos relevantes y realizando diagnósticos automatizados. Este comando ayuda a identificar por qué los paquetes se quedan atascados durante las fases de direccionamiento y ampliación, y proporciona información útil sobre la salud de tu instalación de SUSE® Rancher Prime Continuous Delivery.

fleet monitor [flags]

Opciones

  -n, --namespace string          Namespace to monitor (default: all namespaces)
      --system-namespace string    {product_name} system namespace (default: cattle-fleet-system)
      --agent-staleness duration  Consider agent stale after this duration (default: 24h)
      --watch                     Watch for changes and output continuously
      --interval int              Interval in seconds between checks when watching (default: 60)
  -h, --help                      help for monitor

Inicio rápido

El comando monitor genera JSON compacto (una instantánea por línea). Utiliza jq para formatear para una mejor legibilidad.

# Single snapshot with formatted output
fleet monitor | jq

# Single snapshot with human-readable analysis
fleet monitor | fleet analyze

# Continuous monitoring with built-in watch mode (every 60 seconds)
fleet monitor --watch --interval 60 >> monitor.json

Lo que Detecta

El comando monitor realiza diagnósticos exhaustivos para detectar:

Problemas del Ciclo de Vida de Recursos

Paquetes con Desajuste de Generación: Paquetes que no avanzan a través de su ciclo de vida (generación != generación observada)
Despliegues de Paquetes Atascados: Despliegues de paquetes donde el agente no está aplicando nuevos IDs de ampliación
Múltiples Finalizadores: Recursos con más de un finalizador (indica errores - solo los Contenidos deberían tener múltiples finalizadores para el conteo de referencias, en SUSE® Rancher Prime Continuous Delivery v0.11.1 a v0.14.x)
Recursos Huérfanos: Recursos con marcas de tiempo de eliminación que no pueden ser recolectados como basura

Problemas de Consistencia de Datos

Viaje en el Tiempo de la API: Servidor API de Kubernetes devolviendo datos en caché obsoletos (detectado al obtener recursos múltiples veces)
Desajustes de Hash de Compromiso: Los Bundles/BundleDeployments no se han actualizado al último compromiso de GitRepo
Desviación de Generación de Sincronización Forzada: Los Bundles no reflejan el valor de forceSyncGeneration de su GitRepo
Desajustes de UID: Secretos con referencias de propietario a recursos eliminados/recreados
Desajustes de ID de Despliegue: BundleDeployments where spec.deploymentID != status.appliedDeploymentID

Problemas de Coincidencia de Objetivos

Bundles sin ampliaciones: Bundles creados pero ningún clúster coincidió con el selector de objetivo
GitRepos sin Bundles: GitRepos que no han creado ningún bundle (podría ser una mala vía, objetivos o errores de procesamiento)
Grupos de Clústeres sin Clústeres: Grupos de Clústeres con selectores que no coinciden con ningún clúster
BundleDeployments Huérfanos: BundleDeployments cuyo Bundle padre fue eliminado

Problemas de Rendimiento

Bundles Grandes: Bundles >1MB que pueden afectar el rendimiento de etcd
Recursos de Contenido Faltantes: Paquetes con resourcesSHA256Sum pero sin recurso de contenido correspondiente
Altas Cantidades de Recursos: Grandes cantidades de recursos de paquetes que pueden causar presión en etcd

Problemas de Agente y Clúster

Agente No Listo: Clústeres con estado de agente no listo
Última Vez Vista Faltante: Clústeres sin marca de tiempo de pulsación del agente
Última Vez Vista Obsoleta: Clústeres donde el agente no ha registrado su presencia recientemente (por defecto: 24h, configurable con --agent-staleness)
Missing Agent Bundles: Bundles de Agente Faltantes Espacios de nombres de clúster sin ampliaciones de paquetes de agente esperadas

Problemas de Cadena de Propiedad

Propiedad Rota: Bundles sin propietarios de GitRepo, BundleDeployments sin propietarios de Bundle
Propietarios de Secreto Inválidos: Bundle Secrets con referencias de propietario incorrectas o faltantes

Desajustes de Generación/Observación

Desviación de Generación de GitRepo: La generación de GitRepo != generación observada (el controlador no está procesando actualizaciones)
Generación de Drift de Bundle: La generación de Bundle != generación observada (el controlador no está procesando actualizaciones)
Desviación de Generación de Sincronización de BundleDeployment: La sincronización de generación de BundleDeployment != generación de sincronización forzada (el agente no ha aplicado la sincronización forzada)
Generación Obsoleta del Contenido: Recursos de contenido con valores de generación obsoletos

Ejemplos de Uso

Monitoreo Básico

# Single snapshot with pretty formatting
fleet monitor | jq

# Monitor specific namespace
fleet monitor -n fleet-local | jq

# Check fleet-default namespace (common for local clusters)
fleet monitor -n fleet-default | jq

Monitoreo Continuo

# Collect snapshots every 60 seconds using watch mode
fleet monitor --watch --interval 60 >> monitor.json

# Or monitor with a shorter interval (every 30 seconds)
fleet monitor --watch --interval 30 >> monitor.json

Diagnósticos Dirigidos

# Check for stuck resources
fleet monitor | jq '.diagnostics | {
  bundlesWithGenerationMismatch: .bundlesWithGenerationMismatch | length,
  stuckBundleDeployments: .stuckBundleDeployments | length
}'

# Find bundles with old commits
fleet monitor | jq '.diagnostics.gitRepoBundleInconsistencies'

# Check agent health across all clusters
fleet monitor | jq '.diagnostics.clustersWithAgentIssues'

# Find large bundles that might impact etcd
fleet monitor | jq '.diagnostics.largeBundles'

# Check target matching issues
fleet monitor | jq '.diagnostics | {
  bundlesNoDeployments: .bundlesWithNoDeployments | length,
  gitreposNoBundles: .gitReposWithNoBundles | length,
  clusterGroupsNoClusters: .clusterGroupsWithNoClusters | length
}'

Comparando Estados

# Before making changes
fleet monitor > before.json

# Make changes to GitRepo, bundles, etc.
kubectl edit gitrepo my-repo

# After changes
fleet monitor > after.json

Escenarios Comunes de Solución de Problemas

Situación 1: Bundle No Desplegándose

# Capture current state
fleet monitor | jq > bundle-status.json

# Check for bundles with generation mismatch
jq '.diagnostics.bundlesWithGenerationMismatch' bundle-status.json

# Check if bundle matched any targets
jq '.diagnostics.bundlesWithNoDeployments' bundle-status.json

# Check bundle-to-gitrepo consistency
jq '.diagnostics.gitRepoBundleInconsistencies' bundle-status.json

Situación 2: Agente No Reportando Estado

# Check agent health
fleet monitor | jq '.diagnostics.clustersWithAgentIssues'

# See detailed cluster info
fleet monitor | jq '.clusters[] | select(.agentStatus != "ready")'

# Check when agents last checked in
fleet monitor | jq '.clusters[] | {name, lastSeen, agentAge}'

Escenario 3: Recursos Atascados con Tiempos de Eliminación

# Find resources with deletion timestamps
fleet monitor | jq '{
  bundles: [.bundles[] | select(.deletionTimestamp != null) | .name],
  bundledeployments: [.bundledeployments[] | select(.deletionTimestamp != null) | .name]
}'

# Check finalizers preventing deletion
fleet monitor | jq '.bundles[] | select(.deletionTimestamp != null) | {name, finalizers}'

Caso práctico n.º 4: Commits No Propagándose

# Track commits through the lifecycle
fleet monitor | jq '{
  gitrepo: .gitrepos[0].commit[0:8],
  bundles: [.bundles[] | {name, commit: .commit[0:8]}],
  bundledeployments: [.bundledeployments[] | {name, commit: .commit[0:8]}]
}'

# Find commit mismatches
fleet monitor | jq '.diagnostics.gitRepoBundleInconsistencies[] |
  select(.commitMismatch == true)'

Caso práctico n.º 5: Problemas de Rendimiento

# Check bundle sizes
fleet monitor | jq '.diagnostics.largeBundles'

# Find bundles with most resources
fleet monitor | jq '[.bundles[] | {name, size: .sizeBytes, sizeMB: (.sizeBytes / 1048576 | floor)}] |
  sort_by(.size) | reverse'

# Check for missing content resources
fleet monitor | jq '.diagnostics.bundlesWithMissingContent'

Flujo de Trabajo de Monitoreo Continuo

Para el monitoreo a largo plazo y el análisis de tendencias:

# 1. Start continuous collection with watch mode (runs in background)
nohup fleet monitor --watch --interval 60 >> /var/log/fleet-monitor.json 2>&1 &

# 2. Periodically analyze for issues
watch -n 300 "fleet analyze --issues /var/log/fleet-monitor.json | tail -30"

# 3. Generate daily reports
fleet analyze --diff /var/log/fleet-monitor.json > fleet-report-$(date +%Y%m%d).txt

# 4. Log rotation (keep last 7 days)
find /var/log -name "fleet-report-*.txt" -mtime +7 -delete

Integración con Alertas

El comando de monitorización se puede integrar con sistemas de monitoreo:

# Check if there are any issues (exit code 0 = healthy, 1 = issues)
if fleet monitor | jq -e '
  .diagnostics.bundlesWithGenerationMismatch != [] or
  .diagnostics.stuckBundleDeployments != [] or
  .diagnostics.clustersWithAgentIssues != []
' > /dev/null; then
  echo "ALERT: Fleet issues detected!"
  fleet monitor | jq '.diagnostics' | mail -s "Fleet Alert" admin@example.com
fi

# Prometheus-style metrics export
fleet monitor | jq -r '
  "fleet_stuck_bundles \(.diagnostics.bundlesWithGenerationMismatch | length)",
  "fleet_stuck_bundledeployments \(.diagnostics.stuckBundleDeployments | length)",
  "fleet_agent_issues \(.diagnostics.clustersWithAgentIssues | length)",
  "fleet_large_bundles \(.diagnostics.largeBundles | length)"
'

Comprensión de Diagnósticos

Recursos Atascados

Un recurso se considera "atascado" cuando:

Bundle (Desajuste de Generación):

generation != observedGeneration (el controlador no ha procesado la última especificación)

Nota: Los Bundles con marcas de tiempo de eliminación se rastrean por separado como un conteo en diagnostics.bundlesWithDeletionTimestamp.

BundleDeployment (Atascado):

spec.deploymentID != status.appliedDeploymentID (el agente no ha aplicado la última ampliación)
syncGeneration no coincide con forceSyncGeneration (sincronización forzada no aplicada)
Tiene deletionTimestamp pero aún existe

BundleDeployment (SyncGeneration Mismatch):

syncGeneration != forceSyncGeneration cuando forceSyncGeneration > 0 (rastreados por separado de los BundleDeployments atascados)

Verificación de Consistencia de API

El monitor realiza múltiples recuperaciones de los mismos recursos para detectar "viaje en el tiempo" - cuando el servidor API de Kubernetes devuelve diferentes versiones de recursos debido a caché obsoleta. Esto es crítico porque los datos obsoletos pueden hacer que los paquetes parezcan atascados cuando en realidad están progresando.

Seguimiento de Commits

El monitor rastrea los hashes de commits de Git a lo largo de todo el ciclo de vida: 1. GitRepo obtiene el último commit 2. Bundle debería reflejar ese commit 3. BundleDeployment debería coincidir con el commit de Bundle 4. Bundle Secrets almacenan el commit en las anotaciones

Las discrepancias indican dónde está fallando el proceso de sincronización.

Consideraciones referentes al rendimiento

El monitor obtiene todos los recursos de Fleet en el clúster
Para instalaciones grandes (más de 1000 bundles), considera:
Usar --namespace para limitar el alcance
Ejecutar con menos frecuencia (por ejemplo, cada 120+ segundos en lugar de 60)
Monitorear el uso de recursos del propio comando monitor

Solucionar problemas del comando monitor

Si el comando monitor falla:

# Check Fleet controller is running
kubectl get pods -n cattle-fleet-system

# Verify you have proper RBAC permissions
kubectl auth can-i list bundles --all-namespaces
kubectl auth can-i list bundledeployments --all-namespaces

# Check if CRDs are installed
kubectl get crds | grep fleet.cattle.io

# Enable verbose logging
fleet monitor --verbose 2>&1 | tee monitor-debug.log