Mi conector está desconectado

Un conector normalmente cambia a Online dentro de 30 segundos de la instalación. Si no lo hace, o si un conector previamente saludable cambia a Offline, Degraded o Needs recovery, utilice este runbook.

Qué significa el estado

• Offline: el conector no está actualmente conectado, pero puede recuperarse automáticamente después de una interrupción de red transitoria o reinicio de proceso.
• Degraded: al menos una ruta de ejecución no es saludable, pero no todas las rutas del conector están inactivas.
• Needs recovery: el conector ya no está en una ruta de reconexión normal. Trate esto como pérdida de identidad durable, bootstrap fallback inválido u otro caso de recuperación acotada. El conector no reintenta silenciosamente el token de bootstrap original en este estado; falla de forma cerrada y espera un flujo de recuperación iniciado explícitamente por el operador.

Modo autónomo vs recuperación guiada

Cómo se recupera el conector de un reinicio depende de si el almacenamiento de identidad durable está presente.

Modo	Postura de almacenamiento	Resultado en tiempo de ejecución	Acción del operador
Modo autónomo	/data durable o PAM_AGENT_DATA_DIR está montado e íntegro	El conector carga su paquete de identidad al iniciar y realiza reconexión mTLS sin intervención del operador	Ninguna
Recuperación guiada	Sin /data persistente o el volumen de identidad se perdió / recreó vacío	El conector no puede reconectarse normalmente e ingresa a needs_recovery mientras preserva la configuración del conector en el plano de control	Cree un token de inscripción de un solo uso fresco y vuelva a emparejar el conector

El conector carga su paquete de identidad al iniciar y realiza reconexión mTLS sin ninguna acción del operador en modo autónomo. Este es el valor predeterminado para implementaciones correctamente configuradas de VM, Docker y Kubernetes. Los reinicios, pods reprogramados y la recreación de contenedores tienen todos éxito automático siempre que el almacenamiento durable sobreviva.

En recuperación guiada, el conector no tiene identidad local y no puede reconectarse. La configuración del conector — asignación de organización, ID de punto final y redes permitidas — se preserva en el plano de control, pero se requiere una nueva inscripción. Este es el estado explícito needs_recovery.

La jubilación del bootstrap ocurre después de la primera inscripción exitosa y el primer latido en línea confirmado. Una vez que el paquete de identidad del conector se persiste en almacenamiento durable y el plano de control registra ese latido, el token de bootstrap se consume y se retira. Todos los reinicios posteriores deben usar la identidad persistida para reconexión mTLS. No hay ruta — en ninguno de los modos — donde un conector previamente inscrito caiga silenciosamente al token de bootstrap como credencial de reinicio normal.

Comprobaciones rápidas

1. ¿El host está activo? SSH o RDP en la máquina del conector; confirme que Docker / el servicio nativo está en ejecución.
   • Docker: docker ps | grep vaultpam-connector — el contenedor debe estar Up.
   • systemd: systemctl status vaultpam-connector.
2. ¿Puede el host alcanzar el plano de control? Desde la máquina del conector:

   curl -v https://<control-plane-host>/healthz

   Si esto falla, tiene un problema de red/DNS/firewall. Los puertos 443 (HTTPS del plano de control) y opcionalmente 51820/udp (túnel VPN inverso) deben estar abiertos hacia afuera.
3. ¿El token de inscripción sigue siendo válido? Los tokens caducan después de 4 horas por defecto. Si el conector nunca ha estado en línea y el token caducó, genere uno nuevo desde Connectors → seleccione conector → Regenerate token.
4. ¿El conector perdió su almacenamiento de identidad durable? Un conector previamente emparejado debe reiniciarse desde la identidad persistida bajo /data o PAM_AGENT_DATA_DIR.
   • Docker: confirme que el contenedor aún monta el mismo volumen nombrado o bind mount en /data.
   • Nativo / VM: confirme que el servicio aún apunta a la misma ruta de host durable y que el usuario del conector puede leerla.
   • Kubernetes: confirme que el pod aún monta el PVC esperado y no fue reimplementado en emptyDir u otra capa efímera.

Identifique la clase de fallo

1. Fallo de bootstrap de primer arranque

Utilice esta rama si el conector nunca se emparejó correctamente.

