ossfs故障处理_容器服务 Kubernetes 版 ACK(ACK)-阿里云帮助中心

OSS数据卷是通过ossfs文件进行挂载的FUSE文件系统。您可以通过分析Debug日志或查询Pod日志的方式进行ossfs异常问题的排查。本文划分了常见的ossfs异常问题，并通过示例介绍了两种运行方式的ossfs通用的排查方法。

排查说明

CSI存储插件为v1.26.6之前的版本中，ossfs以后台形式运行在业务Pod所在的节点上，运行异常时需要重新以前台方式挂载，您可以通过分析Debug日志进行排查。
CSI存储插件为v1.26.6及之后的版本中，ossfs以容器形式运行在kube-system命名空间下的Pod中，您可以直接查询Pod的日志进行排查。
重要
为避免ossfs运行时产生大量日志，以容器方式运行时默认的日志等级为critical。在进行Debug排查时，可能需要增加Debug参数，重新挂载。

适用场景1：挂载失败

OSS静态卷挂载失败，Pod无法启动，Event提示FailedMount时，请优先参见OSS静态卷挂载失败进行快速排查。

CSI Plugin组件为1.26.6之前的版本

问题现象

业务Pod启动时，长期处于ContainerCreating状态。

问题原因

执行以下命令，查询Pod无法正常启动的原因。
需替换的变量如下：
- <POD_NAMESPACE>：业务Pod所在的命名空间。
- <POD_NAME>：业务Pod名称。
```
kubectl -n <POD_NAMESPACE> describe pod <POD_NAME>
```
查询结果的Events中是否存在原因为FailedMount的事件。
需替换的变量如下：
- <PV_NAME>：OSS存储卷名称。
- <BUCKET>：挂载的OSS Bucket名称。
- <PATH>：挂载的OSS Bucket的路径。
- <POD_UID>：业务Pod的UID。
```
Warning  FailedMount  3s  kubelet  MountVolume.SetUp failed for volume "<PV_NAME>" : rpc error: code = Unknown desc = Mount is failed in host, mntCmd:systemd-run --scope -- /usr/local/bin/ossfs <BUCKET>:/<PATH> /var/lib/kubelet/pods/<POD_UID>/volumes/kubernetes.io~csi/<PV_NAME>/mount -ourl=oss-cn-beijing-internal.aliyuncs.com -o allow_other , err: ..... with error: exit status 1
```
  出现此类事件的原因：CSI组件在拉起ossfs时，ossfs异常退出，此时节点上无对应的ossfs进程在运行。OSS连通性检查出错（Bucket不存在，权限配置错误等）、挂载路径不存在、无读写权限等初始化检查的错误都可能导致此错误现象。

解决方案

步骤1：获取原ossfs启动指令

通过查询FailedMount事件，查看挂载异常的输出。具体操作，请参见适用场景1：挂载失败中的场景1。

通过挂载异常的输出获取原ossfs启动指令。

挂载异常输出示例如下：

Warning  FailedMount  3s  kubelet  MountVolume.SetUp failed for volume "<PV_NAME>" : rpc error: code = Unknown desc = Mount is failed in host, mntCmd:systemd-run --scope -- /usr/local/bin/ossfs <BUCKET>:/<PATH> /var/lib/kubelet/pods/<POD_UID>/volumes/kubernetes.io~csi/<PV_NAME>/mount -ourl=oss-cn-beijing-internal.aliyuncs.com -o allow_other , err: ..... with error: exit status 1

其中，在mntCmd中，system-run --scope -- 后端内容为原ossfs的启动指令。获取到原ossfs启动指令如下：

/usr/local/bin/ossfs <BUCKET>:/<PATH> /var/lib/kubelet/pods/<POD_UID>/volumes/kubernetes.io~csi/<PV_NAME>/mount -ourl=oss-cn-beijing-internal.aliyuncs.com -o allow_other

步骤2：前台挂载ossfs并获取Debug日志

ossfs挂载的目录访问权限默认为挂载点的所有者，即执行挂载命令的用户，其他用户无法访问。因此若原指令中没有-o allow_other配置项，可能导致挂载根路径的权限问题。

