#不使用 TopoLVM 部署 MySQL-MGR

本指南介绍如何在不支持 TopoLVM 的集群上部署 MySQL Group Replication (MGR) 实例，例如运行 Alauda OS 的集群，或其他使用替代存储 provisioner 的环境。

#背景

#面临的挑战

MySQL-MGR 通常依赖 TopoLVM 进行动态卷供给。然而，某些环境并不支持 TopoLVM：

• Alauda OS 集群：根文件系统为只读，且可能未安装 TopoLVM。
• 裸金属集群：部分集群使用本地存储，并采用手动 PV 供给。
• 测试/评估环境：不包含 TopoLVM 的轻量级部署。

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

#解决方案

使用本地 StorageClass，并手动供给 PersistentVolume (PV)。本指南涵盖以下内容：

• 依赖安装：在部署 MySQL-MGR 之前，确保已安装所有必需的 operator。
• 创建 StorageClass：设置使用 WaitForFirstConsumer 绑定模式的本地 StorageClass。
• 供给 PV：创建具有正确路径、权限和回收策略的本地 PV。
• ClickHouse 存储修复（可选）：避免 query-analytics 插件硬编码的 host path 导致的 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 个成员才能形成组复制法定人数）。测试环境可以使用单成员部署。
• 每个节点具备充足的 CPU 和内存资源。
• 所有节点上均有可写目录路径（例如，Alauda OS 上的 /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：供给本地 PersistentVolume

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

#在节点上创建目录

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

# Run on each worker node, or use a privileged 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 成员集群：

# Define your node names
NODE1=<node1-hostname>
NODE2=<node2-hostname>
NODE3=<node3-hostname>

# Create 3 PVs per node (9 total) to allow for scaling and reprovisioning
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 -l '!pv-is-managed' | grep mgr-local-pv

在继续操作之前，所有 PV 应显示 Available 状态。

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

query-analytics 插件使用宿主机目录 PV 部署 ClickHouse。默认 host path 为 /cpaas/ck。在 Alauda OS 或其他根文件系统为只读的系统上，这会导致 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 host path：

   kubectl edit rdsinstaller <name> -n <namespace>

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

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

   在 Alauda OS 上，请使用 /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 未被调度。

原因：没有与 StorageClass 名称或节点亲和性匹配的可用 PV，或者 PV 处于 Released 状态。

修复：

# Check PV status
kubectl get pv | grep mgr-local-pv
# Check PVC events for details
kubectl describe pvc -n <namespace> <pvc-name>
# Verify StorageClass name matches between PV and PVC
kubectl get pv <pv-name> -o jsonpath='{.spec.storageClassName}'

#MySQL Pod 卡在 CrashLoopBackOff 状态

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

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

修复：

# On the node where the pod is scheduled
chmod 777 /opt/local-pv/pvN

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

现象：由于数据目录非空，mysqld --initialize 失败。

原因：PV 目录包含来自先前部署的残留数据。

修复：

# On the node, or via a privileged pod
rm -rf /opt/local-pv/pvN/*

#PV 卡在 Released 状态

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

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

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

kubectl delete pv <pv-name>
# Then recreate following Step 2

#实例卡在 ErrorReconcile 状态

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

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

修复：为 MySQL CR 添加注解以触发新的 reconcile：

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 插件的默认 ClickHouse host path（/cpaas/ck）在只读文件系统上不存在。

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