ossfs 1.0 クライアントの問題のトラブルシューティング - Container Service for Kubernetes

OSS 永続ボリューム (PV) は、ossfs を使用してマウントされた Filesystem in Userspace (FUSE) ファイルシステムです。デバッグログを分析したり、Pod ログを取得したりすることで、ossfs の問題をトラブルシューティングできます。このトピックでは、一般的な ossfs の問題について説明し、例を挙げて一般的なトラブルシューティング方法を説明します。

トラブルシューティング手順

CSI プラグインのバージョン	ossfs ランタイムモード	トラブルシューティング方法
v1.28 より前のバージョン	ossfs は、アプリケーション Pod が配置されているノードでバックグラウンドプロセスとして実行されます。問題が発生した場合は、前景で ossfs を再マウントする必要があります。	デバッグログの分析
v1.28 から v1.30.4	ossfs は、`kube-system` 名前空間内の Pod のコンテナーとして実行されます。	Pod ログのクエリ
v1.30.4 以降	ossfs は、`ack-csi-fuse` 名前空間内の Pod のコンテナーとして実行されます。	Pod ログのクエリ

重要

ossfs が過剰なログを生成するのを防ぐため、コンテナーランタイムのデフォルトのログレベルは critical または error です。デバッグ中に、デバッグパラメーターを追加してボリュームを再マウントする必要がある場合があります。

シナリオ 1: マウントの失敗

静的にプロビジョニングされた OSS ボリュームのマウントに失敗し、Pod が起動できず、イベントに FailedMount が表示される場合は、まず「OSS ボリュームのマウントに失敗し、アプリケーション Pod イベントに FailedMount が表示される」を参照してクイックチェックを実行してください。

CSI プラグインバージョン 1.26.6 以降

症状

アプリケーション Pod が起動すると、長時間 ContainerCreating 状態のままになります。

原因

まず、ossfs コンテナーが期待どおりに実行されているかどうかを確認します。実行されている場合は、ノードの問題など、他の理由でアプリケーション Pod が ContainerCreating 状態になっていないか確認します。

説明

コマンドの <NODE_NAME> は、影響を受けるアプリケーション Pod が配置されているノードの名前です。
コマンドの <VOLUME_ID> は、通常、アプリケーションの PV の名前です。次の 2 つのシナリオでこの値を取得する必要があります。
- PV 名が PV の `volumeHandle` フィールドの値と異なる場合は、`volumeHandle` フィールドを使用します。次のコマンドを実行して、PV の `volumeHandle` 値を取得します。
```
kubectl get pv <PV_NAME> -o jsonpath='{.spec.csi.volumeHandle}'
```
- PV 名が長すぎる場合、<VOLUME_ID> は "h1." とその SHA-1 値を連結して形成されます。次のコマンドを実行してこの値を取得します。
```
echo -n "<PV_NAME>" | sha1sum | sed 's/^/h1./'
```
  システムが sha1sum 操作をサポートしていない場合は、OpenSSL ライブラリを使用して値を取得することもできます。
```
echo -n "<PV_NAME>" | openssl sha1 -binary | xxd -p -c 40 | sed 's/^/h1./'
```

CSI v1.30.4 以降
```
kubectl -n ack-csi-fuse get pod -l csi.alibabacloud.com/volume-id=<VOLUME_ID> -o wide | grep <NODE_NAME>
```
このバージョンでは ossfs コンテナーにデーモンプロセスが追加されるため、ossfs プロセスが期待どおりに実行されているかどうかに関係なく、期待される出力は同じです。
```
NAME                   READY   STATUS             RESTARTS     AGE
csi-fuse-ossfs-xxxx    1/1     Running            0            5s
```
ossfs コンテナーが `Running` 状態でない場合は、まずその問題をトラブルシューティングします。

v1.30.4 より前の CSI バージョン

kubectl -n kube-system get pod -l csi.alibabacloud.com/volume-id=<VOLUME_ID> -o wide | grep <NODE_NAME>

ossfs コンテナーが期待どおりに実行されていない場合、出力は次のようになります。

NAME                   READY   STATUS             RESTARTS     AGE
csi-fuse-ossfs-xxxx    0/1     CrashLoopBackOff   1 (4s ago)   5s

