JindoFuse による OSS-HDFS のローカルファイルシステムとしてのマウント - OSS

JindoFuse は、OSS-HDFS をローカルディレクトリとしてマウントし、POSIX 互換のインターフェイスを介して公開します。Hadoop ジョブ、Spark パイプライン、AI トレーニングワークロードなど、標準のファイルシステムコールに依存するアプリケーションは、コードを変更することなく OSS-HDFS への読み書きができます。

利用シーン

AI と機械学習：OSS-HDFS をトレーニングノードにマウントし、ローカルファイルシステムのパスを介して直接データセットをロードしたり、モデルのチェックポイントを保存したりします。
ビッグデータ分析：標準の HDFS API 呼び出しを使用して、OSS-HDFS に対して Hadoop および Spark ジョブを実行します。
POSIX アプリケーションの移行：ローカルファイルシステムのセマンティクスに依存するワークロードを、アプリケーションコードを変更せずに OSS-HDFS に移行します。

制限事項

JindoFuse は幅広い POSIX カバー率を提供しますが、一部の動作はローカルファイルシステムとは異なります。

シンボリックリンク：OSS-HDFS でのみ利用可能です。キャッシュアクセラレーションはサポートしていません。

サポートされているすべての POSIX 操作については、「付録1：サポートされる操作」をご参照ください。

前提条件

開始する前に、次のことを確認してください。

ご利用のバケットで OSS-HDFS が有効になっており、必要なアクセス権限が付与されていること。詳細については、「OSS-HDFS の有効化」をご参照ください。
次のいずれかの環境が準備できていること。
- Alibaba Cloud EMR クラスター (バージョン 3.44.0 以降、または 5.10.0 以降)：JindoFuse はプリインストール済みです。詳細については、「クラスターの作成」をご参照ください。
- EMR 以外の環境：JindoSDK 4.6.2 以降がインストールおよびデプロイされていること。詳細については、「EMR 以外の環境での JindoSDK のデプロイ」をご参照ください。

JindoFuse の設定 (EMR 以外の環境のみ)

EMR クラスターをご利用の場合は、このセクションをスキップしてください。EMR クラスターには JindoFuse がプリインストールおよび設定済みです。

ECS インスタンスに接続します。詳細については、「インスタンスに接続する」をご参照ください。
以下の環境変数を設定します。x.x.x をご使用の JindoSDK バージョン番号に置き換えてください。
```
   export JINDOSDK_HOME=/root/jindosdk-x.x.x
   export HADOOP_CLASSPATH=`hadoop classpath`:${JINDOSDK_HOME}/lib/*
   export JINDOSDK_CONF_DIR=/root/jindosdk-x.x.x/conf
   export PATH=$PATH:$JINDOSDK_HOME/bin
   export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${JINDOSDK_HOME}/lib/native
```
この例では、JindoSDK が /root/jindosdk-x.x.x にインストールされていることを前提としています。実際のインストールディレクトリに合わせてパスを調整してください。

JindoSDK のインストール先の conf/ ディレクトリに、jindosdk.cfg という名前の構成ファイルを作成し、以下の内容を追加します：

プレースホルダー	説明	例
`<region-id>`	ご利用の OSS-HDFS バケットが配置されているリージョン	`cn-hangzhou`
`<your-access-key-id>`	ご利用の AccessKey ID	`LTAI****************`
`<your-access-key-secret>`	ご利用の AccessKey Secret	—

   [common]
   logger.dir = /tmp/fuse-log

   [jindosdk]
   fs.oss.endpoint = <region-id>.oss-dls.aliyuncs.com
   fs.oss.accessKeyId = <your-access-key-id>
   fs.oss.accessKeySecret = <your-access-key-secret>

プレースホルダーを実際の値に置き換えてください。

OSS-HDFS のマウント

マウントポイントとして使用するローカルディレクトリを作成します。
```
   mkdir -p <mount-point>
```

OSS-HDFS をマウントします。

パラメーター	説明	例
`<mount-point>`	OSS-HDFS がマウントされるローカルディレクトリ	`/mnt/oss`
`-ouri`	マップする dls パス。バケットのルートまたはサブディレクトリを使用します。	`-ouri=oss://examplebucket.cn-hangzhou.oss-dls.aliyuncs.com/`

   jindo-fuse <mount-point> -ouri=<oss-path>

コマンドを実行すると、デーモンプロセスがバックグラウンドで指定された OSS-HDFS パスをローカルのマウントポイントにマウントします。追加のマウントオプションについては、「付録2：マウントオプション」をご参照ください。