确认是否为挂载点路径权限问题。
如果权限存在问题，请直接在创建PV时，增加配置项-o allow_other。关于ossfs的挂载点目录访问权限配置，请参见配置访问权限，关于如何增加配置项，请参见使用OSS静态存储卷。

执行以下命令，在业务Pod所在节点以前台方式运行ossfs，并设置日志为Debug模式。

其中，/test为测试用的挂载点路径，前台运行的ossfs将把OSS Bucket挂载到/test中。

mkdir /test && /usr/local/bin/ossfs <BUCKET>:/<PATH> /test -ourl=oss-cn-beijing-internal.aliyuncs.com -d -f -o allow_other -o curldbg

参数	说明
-d	打开日志信息。
-f	以前台方式而非守护进程方式运行ossfs，在前台模式下，日志会输出到终端屏幕。该参数一般用于调试问题时使用。
-o allow_other	赋予计算机上其他用户访问挂载目录的权限，避免前台挂载ossfs时，出现新的挂载点路径权限问题。
-o curldbg	打开libcurl的日志信息，用于排查OSS服务端返回的错误。

步骤3：分析Debug日志

以前台方式运行ossfs后，日志将输出到终端。通常ossfs抛错的原因可以分为两类，分别为ossfs自身抛错，以及ossfs向OSS服务端发送请求后收到非200错误码。下文分别以两种抛错类型的例子介绍通用的排查方法。

下文以挂载失败场景中，ossfs运行后很快退出为例介绍如何进行问题排查。

ossfs自身抛错

查询日志，发现ossfs退出前打印的错误日志如下。

ossfs: MOUNTPOINT directory /test is not empty. if you are sure this is safe, can use the 'nonempty' mount option.

根据日志信息定位，报错的原因是挂载点路径本为非空，可通过增加配置项-o nonempty解决。

说明

根据错误日志，可在OSS文档ossfs常见问题查询相关解决方法。若未找到相关原因，请提交工单解决。

OSS服务端返回非200错误码

查询日志，发现ossfs退出前打印的OSS服务端的返回码为404，错误原因为NoSuchBucket，错误信息为The specified bucket does not exist。

[INFO]       Jul 10 2023:13:03:47:/tmp/ossfs/src/curl.cpp:RequestPerform(2382): HTTP response code 404 was returned, returning ENOENT, Body Text: <?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>NoSuchBucket</Code>
  <Message>The specified bucket does not exist.</Message>
  <RequestId>xxxx</RequestId>
  <HostId><BUCKET>.oss-cn-beijing-internal.aliyuncs.com</HostId>
  <BucketName><BUCKET></BucketName>
  <EC>0015-00000101</EC>
</Error>

通过日志信息定位，报错的原因为挂载的OSS Bucket不存在，可通过登录OSS管理控制台创建Bucket后重新挂载解决。

说明

通过错误码及错误原因，可在OSS文档HTTP错误码中查询相关的解决办法。

CSI Plugin组件为1.26.6及之后的版本

问题现象

业务Pod启动时，长期处于ContainerCreating状态。

问题原因

执行以下命令，确认ossfs容器是否正常运行。
替换以下<PV_NAME>为实际业务PV的名称。
```
kubectl -n kube-system get pod -l csi.alibabacloud.com/volume-id=<PV_NAME>
```
- 若ossfs容器运行异常，则预期输出为：
```
NAME                   READY   STATUS             RESTARTS     AGE
csi-fuse-ossfs-xxxx   0/1     CrashLoopBackOff   1 (4s ago)   5s
```
- 若ossfs容器运行正常，请排查是否由于节点异常等原因导致Pod处于ContainerCreating状态。

出现此类事件的原因：CSI组件在拉起ossfs容器时，ossfs异常退出，导致Pod CrashLoopBackOff。OSS连通性检查出错（例如Bucket不存在和权限配置错误等）、OSS挂载路径不存在、无读写权限等初始化检查的错误均可能导致此问题。

解决方案

执行以下命令，查询ossfs容器日志。

kubectl -n kube-system logs -p csi-fuse-ossfs-xxxx

