JindoFuse を使用した OSS-HDFS のマウントとアクセス - Object Storage Service

JindoFuse を使用すると、OSS-HDFS をローカルファイルシステムにマッピングし、標準の HDFS API を呼び出して OSS-HDFS 内のオブジェクトにアクセスし、オブジェクトの読み取り、書き込み、削除などの操作を実行できます。JindoFuse は、オープンソースの分散ファイルシステムへのアクセスを可能にする、POSIX 互換のツールです。JindoFuse を使用すると、AI アプリケーションはデータストレージと処理に OSS-HDFS を直接利用できます。

前提条件

バケットに対して OSS-HDFS が有効化され、OSS-HDFS へのアクセス権が付与されていること。詳細については、「OSS-HDFS の有効化」をご参照ください。

事前準備

以下のいずれかの方法で OSS-HDFS にアクセスできます。

Alibaba Cloud E-MapReduce (EMR) クラスターを使用して OSS-HDFS にアクセスする場合、バージョンが 3.44.0 以降または 5.10.0 以降の EMR クラスターが作成されていることを確認してください。これらの要件を満たす EMR クラスターには、デフォルトで JindoFuse が統合されています。詳細については、「クラスターの作成」をご参照ください。
Alibaba Cloud EMR クラスターを使用せずに OSS-HDFS にアクセスする場合、JindoSDK 4.6.2 以降がインストールおよびデプロイされていることを確認してください。詳細については、「EMR 以外のクラスターでの JindoSDK のデプロイ」をご参照ください。

操作手順

環境変数の設定
- Alibaba Cloud EMR クラスターを使用して OSS-HDFS にアクセスする場合は、この手順をスキップして手順 2 に進んでください。
- Alibaba Cloud EMR クラスターを使用せずに OSS-HDFS にアクセスする場合は、次の手順で JindoFuse を設定します。
  1. ECS インスタンスに接続します。詳細については、「ECS インスタンスへの接続」をご参照ください。
  2. 環境変数の変更
    この例では、jindosdk-x.x.x は root/ パスにインストールされています。x.x.x は JindoSDK のバージョン番号を示します。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
```
  3. 設定ファイルの設定
    1. JindoSDK の conf/ ディレクトリに jindosdk.cfg という名前の設定ファイルを作成します。
    2. jindosdk.cfg 設定ファイルに以下の設定項目を追加します：
```
[common]
logger.dir = /tmp/fuse-log

