MongoDB Migration Resource Settings

External Members

These fields identify the source virtual machine or bare-metal processes that a migration is extending into Kubernetes. They apply to the MongoDB resource, apiVersion: mongodb.com/v1.

spec.externalMembers

Type: array of ExternalMember objects

The virtual machine or bare-metal source processes that are part of the migration. This field exists for migration only.

You may remove entries from this list, but you must never add entries once migration has started. An empty spec.externalMembers list means the migration is complete.

spec.externalMembers[].processName

Type: string

Required

This field exists for migration only. The process name exactly as it appears in the processes array of the automation config.

spec.externalMembers[].hostname

Type: string

Required

This field exists for migration only. The host:port value for the process, exactly as it appears in the automation config.

spec.externalMembers[].type

Type: enum: mongod or mongos

Required for sharded clusters

This field exists for migration only. A replica set has only mongod external members.

spec.externalMembers[].replicaSetName

Type: string

Optional

This field exists for migration only. Required for a sharded-cluster mongod external member. Identifies whether the process belongs to the config server replica set or to a specific shard's replica set.

Name Overrides

These fields exist for migration only, and override the resource or automation config name that Kubernetes Operator would otherwise use or generate.

spec.replicaSetNameOverride

Type: string

This field exists for migration only. The automation config replica set name, when it differs from the Kubernetes resource name, or when the automation config replica set name is not a valid Kubernetes name. The kubectl mongodb migrate-to-mck plugin sets this field for you through its --resource-name-override flag.

spec.configServerNameOverride

Type: string

This field exists for migration only. The config server replica set name as it appears in the automation config.

spec.shardNameOverrides

Type: array of ShardNameOverride objects

This field exists for migration only. Per-shard automation config replica set name and shard _id.

Note

Do not confuse spec.shardNameOverrides with spec.shardOverrides. spec.shardOverrides configures per-shard resource settings and is unrelated to migration naming.

Kubernetes StatefulSet names are never affected by these overrides.

Configurable Automation Config Paths

Kubernetes Operator previously hard-coded these automation config settings. Migration requires them to be configurable so that a Kubernetes deployment can match paths already in use on the source virtual machines.

spec.downloadBase

Type: string

Default: /var/lib/mongodb-mms-automation

Directory where the MongoDB Agent downloads the agent binary. Kubernetes Operator derives the keyfile path from this setting as <downloadBase>/keyfile.

spec.security.tls.caFilePath

Type: string

Default: /mongodb-automation/tls/ca/ca-pem

Absolute path where Kubernetes Operator projects the CA certificate inside the pod. This path must contain at least two path segments. Not supported for the Application Database.

Note

If your pod template mounts a volume at or above this path, the mount can shadow the projected CA file. Review your podTemplate volume mounts before you set a custom value.

spec.security.authentication.agents.autoPEMKeyFilePath

Type: string

Absolute path of the MongoDB Agent's combined PEM file inside database pods. Setting this field sets the Ops Manager or Cloud Manager tls.autoPEMKeyFilePath value, and mounts the secret referenced by spec.security.authentication.agents.clientCertificateSecretRef at that path.

Requires spec.security.authentication.agents.clientCertificateSecretRef.

Defaults to the hash-derived agent certificate mount path that Kubernetes Operator uses for non-migrated deployments.

Status Conditions

status.conditions

Type: array of Kubernetes Conditions

Standard Kubernetes conditions, keyed by type. This field is new on the MongoDB resource and supports migration.

status.conditions[type=Migrating]

Type: Kubernetes condition

The top-level indicator of whether a migration is active. status is True while spec.externalMembers is non-empty, and flips to False with reason MigrationComplete once you remove the last external member.

Reason	Status	Meaning
Validating	True	The dry-run annotation is set.
Extending	True	The desired Kubernetes member count exceeds the last reconciled count.
Pruning	True	The externalMembers count dropped below status.migrationObservedExternalMembersCount.
InProgress	True	External members exist but nothing is changing. This is also the reason on the first reconcile.
MigrationComplete	False	All external members have been removed.

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.

Pruning and extending are not allowed at the same time.

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

status.conditions[type=NetworkConnectivityVerified]

Type: Kubernetes condition

The result of the dry-run connectivity check. Kubernetes Operator removes this condition from status.conditions entirely once no external members remain.

Validator Job Exit Code	Condition Status	Reason	Meaning
Job still running	Unknown	Running	The status.phase is ConnectivityCheckRunning.
0	True	NetworkValidationPassed	All external members are reachable and authenticated.
2	False	AuthenticationFailed	Credentials, the authentication mechanism, or a missing __system@local role.
3	False	NetworkFailed	DNS, TLS, timeouts, or unreachable members. Check the Job Pod logs.
1 or other	False	UnknownError	Unclassified failure. Check the Job Pod logs.

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.

status.migrationObservedExternalMembersCount

Type: integer

The number of spec.externalMembers entries that Kubernetes Operator observed on the last reconcile. Kubernetes Operator compares this value against the current spec.externalMembers count on the next reconcile to detect that you pruned an external member. This field is unset when no external members remain.

Note

This field also appears in the MongoDBOpsManager custom resource schema, as a side effect of Go struct embedding. On the MongoDBOpsManager resource, the field is always null. Ignore it there.

Annotations

metadata.annotations.mongodb.com/migration-dry-run

Type: string (boolean value)

The kubectl mongodb migrate-to-mck plugin sets this annotation to true. While this annotation is present, Kubernetes Operator makes no automation config changes and performs connectivity validation only. Removing the annotation starts the real migration.

metadata.annotations.mongodb.com/migrate-tool-version

Type: string

Records the version of the kubectl mongodb migrate-to-mck plugin that generated the resource. Kubernetes Operator validates this annotation against its own version on every reconcile, including during the dry run.

Related Fields That Need Migration-Specific Attention

The following existing MongoDB resource fields are not migration-only, but require specific values or review during a migration:

• spec.members, spec.mongodsPerShardCount, spec.configServerCount, and spec.mongosCount all start at 0 in the resource that the kubectl mongodb migrate-to-mck plugin generates.

• spec.memberConfig[].votes (integer, default 1) and spec.memberConfig[].priority (string containing a float, default "1"). You must provide at least as many spec.memberConfig entries as spec.members. Kubernetes Operator ignores the top-level spec.memberConfig for sharded clusters. The kubectl mongodb migrate-to-mck plugin does not generate spec.memberConfig, and Kubernetes Operator does not default new members to non-voting, so the CRD defaults of 1 and "1" are exactly wrong while a new member is syncing.

  Warning

  Set spec.memberConfig before you raise the member count

  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.

• spec.shardOverrides, spec.externalAccess, and spec.connectivity.replicaSetHorizons.

• spec.security.certsSecretPrefix and spec.security.tls.ca.

• Fields that must match the source deployment exactly: spec.version, spec.featureCompatibilityVersion, spec.additionalMongodConfig.net.port, spec.security.authentication.modes, and spec.security.authentication.internalCluster.

Learn More

• Migrate a Self-Managed Deployment to Kubernetes

• Migrate a Replica Set to Kubernetes

• migrate-to-mck Plugin Command Reference

• Troubleshoot a Migration to Kubernetes

• MongoDB Database Resource Specification