（可选）如果日志为空，或信息过少无法定位问题，说明日志等级过高，需要通过以下方式增加相关配置。
说明
该方式无需重新部署新的Debug存储卷及对应的存储声明，但无法直获取OSS侧的rest请求响应。
1. 创建用于Debug的OSS存储卷，在原存储卷配置的基础上，在otherOpts字段中增加-o dbglevel=debug -o curldbg。使用新建的OSS存储卷挂载后，通过kubectl logs指令从ossfs Pod获取Debug日志。Debug日志量较大，仅建议在Debug场景使用。
2. 使用以下内容，在kube-system空间创建名为csi-plugin的ConfiMap。将日志等级设为debug。
  说明
  CSI plugin 1.28.2及之前的版本，日志等级只能设置到info。
```
apiVersion: v1
kind: ConfigMap
metadata:
  name: csi-plugin
  namespace: kube-system
data:
  fuse-ossfs: |
    dbglevel=debug # 日志  level
```
  重启应用所在节点的csi-plugin Pod使Configmap的配置生效，重启应用Pod触发重挂载，并确认重挂载后的csi-fuse-ossfs-xxxx重新部署。
  重要
  Configmap为全局配置，Debug完成后，请删除该Configmap，再次重启节点的csi-plugin Pod以关闭Debug日志。最后重启应用Pod再次触发重挂载，避免ossfs产生大量Debug日志。
分析ossfs容器日志。
通常ossfs抛错的原因可以分为两类，分别为ossfs自身抛错和ossfs向OSS服务端发送请求后收到非200错误码。以下通过两种抛错类型的示例介绍通用的排查方法。
ossfs自身抛错
查询日志，发现ossfs退出前打印的错误日志如下。
```
ossfs: MOUNTPOINT directory /test is not empty. if you are sure this is safe, can use the 'nonempty' mount option.
```
根据日志信息定位，报错的原因是挂载点路径本应为非空，可通过增加配置项-o nonempty解决。
说明
根据错误日志，可在OSS文档ossfs常见问题查询相关解决方法。若未找到相关原因，请提交工单解决。
OSS服务端返回非200错误码
查询日志，发现ossfs退出前检查挂载Bucket时，OSS服务端返回的错误码为404，错误原因为NoSuchBucket，错误信息为The specified bucket does not exist。
```
[ERROR]  2023-10-16 12:38:38:/tmp/ossfs/src/curl.cpp:CheckBucket(3420): Check bucket failed, oss response: <?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>NoSuchBucket</Code>
  <Message>The specified bucket does not exist.</Message>
  <RequestId>652D2ECEE1159C3732F6E0EF</RequestId>
  <HostId><bucket-name>.oss-<region-id>-internal.aliyuncs.com</HostId>
  <BucketName><bucket-name></BucketName>
  <EC>0015-00000101</EC>
  <RecommendDoc>https://api.aliyun.com/troubleshoot?q=0015-00000101</RecommendDoc>
</Error>
```
通过日志信息定位，报错的原因为挂载的OSS Bucket不存在，可通过登录OSS管理控制台创建Bucket后重新挂载解决。
说明
通过错误码及错误原因，可在OSS文档HTTP错误码中查询相关的解决办法。
其他说明
- 如果您的日志等级过高，无法定位问题，并且包含以下需求：
  - 不希望重建OSS存储卷。
  - 担心全局ConfigMap配置影响其他问题，例如，Debug期间可能发生的其他OSS存储卷的挂载或卸载。
  此时，您可以以前台方式挂载ossfs并获取Debug日志进行定位。具体操作，请参见CSI Plugin组件为1.26.6之前的版本问题的处理。
- 如果ossfs容器化后，节点上未默认安装ossfs。
  1. 可以直接通过yum安装，并通过csi-fuse-ossfs-xxxx Pod的spec.container.args字段获取初始启动参数。
  2. 在节点上执行以下命令，生成ossfs挂载时需要的鉴权信息。在Debug之后，请您及时清理该文件。
```
mkdir -p /etc/ossfs && echo "<bucket-name>:<akId>:<akSecret>" > /etc/ossfs/passwd-ossfs && chmod 600 /etc/ossfs/passwd-ossfs
```