JindoFuse プロセスが実行中であることを確認して、マウントを検証します。
```
   ps -ef | grep jindo-fuse
```
期待される出力：
```
   root      2162     1  0 13:21 ?        00:00:00 jindo-fuse <mount-point> -ouri=[<oss-path>]
   root      2714  2640  0 13:39 pts/0    00:00:00 grep --color=auto jindo-fuse
```
最初の行が表示されれば、OSS-HDFS は正常にマウントされています。

ファイルの読み書き

マウント後、標準のファイルシステムコマンドを使用して、マウントポイント経由で OSS-HDFS と対話します。

# ディレクトリを作成
mkdir /mnt/oss/dir1

# ディレクトリの内容を一覧表示
ls /mnt/oss/

# ファイルを書き込む
echo "hello world" > /mnt/oss/dir1/hello.txt

# ファイルを読み取る
cat /mnt/oss/dir1/hello.txt

# ディレクトリを削除
rm -rf /mnt/oss/dir1/

OSS-HDFS のアンマウント

次のいずれかの方法を選択します。

手動アンマウント: umount <mount-point> を実行します。
プロセス終了時の自動アンマウント: マウント時に -oauto_unmount オプションを指定します。killall -9 jindo-fuse が JindoFuse プロセスに SIGINT を送信すると、プロセス終了前に OSS-HDFS が自動的にアンマウントされます。

トラブルシューティング

JindoFuse での I/O エラー

JindoFuse でエラーが発生すると、オペレーティングシステムは次のような一般的なメッセージを返します。

ls: /mnt/oss/: Input/output error

根本原因を特定するには、jindosdk.log を、logger.dir 設定項目で指定されたディレクトリ内で確認してください。

一般的な原因は、認証または接続性の問題です。次のようなエラーを探してください。

EMMDD HH:mm:ss jindofs_connectivity.cpp:13] Please check your Endpoint/Bucket/RoleArn.
Failed test connectivity, operation: mkdir, errMsg: [RequestId]: 618B8183343EA53531C62B74 [HostId]: oss-cn-shanghai-internal.aliyuncs.com [ErrorMessage]: [E1010]HTTP/1.1 403 Forbidden ...

このエラーが表示された場合は、エンドポイント、バケット名、およびロール ARN が正しく設定されていることを確認してください。詳細については、「EMR 以外のクラスターから OSS-HDFS への接続」をご参照ください。

その他のエラーについては、チケットを送信してください。

付録1：サポートされる操作

JindoFuse では、以下の POSIX ベースの操作がサポートされています。

操作	説明
`getattr()`	オブジェクト属性を照会します (`ls` に相当)
`mkdir()`	`mkdir`ディレクトリを作成します (`mkdir` に相当)
`rmdir()`	`rm -rf`ディレクトリを削除します (`rm -rf` に相当)
`unlink()`	`unlink`オブジェクトを削除します (`unlink` に相当)
`rename()`	`mv`オブジェクトまたはディレクトリの名前を変更します (`mv` に相当)
`read()`	データをシーケンシャルに読み取ります
`pread()`	ランダムオフセットでデータを読み取ります
`write()`	データをシーケンシャルに書き込みます
`pwrite()`	ランダムオフセットでデータを書き込みます
`flush()`	データをメモリからカーネルキャッシュにフラッシュします
`fsync()`	データをメモリからディスクにフラッシュします
`release()`	オブジェクトを閉じます
`readdir()`	ディレクトリを読み取ります
`create()`	オブジェクトを作成します
`open() O_APPEND`	オブジェクトを追加モードで開きます
`open() O_TRUNC`	オブジェクトを上書きモードで開きます
`ftruncate()`	開いているオブジェクトを切り詰めます
`truncate()`	`truncate -s`閉じているオブジェクトを切り詰めます (`truncate -s` に相当)
`lseek()`	開いているオブジェクトの読み書き位置を設定します
`chmod()`	オブジェクトの権限を変更します（`chmod` と同等）
`access()`	オブジェクトの権限を照会します
`utimes()`	オブジェクトのアクセスおよび変更タイムスタンプを変更します
`setxattr()`	オブジェクトに拡張属性を設定します
`getxattr()`	オブジェクトの拡張属性を取得します
`listxattr()`	オブジェクトの拡張属性を一覧表示します
`removexattr()`	オブジェクトから拡張属性を削除します
`lock()`	`fcntl`POSIX ロックをサポートします (`fcntl` に相当)
`fallocate()`	オブジェクトの物理空間を事前に割り当てます
`symlink()`	シンボリックリンクを作成します (OSS-HDFS のみ、キャッシュアクセラレーションはサポートしていません)
`readlink()`	シンボリックリンクを読み取ります

付録2：マウントオプション