このイベントの原因: CSI コンポーネントが ossfs コンテナーを起動すると、ossfs は予期せず終了します。この問題は、OSS 接続チェックの失敗 (バケットが存在しない、権限が正しくないなど)、OSS マウントパスが存在しない、読み取りおよび書き込み権限が不十分であるなどの初期化チェックエラーが原因である可能性があります。

ソリューション

ossfs コンテナーのログを取得します。
- CSI v1.30.4 以降の場合
```
kubectl -n ack-csi-fuse logs csi-fuse-ossfs-xxxx 
```
- v1.30.4 より前の CSI バージョンの場合
```
kubectl -n kube-system logs csi-fuse-ossfs-xxxx 
```
  Pod が `CrashLoopBackOff` 状態の場合は、Pod の以前の予期しない終了からログを取得します。
```
kubectl -n kube-system logs -p csi-fuse-ossfs-xxxx 
```
(オプション) ログが空であるか、問題を特定するのに十分な情報が提供されていない場合、ログレベルが高すぎる可能性があります。この場合、次のように必要な構成を追加します。
説明
このメソッドでは、新しいデバッグ PV とそれに対応する永続ボリューム要求 (PVC) を再デプロイする必要はありません。ただし、OSS から REST リクエストの応答を直接取得することはできません。
1. デバッグ用の OSS PV を作成します。元の PV 構成に基づいて、-o dbglevel=debug -o curldbg フィールドに otherOpts を追加します。新しい OSS PV をマウントした後、kubectl logs コマンドを実行して ossfs Pod からデバッグログを取得します。
  重要
  デバッグログは大きくなる可能性があります。この設定はデバッグにのみ使用することをお勧めします。
2. 次の内容を使用して、`kube-system` 名前空間に `csi-plugin` という名前の ConfigMap を作成します。ログレベルを debug に設定します。
  説明
  CSI プラグイン v1.28.2 以前では、ログレベルを `info` にしか設定できません。
```
apiVersion: v1
kind: ConfigMap
metadata:
  name: csi-plugin
  namespace: kube-system
data:
  fuse-ossfs: |
    dbglevel=debug     # ログレベル
```
  アプリケーションが配置されているノードの `csi-plugin` Pod とすべての `csi-provisioner` Pod を再起動して、ConfigMap 構成を適用します。アプリケーション Pod を再起動して再マウントをトリガーし、再マウント後に csi-fuse-ossfs-xxxx Pod が再デプロイされることを確認します。
  重要
  ConfigMap はグローバル構成です。デバッグ後、ConfigMap を削除します。次に、ノード上の `csi-plugin` Pod とすべての `csi-provisioner` Pod を再度再起動して、デバッグログをオフにします。最後に、アプリケーション Pod を再起動して別の再マウントをトリガーし、ossfs が過剰なデバッグログを生成するのを防ぎます。
ossfs コンテナーのログを分析します。
通常、ossfs のエラーは、ossfs 自体からのエラーとリクエスト後に OSS サーバーから返される 200 以外のエラーコードの 2 つのカテゴリに分類されます。各エラータイプの次の例は、一般的なトラブルシューティング方法を示しています。
ossfs 自体からのエラー
```
ossfs: MOUNTPOINT directory /test is not empty. if you are sure this is safe, can use the 'nonempty' mount option.
```
ログメッセージに基づくと、マウントポイントパスが空でないためにエラーが発生します。この問題は、-o nonempty 構成項目を追加することで解決できます。
説明
エラーログに基づいて、ossfs FAQ ドキュメントでソリューションを見つけることができます。原因が見つからない場合は、チケットを送信してください。
OSS サーバーから返された 200 以外のエラーコード
ログを取得します。ossfs が終了する前に、マウントするバケットをチェックします。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 バケットが存在しないためにエラーが発生します。この問題を解決するには、OSS コンソールにログインし、バケットを作成してから、ボリュームを再マウントします。
説明
エラーコードとエラーメッセージを使用して、OSS ドキュメントの HTTP エラーコードトピックでソリューションを見つけることができます。
追加情報
ログレベルの説明
ログレベルが高すぎて問題を特定できず、次の要件がある場合：
- OSS PV を再作成したくない。
- グローバル ConfigMap 構成が、デバッグ中の他の OSS PV のマウントやアンマウントなど、他の操作に影響を与える可能性があることを懸念している。
この場合、ossfs を前景でマウントし、デバッグログを取得して問題を特定できます。具体的な手順については、CSI プラグインバージョン 1.26.6 より前のソリューションをご参照ください。
重要
ossfs がコンテナー化された後、デフォルトではノードにインストールされません。手動でインストールする ossfs のバージョンは、Pod で実行されているバージョンと異なる場合があります。まず、PV マウントパラメーターまたはグローバル ConfigMap 構成を変更して、上記で説明したソリューションを試すことをお勧めします。
ossfs をマウントするには、次の手順を実行します。
1. 最新バージョンの ossfs をインストールします。
2. ノードで、次のコマンドを実行して PV 名の SHA-256 値を取得します。
```
echo -n "<PV_NAME>" | sha256sum
```
  システムが `sha256sum` 操作をサポートしていない場合は、OpenSSL ライブラリを使用して値を取得することもできます。
