Kubernetes中部署MongoDB副本集的完整步骤指南

目前，MongoDB Controllers for Kubernetes Operator 是当前唯一受支持的生产级部署方案，MongoDB Enterprise Kubernetes Operator 已于 2026 年正式停用。现在必须使用新 Helm 仓库 https://mongodb.github.io/helm-charts 中的 mongodb/mongodb-kubernetes chart，并正确配置 Cloud Manager/Ops Manager API Key、强制启用 TLS、显式设置 externalAccess 以及 publishNotReadyAddress: true。

直接说结论：在 Kubernetes 中部署 MongoDB 副本集时，使用 MongoDB Controllers for Kubernetes Operator 是目前唯一官方支持的生产环境方式，而 MongoDB Enterprise Kubernetes Operator 已在 2026 年完成弃用，最后版本生命周期也已结束。

确认 Operator 版本与 Helm 仓库

这一步不要省略，很多 MongoDB on Kubernetes 部署失败、连接异常或 CRD 不生效的问题，根源都在于使用了旧仓库或已废弃的 chart。

• 必须使用新的 Helm 仓库：https://mongodb.github.io/helm-charts，旧的 stable/mongodb-enterprise 等仓库已经不可用
• 应安装的是 mongodb/mongodb-kubernetes chart，而不是 mongodb/enterprise-operator，后者对应的是已弃用的旧版 Operator
• 检查本地 Helm 仓库是否已更新：helm repo update；如果之前添加过旧源，建议先执行 helm repo remove mongodb，再重新添加新仓库

部署 Operator 前必须配置 Cloud Manager / Ops Manager API Key

Operator 启动后会立即尝试连接 Cloud Manager 或 Ops Manager（6.0.x+）。如果相关配置不完整，部署通常会卡在 Pending 状态，日志中还会反复出现 Unauthorized 或 connection refused 等报错。

• 登录 Cloud Manager 控制台，进入 Kubernetes Settings，然后选择 Generate Key and YAML
• 生成后的 config-map.yaml 必须提前执行 apply，并确保其中的 baseUrl 能被 Operator Pod 正常访问，例如不能填写 localhost 或集群无法访问的内网地址
• API Key 权限必须包含 Automation Administrator 角色，仅分配 Viewer 权限会导致资源创建请求被拒绝

定义 MongoDBReplicaSet CR 时 TLS 是必须显式配置的关键项

如果没有明确声明 spec.security.tls.enabled，Operator 默认会关闭 TLS；但 Cloud Manager 6.0.10+ 实际要求所有新建 MongoDB 副本集启用 TLS，否则部署过程通常会停留在 WaitingForAgent 状态。

• 如果使用自签名证书，必须同时提供：spec.security.certsSecretPrefix（指向包含 ca.pem、server.pem 等文件的 Secret）以及 spec.security.tls.ca（CA 公钥内容）
• 如果使用 Let’s Encrypt 或云服务厂商提供的证书，需要确保 Secret 中的 key 名称为 tls.crt 和 tls.key，这样 Operator 才能正确自动挂载
• 常见错误示例：只设置 spec.security.tls.enabled: true，却没有配置 certsSecretPrefix，会导致 Pod 启动失败，并报出 failed to load TLS certificate

外部访问必须显式开启 externalAccess

MongoDB 副本集成员默认只能通过 Kubernetes 集群内部 DNS 解析，例如 mongo-0.mongo-svc.mongodb.svc.cluster.local。如果要让外部应用连接 MongoDB，仅仅暴露 Service NodePort 并不足够，因为 Operator 不会自动对外发布成员访问地址。

• 必须在 CR 中明确设置：externalAccess: {}，否则 Operator 不会创建 LoadBalancer 类型的外部访问服务
• 每个 Pod 都会生成一个独立的 -svc-external Service，名称固定不可修改，默认端口为 27017
• publishNotReadyAddress: true 是必须项，如果设置为 false，会导致 DNS 记录生成延迟，进而引发客户端首次连接超时

真正容易被忽视的一点是：Cloud Manager 对 Kubernetes 集群的准入校验会在 CR 创建后的 30 秒内触发。如果此时 Operator Pod 还没有完成初始化，例如 configmap 尚未加载完成，或 API Key 权限还未同步，CR 可能会被静默拒绝，而且事件列表中不一定显示错误信息——这时需要进入 Operator Pod 日志，搜索 Failed to create automation config，才能定位真实原因。