适用场景2：执行POSIX指令抛错

CSI Plugin组件为1.26.6之前的版本

问题现象

业务Pod状态为Running，但执行读写等POSIX指令时ossfs抛错。

问题原因

借助业务的日志确认发生错误的指令及返回的错误类型。例如，执行chmod -R 777 /mnt/path指令时返回I/O error。

执行以下命令，进入业务Pod确认。

kubectl -n <POD_NAMESPACE> exec -it <POD_NAME> -- /bin/bash

bash-4.4# chmod -R 777 /mnt/path
chmod: /mnt/path: I/O error

出现此类事件的原因：CSI组件在拉起ossfs后，ossfs进程正常运行，并在业务Pod所在节点指定的挂载点路径挂载OSS Bucket。但在执行chmod、read、open等POSIX指令时，ossfs运行异常并返回错误。

解决方案

步骤1：获取原ossfs启动指令

由于ossfs已在节点上运行，您可以通过OSS存储卷名称在业务Pod所在的节点上执行以下指令，获取原ossfs启动指令。

ps -aux | grep ossfs | grep <PV_NAME>

预期输出：

root     2097450  0.0  0.2 124268 33900 ?        Ssl  20:47   0:00 /usr/local/bin/ossfs <BUCKET> /<PATH> /var/lib/kubelet/pods/<POD_UID>/volumes/kubernetes.io~csi/<PV_NAME>/mount -ourl=oss-cn-beijing-internal.aliyuncs.com -o allow_other

将预期输出中<BUCKET>后面的空格替换为冒号（:），即由<BUCKET> /<PATH>改为<BUCKET>:/<PATH>，获取到原ossfs启动指令如下。

/usr/local/bin/ossfs <BUCKET>:/<PATH> /var/lib/kubelet/pods/<POD_UID>/volumes/kubernetes.io~csi/<PV_NAME>/mount -ourl=oss-cn-beijing-internal.aliyuncs.com -o allow_other

步骤2：前台挂载ossfs并获取Debug日志

确认是否为挂载点路径权限问题。
如果权限存在问题，请直接在创建PV时，增加配置项-o allow_other。关于ossfs的挂载点目录访问权限配置，请参见配置访问权限，关于如何增加配置项，请参见使用OSS静态存储卷。

执行以下命令，在业务Pod所在节点以前台方式运行ossfs，并设置日志为Debug模式。

其中，/test为测试用的挂载点路径，前台运行的ossfs将把OSS Bucket挂载到/test中。

mkdir /test && /usr/local/bin/ossfs <BUCKET>:/<PATH> /test -ourl=oss-cn-beijing-internal.aliyuncs.com -d -f -o allow_other -o curldbg

参数	说明
-d	打开日志信息。
-f	以前台方式而非守护进程方式运行ossfs，在前台模式下，日志会输出到终端屏幕。该参数一般用于调试问题时使用。
-o allow_other	赋予计算机上其他用户访问挂载目录的权限，避免前台挂载ossfs时，出现新的挂载点路径权限问题。
-o curldbg	打开libcurl的日志信息，用于排查OSS服务端返回的错误。

步骤3：分析Debug日志

执行POSIX失败场景中，需要另起终端执行出错的指令，并分析执行新打印的ossfs日志。

ossfs自身抛错

下文以执行chmod -R 777 <业务Pod中的挂载点路径>指令出错为例，介绍如何进行问题排查。

由于测试ossfs进程挂载至/test路径下，则需执行的指令如下。

chmod -R 777 /test

查询日志，发现挂载点路径/test下的文件Chmod成功，而Chmod /test本身的错误日志如下。

[ERROR] Jul 10 2023:13:03:18:/tmp/ossfs/src/ossfs.cpp:ossfs_chmod(1742): Could not change mode for mount point.

根据日志信息定位，挂载点路径不支持通过Chmod变更权限。关于如何修改挂载点的权限，请参见OSS存储卷FAQ。

说明

根据错误日志，可在OSS文档ossfs常见问题查询相关解决方法。若未找到相关原因，请提交工单解决。