uri を除くすべてのオプションは任意です。オプションは -o プレフィックスを使用して指定します（例： -oauto_unmount）。

オプション	説明	デフォルト	例
`uri`	マップする dls パス。バケットのルートまたはサブディレクトリを使用します。	必須	`-ouri=oss://examplebucket.cn-beijing.oss-dls.aliyuncs.com/`
`f`	JindoFuse プロセスを開始します。デフォルトでは、デーモンプロセスを使用して JindoFuse プロセスをバックグラウンドで開始します。このオプションを使用する場合は、ターミナルログを有効にすることを推奨します。	デーモン (バックグラウンド)	`-f`
`d`	デバッグモードを有効にし、JindoFuse をフォアグラウンドで実行します。このオプションを使用する場合は、ターミナルログを有効にしてください。	—	`-d`
`auto_unmount`	JindoFuse プロセスが終了したときに、マウントポイントを自動的にアンマウントします。	—	`-oauto_unmount`
`ro`	OSS-HDFS を読み取り専用モードでマウントします。書き込み操作は無効になります。	—	`-oro`
`direct_io`	オブジェクトの読み書きでページキャッシュをバイパスします。	—	`-odirect_io`
`kernel_cache`	カーネルキャッシュを使用して読み取りパフォーマンスを最適化します。	—	`-okernel_cache`
`auto_cache`	自動キャッシュを有効にします。`kernel_cache` とは異なり、このオプションはオブジェクトのサイズまたは変更時間が変更されると、キャッシュを自動的にフラッシュします。	—	`-oauto_cache`
`entry_timeout`	`0`読み取り時にオブジェクト名をキャッシュする時間 (秒単位)。無効にするには `0` に設定します。	`0.1`	`-oentry_timeout=60`
`attr_timeout`	オブジェクト属性をキャッシュする期間（秒単位）。`0` に設定すると無効になります。	`0.1`	`-oattr_timeout=60`
`negative_timeout`	`0`読み取りが失敗したときにオブジェクト名をキャッシュする時間 (秒単位)。無効にするには `0` に設定します。	`0.1`	`-onegative_timeout=0`
`jindo_entry_size`	キャッシュするディレクトリの数。`readdir` のパフォーマンスを向上させます。`0` に設定すると無効になります。	`5000`	`-ojindo_entry_size=5000`
`jindo_attr_size`	キャッシュするオブジェクト属性エントリの数。`getattr` のパフォーマンスを向上させます。`0` に設定すると無効になります。	`50000`	`-ojindo_attr_size=50000`
`max_idle_threads`	アイドルスレッドの最大数。	`10`	`-omax_idle_threads=10`
`metrics_port`	`http://localhost:9090/brpc_metrics`メトリックを提供するための HTTP ポート (例：`http://localhost:9090/brpc_metrics`)。	`9090`	`-ometrics_port=9090`
`enable_pread`	オブジェクトの読み取りには、`pread` 操作を使用します。	—	`-oenable_pread`

付録3：設定項目

これらの項目を jindosdk.cfg で設定します。

項目	セクション	説明	デフォルト値
`logger.dir`	`[common]`	ログが保存されるディレクトリ	`/tmp/jindodata-log`
`logger.sync`	`[common]`	ログの書き込みモード。`true`：同期。`false`：非同期。	`false`
`logger.consolelogger`	`[common]`	ログをコンソールに出力するかどうか。	`false`
`logger.level`	`[common]`	出力する最小ログレベル。ターミナルログが有効な場合 (`logger.consolelogger = true`)、有効な値は `0` (TRACE)、`1` (DEBUG)、`2` (INFO)、`3` (WARN)、`4` (ERROR)、`5` (CRITICAL)、`6` (OFF) です。ターミナルログが無効な場合、値が `1` 以下であれば WARN レベルのログが出力され、`1` より大きい場合は INFO レベルのログが出力されます。	`2` (INFO)
`logger.verbose`	`[common]`	出力する最小詳細ログレベル。有効な値： `0`～`99`。`0` は詳細ログを無効にします。	`0`
`logger.cleaner.enable`	`[common]`	ログの自動クリーンアップを有効にするかどうか。	`false`
`fs.oss.endpoint`	`[jindosdk]`	OSS-HDFS へのアクセスに使用するエンドポイント。例： `cn-hangzhou.oss-dls.aliyuncs.com`。	—
`fs.oss.accessKeyId`	`[jindosdk]`	OSS-HDFS へのアクセスに使用する AccessKey ID。	—
`fs.oss.accessKeySecret`	`[jindosdk]`	OSS-HDFS へのアクセスに使用する AccessKey シークレット。	—