#不依赖 TopoLVM 部署 MySQL-MGR

本指南介绍如何在未安装 TopoLVM 的集群上部署 MySQL Group Replication（MGR）实例，例如运行 MicroOS（SUSE Linux Enterprise Micro）或使用其他存储 provisioner 的环境。

#背景

#挑战

MySQL-MGR 通常依赖 TopoLVM 进行动态卷分配。但是，某些环境不支持 TopoLVM：

• MicroOS 集群：根文件系统为只读，且可能未安装 TopoLVM。
• 裸金属集群：某些集群使用本地存储并通过手动方式 provision PV。
• 测试/评估环境：不包含 TopoLVM 的轻量级部署。

如果没有正确配置存储，MySQL Pod 将因 PVC 绑定失败或权限问题而无法启动。

#解决方案

使用通过手动 provision 的 PersistentVolumes（PV）构建本地 StorageClass。本指南涵盖以下内容：

• 依赖安装：在部署 MySQL-MGR 之前，确保已安装所有必需的 operator。
• StorageClass 创建：配置带有 WaitForFirstConsumer 绑定模式的本地 StorageClass。
• PV provision：创建具有正确路径、权限和回收策略的本地 PV。
• ClickHouse 存储修复（可选）：避免由 query-analytics plugin 的硬编码主机路径导致的 read-only file system 错误。
• 实例创建：使用本地 StorageClass 部署 MySQL-MGR。

#前提条件

#必需的 Operator

在部署 MySQL-MGR 之前，请确保集群上已安装以下核心 operator：

如果你需要查询分析功能（慢查询日志、查询分析），还需要以下 operator：

你可以通过检查 CSV 来验证这些 operator 是否已安装：

kubectl get csv -A | grep -E "application-services-core|rds-operator|clickhouse-operator|query-analytics-operator"

所有 operator 在 PHASE 列中都应显示 Succeeded。

#集群要求

• 生产部署建议至少有 3 个 worker 节点（MySQL-MGR 需要 3 个成员才能满足 group replication quorum）。测试环境可以使用单成员部署。
• 每个节点都应具备足够的 CPU 和内存资源。
• 所有节点上都应有一个可写目录路径可用（例如 MicroOS 上的 /opt/local-pv/）。

#步骤 1：创建本地 StorageClass

如果你的集群尚未拥有合适的 StorageClass，请创建一个：

kubectl apply -f - <<EOF
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: mgr-local-pv
provisioner: kubernetes.io/no-provisioner
volumeBindingMode: WaitForFirstConsumer
EOF

#步骤 2：provision 本地 PersistentVolumes

每个 MySQL-MGR 成员都需要一个 PV。对于 3 成员集群，至少创建 3 个 PV，并分布在不同节点上。

#在节点上创建目录

在 MicroOS 上，根文件系统是只读的。请使用 /opt/local-pv/ 作为基础路径：

# 在每个 worker 节点上执行，或者使用特权 Pod
for i in $(seq 1 9); do
  mkdir -p /opt/local-pv/pv$i
  chmod 777 /opt/local-pv/pv$i
done

#创建 PV 资源

首先，获取节点名称：

kubectl get nodes -o wide

然后创建 PV，并将每个 PV 映射到特定节点。对于跨 3 个节点的 3 成员集群：

# 定义节点名称
NODE1=<node1-hostname>
NODE2=<node2-hostname>
NODE3=<node3-hostname>

# 每个节点创建 3 个 PV（总共 9 个），以便进行扩容和重新 provision
nodes=("$NODE1" "$NODE2" "$NODE3")
for n in "${!nodes[@]}"; do
  node="${nodes[$n]}"
  for i in 1 2 3; do
    idx=$(( n * 3 + i ))
    kubectl apply -f - <<EOF
apiVersion: v1
kind: PersistentVolume
metadata:
  name: local-pv-$idx
spec:
  capacity:
    storage: 20Gi
  volumeMode: Filesystem
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Delete
  storageClassName: mgr-local-pv
  local:
    path: /opt/local-pv/pv$idx
  nodeAffinity:
    required:
      nodeSelectorTerms:
        - matchExpressions:
            - key: kubernetes.io/hostname
              operator: In
              values:
                - $node
