Saltar al contenido principal
Esta página recopila los fallos que vemos con más frecuencia durante la instalación y la operación continua, junto con los comandos de diagnóstico y las soluciones. Cada entrada sigue la estructura Síntoma → Diagnóstico → Solución. Si no logra resolverlo, capture los logs del operador, el estado del recurso Vantage y cualquier estado de aplicación de ArgoCD con errores antes de ponerse en contacto con su equipo de cuenta de ABBYY:

​
Operador y CRD

​
Forzar un reintento tras corregir un problema por falta de recursos

Síntoma. Has corregido la causa subyacente de un error (has agregado un secreto de Key Vault que faltaba, concedido permisos de RBAC o reparado una base de datos), pero el operador no ha vuelto a reconciliar. Diagnóstico. El operador responde a eventos en el propio recurso Vantage; los cambios de estado fuera del recurso (permisos de Key Vault, políticas de red, servicios externos) no desencadenan una reconciliación. Los recursos Vantage son mutables, pero para reintentar la instalación de Vantage, el recurso debe anotarse con vantage.abbyy.com/reprocess (cualquier valor). Solución. Anota el recurso Vantage con vantage.abbyy.com/reprocess (cualquier valor) para forzar una nueva reconciliación desde la fase Preflight:
Actualice el valor de la anotación (por ejemplo, una marca de tiempo) cada vez que quiera volver a intentarlo. El operador solo reconcilia de nuevo cuando cambia el valor de la anotación.

​
Recurso Vantage atascado en Progressing

Síntoma. kubectl describe vantages.vantage.abbyy.com $release_name -n $install_namespace muestra Progressing=True durante mucho tiempo y Ready nunca pasa a True. Diagnóstico. Revise status.degradationReasons[] en el recurso; el operador indica allí qué componente está fallando. Luego, compruebe la aplicación de ArgoCD correspondiente:
Solución. Resuelva el error de sincronización de ArgoCD subyacente. Causas habituales: un chart de Helm upstream necesita un valor que el clúster todavía no tiene (falta un secreto de Key Vault, error al descargar la imagen) o no hay un ingress gateway. Una vez corregido el problema subyacente, añada la anotación vantage.abbyy.com/reprocess al recurso Vantage para reintentar la instalación (Forzar un reintento)).

​
El operador nunca detecta un nuevo recurso Vantage

Síntoma. Aplica un recurso Vantage y kubectl get vantages lo muestra, pero el operador nunca refleja ningún estado. Diagnóstico. Compruebe que el operador se está ejecutando y reconciliando:
Solución. El operador supervisa los recursos de Vantage en todo el clúster; el chart no expone ningún valor que restrinja qué espacios de nombres supervisa. Si el operador está en ejecución pero los logs no muestran ningún intento de reconciliar su recurso, verifique que la CRD esté en la versión que espera el operador (vantage.abbyy.com/v1alpha1) y que haya exactamente una instancia del operador instalada en el clúster. Para consultar los valores que el chart admite realmente, ejecute helm show values $charts_uri/vantage-operator --version $operator_version (Valores del Helm chart).

​
Error de validación al aplicar el CRD

Síntoma. kubectl apply rechaza el recurso Vantage con un mensaje de validación CEL. Diagnóstico. El mensaje de error proviene de las reglas CEL del CRD. Las causas más comunes son un bloque ociMigration con enabled: true pero sin destination, o un bloque techcore con keepPreviousVersion: true pero sin previousVersion. Solución. Establezca el campo que se indica en el mensaje de validación. Consulte la referencia de la API para ver las reglas de validación completas.

​
Migración OCI

​
El trabajo de migración de OCI nunca se inicia

Síntoma. El recurso Vantage permanece en Progressing; no existe ningún trabajo llamado $release_name-oci-migration en tu espacio de nombres de instalación. Diagnóstico. Revisa las comprobaciones previas del operador en los logs del operador y los motivos de degradación del recurso. El trabajo se crea solo cuando las comprobaciones previas se completan correctamente. Solución. Resuelve la comprobación previa que está fallando. Durante las comprobaciones previas, se valida la configuración, incluida la configuración de secretos, así que empieza por confirmar que exista cada alias requerido en tu proveedor de secretos (Secretos y Key Vault).

​
El trabajo de migración de OCI se ejecuta, pero falla