```
echo -n "<PV_NAME>" | openssl sha256 -binary | xxd -p -c 256
```
  `pv-oss` の場合、期待される出力は次のとおりです。
```
8f3e75e1af90a7dcc66882ec1544cb5c7c32c82c2b56b25a821ac77cea60a928
```
3. ノードで、次のコマンドを実行して ossfs マウントパラメーターを取得します。
```
ps -aux | grep <sha256-value>
```
  出力には ossfs のプロセスレコードが含まれています。
4. ノードで、次のコマンドを実行して ossfs のマウントに必要な認証情報を生成します。デバッグ後、このファイルを速やかに削除してください。
```
mkdir -p /etc/ossfs && echo "<bucket-name>:<akId>:<akSecret>" > /etc/ossfs/passwd-ossfs && chmod 600 /etc/ossfs/passwd-ossfs
```
セグメンテーション違反のトラブルシューティング
エラーログに "ossfs exited with error" err="signal: segmentation fault (core dumped) " が含まれている場合、ランタイム中にセグメンテーション違反が原因で ossfs プロセスが予期せず終了したことを示します。
技術サポートが問題を特定できるように、ログインノードにログインし、以下の手順に従ってコアダンプファイルを取得してから、チケットを送信してください。
1. ossfs プロセスのクラッシュレコードを見つけます。
```
coredumpctl list
```
  期待される出力:
```
TIME                          PID       UID   GID  SIG   COREFILE   EXE
Mon 2025-11-17 11:21:44 CST   2108767   0     0    1     present    /usr/bin/xxx
Tue 2025-11-18 19:35:58 CST   493791    0     0    1     present    /usr/local/bin/ossfs
```
  上記の出力は、このノード上の 2 つのプロセスがセグメンテーション違反のために終了したことを示しています。
  時間 (TIME) とプロセス名 (EXE) に基づいてトラブルシューティングするレコードを見つけ、その PID をメモします。上記の例では、PID は 493791 です。
2. コアダンプファイルをエクスポートします。前のステップの PID を使用して、次のコマンドを実行してコアファイルをエクスポートします。--output パラメーターは、生成されるファイルの名前を指定します。
```
# <PID> を実際の PID に置き換えます
coredumpctl dump <PID> --output ossfs.dump
```
3. チケットを送信し、生成された ossfs.dump ファイルを提供してください。

CSI プラグインバージョン 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 バケットの名前。
- <PATH>: マウントされた OSS バケットのパス。
- <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 接続チェックの失敗 (バケットが存在しない、権限が正しくないなど)、マウントパスが存在しない、読み取りおよび書き込み権限が不十分であるなどの初期化チェックエラーが原因である可能性があります。

ソリューション

ステップ 1: 元の ossfs 起動コマンドの取得

