升级

本页介绍如何将 operator 2.8.0 原地升级到 Alauda Data Services Search Engine E1 3.0。

变更内容

operator 2.8.0 管理 opensearch.opster.io/v1 API 组中的资源。E1 3.0 管理 opensearch.org/v1 API 组中的资源。两个组中的资源种类及其字段相同。

	2.8.0	E1 3.0
API 组	`opensearch.opster.io/v1`	`opensearch.org/v1`
Pod 标签	`opster.io/opensearch-cluster`、`opster.io/opensearch-nodepool`	`opensearch.org/opensearch-cluster`、`opensearch.org/opensearch-nodepool`

E1 3.0 bundle 会安装两个组的 CRD。升级后：

自动迁移。 对于 opensearch.opster.io/v1 中的每个资源，operator 都会在 opensearch.org/v1 中创建一个名称和命名空间相同的资源，并复制相同的 spec、标签和注释，以及状态。
旧组变为只读。 验证 webhook 会拒绝创建新的 opensearch.opster.io/v1 资源，也会拒绝更改现有资源的 spec。仍允许更新状态和删除资源。
每个节点池滚动重启一次。 每个现有集群中的每个节点池都会重启一次，每次重启一个 Pod。

此后，opensearch.org/v1 资源是需要编辑的资源。operator 会将其状态复制回旧资源，但迁移完成后，不会再向任一方向复制 spec 变更。

迁移的工作原理

迁移涵盖以下种类：OpenSearchCluster、OpensearchUser、OpensearchRole、OpensearchUserRoleBinding、OpensearchTenant、OpensearchActionGroup、OpenSearchISMPolicy、OpensearchSnapshotPolicy、OpensearchIndexTemplate 和 OpensearchComponentTemplate。

资源只有在就绪状态下才会迁移：

种类	迁移条件
`OpenSearchCluster`	`status.phase` 为 `RUNNING`
所有其他种类	`status.state` 为 `CREATED`

未就绪的资源会被跳过，并每 30 秒重新检查一次。资源一旦就绪，就会立即迁移。

每个迁移后的资源都会带有记录其来源的注释：

metadata:
  annotations:
    opensearch.org/migrated-from: opensearch.opster.io/v1
    opensearch.org/migration-timestamp: "<time of migration>"
    opensearch.org/source-uid: "<uid of the old resource>"

对于集群，operator 还会将新的资源设为 TLS 证书 Secret（<cluster>-ca、<cluster>-transport-cert、<cluster>-http-cert、<cluster>-admin-cert）的所有者，因此即使之后删除旧资源，证书也会保留。

为什么每个节点池都会重启一次

StatefulSet 的 Pod 选择器无法更改，而 E1 3.0 会使用新的 opensearch.org/... 标签选择 Pod。因此，对于每个节点池，operator 会：

为运行中的 Pod 添加新标签；
删除 StatefulSet，但不删除其 Pod；
使用 3.0 规范重新创建 StatefulSet，使其接管运行中的 Pod；
由于 3.0 Pod 模板与 2.8.0 的不同，因此逐个重启接管的 Pod。

重启采用常规滚动重启操作步骤：每次重启一个 Pod，并等待集群恢复后再继续。持久卷上的数据会保留。

对于每个重新创建的 StatefulSet，operator 都会在集群上记录一个原因是 StatefulSetRecreated 的 Warning 事件，随后记录 RollingRestart 事件。如果同时正在进行 OpenSearch 版本升级，则由版本升级负责重启 Pod。

升级前

检查要升级的每个 Kubernetes 集群中的以下各项。

WARNING

将 Subscription 的 channel 切换为 stable 时，升级即会开始（请参阅升级 operator）。如果 Subscription 使用自动审批，升级会立即开始。请先完成此检查清单，并将 Subscription 切换为手动审批，以便由您决定何时开始升级：

kubectl -n <operator-namespace> patch subscription <subscription-name> \
  --type merge -p '{"spec":{"installPlanApproval":"Manual"}}'

在节点上设置 vm.max_map_count。 无论 spec.general.setVMMaxMapCount 的值是什么，E1 都不会运行用于在 2.8.0 中设置 vm.max_map_count 的特权 init 容器。升级之前，每个运行 OpenSearch 的节点都必须将 vm.max_map_count 设置为 262144 或更高；否则，Pod 重启后将无法启动。请参阅在节点上设置 vm.max_map_count。

所有集群都处于健康状态且为 RUNNING。 未处于 RUNNING 状态的集群要等到达到该状态后才会迁移。

kubectl get opensearchclusters.opensearch.opster.io -A \
  -o custom-columns=NAMESPACE:.metadata.namespace,NAME:.metadata.name,PHASE:.status.phase,VERSION:.spec.general.version

另请检查 OpenSearch 集群的健康状态是否为 green。

其他资源均为 CREATED。 例如：

kubectl get opensearchusers.opensearch.opster.io -A \
  -o custom-columns=NAMESPACE:.metadata.namespace,NAME:.metadata.name,STATE:.status.state

对你使用的上述其他类型重复此检查。