[jindosdk]
# 次の例では、中国 (杭州) リージョンを使用しています。実際のリージョンに置き換えてください。
fs.oss.endpoint = cn-hangzhou.oss-dls.aliyuncs.com
# OSS-HDFS にアクセスするための AccessKey ID と AccessKey Secret を設定します。
fs.oss.accessKeyId = LTAI****************    
fs.oss.accessKeySecret = yourAccessKeySecret
```
OSS-HDFS のマウント
1. 次のコマンドを実行してマウントポイントを作成します：
```
mkdir -p <mount-point>
```
2. 次のコマンドを実行して OSS-HDFS をマウントします：
```
jindo-fuse <mount_point> -ouri=[<oss_path>]
```
  -ouri には、マッピングする dls パスを設定する必要があります。このパスは、バケットのルートディレクトリまたはサブディレクトリにすることができます。コマンドを実行すると、バックグラウンドでデーモンプロセスが起動し、指定した <oss_path> をローカルファイルシステムのマウントポイントにマウントします。マウントポイントは <mount_point> で指定されます。
  OSS-HDFS をマウントする際に設定できるマウントオプションの詳細については、「付録2：マウントオプション」をご参照ください。
3. 次のコマンドを実行して、OSS-HDFS がマウントされているかどうかを確認します。
```
ps -ef | grep jindo-fuse
```
  次の結果が返された場合、OSS-HDFS はマウントされています。
```
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
```
JindoFuse を使用して、OSS-HDFS のオブジェクトに対する読み書き操作を実行します。
- ディレクトリの作成
```
mkdir /mnt/oss/dir1
```
- /mnt/oss/ ディレクトリ内のすべてのサブディレクトリを一覧表示
```
ls /mnt/oss/
```
- オブジェクトの書き込み
```
echo "hello world" > /mnt/oss/dir1/hello.txt
```
- オブジェクトの読み取り
```
cat /mnt/oss/dir1/hello.txt
```
- ディレクトリの削除
```
rm -rf /mnt/oss/dir1/
```
任意。OSS-HDFS をアンマウントします。
以下のいずれかの方法で OSS-HDFS をアンマウントできます。
- OSS-HDFS の手動アンマウント
```
umount <mount_point>
```
- OSS-HDFS の自動アンマウント
```
-oauto_unmount
```
  前述のコマンドを実行して jindo-fuse プロセスに SIGINT を送信するには、killall -9 jindo-fuse を使用できます。OSS-HDFS は、プロセスが終了する前に自動的にアンマウントされます。

よくある質問

JindoFuse エラーのトラブルシューティング

JindoSDK を使用して API を呼び出す場合、エラーが発生した際にエラーメッセージの詳細を確認できます。JindoFuse を使用する場合、OS 標準のエラーメッセージしか表示されません。

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

エラーの原因を特定するには、JindoSDK の logger.dir 設定項目で指定されたパスにある jindosdk.log ファイルを見つける必要があります。次のメッセージは、JindoFuse を使用するときに表示される可能性がある一般的な認証エラーメッセージです。

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 ベースの API を示します。

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

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

次の表に、JindoFuse を使用して OSS-HDFS からローカルファイルシステムにオブジェクトをマウントするために設定できるオプションを示します。

オプション	必須	説明	例
uri	はい	マップする dls パスです。パスには、-ouri=oss://bucket.endpoint/ のようなバケットのルートディレクトリ、または -ouri=oss://bucket.endpoint/subdir のようなバケットのサブディレクトリを指定できます。	`-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` とは異なり、`auto-cache` は、オブジェクトサイズやオブジェクトの変更時刻が変更されると、キャッシュを自動的にフラッシュします。	`-oauto_cache`
entry_timeout	いいえ	オブジェクト読み取り時のキャッシュ内のオブジェクト名の保持期間。単位：秒。このオプションは、パフォーマンスを最適化するために使用されます。値 0 は、オブジェクト名がキャッシュされないことを意味します。デフォルト値：0.1。	`-oentry_timeout=60`
attr_timeout	いいえ	キャッシュ内のオブジェクト属性の保持期間。単位：秒。このオプションは、パフォーマンスを最適化するために使用されます。値 0 は、オブジェクト属性がキャッシュされないことを意味します。デフォルト値：0.1。	`-oattr_timeout=60`
negative_timeout	いいえ	オブジェクトの読み取りに失敗した場合のキャッシュ内のオブジェクト名の保持期間。単位：秒。このオプションは、パフォーマンスを最適化するために使用されます。値 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 ポートを有効にして、http://localhost:9090/brpc_metrics などのメトリクスを出力します。デフォルト値は 9090 です。	`-ometrics_port=9090`
enable_pread	いいえ	pread 操作を呼び出してオブジェクトを読み取ります。	`-oenable_pread`

付録3：設定項目

項目	設定ノード	説明
logger.dir	common	ログが保存されるディレクトリです。デフォルト値： /tmp/jindodata-log。
logger.sync	common	ログを出力するモード。有効な値： true: 同期モードでログを返します。 false (デフォルト): 非同期モードでログを返します。
logger.consolelogger	common	ログを表示するかどうかを指定します。有効な値： true：ログを表示します。 false (デフォルト): ログを表示しません。
logger.level	common	この設定項目の値以上のレベルのログを出力します。ターミナルログが有効な場合この設定値とログレベルの対応は以下の通りです (有効な値：0～6)。 0: TRACE 1: DEBUG 2 (デフォルト): INFO 3: 警告 4: エラー 5：クリティカル 6: オフターミナルログが無効な場合、INFO レベル以上のログが出力されます。ログレベルが 1 以下の場合、WARN を示します。ログレベルが 1 より大きい場合、INFO を示します。
logger.verbose	common	この設定項目の値以上のレベルの Verbose ログを出力します。有効な値：0 から 99。デフォルト値：0。値 0 は、Verbose ログが出力されないことを意味します。
logger.cleaner.enable	common	ログクリーンアップを有効にするかどうかを指定します。有効な値： true: ログクリーンアップを有効にします。 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 Secret。