`FailedMount` イベントをチェックして、マウント失敗からの出力を表示します。詳細については、「シナリオ 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` では、systemd-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 を前景でマウントし、デバッグログを取得する

デフォルトでは、マウントコマンドを実行したユーザーのみが ossfs によってマウントされたディレクトリにアクセスできます。他のユーザーはディレクトリにアクセスできません。したがって、元のコマンドに -o allow_other 構成項目が含まれていない場合、ルートマウントパスで権限の問題が発生する可能性があります。

マウントポイントパスの権限の問題が存在するかどうかを確認します。
権限の問題が存在する場合は、PV を作成するときに -o allow_other 構成項目を追加します。ossfs マウントポイントのアクセス権限を構成する方法の詳細については、「バケットのマウント」をご参照ください。構成項目を追加する方法の詳細については、「静的にプロビジョニングされた ossfs 1.0 ボリュームの使用」をご参照ください。

アプリケーション Pod が配置されているノードで次のコマンドを実行して、ossfs を前景で実行し、ログモードをデバッグに設定します。

このコマンドでは、/test はテストマウントポイントパスです。前景で実行される ossfs プロセスは、OSS バケットを /test にマウントします。

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

パラメーター	説明
-f	ossfs をデーモンプロセスとしてではなく、前景で実行します。前景モードでは、ログは端末画面に出力されます。このパラメーターは通常、デバッグに使用されます。
-o allow_other	コンピューター上の他のユーザーに、マウントされたディレクトリへのアクセス権限を付与します。これにより、ossfs を前景でマウントする際の新しいマウントポイントパスの権限の問題を防ぎます。
-o dbglevel=debug	ossfs のログレベルをデバッグに設定します。
-o curldbg	libcurl のログを有効にして、OSS サーバーから返されたエラーをトラブルシューティングします。

ステップ 3: デバッグログの分析

ossfs を前景で実行すると、ログが端末に出力されます。通常、ossfs のエラーは、ossfs 自体からのエラーとリクエスト後に OSS サーバーから返される 200 以外のエラーコードの 2 つのカテゴリに分類されます。各エラータイプの次の例は、一般的なトラブルシューティング方法を示しています。

次の例は、マウント失敗中に 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 FAQ トピックでソリューションを見つけることができます。原因が見つからない場合は、チケットを送信してください。

OSS サーバーから返された 200 以外のエラーコード

ログを確認します。OSS サーバーから返され、ossfs が終了する前に出力されるエラーコードは 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 バケットが存在しないためにエラーが発生します。この問題を解決するには、OSS コンソールにログインし、バケットを作成してから、ボリュームを再マウントします。

説明

エラーコードとエラーメッセージを使用して、OSS ドキュメントの HTTP エラーコードトピックでソリューションを見つけることができます。

シナリオ 2: POSIX コマンド実行時のエラー

CSI プラグインバージョン 1.26.6 以降

症状

アプリケーション Pod は `Running` 状態ですが、読み取りまたは書き込みコマンドなどの POSIX コマンドが実行されると、ossfs はエラーを報告します。

原因

ossfs コンテナーが期待どおりに実行されているかどうかを確認します。
説明
- コマンドの <NODE_NAME> は、影響を受けるアプリケーション Pod が配置されているノードの名前です。
- コマンドの <VOLUME_ID> は、通常、アプリケーションの PV の名前です。次の 2 つのシナリオでこの値を取得する必要があります。
  - PV 名が PV の `volumeHandle` フィールドの値と異なる場合は、`volumeHandle` フィールドを使用します。次のコマンドを実行して、PV の `volumeHandle` 値を取得します。
    kubectl get pv <PV_NAME> -o jsonpath='{.spec.csi.volumeHandle}'
  - PV 名が長すぎる場合、<VOLUME_ID> は "h1." とその SHA-1 値を連結して形成されます。次のコマンドを実行してこの値を取得します。
    echo -n "<PV_NAME>" | sha1sum | sed 's/^/h1./'
    システムが sha1sum 操作をサポートしていない場合は、OpenSSL ライブラリを使用して値を取得することもできます。
    echo -n "<PV_NAME>" | openssl sha1 -binary | xxd -p -c 40 | sed 's/^/h1./'
- CSI v1.30.4 以降
```
kubectl -n ack-csi-fuse get pod -l csi.alibabacloud.com/volume-id=<VOLUME_ID> -o wide | grep <NODE_NAME>
```
  このバージョンでは ossfs コンテナーにデーモンプロセスが追加されるため、ossfs プロセスが期待どおりに実行されているかどうかに関係なく、期待される出力は同じです。
```
NAME                   READY   STATUS             RESTARTS     AGE
csi-fuse-ossfs-xxxx    1/1     Running            0            5s
```
  ossfs コンテナーが `Running` 状態でない場合は、まずその問題をトラブルシューティングします。
- v1.30.4 より前の CSI バージョン
```
kubectl -n kube-system get pod -l csi.alibabacloud.com/volume-id=<VOLUME_ID> -o wide | grep <NODE_NAME>
```
  ossfs コンテナーが期待どおりに実行されていない場合、出力は次のようになります。
```
NAME                   READY   STATUS             RESTARTS     AGE
csi-fuse-ossfs-xxxx    0/1     CrashLoopBackOff   1 (4s ago)   5s
```
アプリケーションログをチェックして、エラーの原因となったコマンドと返されたエラータイプを確認します。たとえば、chmod -R 777 /mnt/path コマンドを実行すると、I/O error が返されます。

このイベントの原因: CSI コンポーネントが ossfs コンテナーを起動した後、ossfs Pod は期待どおりに実行され、OSS バケットをアプリケーション Pod が配置されているノードの指定されたマウントポイントパスにマウントします。ただし、`chmod`、`read`、`open` などの POSIX コマンドが実行されると、ossfs は異常に実行され、エラーを返し、対応するエラーをログに出力します。

ソリューション

ossfs コンテナーのログを取得します。
- CSI v1.30.4 以降の場合
```
kubectl -n ack-csi-fuse logs csi-fuse-ossfs-xxxx 
```
- v1.30.4 より前の CSI バージョンの場合
```
kubectl -n kube-system logs csi-fuse-ossfs-xxxx 
```
  Pod が `CrashLoopBackOff` 状態の場合は、Pod の以前の予期しない終了からログを取得します。
```
kubectl -n kube-system logs -p csi-fuse-ossfs-xxxx 
```
(オプション) ログが空であるか、問題を特定するのに十分な情報が提供されていない場合、ログレベルが高すぎる可能性があります。この場合、次のように必要な構成を追加します。
説明
このメソッドでは、新しいデバッグ PV とそれに対応する永続ボリューム要求 (PVC) を再デプロイする必要はありません。ただし、OSS から REST リクエストの応答を直接取得することはできません。
1. デバッグ用の OSS PV を作成します。元の PV 構成に基づいて、-o dbglevel=debug -o curldbg フィールドに otherOpts を追加します。新しい OSS PV をマウントした後、kubectl logs コマンドを実行して ossfs Pod からデバッグログを取得します。
  重要
  デバッグログは大きくなる可能性があります。この設定はデバッグにのみ使用することをお勧めします。
2. 次の内容を使用して、`kube-system` 名前空間に `csi-plugin` という名前の ConfigMap を作成します。ログレベルを debug に設定します。
  説明
  CSI プラグイン v1.28.2 以前では、ログレベルを `info` にしか設定できません。
```
apiVersion: v1
kind: ConfigMap
metadata:
  name: csi-plugin
  namespace: kube-system
