Mejores prácticas para Operadores de Kubernetes

Reconciliadores idempotentes, diseño basado en nivel y lista de verificación de producción para operadores.

Estas reglas convierten los puntos débiles recurrentes de los operadores en hábitos de revisión, puertas de CI y opciones de empaquetado que mantienen los controladores seguros a escala.

Cómo usar esta lista

• Revise las secciones A-E durante la revisión de diseño antes de agregar nuevos campos de API o tipos de recursos hijos.
• Ejecute envtest y operator-sdk bundle validate en CI en cada etiqueta de lanzamiento.
• Habilite la elección de líder y recopile métricas de reconciliación antes de aumentar las réplicas de Deployment por encima de uno.
• Haga coincidir los modos de instalación de OLM y el alcance de RBAC con el modelo de tenencia más pequeño que su producto admita.

A - Diseño de reconciliación

• Trate cada reconciliación como una pasada completa de convergencia. Compare la especificación deseada con el estado observado; nunca asuma que un solo evento representa el delta completo.
• Mantenga la reconciliación idempotente. Ejecutarla dos veces con el mismo estado del clúster no debe crear recursos externos duplicados ni parchear hijos dos veces.
• Devuelva client.IgnoreNotFound en objetos primarios eliminados. Evite métricas de error para carreras entre la eliminación y la reconciliación final.
• Use Status().Update para condiciones y preparación. Nunca modifique campos de estado a través de Update genérico en el objeto completo.
• Prefiera RequeueAfter para esperas esperadas. Reserve los errores devueltos para fallos genuinos que merezcan una alerta.
• Establezca referencias de propietario en cada objeto hijo que cree. Habilite la recolección de basura y las vigilancias Owns sin pegamento solo de etiquetas.

B - API, webhooks y CRDs

• Valide límites simples en marcadores CRD; use webhooks para reglas entre campos. Mantenga las capas OpenAPI y de admisión complementarias, no duplicadas de manera inconsistente.
• Establezca valores predeterminados para especificaciones faltantes en webhooks mutadores. La reconciliación aún debe tolerar objetos heredados que carecen de campos nuevos.
• Use failurePolicy: Fail para validación crítica de seguridad. Empareje con pods de webhook HA y monitoreo de certificados.
• Aumente la versión de la API en lugar de romper los nombres de campos JSON. Agregue conversión cuando la versión de almacenamiento cambie de forma.
• Regenere los manifiestos después de editar marcadores. Nunca edite manualmente config/crd/bases sin sincronizar los tipos de Go.
• Exhiba columnas significativas en kubectl get. Los ingenieros de soporte deben ver la fase y la preparación sin volcados de YAML.

C - Ciclo de vida, finalizadores y eliminación

• Agregue un finalizador antes de crear dependencias externas. Bloquee la eliminación del CR hasta que se complete la limpieza de bases de datos en la nube, DNS o IAM.
• Haga que la limpieza sea idempotente. Las API de eliminación externas pueden llamarse más de una vez durante tormentas de reintentos.
• Elimine los finalizadores solo después de una limpieza exitosa. Los objetos atascados en Terminating indican una lógica de limpieza faltante.
• Use predicados para reducir el ruido del estado en objetos primarios. Deje que el tráfico de Owns hijo impulse las actualizaciones de preparación.
• Documente el comportamiento huérfano para objetos hijos opcionales. Aclare si la eliminación del CR debe eliminar recursos compartidos del clúster.

D - Pruebas, observabilidad y operaciones

• Refleje el registro del Scheme de producción en las pruebas. Los tipos faltantes en envtest ocultan fallos de decodificación en producción.
• Cubra las rutas de adición, activa y eliminación de finalizadores en tablas envtest o fake client. Los errores de eliminación son incidentes de producción.
• Habilite la elección de líder cuando las réplicas puedan exceder uno. Los pods en espera no deben reconciliarse concurrentemente.
• Exhiba métricas de Prometheus y alerte sobre las tasas de reintento. Los picos de workqueue_retries_total preceden a las páginas de incidentes.
• Conecte las sondas de liveness y readiness a puertos de salud dedicados. No vincule las sondas a los puntos finales de recopilación de métricas.
• Inicie el Manager con ctrl.SetupSignalHandler. Libere las concesiones de manera oportuna en las actualizaciones continuas.

E - Empaquetado, RBAC y multi-tenencia

• Alinee los permisos de CSV con el RBAC generado. Las instalaciones de OLM fallan silenciosamente de forma parcial cuando las reglas se desvían de las necesidades del reconciliador.
• Deshabilite los modos de instalación que no implemente. Reclamar AllNamespaces sin RBAC de clúster bloquea la revisión de seguridad.
• Alcance los Roles a los namespaces del inquilino cuando sea posible. Prefiera OwnNamespace sobre la lista de Secretos a nivel de clúster para plataformas SaaS.
• Pase --leader-elect y límites de recursos en el Deployment de CSV. HA sin elección duplica efectos secundarios externos.
• Valide los bundles en CI antes de la publicación en el catálogo. operator-sdk bundle validate detecta descriptores de CRD poseídos faltantes.
• Planifique omisiones de actualización para lanzamientos intermedios incorrectos. Documente replaces y skips en los metadatos de CSV.

Preguntas frecuentes

Relacionado

• Escribiendo un Reconciliador: ctrl.Request & Bucle de Reconciliación - patrones de reconciliación idempotentes
• Watches, Predicates, Owner References & Finalizers - seguridad del ciclo de vida
• Pruebas de Operadores con envtest & fake client - arnés de pruebas CI
• Elección de Líder, Métricas & Observabilidad de Operadores - operaciones de producción
• OLM Bundles, Upgrades & RBAC Multi-Inquilino - empaquetado y tenencia

Versiones de Stack: Esta página fue escrita para Go 1.26.x (GC por defecto 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 (última - verificar objetivos de placa en la compilación), wazero (última - verificar en la compilación), y golangci-lint (última - verificar conjunto de linters en la compilación).