EOF
  done
done

验证所有 PV 都已创建且可用：

kubectl get pv | grep mgr-local-pv

在继续之前，所有 PV 的状态都应显示为 Available。

#步骤 3（可选）：在只读文件系统上配置 ClickHouse 存储路径

query-analytics plugin 会使用主机目录 PV 来部署 ClickHouse。默认情况下，主机路径是 /cpaas/ck。在 MicroOS 或其他根文件系统只读的系统上，这会导致 ClickHouse Pod 启动失败，并出现如下错误：

mkdir /cpaas: read-only file system

#在安装 query-analytics-operator 之前配置 hostPath

1. 先安装 rds-operator（如果尚未安装）。RdsInstaller CR 会在 rds-operator 初始化期间创建。

2. 查找 RdsInstaller 资源：

   kubectl get rdsinstaller -A

3. 编辑 RdsInstaller，覆盖 ClickHouse 的主机路径：

   kubectl edit rdsinstaller <name> -n <namespace>

   将 spec.slowSQLCK.hostPath 设置为节点上的可写路径：

   spec:
     slowSQLCK:
       hostPath: /opt/local-pv/ck
   INFO

   在 MicroOS 上，请使用 /opt/ 下的路径（例如 /opt/local-pv/ck）。该目录将通过 DirectoryOrCreate 类型自动创建。

4. 现在安装 clickhouse-operator 和 query-analytics-operator。ClickHouse PV 将使用已配置的路径创建，而不是默认的 /cpaas/ck。

#修复使用错误 hostPath 的现有部署

如果 query-analytics-operator 已使用默认路径安装且 ClickHouse Pod 已经失败，仅编辑 RdsInstaller.spec.slowSQLCK.hostPath 还不够——因为合并到 QueryAnalyticsInstaller 的逻辑只会在 qai 首次创建时运行。你还必须强制重新创建 qai（或直接编辑 qai）。

方案 A — 重新创建 qai 以重新执行合并：

1. 按照上面的预安装步骤更新 RdsInstaller：

   kubectl edit rdsinstaller <name> -n <namespace>
   # set spec.slowSQLCK.hostPath: /opt/local-pv/ck

2. 删除 ClickHouse 安装和旧 PV：

   kubectl delete chi pxc-ck -n <clickhouse-namespace>
   kubectl get pv | grep pxc-ck
   kubectl delete pv <pv-name>

3. 删除 QueryAnalyticsInstaller CR。query-analytics-operator 将重新创建它，并合并更新后的 RdsInstaller 设置：

   kubectl delete qai qai

4. 验证新的 hostPath：

   kubectl get qai qai -o jsonpath='{.spec.slowSQL.hostPath}{"\n"}'
   kubectl get pv pxc-ck-pv -o jsonpath='{.spec.hostPath.path}{"\n"}'

   两者都应显示已配置的路径（例如 /opt/local-pv/ck）。

方案 B — 直接编辑 qai（更快，但在下次重新创建之前，RdsInstaller 将与 qai 不一致）：

kubectl edit qai qai
# set spec.slowSQL.hostPath: /opt/local-pv/ck
kubectl delete chi pxc-ck -n <clickhouse-namespace>
kubectl delete pv <old-pv-name>

query-analytics-operator 将使用 qai 上设置的路径重新创建 ClickHouse 安装和 PV。

#步骤 4：创建 MySQL-MGR 实例

1. 创建密码 secret：

   kubectl -n ${namespace} create secret generic mgr-${instance_name}-password \
     --from-literal=clusterchecker=${password} \
     --from-literal=exporter=${password} \
     --from-literal=manage=${password} \
     --from-literal=root=${password}