每个索引至少有一个从节点。 在滚动重启期间，没有从节点的索引会在承载该索引的节点重启时不可用。每个节点重启期间，集群健康状态预计为 yellow。
创建快照。 没有自动回滚机制（请参阅回滚）。升级前请为数据创建快照。
检查引擎版本。 迁移会保持 spec.general.version 不变；operator 升级不会升级 OpenSearch。由于每个 Pod 都会重启，各集群当前运行版本的镜像必须仍可供节点使用。
检查未启用 TLS 的集群。 在 E1 3.0 中，spec 未配置 TLS（没有 spec.security.tls.transport 或 spec.security.tls.http）的集群会禁用 OpenSearch security plugin，并以未加密的 HTTP 提供服务，且不进行身份验证。如果此类集群依赖 security plugin，请在升级前解决此问题。
检查 Pod Security 设置。 重启后，OpenSearch 和 Dashboards Pod 将采用安装中所述的受限默认设置，包括 OpenSearch Pod 的 fsGroup: 1000。如果你设置了自己的 podSecurityContext 或 securityContext，则仍以你的设置为准。
规划维护时段。 对于节点数量较多或数据量较大的节点池，滚动重启可能需要很长时间。
更新自动化配置。 创建或修改 opensearch.opster.io/v1 资源的脚本、GitOps 仓库和 Helm chart 在升级后将会失败。请将其切换为 opensearch.org/v1，并将标签选择器从 opster.io/... 切换为 opensearch.org/...。

升级 operator

E1 3.0 在 opensearch-operator OLM 软件包中发布，且仅位于 stable channel，并标记为可替换任何 2.8.x 版本。operator 2.8.0 位于 alpha channel，该 channel 保持为 2.8.0，因此只有将 2.8.0 Subscription 切换到 stable 后，才会升级该 Subscription：

kubectl -n <operator-namespace> patch subscription <subscription-name> \
  --type merge -p '{"spec":{"channel":"stable"}}'

WARNING

平台日志存储（平台日志功能的 OpenSearch 日志存储）在 alpha channel 上使用 operator 2.8.0，并创建 opensearch.opster.io/v1 集群，而 E1 会将这些集群设为只读。不要将平台日志存储使用的 Subscription 切换到 stable。

使用自动批准时，切换 channel 后，OLM 会立即升级 operator。

使用手动批准时，请在 Web 控制台中批准待处理的 InstallPlan，或使用 kubectl：

kubectl -n <operator-namespace> get installplan
kubectl -n <operator-namespace> patch installplan <installplan-name> \
  --type merge -p '{"spec":{"approved":true}}'

如果没有提供升级，请检查 Subscription 的 channel 是否为 stable，以及其 catalog source 是否提供 E1 3.0 bundle。OLM 只会提供 Subscription 所引用的 catalog source 和 channel 中的升级。

如果你的 2.8.0 Subscription 指向发布 E1 的 catalog source 之外的其他 catalog source，OLM 将不会提供升级，因为它不会在 catalog source 之间迁移 Subscription。编辑 Subscription，使 spec.source 和 spec.sourceNamespace 指向发布 E1 的 catalog source，并将 spec.channel 设置为 stable：

kubectl -n <operator-namespace> patch subscription <subscription-name> --type merge \
  -p '{"spec":{"source":"<catalog-source>","sourceNamespace":"<catalog-namespace>","channel":"stable"}}'

等待新的 ClusterServiceVersion 变为 Succeeded：

kubectl -n <operator-namespace> get csv

升级后

新资源存在。 每个旧资源在新 group 中都有对应资源：
kubectl get opensearchclusters.opensearch.opster.io -A kubectl get opensearchclusters.opensearch.org -A
对你使用的其他类型重复此操作，例如 opensearchusers.opensearch.org。

观察滚动重启。

kubectl -n <namespace> get events --field-selector involvedObject.name=<cluster-name>
kubectl -n <namespace> get pods -l opensearch.org/opensearch-cluster=<cluster-name> -w

预计每个节点池会有一个 StatefulSetRecreated 事件，随后会有 RollingRestart 事件。

所有 Pod 重启后，集群将处于 RUNNING 状态且运行正常：
kubectl -n <namespace> get opensearchclusters.opensearch.org <cluster-name> \ -o jsonpath='{.status.phase}{"\n"}'
检查 OpenSearch 集群健康状态是否恢复为 green。
仅在新 group 上进行更改。 使用 kubectl edit opensearchclusters.opensearch.org <cluster-name>（对于其他每种类型，使用 opensearch.org group）。尝试更改旧资源的 spec 时会被拒绝，并显示 opensearch.opster.io/v1 API group 已弃用的消息。

迁移后的旧资源

无需删除旧的 opensearch.opster.io/v1 资源。如果删除这些资源：

删除旧资源的操作会一直等待，直到其 opensearch.org/v1 对应资源存在，因此该资源不会在迁移前被删除。
删除已迁移的 opensearch.org/v1 资源也会删除相应的旧资源。

回滚

无法自动回滚到 operator 2.8.0：

OLM 不会降级已安装的 operator。
迁移后，旧资源会保留迁移时的 spec。对 opensearch.org/v1 资源所做的更改不会复制回旧资源。
节点池 StatefulSet 已使用 opensearch.org/... 选择器标签重新创建。

如果升级失败，请收集 operator 日志和集群事件，保留数据卷，并在需要时从升级前创建的快照恢复。

故障排除

症状	检查
未出现 `opensearch.org/v1` 集群	旧集群的 `status.phase` 必须为 `RUNNING`。检查 operator 日志中是否有迁移相关消息。
升级后 Pod 反复重启	检查 Pod 日志。有关 `vm.max_map_count` 的消息表示未满足节点先决条件。
Pod 被 Pod Security admission 拒绝	集群自身的 `podSecurityContext` 或 `securityContext` 中设置了 `restricted` 不允许的值。
创建或更改 `opensearch.opster.io/v1` 资源失败	符合预期：旧 group 为只读。使用 `opensearch.org/v1`。

OpenSearch® 是 LF Projects, LLC 的注册商标。

#升级

#目录

#变更内容

#迁移的工作原理

#为什么每个节点池都会重启一次

#升级前

#升级 operator

#升级后

#迁移后的旧资源

#回滚

#故障排除

升级

目录