data:
  fuse-ossfs: |
    dbglevel=debug     # ログレベル
```
  アプリケーションが配置されているノードの `csi-plugin` Pod とすべての `csi-provisioner` Pod を再起動して、ConfigMap 構成を適用します。アプリケーション Pod を再起動して再マウントをトリガーし、再マウント後に csi-fuse-ossfs-xxxx Pod が再デプロイされることを確認します。
  重要
  ConfigMap はグローバル構成です。デバッグ後、ConfigMap を削除します。次に、ノード上の `csi-plugin` Pod とすべての `csi-provisioner` Pod を再度再起動して、デバッグログをオフにします。最後に、アプリケーション Pod を再起動して別の再マウントをトリガーし、ossfs が過剰なデバッグログを生成するのを防ぎます。
ossfs コンテナーのログを分析します。
通常、ossfs のエラーは、ossfs 自体からのエラーとリクエスト後に OSS サーバーから返される 200 以外のエラーコードの 2 つのカテゴリに分類されます。各エラータイプの次の例は、一般的なトラブルシューティング方法を示しています。
ossfs 自体からのエラー
このセクションでは、chmod -R 777 <mount_point_path_in_application_pod> コマンドを実行したときに発生するエラーを例として、問題のトラブルシューティング方法を示します。
1. ossfs のテストマウントパスが /test の場合は、次のコマンドを実行します。
```
chmod -R 777 /test
```
  ログを確認すると、/test マウントポイントパス内のファイルに対する `chmod` 操作は成功しますが、/test 自体に対する `chmod` 操作では次のエラーログが生成されます。
```
[ERROR]  2023-10-18 06:03:24:/tmp/ossfs/src/ossfs.cpp:ossfs_chmod(1745): Could not change mode for mount point.
```
  ログメッセージに基づくと、`chmod` を使用してマウントポイントパスの権限を変更することはできません。マウントポイントの権限を変更する方法の詳細については、「ossfs 1.0 ボリューム FAQ」をご参照ください。
  説明
  エラーログに基づいて、OSS ドキュメントの ossfs FAQ トピックでソリューションを見つけることができます。原因が見つからない場合は、チケットを送信してください。
OSS サーバーから返された 200 以外のエラーコード
次の例は、バケット内のオブジェクトに対するすべての操作でエラーが返される問題のトラブルシューティング方法を示しています。
```
[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 PV を再作成したくない。
- グローバル ConfigMap 構成が、デバッグ中の他の OSS PV のマウントやアンマウントなど、他の操作に影響を与える可能性があることを懸念している。
この場合、ossfs を前景でマウントし、デバッグログを取得して問題を特定できます。具体的な手順については、CSI プラグインバージョン 1.26.6 より前のソリューションをご参照ください。
重要
ossfs がコンテナー化された後、デフォルトではノードにインストールされません。手動でインストールする ossfs のバージョンは、Pod で実行されているバージョンと異なる場合があります。まず、PV マウントパラメーターまたはグローバル ConfigMap 構成を変更して、上記で説明したソリューションを試すことをお勧めします。
ossfs をマウントするには、次の手順を実行します。
1. 最新バージョンの ossfs をインストールします。
2. ノードで、次のコマンドを実行して PV 名の SHA-256 値を取得します。
```
echo -n "<PV_NAME>" | sha256sum
```
  システムが `sha256sum` 操作をサポートしていない場合は、OpenSSL ライブラリを使用して値を取得することもできます。
```
echo -n "<PV_NAME>" | openssl sha256 -binary | xxd -p -c 256
```
  `pv-oss` の場合、期待される出力は次のとおりです。
```
8f3e75e1af90a7dcc66882ec1544cb5c7c32c82c2b56b25a821ac77cea60a928
```
3. ノードで、次のコマンドを実行して ossfs マウントパラメーターを取得します。
```
ps -aux | grep <sha256-value>
```
  出力には ossfs のプロセスレコードが含まれています。
4. ノードで、次のコマンドを実行して ossfs のマウントに必要な認証情報を生成します。デバッグ後、このファイルを速やかに削除してください。
```
mkdir -p /etc/ossfs && echo "<bucket-name>:<akId>:<akSecret>" > /etc/ossfs/passwd-ossfs && chmod 600 /etc/ossfs/passwd-ossfs
```
セグメンテーション違反のトラブルシューティング
エラーログに "ossfs exited with error" err="signal: segmentation fault (core dumped) " が含まれている場合、ランタイム中にセグメンテーション違反が原因で ossfs プロセスが予期せず終了したことを示します。
技術サポートが問題を特定できるように、ログインノードにログインし、以下の手順に従ってコアダンプファイルを取得してから、チケットを送信してください。
1. ossfs プロセスのクラッシュレコードを見つけます。
```
coredumpctl list
```
  期待される出力:
```
TIME                          PID       UID   GID  SIG   COREFILE   EXE
Mon 2025-11-17 11:21:44 CST   2108767   0     0    1     present    /usr/bin/xxx
Tue 2025-11-18 19:35:58 CST   493791    0     0    1     present    /usr/local/bin/ossfs
```
  上記の出力は、このノード上の 2 つのプロセスがセグメンテーション違反のために終了したことを示しています。
  時間 (TIME) とプロセス名 (EXE) に基づいてトラブルシューティングするレコードを見つけ、その PID をメモします。上記の例では、PID は 493791 です。
2. コアダンプファイルをエクスポートします。前のステップの PID を使用して、次のコマンドを実行してコアファイルをエクスポートします。--output パラメーターは、生成されるファイルの名前を指定します。
```
# <PID> を実際の PID に置き換えます
coredumpctl dump <PID> --output ossfs.dump
```
3. チケットを送信し、生成された ossfs.dump ファイルを提供してください。

CSI プラグインバージョン 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 プロセスが期待どおりに実行され、OSS バケットをアプリケーション Pod が配置されているノードの指定されたマウントポイントパスにマウントするために発生します。ただし、chmod、read、または open などの POSIX コマンドが実行されると、ossfs は異常に実行され、エラーを返します。

ソリューション

ステップ 1: 元の ossfs 起動コマンドの取得

ossfs はすでにノードで実行されているため、アプリケーション Pod が配置されているノードで次のコマンドを実行して、OSS ボリューム名を使用して元の 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 を前景でマウントし、デバッグログを取得する

マウントポイントパスの権限の問題が存在するかどうかを確認します。
権限の問題が存在する場合は、PV を作成するときに -o allow_other 構成項目を追加します。ossfs マウントポイントのアクセス権限を構成する方法の詳細については、「バケットのマウント」をご参照ください。構成項目を追加する方法の詳細については、「静的にプロビジョニングされた ossfs 1.0 ボリュームの使用」をご参照ください。

アプリケーション Pod が配置されているノードで次のコマンドを実行して、ossfs を前景で実行し、ログモードをデバッグに設定します。

このコマンドでは、/test はテストマウントポイントパスです。前景で実行される ossfs プロセスは、OSS バケットを /test にマウントします。

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

パラメーター	説明
-f	ossfs をデーモンプロセスとしてではなく、前景で実行します。前景モードでは、ログは端末画面に出力されます。このパラメーターは通常、デバッグに使用されます。
-o allow_other	コンピューター上の他のユーザーに、マウントされたディレクトリへのアクセス権限を付与します。これにより、ossfs を前景でマウントする際の新しいマウントポイントパスの権限の問題を防ぎます。
-o dbglevel=debug	ossfs のログレベルをデバッグに設定します。
-o curldbg	libcurl のログを有効にして、OSS サーバーから返されたエラーをトラブルシューティングします。

ステップ 3: デバッグログの分析

POSIX コマンドが失敗した場合は、別の端末を開いてコマンドを再実行し、新しい ossfs ログを分析する必要があります。

ossfs 自体からのエラー

次の例では、chmod -R 777 <mount_point_path_in_application_pod> コマンドを実行したときに発生するエラーのトラブルシューティング方法について説明します。

テスト ossfs プロセスは /test パスにマウントされているため、コマンドは次のようになります。

chmod -R 777 /test

ログをクエリできます。/test マウントポイントパス内のファイルに対する `chmod` 操作は成功します。ただし、/test 自体に対する `chmod` 操作では、次のエラーログが生成されます。

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

ログメッセージに基づくと、`chmod` を使用してマウントポイントパスの権限を変更することはできません。マウントポイントの権限を変更する方法の詳細については、「ossfs 1.0 ボリューム FAQ」をご参照ください。

説明

OSS サーバーから返された 200 以外のエラーコード

次の例では、バケット内のオブジェクトに対して操作を実行するときにサーバーがエラーを返す問題をトラブルシューティングする方法について説明します。

[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 エラーコード」Topic でソリューションを見つけることができます。

トラブルシューティング手順

シナリオ 1: マウントの失敗

CSI プラグインバージョン 1.26.6 以降

症状

原因

ソリューション

ossfs 自体からのエラー

OSS サーバーから返された 200 以外のエラーコード

追加情報

ログレベルの説明

セグメンテーション違反のトラブルシューティング

CSI プラグインバージョン 1.26.6 以前

症状

原因

ソリューション

ステップ 1: 元の ossfs 起動コマンドの取得

ステップ 2: ossfs を前景でマウントし、デバッグログを取得する

ステップ 3: デバッグログの分析

ossfs 自体からのエラー

OSS サーバーから返された 200 以外のエラーコード

シナリオ 2: POSIX コマンド実行時のエラー

CSI プラグインバージョン 1.26.6 以降

症状

原因

ソリューション

ossfs 自体からのエラー

OSS サーバーから返された 200 以外のエラーコード

追加情報

ログレベルの説明

セグメンテーション違反のトラブルシューティング

CSI プラグインバージョン 1.26.6 以前

症状

原因

ソリューション

ステップ 1: 元の ossfs 起動コマンドの取得

ステップ 2: ossfs を前景でマウントし、デバッグログを取得する

ステップ 3: デバッグログの分析

ossfs 自体からのエラー

OSS サーバーから返された 200 以外のエラーコード