2. 使用本地 StorageClass 创建 MySQL CR：

   kubectl apply -n ${namespace} -f - <<EOF
   apiVersion: middleware.alauda.io/v1
   kind: Mysql
   metadata:
     labels:
       mysql/arch: mgr
     name: ${instance_name}
   spec:
     mgr:
       enableStorage: true
       members: 3
       monitor:
         enable: true
       resources:
         server:
           limits:
             cpu: "2"
             memory: 4Gi
           requests:
             cpu: "2"
             memory: 4Gi
       router:
         replicas: 2
         resources:
           limits:
             cpu: 800m
             memory: 640Mi
           requests:
             cpu: 800m
             memory: 640Mi
         svcRO:
           type: ClusterIP
         svcRW:
           type: ClusterIP
       volumeClaimTemplate:
         spec:
           resources:
             requests:
               storage: 20Gi
           storageClassName: mgr-local-pv
     params:
       mysql:
         mysqld:
           character_set_server: utf8mb4
           default_storage_engine: InnoDB
           default_time_zone: "+08:00"
     version: "8.0"
   EOF
   INFO

   • 密码 secret 必须遵循命名约定 mgr-${instance_name}-password。operator 会自动按该名称发现它。
   • 在 volumeClaimTemplate 部分将 storageClassName 设置为 mgr-local-pv（或你的 StorageClass 名称）。这将替换默认的 sc-topolvm。
   • version 字段是必需的。MySQL 8.0 请使用 "8.0"。

3. 监控实例状态：

   kubectl get mysql ${instance_name} -n ${namespace} -w

   等待 STATE 字段显示为 ready。

4. 验证 PVC 绑定和 Pod 调度位置：

   kubectl get pvc -n ${namespace}
   kubectl get pod -n ${namespace} -o wide | grep ${instance_name}

   确认每个 PVC 都已绑定到 PV，且 Pod 分布在不同节点上。

#故障排查

#PVC 一直处于 Pending

现象：PVC 一直处于 Pending 状态，Pod 无法调度。

原因：没有可用 PV 与 StorageClass 名称或 node affinity 匹配，或者 PV 处于 Released 状态。

修复：

# 检查 PV 状态
kubectl get pv | grep mgr-local-pv
# 查看 PVC 事件以获取详情
kubectl describe pvc -n <namespace> <pvc-name>
# 验证 PV 和 PVC 的 StorageClass 名称是否一致
kubectl get pv <pv-name> -o jsonpath='{.spec.storageClassName}'

#MySQL Pod 一直处于 CrashLoopBackOff

现象：MySQL Pod 在初始化期间因 Permission denied 崩溃。

原因：PV 目录没有为非 root 的 MySQL 用户提供写权限。

修复：

# 在 Pod 所在节点上执行
chmod 777 /opt/local-pv/pvN

#MySQL Pod 因 “data directory has files in it” 失败

现象：mysqld --initialize 因数据目录不为空而失败。

原因：PV 目录中包含上一次部署遗留的数据。

修复：

# 在节点上，或者通过特权 Pod 执行
rm -rf /opt/local-pv/pvN/*

#PV 一直处于 Released 状态

现象：PV 显示为 Released，无法绑定到新的 PVC。

原因：PV 创建时使用了 persistentVolumeReclaimPolicy: Retain。

修复：删除这些处于 Released 状态的 PV，并使用 persistentVolumeReclaimPolicy: Delete 重新创建：

kubectl delete pv <pv-name>
# 然后按照步骤 2 重新创建

#实例一直处于 ErrorReconcile

现象：MySQL 实例显示 ErrorReconcile 条件，且即使所有 Pod 都在运行，STATE 字段仍显示为 available 而不是 ready。

原因：operator 的 reconcile 循环在更新 CR 状态时遇到冲突错误。

修复：为 MySQL CR 添加注解，触发一次新的协调：

kubectl annotate mysql ${instance_name} -n ${namespace} \
  force-reconcile="$(date +%s)" --overwrite

#ClickHouse Pod 因 “read-only file system” 失败

现象：ClickHouse Pod 启动失败，并出现 mkdir /cpaas: read-only file system。

原因：query-analytics plugin 默认的 ClickHouse 主机路径（/cpaas/ck）在只读文件系统上不存在。

修复：按照步骤 3 的说明，在 RdsInstaller CR 中将 spec.slowSQLCK.hostPath 设置为一个可写路径。