Síntoma. kubectl -n $install_namespace get jobs muestra el trabajo de migración, pero no llega a Complete. Diagnóstico. Inspecciona los logs del trabajo:
Solución. La mayoría de los fallos están relacionados con la autenticación: el trabajo no pudo extraer del registro de origen (compruebe el secreto credentialsRef.name o el nombre de usuario/la contraseña de cada entrada vantage.ociMigration.sources[]) o no pudo subir al destino (compruebe las credenciales de vantage.ociMigration.destination y el RBAC de la identidad de carga de trabajo si usa Azure Workload Identity). Si el pod del trabajo ni siquiera llega a descargar su imagen, consulte Pods atascados en ImagePullBackOff.

​
Descarga de imágenes

​
Pods atascados en ImagePullBackOff

Síntoma. Los pods de Operator, el pod del trabajo de OCI migration o los pods de carga de trabajo de Vantage muestran ImagePullBackOff o ErrImagePull, y kubectl describe pod muestra unauthorized: authentication required de su registro. Diagnóstico. Localice los pods que fallan y el error del registro:
Solución. Conceda acceso de extracción de su registro al componente que está fallando:
  • pods de Operator: actualice la release vantage-operator con --set "manager.imagePullSecrets[0].name=my-pull-secret".
  • trabajo de migración de OCI: ejecute el trabajo con una ServiceAccount que incluya el secreto de extracción (vantage.ociMigration.serviceAccountName=my-service-account) o haga referencia al secreto en la entrada de origen (vantage.ociMigration.sources[0].credentialsRef.name=my-pull-secret).
  • cargas de trabajo de Vantage: agregue el secreto de extracción a imagePullSecrets de la ServiceAccount indicada por vantage.serviceAccountName. Si el pod que falla informa otra ServiceAccount, incluida default, conceda acceso de extracción a esa ServiceAccount o configure el componente para que use la ServiceAccount de Vantage prevista.
  • En AKS: en lugar de secretos de extracción, conceda AcrPull en el registro a la kubelet identity del clúster.
Consulte el acceso de extracción de imágenes de Azure o el acceso al registro autoadministrado para conocer la configuración completa.

​
Secrets

​
Los pods no logran iniciarse con MountVolume.SetUp failed for volume "secrets-store"

Síntoma. Los pods de Vantage no logran iniciarse; los eventos del pod muestran errores de montaje del controlador CSI. Diagnóstico. El controlador Secrets Store CSI no pudo recuperar un secreto de Key Vault. Causas más comunes:
  • La identidad seleccionada por vantage.secrets.azure.identityMode no tiene acceso de lectura al secreto o certificado indicado.
  • El nombre de un objeto de Key Vault no coincide con el alias que espera Vantage y no se proporcionó ningún mapeo de objects.
  • El proveedor de Azure para el controlador CSI no está instalado.
Solución. Verifique que la identidad configurada tenga permisos get para cada alias enumerado en Secretos y Key Vault. Si los nombres de los objetos de Key Vault difieren de los alias, proporcione un mapeo de objects en vantage.secrets.azure. Consulte Modos de identidad para saber qué identidad se usa en cada modo.

​
Faltan secretos TLS emparejados

Síntoma. Los servicios de autenticación no se inician y falta uno de los cuatro alias de secretos TLS en su Key Vault. Diagnóstico. Vantage requiere cuatro elementos codificados en PEM almacenados como secretos de Key Vault: un certificado y una clave privada para la firma de autenticación, y un certificado y una clave privada para los tokens de autenticación desactivados. Solución. Confirme que existan los cuatro alias: authSigningTlsCrt, authSigningTlsKey, authDeactivatedTlsCrt, authDeactivatedTlsKey. Consulte Secretos y Key Vault → Alias de certificados.

​
El proveedor de Secret de Kubernetes falla durante la verificación previa

Síntoma. Una instalación autogestionada falla durante la verificación previa porque falta un Secret, falta una clave o se produce un error forbidden. Diagnóstico. El operador lee Secrets nativos en $install_namespace durante la verificación previa. Es posible que el Secret especificado no exista, que una asignación de objects apunte a un nombre incorrecto, que el Secret no contenga la clave de datos esperada o que el RoleBinding creado por el chart no corresponda a la ServiceAccount del operador instalado. Compruebe el permiso del operador para uno de los Secrets afectados:
Corrección. Confirme que cada Secret exista en el espacio de nombres de instalación y, a continuación, compare vantage.secrets.kubernetes.objects con el inventario de alias de secretos. Si la autorización falla, confirme que los valores operator.namespace y operator.controllerManagerServiceAccount del chart de Vantage identifican al operador instalado. Si un controlador externo de secrets crea los Secrets, espere a que informe de una sincronización correcta antes de forzar una nueva reconciliación del operador.