OSS服务端返回非200错误码

下文以对Bucket中的某个对象进行操作时，都返回错误为例，介绍如何进行问题排查。

[INFO]       Aug 23 2022:11:54:11:/tmp/ossfs/src/curl.cpp:RequestPerform(2377): HTTP response code 404 was returned, returning ENOENT, Body Text: <?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>NoSuchKey</Code>
  <Message>The specified key does not exist.</Message>
  <RequestId>xxxx</RequestId>
  <HostId><BUCKET>.oss-cn-beijing-internal.aliyuncs.com</HostId>
  <Key><object-name></Key>
  <EC>0026-00000001</EC>
</Error>

执行出错的指令，发现退出前打印的OSS服务端的返回码为404，错误原因为NoSuchKey，错误信息为The specified key does not exist。

根据日志信息定位，该对象在OSS服务端中不存在。关于出现该现象的原因及对应的解决办法，请参见NoSuchKey。

说明

通过错误码及错误原因，可在OSS文档HTTP错误码中查询相关的解决办法。

CSI Plugin组件为1.26.6及之后的版本

问题现象

业务Pod状态为Running，但执行读写等POSIX指令时ossfs抛错。

问题原因

执行以下命令，确认ossfs容器是否正常运行。
替换以下<PV_NAME>为实际业务PV的名称。
```
kubectl -n kube-system get pod -l csi.alibabacloud.com/volume-id=<PV_NAME>
```
预期输出：
```
NAME                   READY   STATUS             RESTARTS     AGE
csi-fuse-ossfs-xxxx     1/1    Running              0          5s
```
若ossfs容器运行异常，请先排查容器异常的原因。具体操作，请参见Pod异常问题排查。
通过业务的日志确认发生错误的指令及返回的错误类型。例如，执行chmod -R 777 /mnt/path指令时返回I/O error。

出现此类事件的原因：CSI组件在拉起ossfs容器后，ossfs Pod正常运行，并在业务Pod所在节点指定的挂载点路径上挂载OSS Bucket，但在执行chmod、read、open等POSIX指令时，ossfs运行异常并返回错误，并在日志中打印对应错误。

解决方案

执行以下命令，查询ossfs容器日志。

kubectl -n kube-system logs -p csi-fuse-ossfs-xxxx

（可选）如果日志为空，或信息过少无法定位问题，说明日志等级过高，需要通过以下方式增加相关配置。
说明
该方式无需重新部署新的Debug存储卷及对应的存储声明，但无法直获取OSS侧的rest请求响应。
1. 创建用于Debug的OSS存储卷，在原存储卷配置的基础上，在otherOpts字段中增加-o dbglevel=debug -o curldbg。使用新建的OSS存储卷挂载后，通过kubectl logs指令从ossfs Pod获取Debug日志。Debug日志量较大，仅建议在Debug场景使用。
2. 使用以下内容，在kube-system空间创建名为csi-plugin的ConfiMap。将日志等级设为debug。
  说明
  CSI plugin 1.28.2及之前的版本，日志等级只能设置到info。
```
apiVersion: v1
kind: ConfigMap
metadata:
  name: csi-plugin
  namespace: kube-system
data:
  fuse-ossfs: |
    dbglevel=debug # 日志  level
```
  重启应用所在节点的csi-plugin Pod使Configmap的配置生效，重启应用Pod触发重挂载，并确认重挂载后的csi-fuse-ossfs-xxxx重新部署。
  重要
  Configmap为全局配置，Debug完成后，请删除该Configmap，再次重启节点的csi-plugin Pod以关闭Debug日志。最后重启应用Pod再次触发重挂载，避免ossfs产生大量Debug日志。
分析ossfs容器日志。
通常ossfs抛错的原因可以分为两类，分别为ossfs自身抛错和ossfs向OSS服务端发送请求后收到非200错误码。以下通过两种抛错类型的示例介绍通用的排查方法。
ossfs自身抛错
此处以执行chmod -R 777 <业务Pod中的挂载点路径>指令出错为例，介绍如何进行问题排查。
1. 若测试ossfs的挂载路径为/test，则执行以下命令。
```
chmod -R 777 /test
```
  查询日志后，发现挂载点路径/test下的文件Chmod成功，而Chmod /test自身的错误日志如下。
