AKS集群中PgAdmin部署无法适配Azure Files存储类问题

问题现象 #

• 部署PgAdmin使用Azure Files存储类时，Pod无响应，日志抛出错误：

  2022-10-28 08:58:46,535: ERROR pgadmin: Exception in database migration.

• 切换为Azure Disk存储类后Pod可正常运行
• 已测试AKS内置存储类及自定义存储类（配置如下），存储账户和文件共享创建成功，但仅生成0KB空文件，无有效内容：

  kind: StorageClass
  apiVersion: storage.k8s.io/v1
  metadata:
    name: azurefile-default
  provisioner: file.csi.azure.com # replace with "kubernetes.io/azure-file" if aks version is less than 1.21
  allowVolumeExpansion: true
  mountOptions:
    - dir_mode=0777
    - file_mode=0777
    - uid=0
    - gid=0
    - mfsymlinks
    - cache=strict
    - actimeo=30
  parameters:
    skuName: Standard_LRS
  

可能原因及解决方案 #

1. SMB文件锁兼容性问题 #

PgAdmin默认使用SQLite数据库存储配置，而SQLite依赖文件系统的字节范围锁。Azure Files基于SMB协议，默认的锁机制可能导致PgAdmin在执行数据库迁移时出现阻塞，进而触发异常。

解决方法：
在存储类的mountOptions中添加nobrl参数，禁用字节范围锁：

mountOptions:
  - dir_mode=0777
  - file_mode=0777
  - uid=0
  - gid=0
  - mfsymlinks
  - cache=strict
  - actimeo=30
  - nobrl

更新存储类后，重新创建PVC和PgAdmin Deployment，验证是否恢复正常。

2. 权限继承异常 #

尽管配置了dir_mode和file_mode为0777，Azure Files的权限继承可能存在延迟或不生效的情况，导致PgAdmin进程无法写入数据库文件。

解决方法：

• 确保PgAdmin容器以root用户运行（UID=0），与存储类配置的uid=0、gid=0匹配。可在Deployment的容器定义中添加：

  securityContext:
    runAsUser: 0
    runAsGroup: 0
  

• 手动初始化挂载目录权限：创建临时Pod挂载目标PVC，执行权限修复命令：

  kubectl run -it --rm temp-perm-fix --image=alpine --volume=name=pgadmin-data,claimName=pgadmin-pvc -- /bin/sh
  chmod -R 777 /path/to/mount-point # 替换为实际挂载路径，如/var/lib/pgadmin
  exit
  

  之后再启动PgAdmin Pod。

3. 存储性能不足 #

Standard_LRS级别的Azure Files IOPS和吞吐量有限，可能无法满足PgAdmin数据库迁移的性能需求，导致超时无响应。

解决方法：

• 将存储类的skuName修改为Premium_LRS，使用高级文件共享提升性能：

  parameters:
    skuName: Premium_LRS
  

• 增加PgAdmin数据库操作的超时时间，在Deployment的环境变量中添加：

  env:
    - name: PGADMIN_CONFIG_DB_TIMEOUT
      value: "300" # 单位：秒
  

4. CSI驱动版本兼容性 #

若使用file.csi.azure.com驱动，旧版本可能存在与PgAdmin的兼容性问题。

解决方法：

• 升级AKS集群到稳定版本，确保CSI驱动与集群版本匹配
• 通过AKS集群的扩展管理界面更新Azure Files CSI驱动到最新稳定版

验证步骤 #

1. 应用修改后的存储类配置
2. 删除现有PVC和PgAdmin Pod，等待重新创建
3. 查看Pod日志：kubectl logs <pgadmin-pod-name>，确认数据库迁移异常是否消失
4. 检查Azure Files共享中的文件，确认是否有非0KB的有效内容生成

内容的提问来源于stack exchange，提问作者Eric Jansen