/ /

Solución de problemas en una migración a Kubernetes

This page helps you diagnose problems that can occur while you migrate a self-managed replica set or sharded cluster from virtual machines into Kubernetes under Kubernetes Operator, including plugin import failures, dry-run and connectivity problems, authentication mismatches, and validation errors. For background on the migration workflow, see Migrate a Self-Managed Deployment to Kubernetes.

¿En qué punto de la migración me encuentro?

Read the reason field of the status.conditions[type=Migrating] condition first.

Razón	Estado	Significado
`Validating`	`True`	La anotación de prueba está configurada.
`Extending`	`True`	El número deseado de miembros de Kubernetes supera el último recuento conciliado.
`Pruning`	`True`	The `externalMembers` count dropped below `status.migrationObservedExternalMembersCount`.
`InProgress`	`True`	Existen miembros externos, pero nada cambia. Esta es también la razón de la primera reconciliación.
`MigrationComplete`	`False`	Todos los miembros externos han sido eliminados.

Precedence is Validating > Extending > Pruning > InProgress. A prune that also grows the Kubernetes side reports Extending, which is another reason to make one change at a time.

No está permitido podar y alargar al mismo tiempo.

To script against migration completion, use kubectl wait --for=condition=Migrating=False rather than polling status.phase.

If the reason stays Extending, the Kubernetes members that Kubernetes Operator is adding are still provisioning. Wait for them to reach goal state.
If the reason stays InProgress and the external member count is unchanged, your last edit to the resource was a no-op: Kubernetes Operator did not detect a change that requires action.

Errores al importar complementos

The kubectl mongodb migrate-to-mck plugin validates the source automation config before it generates any resource. It exits with an error, rather than generating an incomplete or incorrect resource, in each of the following cases:

The Ops Manager or Cloud Manager project has more than one deployment.
El proyecto cuenta con más de un clúster fragmentado.
El proyecto cuenta con conjuntos de réplicas que no forman parte del clúster fragmentado.
El proyecto no tiene conjuntos de réplicas ni clústeres fragmentados. El complemento solo puede migrar implementaciones de conjuntos de réplicas y clústeres fragmentados.
La configuración de automatización no tiene procesos.
En el clúster fragmentado, un fragmento está respaldado por el mismo conjunto de réplicas que el servidor de configuración. Esta topología de servidor de configuración integrado no es compatible con la migración.
El complemento no puede encontrar un miembro con derecho a voto y prioridad en un conjunto de réplicas, por lo que no puede determinar el proceso de origen para ese conjunto de réplicas.
A process has a processType other than mongod or mongos.

Ruta no configurable y discrepancias en la configuración

El complemento marca los siguientes ajustes de configuración de automatización cuando no coinciden con lo que espera Kubernetes Operator:

auth.keyFile differs from the path that Kubernetes Operator derives from spec.downloadBase.
auth.keyFileWindows está establecido.
monitoringAgentConfig.logPath or backupAgentConfig.logPath is set to a non-default path.
A process has an authSchemaVersion that differs from the Kubernetes Operator default.

Errores de autenticación

auth.autoUser está vacío mientras la autenticación está habilitada.
auth.autoUser has no matching entry in auth.usersWanted for its database. Without a matching entry, agent authentication fails after migration.
MONGODB-X509 agent authentication requires tls.autoPEMKeyFilePath to be set in the automation config. See spec.security.authentication.agents.autoPEMKeyFilePath.
An LDAP bindMethod other than simple is not supported for migration.

Heterogeneidad de los miembros

Kubernetes Operator takes spec.additionalMongodConfig and spec.agent.mongod.systemLog from a single source process. If your replica set members have different configurations, review all members and reconcile the differences before you migrate — the generated resource applies one configuration to all Kubernetes members.

Advertencias que merecen atención

Los siguientes ajustes de configuración de automatización por proceso no se transfieren a los nuevos miembros de Kubernetes. Planifíquelos antes de migrar:

secondaryDelaySecs
miembros ocultos
buildIndexes: false

Si su implementación de origen tiene nodos de análisis o nodos retardados, planifique cómo desea representarlos en Kubernetes antes de comenzar.

Elementos adicionales para revisar:

