本指南介绍了在将 Kubernetes 操作符升级到 MongoDBSearch 的通用版本 (GA) 发布后，重新创建现有 MongoDBSearch 部署时必须进行的更改。
重要
此迁移不是原地升级，因此在迁移过程中搜索不会保持运行。Kubernetes 操作符 会从头开始重建搜索部署。在新部署就绪并完成对数据的重新索引之前，MongoDB Search 和向量搜索查询（$search 和 $vectorSearch 聚合阶段）将不可用。使用本指南在 GA Kubernetes Operator 上重建公开预览部署的等效配置，而不是在不中断的情况下升级运行部署。
在本指南中，“公开预览”是指 GA 之前发布的任何 MongoDBSearch 版本。MongoDBSearch 自定义资源只有一个 API 版本 v1，因此 Kubernetes 和 Kubernetes 操作符都不会自动转换旧字段值。您必须对现有的显示内容手动应用本指南中的每个更改，且只应用一次。
本指南不涉及新的 GA 功能或可选字段。如果某一部分不适用于现有的显示文件，请跳过。
开始之前
GA 实施最低支持的 mongot 版本 1.70.1。如果您的 MongoDBSearch 资源固定的是早于 1.70.1 的明确 spec.version，则升级后协调将因不支持的版本错误而失败。如果您未设置 spec.version，则 Kubernetes 操作符会提供其自己的默认值（截至此 GA 版本为 1.70.1），您无需采取任何操作。
在升级之前，请检查您已固定的版本（如有）：
kubectl get mongodbsearch <name> -n <namespace> -o jsonpath='{.spec.version}'
如果该命令打印的版本早于 1.70.1，请在下一个部分的显示变更中将 spec.version 更新为 1.70.1 或更新版本。
更新 MongoDBSearch 配置
公开预览 MongoDBSearch 自定义资源从未包含 spec.clusters 字段。在 GA 中，spec.clusters 是必需的，并且以前位于 spec 顶层的多个字段现在仅位于 spec.clusters[0] 内部。无论拓扑结构如何，每个现有的显示需要一次相同的机械编辑。
本节中的示例使用 mongodb 命名空间中名为 my-search 的 MongoDBSearch 资源。替换为自己的资源名称和命名空间。
Add the required spec.clusters field and move per-cluster settings into it.
六个顶级 spec 字段移动到 spec.clusters[0] 内部：
公开预览路径 | GA 路径 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
当 spec.clusters 只有一个条目时（每个公开预览工作负载都是这种情况），您无需设置 spec.clusters[0].name 或 spec.clusters[0].index。
logLevel, security、source、version 和 autoEmbedding 保持在 spec 的顶层，不变。
例子
以下公开预览配置：
apiVersion: mongodb.com/v1 kind: MongoDBSearch metadata: name: my-search namespace: mongodb spec: source: mongodbResourceRef: name: my-replica-set replicas: 3 persistence: single: storage: 20Gi resourceRequirements: requests: cpu: "1" memory: 2Gi limits: cpu: "2" memory: 4Gi statefulSet: spec: template: spec: nodeSelector: disktype: ssd loadBalancer: managed: replicas: 2 jvmFlags: - "-Xmx2g"
在GA时成为以下配置：
apiVersion: mongodb.com/v1 kind: MongoDBSearch metadata: name: my-search namespace: mongodb spec: source: mongodbResourceRef: name: my-replica-set clusters: - replicas: 3 persistence: single: storage: 20Gi resourceRequirements: requests: cpu: "1" memory: 2Gi limits: cpu: "2" memory: 4Gi statefulSet: spec: template: spec: nodeSelector: disktype: ssd loadBalancer: managed: replicas: 2 jvmFlags: - "-Xmx2g"
重要
如果跳过此步骤，Kubernetes API 服务器将直接拒绝您的公开预览显示：spec.clusters 是一个必填字段，没有默认值，因此这是一个立即批准失败，而不是延迟或静默失败。
Move spec.prometheus to spec.observability.prometheus.
此更改不仅仅是重命名：在 GA 中，Prometheus 指标终结点默认为启用状态，而在公开预览中，除非显式设置 spec.prometheus，否则处于禁用状态。
如果您已经设置 spec.prometheus，请将其原样移动：
例子
公开预览版：
spec: prometheus: port: 9946
GA:
spec: observability: prometheus: port: 9946
如果您从未设置 spec.prometheus，则无法移动，但升级后，将出现一个用于端口 9946 的 Prometheus 抓取目标，而之前并不存在。
重要
若要在升级后使指标保持禁用，请明确添加以下内容：
spec: observability: prometheus: mode: disabled
将外部 MongoDB TLS CA 引用从 Secret 更新为 ConfigMap。
警告
此变更会破坏现有的 TLS，且无法自动回退。如果您的 MongoDBSearch 资源在 spec.source.external.tls.ca 配置了 TLS CA，并且您跳过此步，则外部 TLS 会在 GA Kubernetes 操作符开始协调的瞬间内崩溃：它只会读取 ConfigMap，并且无法回退到 Secret。如果您的资源根本没有使用 spec.source.external.tls.ca，则此步不适用于您。
字段路径（Field Path） spec.source.external.tls.ca.name 不变。变化的是 Kubernetes 操作符在该名称处预期的 Kubernetes 对象类型：公开预览中的 Secret，GA 中的 ConfigMap。两者都预期在相同的密钥 ca.crt 处查找 CA 证书。
例子
在公开预览中，spec.source.external.tls.ca.name 指的是 Secret：
apiVersion: v1 kind: Secret metadata: name: my-search-external-ca namespace: mongodb type: Opaque stringData: ca.crt: | -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----
在 GA 中，同一名称必须指向具有相同 ca.crt 密钥的 ConfigMap：
apiVersion: v1 kind: ConfigMap metadata: name: my-search-external-ca namespace: mongodb data: ca.crt: | -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----
引用的 MongoDBSearch 资源未变。spec.source.external.tls.ca.name 仍然指向同一个名称：
apiVersion: mongodb.com/v1 kind: MongoDBSearch metadata: name: my-search namespace: mongodb spec: source: external: hostAndPorts: - mongodb-0.example.com:27017 tls: ca: name: my-search-external-ca
如果可以，请在升级 Kubernetes 操作符之前或同时创建 ConfigMap：
kubectl create configmap my-search-external-ca \ --from-file=ca.crt=./ca.crt \ --namespace mongodb
您可以重用旧 Secret 的名称，如上述示例所示，也可以选择新名称。Kubernetes 操作符 不再读取旧 Secret。确认外部 TLS 可以再次工作后，您可以将其删除。
Kubernetes 资源会发生什么
本节介绍了 Kubernetes 操作符 托管 的基础 Kubernetes 对象会发生什么，以及事后要验证和清理什么。变化取决于 MongoDBSearch 资源是从副本集同步还是从分片集群同步。
保留其名称的资源
大多数由操作符托管的资源在 GA 阶段保持名称不变。Kubernetes 操作符会在下一次对账时原地更新这些资源，您无需采取任何操作：
代理服务 (
<name>-search-0-proxy-svc)Envoy 负载均衡器部署、ConfigMap 和证书 (
<name>-search-lb-0...)TLS、X.509 和密码，但操作符管理的每个分片 TLS 密钥除外，如分片集群源：名称未更改，但有一个例外中所述
副本集来源：在新名称下重新创建的资源
如果 MongoDBSearch 资源从副本集（非分片）源同步，则 GA Kubernetes 操作符在第一次协调 MongoDBSearch 资源时会在新名称下重新创建三个资源。Kubernetes 操作符不会采用、重命名或删除旧对象。此行为是按照设计进行的。
以下表使用上一节中的 my-search 示例资源：
Resource | 公开预览名称 | GA 名称 |
|---|---|---|
|
|
|
|
|
|
|
|
|
此变更具有以下实际效果：
新的 StatefulSet 从空开始。其节点获取新的
PersistentVolumeClaims，因此mongot从头开始重新编制索引，这可能会花费一些时间，具体取决于数据集大小。旧 StatefulSet 的 Pod 会继续运行。Kubernetes Operator 不会将其缩小。在删除旧 StatefulSet 之前，您会为
mongotPod 运行 double 的计算。旧的 StatefulSet 的 PVC 和旧的 ConfigMap 变成孤立状态。没有人再读取它们，但也没有人删除它们。
无头服务的 DNS 名称变更无需您操作。在没有负载均衡器的情况下，Kubernetes 操作符 会在每次协调时重写同步源连接字符串。使用托管或非托管负载均衡器时，此服务不属于连接路径的一部分。
重要
The Kubernetes Operator never deletes the old objects for you. After you confirm that the new StatefulSet is healthy (see Verification), delete the old resources to avoid paying for doubled compute indefinitely. This cleanup is a required step, not an optional one.
删除旧的 StatefulSet、Service 和 ConfigMap。
Confirm that the new StatefulSet is healthy first (see Verification), then run:
kubectl delete statefulset my-search-search -n mongodb kubectl delete service my-search-search-svc -n mongodb kubectl delete configmap my-search-search-config -n mongodb
删除孤立的 PersistentVolumeClaims。
删除 StatefulSet 不会删除其 PVC，因此请分开删除它们：
Preview the PVCs to delete: PVCS=$(kubectl get pvc -n mongodb -o name \ | grep -E 'data-my-search-search-[0-9]+$') echo "$PVCS" After confirming, delete exactly what you previewed: echo "$PVCS" | xargs kubectl delete -n mongodb
旧 PVC 匹配 data-my-search-search-<ordinal>，示例 data-my-search-search-0。请勿删除任何匹配 data-my-search-search-0-<ordinal>，例如 data-my-search-search-0-0。这些属于新的 StatefulSet。
分片集群源：名称保持不变，但有一个例外
如果您的 MongoDBSearch 资源是从分片集群源同步的，那么在公共预览版和正式发布版中，各分片的资源名称是相同的。Kubernetes 操作符不会以新名称重新创建它们。相反，它会就地更新它们：
Resource | 公开预览和 GA 中的名称（无变化） |
|---|---|
每分片 |
|
每分片 |
|
Per-shard |
|
每分片代理服务 |
|
如果使用每分片 TLS 证书，则应用一个例外。Kubernetes Operator 将您提供的 TLS Secret 中的证书和密钥组合到每个分片的 Operator 托管 Secret 中，并以新名称重新创建该 Secret：
Resource | 公开预览名称 | GA 名称 |
|---|---|---|
每分片 TLS 操作符组合 Secret |
|
|
您提供的 TLS 秘密保留其名称。仅此操作符托管的秘密将被重命名。Kubernetes 操作符不会删除旧秘密，该秘密将成为孤立秘密。验证新秘密是否存在以及 TLS 是否适用于该分片，然后手动删除旧秘密。
验证
升级 Kubernetes 操作符 并应用显示文件更改后，以及删除任何旧资源前，请完成此核对表：
确认
kubectl get mongodbsearch <name> -n <namespace> -o yaml显示spec.clusters已填充，并且没有剩余的顶级replicas、persistence、resourceRequirements、statefulSet、loadBalancer、jvmFlags或prometheus字段。确认新的
mongotStatefulSet（单集群部署的<name>-search-0）具有所有 PodRunning和Ready。在从旧 StatefulSet 中删除任何内容之前，请确认
mongot已在新 Pod 上完成重新索引。检查mongot的日志或索引状态以确认完成，而不仅仅是 Pod 就绪。如果您依赖 Prometheus 抓取，请确认您的抓取配置或仪表盘反映了新的默认启用行为：指标现在出现，或您的明确
mode: disabled设置使其保持禁用。如果使用带有 TLS 的
spec.source.external，请确认spec.source.external.tls.ca.name引用的 CAConfigMap存在并包含有效的ca.crt密钥，并且mongot与外部 MongoDB 部署的连接正常。对于副本集源，请确认您已定位并删除了旧
<name>-search、<name>-search-svc和<name>-search-config对象及其孤立的 PVC。对于分片的源，请确认您已删除旧的每分片 TLS 秘密。
获取支持
If any part of your upgrade doesn't match what this guide describes, or you encounter an issue that this guide doesn't cover, contact MongoDB Support. Include your MongoDBSearch manifest with secrets redacted, the Kubernetes Operator version you're upgrading from and to, and the output of:
kubectl describe mongodbsearch <name> -n <namespace>