​
Bases de datos

​
Las cargas de trabajo de PostgreSQL indican que no se encontró DataProvider

Síntoma. Los pods de inicio o migración de la base de datos fallan con DataProvider '<value>' not found. Diagnóstico. vantage.databaseProvider distingue entre mayúsculas y minúsculas. El provider de Runtime de PostgreSQL se llama exactamente PostgreSQL. Solución. Establezca:
Los valores como Postgresql y PostgreSql no son válidos en tiempo de ejecución. Aplique los valores corregidos y fuerce un reintento.

​
El esquema de PostgreSQL no está actualizado

Síntoma. Varios servicios no se inician y muestran postgres database schema is not up to date o conflictos entre versiones de migración. Diagnóstico. Varios servicios están usando la misma base de datos lógica de PostgreSQL. Cada servicio mantiene su propio historial de migración y debe usar una base de datos distinta. Solución. Cree una base de datos independiente para cada alias de base de datos. Para las cargas de trabajo que usan la clave genérica Database__ConnectionString, cree Secrets de Kubernetes independientes y asocie cada alias mediante vantage.secrets.kubernetes.objects. Consulte PostgreSQL y Secrets por servicio.

​
ArgoCD

​
La aplicación de ArgoCD muestra OutOfSync después de la instalación

Síntoma. kubectl get application -A indica que una de las aplicaciones gestionadas por el operador aparece como OutOfSync después de que, por lo demás, el operador haya indicado Ready. Diagnóstico. Revise status.conditions[] de la aplicación:
Solución. Si la deriva se debe a ediciones manuales en objetos administrados por el operador, deshágalas; el operador es quien controla esos objetos y los volverá a sincronizar. Si la deriva está en un valor del chart, actualícelo mediante el recurso Vantage (o el release de Helm vantage-selfhosted). Nunca edite directamente el objeto Application subyacente de ArgoCD.

​
Sincronización de ArgoCD ApplicationSet atascada

Síntoma. Las aplicaciones de ArgoCD nunca avanzan por sus oleadas de sincronización. Diagnóstico. Compruebe que Progressive Syncs de ApplicationSet esté habilitado en su instalación de ArgoCD:
Solución. Habilite Progressive Syncs según la documentación de ArgoCD y reinicie el controlador de ApplicationSet.

​
KEDA y Prometheus

​
Los recursos ScaledObject no pueden crear HPA

Síntoma. KEDA indica Ready=False o ScaledObjectCheckFailed, y ArgoCD muestra en estado degradado las aplicaciones de las cargas de trabajo afectadas. Diagnóstico. Compruebe la versión de KEDA instalada y los eventos de ScaledObject:
Los charts actuales de carga de trabajo de Vantage requieren KEDA 2.17.x; KEDA 2.18 y las versiones posteriores eliminaron un campo del escalador que utilizan. Corrección. Instala KEDA 2.17.3 y, a continuación, vuelve a sincronizar las aplicaciones de ArgoCD afectadas.

​
Las métricas de HPA muestran <unknown>

Síntoma. Existen recursos de KEDA, pero kubectl get hpa muestra <unknown> para las métricas de Vantage y las cargas de trabajo no escalan como se espera. Diagnóstico. Los recursos ScaledObject consultan http://prometheus-operated.observability.svc.cluster.local:9090. Puede que falte el Service, que no se esté seleccionando el ServiceMonitor de Vantage o que la malla de servicios esté bloqueando la recopilación de métricas. Solución. Confirme que el Service de Prometheus exista, que sus destinos de Vantage estén UP y que los valores del chart observability estén en el nivel superior:
Consulte Escalado automático con KEDA para conocer el comportamiento de los activadores y la verificación, y Monitorización con Prometheus para la configuración de Istio y Linkerd.

​
Instalación de una Habilidad

​
Faltan skills después de que la instalación indica Ready

