Apache KvRocks 2.7.0 启动失败问题分析与解决方案

Apache KvRocks 是一个基于 RocksDB 的高性能键值存储系统，兼容 Redis 协议。在从 2.5.0 版本升级到 2.7.0 版本时，用户可能会遇到启动失败的问题，错误信息显示"rename file encounter error: Resource busy"。本文将深入分析这一问题的根本原因，并提供详细的解决方案。

问题现象

当用户在 Kubernetes 环境中部署 KvRocks 2.7.0 时，容器启动后会立即失败，日志中会显示以下关键错误信息：

E20240305 11:58:19.558729     1 main.cc:180] Failed to start server: rename file encounter error: Resource busy

相比之下，2.5.0 版本在相同配置下能够正常启动和工作。

根本原因分析

这个问题的根源在于 KvRocks 2.7.0 在启动过程中新增了一个配置重写的行为。具体来说：

1. 在 2.7.0 版本中，KvRocks 启动后会尝试重写配置文件（执行类似 config rewrite 的操作）
2. 当配置文件以 Kubernetes Secret 形式挂载，并且使用了 subPath 方式挂载单个文件时，该文件实际上是只读的
3. 尝试对只读文件进行重命名操作时，系统会返回"Resource busy"错误
4. 这个行为是在 #1776 号提交中引入的，目的是在加载命名空间后重写配置

值得注意的是，即使在 2.5.0 版本中，如果手动执行 config rewrite 命令，也会遇到相同的错误。2.7.0 版本只是将这个操作变成了启动时的默认行为。

解决方案

方案一：修改挂载方式

最直接的解决方案是改变配置文件的挂载方式，不再使用 subPath 挂载单个文件，而是挂载整个目录。具体实现如下：

1. 创建一个临时存储卷（如 emptyDir）
2. 使用 initContainer 将配置文件从 Secret 复制到目标目录
3. 主容器挂载整个目录而非单个文件

这种方式的优势是：

• 保持了配置的安全性（仍从 Secret 加载）
• 允许 KvRocks 对配置文件进行读写操作
• 符合 Kubernetes 的最佳实践

方案二：Kubernetes 部署示例

以下是一个完整的 Kubernetes StatefulSet 配置示例，展示了如何正确部署 KvRocks 2.7.0：

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: kvrocks
spec:
  template:
    spec:
      initContainers:
        - name: copy-kvrocks-conf
          image: busybox
          command: ["sh", "-c", "cp /tmp/kvrocks.conf /var/lib/kvrocks/"]
          volumeMounts:
            - name: kvrocks-config
              mountPath: /tmp/kvrocks.conf
              subPath: kvrocks.conf
            - name: kvrocks-folder
              mountPath: /var/lib/kvrocks
      containers:
        - name: kvrocks
          image: apache/kvrocks:2.7.0
          volumeMounts:
            - name: kvrocks-folder
              mountPath: /var/lib/kvrocks
            - name: kvrocks-data
              mountPath: /data
      volumes:
        - name: kvrocks-folder
          emptyDir: {}
        - name: kvrocks-data
          persistentVolumeClaim:
            claimName: kvrocks-data
        - name: kvrocks-config
          secret:
            secretName: kvrocks-config

技术背景

理解这个问题需要一些背景知识：

1. Kubernetes subPath 挂载：当使用 subPath 挂载单个文件时，Kubernetes 会将该文件以只读方式挂载到容器中，这是设计上的限制。

2. KvRocks 配置管理：KvRocks 在运行时可能需要更新配置文件，例如记录当前的命名空间信息或运行时配置变更。

3. 文件重命名操作：在 Unix 系统中，重命名文件实际上是对目录项的修改，当文件被以只读方式挂载时，这种操作会被拒绝。

最佳实践建议

为了避免类似问题，建议在部署 KvRocks 时遵循以下最佳实践：

1. 配置文件应存储在可写的存储卷中
2. 使用 ConfigMap 或 Secret 作为配置来源时，通过 initContainer 复制到可写目录
3. 为配置目录和数据库目录使用不同的存储卷
4. 在升级前测试配置兼容性，特别是跨大版本的升级

总结

KvRocks 2.7.0 引入的自动配置重写功能暴露了 Kubernetes 中 subPath 挂载的限制。通过调整挂载策略和使用 initContainer 模式，可以顺利解决这个问题。这个案例也提醒我们，在升级存储类服务时，需要特别注意持久化数据和配置文件的处理方式变化。