Señales comunes:

• el conector nunca pasó a Online
• los logs muestran expiración de token, revocación de token, fallo de validación de CSR o fallo de confianza de CA
• la UI aún muestra un estado de incorporación o activación en lugar de ready

Recuperación:

1. Solucione el problema de confianza, red o token.
2. Genere un token de inscripción fresco si el original caducó o fue revocado.
3. Reintente el emparejamiento.

2. Fallo de reconexión normal

Utilice esta rama si el conector se emparejó antes y aún tiene su identidad durable.

Señales comunes:

• Offline temporal después de reinicio, despliegue o parpadeo de red
• actividad de alerta cp_tunnel_heartbeat_timeouts_total
• el directorio de datos local aún está presente y es legible

Recuperación:

1. Restaure la alcanzabilidad HTTPS saliente al plano de control.
2. Confirme que el conector aún tiene su paquete de identidad local en almacenamiento durable.
3. Reinicie el proceso del conector o pod una vez.
4. Valide que el conector regrese a Online sin usar un token de inscripción nuevo.

3. Pérdida de identidad durable o bootstrap fallback inválido

Utilice esta rama si el conector se emparejó antes, pero ahora se comporta como un conector completamente nuevo.

Señales comunes:

• UI o API muestran Needs recovery
• los logs muestran 401 ENROLLMENT_TOKEN_INVALID después de un emparejamiento anteriormente exitoso
• las alertas de 401 del punto final de inscripción aumentan después del reinicio
• el montaje de almacenamiento durable fue reemplazado, eliminado o recreado vacío

Recuperación:

1. Detenga el conector o escale el pod a cero antes de cambiar credenciales.
2. Intente reasignar el almacenamiento durable original primero.
3. Si la identidad original se ha ido, trate esto como reaprovisionamiento controlado:
   • revoque el token de bootstrap obsoleto si aún existe
   • cree un token de inscripción de un solo uso fresco desde el plano de control
   • asegúrese de que el almacenamiento durable esté montado correctamente antes de comenzar nuevamente
   • empareje exactamente una vez con el nuevo token
4. Valide que los reinicios posteriores reutilicen la identidad persistida en lugar de solicitar otro token.
5. Confirme que la configuración del conector preservada aún está presente; si falta la configuración, escale como un problema de despliegue separado.

No trate los reintentossucesivos de bootstrap como una ruta de reinicio normal.

Logs a inspeccionar

• Docker: docker logs -n 200 vaultpam-connector.
• Nativo: /var/log/vaultpam/connector.log (Linux) o %PROGRAMDATA%\VaultPAM\connector.log (Windows).

Errores comunes:

Fragmento de log	Significado	Solución
x509: certificate signed by unknown authority	El host no confía en la CA	Importe el paquete de certificados de CA (/etc/vaultpam/ca.crt) — vea el runbook impreso durante la instalación
connection refused	Red bloqueada	Compruebe la lista de permisos de salida del firewall corporativo
enrolment token revoked	Alguien hizo clic en Revoke en la UI	Genere un nuevo token
401 ENROLLMENT_TOKEN_INVALID después de que el conector ya estuviera emparejado una vez	El conector perdió su identidad persistida y recurrió al bootstrap	Reasigne el directorio de datos durable original si está disponible. Si la identidad se ha ido, genere un token fresco y empareje nuevamente en almacenamiento durable

Validación posterior a la recuperación

Después de cualquier corrección:

1. Confirme que el conector llegue a Online.
2. Reinicie el conector una vez más.
3. Confirme que se reconecta sin un token de inscripción fresco.
4. Confirme que la ruta de almacenamiento durable aún contiene el estado del conector después del reinicio.
5. Capture la evidencia para auditoría:
   • estado del conector antes y después
   • la línea de log que prueba que la reconexión o renovación fue exitosa
   • cualquier entrada de auditoría endpoint.cert_renewed o gateway.enrollment_failed vinculada al incidente
   • el nombre de la alerta y la ventana de tiempo si el monitoreo se activó

Aún atascado

Contacte con soporte e incluya: versión del conector, cola de logs, salida de curl -v https://<control-plane-host>/healthz.

Artículos relacionados

• Pair your first connector
• What is a Connector?