Síntoma. El recurso Vantage indica Ready y Vantage es accesible, pero faltan las skills esperadas y no aparece nada sobre skills en ArgoCD. Diagnóstico. Las skills se instalan mediante un trabajo de Kubernetes independiente que no se muestra a través de ArgoCD, por lo que nunca aparece en argocd app list (incluida la captura de diagnóstico de la parte superior de esta página). El trabajo puede seguir ejecutándose después de Ready; mientras tanto, puede usar Vantage. Compruebe el trabajo:
Solución. Si el trabajo sigue ejecutándose, espere a que llegue a Complete. Si el trabajo falló, revise sus logs para identificar y resolver el error subyacente; si el fallo persiste, recopile los logs del trabajo junto con los logs del operador para su ABBYY account team.

​
Malla de servicios e ingress

​
503 en el ingress, tráfico de la aplicación bloqueado

Síntoma. https://$your_vantage_hostname devuelve 503 aunque los pods aparezcan como Ready. Diagnóstico. En AKS con el ingress de Istio integrado, la puerta de enlace externa puede estar inactiva o el Secret de TLS puede no coincidir con ingress.tls.secretName. Con un ingress administrado por el cliente, es posible que el controlador no tenga una ruta correspondiente, que el nombre o el puerto del Service de backend sean incorrectos, o que el certificado TLS aún no esté listo. Solución. Para Istio, confirma la puerta de enlace y el Secret de TLS:
Confirme que existe un Secret de tipo kubernetes.io/tls en el namespace del gateway externo con el nombre proporcionado al chart, y que su certificado es válido para dnsRecord. Para el ingress gestionado por el cliente, inspeccione los logs del controlador y el estado de la ruta. Confirme que el nombre de host de la ruta sea vantage.dnsRecord, que TLS esté listo y que cada Service de backend exista en $install_namespace. Consulte Configurar ingress y TLS.

​
Los redireccionamientos de inicio de sesión o los metadatos de OIDC usan http://

Síntoma. Vantage se sirve a través de HTTPS, pero el inicio de sesión del administrador de la plataforma falla o /auth2/.well-known/openid-configuration publica un emisor y endpoints con http://. Diagnóstico. La terminación TLS se realiza en el controlador de ingress, pero las cargas de trabajo de autenticación no respetan el protocolo HTTPS reenviado. Solución. Confirme que el ingress envía X-Forwarded-Proto: https y que los contenedores de la aplicación para auth-identity, auth-adminapi2, api-gateway y api-registry tienen:
Si el chart de su carga de trabajo no expone esta configuración de entorno, aplique la mutación de admisión aprobada antes de reiniciar los pods afectados. Consulte Esquema HTTPS reenviado.

​
Los objetivos de scrape de Prometheus aparecen como DOWN para /metrics-text

Síntoma. En Prometheus en la malla, los destinos de la aplicación Vantage aparecen como DOWN. Diagnóstico. En Istio, es posible que al pod de Prometheus le falte el sidecar o que los certificados de salida de Istio no se escriban en /etc/prom-certs/. En Linkerd, una política de autorización estricta puede bloquear la recopilación de métricas en texto sin formato desde un Prometheus fuera de la malla.
Solución. Con Istio, verifique que el pod de Prometheus tenga tres contenedores (prometheus, config-reloader, istio-proxy) y que esté presente la anotación proxy.istio.io/config con OUTPUT_CERTS: /etc/istio-output-certs. Con Linkerd, aplique la inyección al espacio de nombres observability o configure ServiceMonitor y Prometheus con los certificados de cliente que exija su política. Consulte monitorización con Prometheus.

​
Operaciones posteriores al despliegue

​
Después de la actualización, el operador informa la nueva versión, pero Vantage sigue en la anterior

Síntoma. status.installedVantageVersion no cambia después de actualizar los releases de Helm. Diagnóstico. Es posible que los releases vantage-operator y vantage-selfhosted no estén en la misma versión nueva, o que ArgoCD aún esté aplicando los cambios por componente. Compruebe ambos releases de Helm y el estado de sincronización de la aplicación de ArgoCD. Solución. Actualice ambos charts a la misma versión y, a continuación, espere a que las aplicaciones de ArgoCD terminen de sincronizarse. Si el operador muestra una condición Degraded, siga la causa de la degradación hasta el componente con errores, resuélvalo y, después, anote el recurso Vantage con vantage.abbyy.com/reprocess para volver a intentarlo (Forzar un reintento). Consulte Upgrading.

​
Qué sigue

Arquitectura

Qué hace el operador en cada reconciliación, contexto útil para el diagnóstico.

Limitaciones conocidas

Restricciones actuales que determinan qué es realmente un error y qué no lo es.