El complemento omite un proceso deshabilitado; no aparece como un miembro externo.
If a process has no TLS configured, set net.tls.mode to disabled in Ops Manager or Cloud Manager, on the existing virtual machine deployment, before you migrate. Do not set this on the generated MongoDB resource. Otherwise the Kubernetes member's TLS setting does not match the source process, and migration causes an unplanned deployment change.
If a process's logRotate or auditLogRotate setting differs from the project-level configuration, Kubernetes Operator uses the project-level value.

Discrepancia de versión

The mongodb.com/migrate-tool-version annotation records the kubectl mongodb migrate-to-mck plugin version that generated the resource. Kubernetes Operator validates this annotation against its own version on every reconcile, including during the dry run. If the versions are incompatible, regenerate the resource with a compatible plugin version.

Problemas de la prueba en seco

La prueba piloto parece haberse estancado.

Delete the <resourceName>-connectivity-check Job. The next reconcile re-creates it.

If the Job never gets created, check that your Kubernetes RBAC permissions include batch/jobs. Missing batch/jobs permissions prevent Kubernetes Operator from creating the connectivity validator Job.

Fallos de conectividad

Código de salida del trabajo del validador	Estado de la condición	Razón	Significado
El trabajo sigue en marcha.	`Unknown`	`Running`	The `status.phase` is `ConnectivityCheckRunning`.
`0`	`True`	`NetworkValidationPassed`	Todos los miembros externos son accesibles y están autenticados.
`2`	`False`	`AuthenticationFailed`	Credentials, the authentication mechanism, or a missing `__system@local` role.
`3`	`False`	`NetworkFailed`	Problemas con DNS, TLS, tiempos de espera o miembros inaccesibles. Consulte los registros del Job Pod.
`1` u otro	`False`	`UnknownError`	Error no clasificado. Compruebe los registros del Job Pod.

Failures that occur before the Job starts use the reasons OperatorImageUnknown, BuildStatefulSetOptions, AgentCertSecretFailed, and AgentCertSubject.

Kubernetes Operator removes the NetworkConnectivityVerified condition from status.conditions entirely once no external members remain.

Fracasos previos al empleo

El operador de Kubernetes puede fallar antes de que comience el trabajo del validador de conectividad, por una de estas razones:

OperatorImageUnknown
BuildStatefulSetOptions
AgentCertSecretFailed
AgentCertSubject

Desajuste de TLS CA

Los certificados de los miembros de Kubernetes deben ser emitidos por la misma autoridad de certificación que firmó los certificados de los miembros de la máquina virtual. De lo contrario, la validación de la conectividad y la replicación entre la máquina virtual y los miembros de Kubernetes fallarán.

`memberConfig` Problemas

spec.memberConfig has fewer entries than spec.members. Add one entry per member.
Kubernetes Operator ignores the top-level spec.memberConfig field for sharded clusters.

Advertencia

Establezca spec.memberConfig antes de aumentar el número de miembros.

By default, new Kubernetes members join as voting members. The CRD defaults are votes: 1 and priority: "1", which let a still-syncing member participate in an election before it has finished its initial sync.

MongoDB recommends that you write one spec.memberConfig entry per new Kubernetes member with votes: 0 and priority: "0" before you raise the member count, so that a still-syncing member cannot win an election. votes is an integer. priority is a string.

Problemas de nomenclatura

El nombre del recurso o del conjunto de réplicas es demasiado largo o no es un nombre válido según la RFC 1123. Utilice spec.replicaSetNameOverride o --resource-name-override para proporcionar un nombre válido de Kubernetes.

Sorpresas de validación

Validations can fire while the dry-run annotation (mongodb.com/migration-dry-run) is set, not only after you start the real migration.
La validación del límite de miembros con derecho a voto puede surgir durante la conciliación, en lugar de en el momento de la admisión, si se aplica indirectamente un cambio que excedería el límite.
Realizar demasiados cambios en una sola edición puede provocar que el despliegue pierda el quórum. Realice solo un tipo de cambio a la vez: agregar miembros de Kubernetes, eliminar miembros externos o modificar los votos y la prioridad.

Diagnóstico para recopilar

Si el problema persiste después de seguir los pasos indicados en las secciones anteriores, recopile la siguiente información antes de ponerse en contacto con el servicio de asistencia:

The MongoDB resource YAML, including status.conditions:
kubectl get mdb <resource-name> -n <namespace> -o yaml
The MongoDBUser resources for the deployment.
Registros del operador de Kubernetes.
Registros del pod del trabajo de validación de conectividad.
The automation config JSON from Ops Manager or Cloud Manager.