Diagnóstico de incidencias¶
Empezar por el primer job o recurso que falla y conservar su SHA, destino y mensaje. Las comprobaciones siguientes relacionan síntomas con contratos del código; no afirman que todos ellos hayan ocurrido en el entorno original.
CI y artefactos¶
| Síntoma | Comprobar primero | Acción |
|---|---|---|
| No aparecen jobs de build/deploy | Protección de referencia, rama literal main, flags |
Revisar reglas efectivas; una rama de feature no protegida queda fuera de los jobs propios |
| Include no encontrado | Namespace de cicd-templates, ref, permisos y versión de GitLab |
Validar composición expandida en CI Lint |
| Code Quality deja de funcionar | Dependencia de CodeClimate deprecada y runner | Sustituir el analizador con exportación compatible; no ocultar el fallo con un informe vacío |
| Docker no conecta | Servicio DinD, permisos, host y TLS del runner | Ajustar el runner conforme al modo elegido |
No existe target/app.jar |
Job Maven, nombre final y descarga de artefactos | Reparar el build o reconstruir el artefacto caducado |
| Imagen no encontrada por scanner | Ruta, slug, SHA y variables CS_IMAGE/registro |
Alinear análisis y build; comprobar acceso al registro |
| Push de manifiestos denegado | Identidad CD y protección de main |
Usar permiso de escritura válido; read_repository de un Deploy Token no basta |
Conflicto al enviar a main |
Pipelines concurrentes | Serializar entregas y revalidar la revisión; evitar force push automático |
| Error de job necesitado inexistente en IaC | needs y exclusión de applies fuera de main |
Validar la DAG con las variables/rama reales; ajustar reglas conjuntamente |
Conexión y Kubernetes¶
| Síntoma | Comprobar primero | Acción |
|---|---|---|
| Contexto de agente ausente | Nombre exacto, ci_access, conexión de agente |
Corregir autorización/proyecto y esperar propagación |
Forbidden con contexto correcto |
Identidad y RBAC efectivos | Comprobar kubectl auth can-i para el verbo/recurso/namespace |
| Provider Kubernetes falla pero agente conecta | Acceso directo del runner al API en la fase platform | Revisar red y autenticación del provider; el agente no sustituye esa ruta |
ImagePullBackOff |
Secret registry, ruta/tag y conectividad |
Crear/rotar credencial externa y comprobar imagen |
Pod Pending |
Memoria disponible, requests, nodos y eventos | Ajustar capacidad o scheduling; min/max de EKS no instala un autoscaler |
CrashLoopBackOff en rest |
Variables de BD, red privada, permisos, logs | Verificar contrato del Secret sin volcar sus valores |
| Error de escritura en filesystem | Ruta temporal requerida y raíz de solo lectura | Incorporar un volumen escribible acotado si la aplicación lo necesita |
| Pipeline verde, servicio no listo | Falta de espera de rollout y pruebas de aplicación | Consultar condiciones de Deployment, pods, endpoints y sondas |
| Cambios borrados de Git siguen en el clúster | Semántica de kubectl apply |
Retirar explícitamente objetos de los que el proyecto es propietario |
Comandos iniciales de lectura, con un contexto ya seleccionado y autorizado:
kubectl --context "$KUBE_CONTEXT" -n app get pods -o wide
kubectl --context "$KUBE_CONTEXT" -n app get events --sort-by=.lastTimestamp
kubectl --context "$KUBE_CONTEXT" -n app describe deployment rest
kubectl --context "$KUBE_CONTEXT" auth can-i patch deployments -n app
Exposición y base de datos¶
| Síntoma | Comprobar primero | Acción |
|---|---|---|
| Ingress sin dirección en GKE | Clase alb del único manifiesto público |
Definir una variante/controlador GKE; no asumir portabilidad de anotaciones AWS |
| Error TLS o host en AWS | Certificado ACM, región, DNS y controlador ALB | Adaptar referencias del entorno; DNS y certificado no se aprovisionan aquí |
| UI carga, API falla | Request real del navegador, ruta /api/v1, servicios |
Confirmar origen/rutas; rest interno no es un host público |
| MySQL connection refused/timeout | Endpoint, puerto, SG/firewall, peering y nodos | Verificar red privada de la nube seleccionada |
| Error de autenticación MySQL | Coherencia BD/Secret y reinicio del pod | Completar la rotación de credenciales |
| Versión antigua no arranca tras rollback | Esquema modificado por Hibernate | Usar estrategia de recuperación de datos compatible; no insistir sólo con imágenes |
Estado y destrucción¶
Un lock activo no se resuelve borrando recursos del estado. Comprobar propietario del lock y jobs todavía ejecutándose. Si el plan está obsoleto, generar un nuevo plan contra el mismo estado. Si fallan dependencias durante la retirada, comprobar recursos creados por controladores y recursos externos, como el balanceador o el peering de servicio privado.
El job de recuperación de Private Service Access cambia el estado y puede dejar recursos existentes fuera de su administración. La decisión exige conocer el error original, respaldar el estado y reconciliar los recursos. Consultar teardown.
Sitio documental¶
Si un pipeline de Pages falla, consultar publicación. Las causas habituales de este repositorio son dependencias no instaladas, una traducción sin pareja, enlaces internos rotos o configuración de URL base incorrecta. No requiere credenciales de infraestructura para diagnosticarlo.