Resolución de problemas de despliegue

Empieza por localizar la capa que falla. Una respuesta del Gateway y un pod no preparado requieren evidencias distintas. Para emisión rechazada o resultados de validación, consulta el diagnóstico PKI; para enrolamiento, el diagnóstico EST.

Secuencia de diagnóstico

Reproduce una sola operación

Anota hora en UTC, usuario o principal, recurso, endpoint y resultado. Evita repetir una acción destructiva como revocación o eliminación.

Separa cliente, Gateway y servicio

Comprueba el código HTTP. Un 401 apunta a autenticación; un 403, a autorización; un 404, a ruta o recurso; un 5xx, al servicio o una dependencia.

Revisa el estado de Kubernetes

Localiza pods no preparados, reinicios, eventos recientes y el estado del release.

Consulta el servicio afectado

Revisa su endpoint /health y sus logs en la misma ventana temporal. Después sigue la dependencia indicada: PostgreSQL, RabbitMQ, proveedor OIDC o motor criptográfico.

Valida el resultado desde fuera

Para PKI, comprueba el certificado, la cadena, OCSP o CRL con el mismo tipo de cliente que utiliza producción.

Recogida mínima de evidencias

Sustituye los marcadores por tu release, namespace y deployment reales.

helm status <release> -n <namespace>
kubectl get pods -n <namespace> -o wide
kubectl get deployments,statefulsets,jobs -n <namespace>
kubectl get events -n <namespace> --sort-by=.lastTimestamp
kubectl describe pod <pod> -n <namespace>
kubectl logs <pod> -n <namespace> --all-containers --since=30m

Ejecuta también la prueba de conectividad del chart:

helm test <release> -n <namespace>

El test consulta la salud de CA, DMS Manager, Device Manager y VA, y comprueba que la UI devuelve HTML. Un test correcto confirma conectividad básica, no un flujo completo de emisión.

Las sondas usan /health

Los servicios del chart exponen sondas de inicio, disponibilidad y vida sobre /health. Un pod puede estar ejecutándose pero no recibir tráfico si la readiness probe falla.

No puedo iniciar sesión

Si recibes un 401:

comprueba que la autoridad OIDC de la UI sea accesible desde el navegador;
verifica emisor, audiencia y expiración del token;
confirma que el Gateway puede obtener las claves de la URI JWKS;
revisa que la ruta pública e interna del proveedor apunten al mismo realm.

Si el login termina pero las APIs devuelven 403:

inspecciona los claims reales del token;
confirma que coinciden con un principal activo;
revisa las políticas concedidas al principal;
verifica que authz alcanza PostgreSQL y su JWKS.

En una instalación nueva, confirma que el Job de migración terminó. Ese Job crea esquemas, migra authz, precarga políticas y provisiona los principales definidos en services.authz.bootstrap.

Todo devuelve 403 o 5xx

La autorización externa falla cerrada por defecto. Si authz no está disponible, las rutas protegidas se bloquean.

Localiza el pod y Service de authz.
Comprueba /health, logs y conexión a su base de datos.
Verifica el DNS y puerto configurados en externalAuthorization.
Comprueba que la ruta del check es /v1/ext_authz/check.
No cambies a failOpen: true como solución permanente: permitiría tráfico sin autorización durante la caída.

Un pod no está Ready

Revisa primero kubectl describe pod. Las causas habituales son:

credenciales o DNS incorrectos para PostgreSQL o RabbitMQ;
volumen persistente sin enlazar;
imagen inaccesible o política de pull incorrecta;
configuración inválida del motor criptográfico;
límites de CPU o memoria demasiado bajos;
migración previa incompleta.

Los valores genéricos solicitan 100 mCPU y 128 MiB y limitan a 500 mCPU y 512 MiB. Ajusta por servicio cuando haya OOMKills, throttling o arranques lentos.

Los motores KMS basados en filesystem y el almacenamiento local de VA utilizan volúmenes de acceso exclusivo. Mantén una réplica o migra a backends compartidos antes de habilitar autoscaling.

Las llamadas internas ahora fallan rápido en lugar de bloquearse para los clientes cubiertos por Proxy de salida: los intentos de conexión agotan el tiempo tras 30 segundos y los handshakes TLS tras 10 segundos. El conector del motor de autorización mantiene su propio transporte sin estos timeouts de conexión ni de handshake TLS; solo su timeout global de petición de 30 segundos acota cada llamada. Si un proxy de salida gestiona el tráfico de salida del clúster, comprueba las variables de entorno HTTP_PROXY, HTTPS_PROXY y NO_PROXY del pod e incluye los nombres de servicio internos en NO_PROXY.

Los eventos no llegan

Los eventos de dominio y auditoría dependen del publisher del bus:

verifica que esté habilitado en el servicio emisor;
comprueba conectividad y credenciales AMQP;
revisa exchange, routing key, colas y consumidores;
inspecciona dead-letter queues;
alerta sobre colas durables huérfanas y crecimiento de backlog.

Una caída del consumidor no siempre impide que la operación principal termine. Por eso debes monitorizar RabbitMQ y verificar de forma independiente la persistencia de auditoría.

Observabilidad

El chart puede habilitar instrumentación OpenTelemetry. Las trazas se exportan por OTLP HTTP y los logs pueden dirigirse a un endpoint compatible, como VictoriaLogs. Usa un identificador de correlación y la misma ventana temporal para unir Gateway, authz, servicio y dependencia.

Antes de cerrar una incidencia, guarda:

causa confirmada;
alcance temporal y recursos afectados;
comandos o consultas utilizados;
cambio aplicado y forma de revertirlo;
validación desde un consumidor;
acción preventiva y propietario.

En esta página