```
[ERROR]  2023-10-18 06:03:24:/tmp/ossfs/src/ossfs.cpp:ossfs_chmod(1745): Could not change mode for mount point.
```
  根据日志信息定位，挂载点路径不支持通过Chmod变更权限。关于如何修改挂载点的权限，请参见OSS存储卷FAQ。
  说明
  根据错误日志，可在OSS文档ossfs常见问题查询相关解决方法。若未找到相关原因，请提交工单解决。
OSS服务端返回非200错误码
下文以对Bucket中的某个对象进行操作时，都返回错误为例，介绍如何进行问题排查。
```
[INFO]        2023-10-18 06:05:46:/tmp/ossfs/src/curl.cpp:HeadRequest(3014): [tpath=/xxxx]
[INFO]        2023-10-18 06:05:46:/tmp/ossfs/src/curl.cpp:PreHeadRequest(2971): [tpath=/xxxx][bpath=][save=][sseckeypos=-1]
[INFO]        2023-10-18 06:05:46:/tmp/ossfs/src/curl.cpp:prepare_url(4660): URL is http://oss-cn-beijing-internal.aliyuncs.com/<bucket>/<path>/xxxxx
[INFO]        2023-10-18 06:05:46:/tmp/ossfs/src/curl.cpp:prepare_url(4693): URL changed is http://<bucket>.oss-cn-beijing-internal.aliyuncs.com/<path>/xxxxx
[INFO]        2023-10-18 06:05:46:/tmp/ossfs/src/curl.cpp:RequestPerform(2383): HTTP response code 404 was returned, returning ENOENT, Body Text:
```
执行出错的指令，发现退出前打印的OSS服务端的HTTP返回码为404。推断原因为该对象在OSS服务端中不存在。关于出现该现象的原因及对应的解决办法，请参见404错误。
说明
通过错误码及错误原因，可在OSS文档HTTP错误码中查询相关的解决办法。
其他说明
- 如果您的日志等级过高，无法定位问题，并且包含以下需求：
  - 不希望重建OSS存储卷。
  - 担心全局ConfigMap配置影响其他问题，例如，Debug期间可能发生的其他OSS存储卷的挂载或卸载。
  此时，您可以以前台方式挂载ossfs并获取Debug日志进行定位。具体操作，请参见CSI Plugin组件为1.26.6之前的版本问题的处理。
- 如果ossfs容器化后，节点上未默认安装ossfs。
  1. 可以直接通过yum安装，并通过csi-fuse-ossfs-xxxx Pod的spec.container.args字段获取初始启动参数。
  2. 在节点上执行以下命令，生成ossfs挂载时需要的鉴权信息。在Debug之后，请您及时清理该文件。
```
mkdir -p /etc/ossfs && echo "<bucket-name>:<akId>:<akSecret>" > /etc/ossfs/passwd-ossfs && chmod 600 /etc/ossfs/passwd-ossfs
```

排查说明

适用场景1：挂载失败

CSI Plugin组件为1.26.6之前的版本

问题现象

问题原因

解决方案

步骤1：获取原ossfs启动指令

步骤2：前台挂载ossfs并获取Debug日志

步骤3：分析Debug日志

ossfs自身抛错

OSS服务端返回非200错误码

CSI Plugin组件为1.26.6及之后的版本

问题现象

问题原因

解决方案

ossfs自身抛错

OSS服务端返回非200错误码

其他说明

适用场景2：执行POSIX指令抛错

CSI Plugin组件为1.26.6之前的版本

问题现象

问题原因

解决方案

步骤1：获取原ossfs启动指令

步骤2：前台挂载ossfs并获取Debug日志

步骤3：分析Debug日志

ossfs自身抛错

OSS服务端返回非200错误码

CSI Plugin组件为1.26.6及之后的版本

问题现象

问题原因

解决方案

ossfs自身抛错

OSS服务端返回非200错误码

其他说明