gcsfuse CLI

このページでは、Cloud Storage FUSE の操作に使用する gcsfuse コマンドライン オプションについて説明します。Cloud Storage FUSE CSI ドライバを使用して Google Kubernetes Engine のローカル ファイル システムにバケットをマウントする場合は、Cloud Storage FUSE CSI ドライバのマウント オプションをご覧ください。

概要

gcsfuse GLOBAL_OPTIONS BUCKET_NAME MOUNT_POINT

ここで

  • GLOBAL_OPTIONS は、マウントの設定方法と Cloud Storage FUSE の動作を制御するオプションです。

  • BUCKET_NAME は、マウントするバケットの名前です。たとえば、my-mount-bucket のようにします。省略可。動的マウントを実行するときに、このコマンドからバケット名を除外します。

  • MOUNT_POINT は、バケットがマウントされるローカル ディレクトリです。例: /path/to/mount/point

説明

gcsfuse CLI は、Cloud Storage バケットをファイル システムとしてローカルマシンにマウントするために使用します。

グローバル オプション

オプション 説明 有効な値 デフォルト値
--anonymous-access リクエストの認証を無効にします。このオプションは、認証をサポートしていないカスタム エンドポイントを使用している場合に設定する必要があります。公開バケットで Cloud Storage FUSE を使用している場合も、このオプションを設定する必要があります。 ブール値: true、false。 false
--app-name マウントのアプリケーション名。 文字列値（例: my-bucket-mount）。 ""
--billing-project マウントされたバケットにアクセスされたときに、課金に使用するプロジェクトを指定します。リクエスト元による支払いで有効にしたバケットをマウントするときに、多くの場合、このオプションは必要になります。 プロジェクト ID を表す文字列値。 ""
--cache-dir

ファイル キャッシュ データを格納するディレクトリを指定します。

ファイルのキャッシュ保存を有効にする方法については、ファイルのキャッシュ保存を使用するをご覧ください。

 パス（例: /tmp/gcsfuse-cache-path）。 ""
--client-protocol Cloud Storage バックエンドとの通信に使用されるプロトコルを指定します。
  • http1: HTTP/1.1
  • http2: HTTP/2
  • grpc: gRPC
 http1
--config-file Cloud Storage FUSE の動作の構成に使用する構成ファイルのパスを指定します。 パス（例: /etc/gcsfuse.yaml）。 ""
--custom-endpoint データを取得するための代替カスタム エンドポイントを指定します。カスタム エンドポイントは、Cloud Storage JSON エンドポイント https://storage.googleapis.com/storage/v1 と同等のリソースとオペレーションをサポートする必要があります。カスタム エンドポイントが指定されていない場合、Cloud Storage FUSE はグローバル Cloud Storage JSON API エンドポイント https://storage.googleapis.com/storage/v1 を使用します。指定したカスタム エンドポイントで認証がサポートされていない場合は、--anonymous-access フラグを true に設定して認証をバイパスします。 エンドポイント（例: http://localhost:443/storage/v1）。 ""
--debug_fuse（非推奨） FUSE 関連のデバッグ出力を有効にします。このオプションは --log-severity オプションに置き換えられました。デバッグ出力を有効にするには、--log-severity オプションを trace に設定します。これには、トレースログ、デバッグログ、情報ログ、警告ログ、エラーログが含まれます。 ブール値: true、false。 false
--debug_gcs（非推奨） Cloud Storage のリクエストとタイミング情報を出力します。このオプションは --log-severity オプションに置き換えられました。デバッグ出力を有効にするには、--log-severity オプションを trace に設定します。これには、トレースログ、デバッグログ、情報ログ、警告ログ、エラーログが含まれます。 ブール値: true、false。 false
--debug_invariants 内部不変条件違反が検出されると、プログラムを終了します。 ブール値: true、false。 false
--debug_mutex ミューテックスの保持時間が長くなりすぎると、デバッグ メッセージを出力します。このオプションを指定すると、ログの重大度が自動的に trace に設定されます。これには、トレースログ、デバッグログ、情報ログ、警告ログ、エラーログが含まれます。 ブール値: true、false。 false
--dir-mode ディレクトリの権限ビット（8 進数）。 000～777 の整数（両端を含む）。 755
--enable-nonexistent-type-cache Cloud Storage でファイルが見つからない場合、NonexistentType 型のタイプ キャッシュ エントリが作成されます。ファイルが Cloud Storage で作成されても、ファイルの NonexistentType エントリがキャッシュに保存されている場合、Cloud Storage FUSE は、NonexistentType エントリがタイプ キャッシュから削除されるまで、そのファイルをリクエストできません。 ブール値: true、false。 false
--file-cache-cache-file-for-range-read ゼロ以外のオフセットから最初の読み取りが行われたときに、オブジェクト全体を非同期的にダウンロードして Cloud Storage FUSE キャッシュ ディレクトリに保存するかどうかを示します。複数のランダム読み取りまたは部分読み取りを行う場合は、このオプションを true に設定する必要があります。

注: オフセット 0 から部分読み取りを行う場合、Cloud Storage FUSE は完全なオブジェクトを非同期でダウンロードしてキャッシュに保存します。

 ブール値: true、false。 false
--file-cache-download-chunk-size-mb オブジェクトをファイル キャッシュにダウンロードするときに、各 goroutine が Cloud Storage に対して行う 1 回の読み取りリクエストのサイズを MiB で指定します。 整数 50
--file-cache-enable-parallel-downloads

ファイル キャッシュ ディレクトリをプリフェッチ バッファとして使用し、複数のワーカーを使用してサイズの大きいファイルを並列でダウンロードすることで、サイズの大きいファイルの読み取りを高速化します。並列ダウンロードと、そのサポート プロパティの構成方法について詳しくは、並列ダウンロードを使用して読み取りパフォーマンスを改善するをご覧ください。

並列ダウンロードを使用するには、まずファイル キャッシュを有効にする必要があります。

 ブール値: true、false。 false
--file-cache-max-parallel-downloads ファイルのダウンロード ジョブ全体で、任意の時点で生成できる goroutine の最大数。
  • 整数
  • -1: 無制限の並列ダウンロードを指定します。
  • 0: 並列ダウンロードを無効にします。--enable-parallel-downloads が渡されていない場合、または false として渡された場合にのみ使用できます。
  • 0: 上限を指定しません。Cloud Storage FUSE は、マシンの構成で指定された、生成できる goroutine の最大数に基づいて、内部で値を制限します。
 マシン上の CPU コア数の 2 倍、または 16 のいずれか大きいほう。
--file-cache-parallel-downloads-per-file ファイルあたりの同時ダウンロード リクエストの数。 整数 16
--file-cache-max-size-mb

ファイル キャッシュで使用できる最大サイズ（MiB 単位）。--file-cache-max-size-mb が存在する場合、Cloud Storage FUSE でファイル キャッシュを有効にします。これは、Cloud Storage FUSE キャッシュがマウントされたディレクトリ内で使用できる合計容量を制限する場合に便利です。
  • 整数
  • -1: cache-dir に指定したディレクトリのキャッシュで使用可能な容量をすべて使用するように指定します。
  • 0: ファイル キャッシュを無効にします。
 -1
--file-mode ファイルの権限ビットを 8 進数で指定します。 000～777 の整数（両端を含む）。 644
--foreground フォアグラウンドで gcsfuse コマンドを実行します。 ブール値: true、false。 false
--gid すべての i ノードのグループ識別子（GID）オーナーを指定します。
  • GID を表す整数。
  • -1: 呼び出し元の GID が使用されます。
 -1
--help Cloud Storage FUSE に関するヘルプを表示します。 なし なし
--version インストールした Cloud Storage FUSE のバージョンを表示します。 なし なし
--http-client-timeout Cloud Storage FUSE HTTP クライアントがタイムアウトになる前にサーバーからのレスポンスを待つ時間を指定します。 時間（例: 1h10m10s（1 時間 10 分 10 秒））。0s はタイムアウトなしを指定します。 0s
--ignore-interrupts Control+C によってトリガーされる SIGINT など、システム割り込みシグナルを無視するように Cloud Storage FUSE に指示します。これにより、実行中のオペレーションがシグナルによって終了することがなくなります。 ブール値: true、false。 true
--implicit-dirs フォルダとマネージド フォルダを暗黙的に含めます。詳細については、GitHub のファイルとディレクトリのドキュメントをご覧ください。 ブール値: true、false。 false
--kernel-list-cache-ttl-secs リスト キャッシュを有効にし、キャッシュに保存されたリストエントリの有効期間（TTL）を秒単位で定義します。リスト キャッシュはページ キャッシュのメモリに保持され、使用可能なメモリに基づいてカーネルによって制御されます。
  • 秒を表す整数（例: 10（10 秒））。
  • 0: リスト キャッシュ保存を無効にします。
  • -1: エントリの有効期限をバイパスし、キャッシュから利用可能な場合に常にキャッシュからリスト レスポンスを返します。
 0
--key-file Cloud Storage へのリクエストを認証するための認証情報 JSON キーファイルの絶対パスを指定します。デフォルトでは、Cloud Storage FUSE はアプリケーションのデフォルト認証情報を使用してリクエストを認証します。 パス（例: /home/example_user/gcloud-key.json）。 このオプションを設定しない場合、アプリケーションのデフォルト認証情報が使用されます。
--limit-bytes-per-sec Cloud Storage FUSE が Cloud Storage からデータを読み込むことができる帯域幅の上限を指定します。測定時間は 30 秒です。 浮動小数点数。-1 は上限を指定しません。 -1
--limit-ops-per-sec 30 秒間に測定される 1 秒あたりのオペレーションの上限を指定します。 浮動小数点数。-1 は上限を指定しません。 -1
--log-file Fluentd で解析できるログを保存するためのファイルを指定します。 パス（例: /tmp/user-example-bucket-gcsfuse-logs.txt）。 Cloud Storage FUSE がフォアグラウンドで実行されている場合は stdout、Cloud Storage FUSE がバックグラウンドで実行されている場合は syslog
--log-format ログファイルの形式を指定します。
  • text
  • json
 json
--log-rotate-backup-file-count ローテーション後に保持しておくログファイルの最大数。ログが書き込まれているアクティブなファイルは除きます。
  • 整数
  • 0: ローテーションされたすべてのログファイルを保持します。
 10
--log-rotate-compress ローテーションされたログファイルを gzip で圧縮するかどうかを指定します。 ブール値: true、false。 true
--log-rotate-max-file-size-mb ログファイルがローテーションされる前に到達可能な最大サイズ（MB 単位）。 整数。最小値は 1 です。 512
--log-severity

Cloud Storage FUSE でログを生成する重大度。重大度は、低いものから高いものの順に並べられています。たとえば、warning を指定すると、Cloud Storage FUSE は警告とエラーのログを生成します。通常は、重大度 info を使用することをおすすめします。
  • trace
  • debug
  • info
  • warning
  • error
  • off: すべてのロギングを無効にします。
 info
--max-conns-per-host サーバーごとに許可される TCP 接続の最大数を指定します。これは、--client-protocol が http1 に設定されている場合に有効になります。 0～2147483647 の整数。0 は TCP 接続の上限を指定しません。 0
--max-idle-conns-per-host サーバーごとに許可されるアイドル状態の接続の最大数を指定します。これは、--client-protocol が http1 に設定されている場合に有効になります。 0～2147483647 の整数。0 はアイドル状態の接続の上限を指定しません。 0
--max-retry-sleep 指数バックオフを使用した再試行ループで Cloud Storage FUSE がスリープできる最大時間を指定します。バックオフ時間が指定の最大時間を超えると、指定された最大時間で再試行が続行されます。 時間（例: 1h5m50s（1 時間 5 分 50 秒）、60s（60 秒））。 30s
--metadata-cache-negative-ttl-secs

ネガティブな統計情報キャッシュ エントリの有効期間（TTL）を秒単位で定義します。このエントリには、存在しないファイルの結果がキャッシュに保存されます。
  • 秒を表す整数（例: 10（10 秒））。
  • 0: ネガティブな統計情報キャッシュを無効にします。
  • -1: 無制限のネガティブな統計情報キャッシュを許可し、TTL の有効期限を無効にします。
 5
--metadata-cache-ttl-secs キャッシュに保存されたメタデータ エントリの有効期間（TTL）を秒単位で指定します。
  • 秒を表す整数（例: 30（30 秒））。
  • -1: TTL の有効期限をバイパスし、キャッシュから利用可能な場合にファイルを配信します。
  • 0: 最新のファイルを使用します。この値を使用すると、Get メタデータ呼び出しが行われ、キャッシュ内のファイルのオブジェクトの世代が Cloud Storage に保存されているものと一致していることを確認します。詳細については、キャッシュの無効化の構成をご覧ください。
 60
-o 追加のシステム固有のマウント オプションを指定します。FUSE のほとんどの汎用マウント オプション（suid など）は Cloud Storage FUSE でサポートされており、-o オプションとともに渡すことができます。 FUSE のマウント オプション。例:
  • rw: 読み取り / 書き込みとしてマウントします。
  • ro: 読み取り専用としてマウントします。
 ""
--only-dir バケット内の特定のディレクトリのみをマウントします。 パス（例: /etc/gcsfuse.yaml）。 ""
--rename-dir-limit 指定した上限よりも子孫の少ないディレクトリの名前を変更できます。 0～2147483647 の整数。 0
--retry-multiplier 連続する再試行間の指数バックオフの乗数を指定します。 浮動小数点数 2
--reuse-token-from-url --token-url から取得したトークンを再利用するかどうかを指定します。 ブール値: true、false。 true
--sequential-read-size-mb Cloud Storage からダウンロードするデータのチャンクサイズを MB 単位で指定します。 1～1024 の整数。 200
--stackdriver-export-interval 指定した間隔で指標を Stackdriver にエクスポートします。 時間（例: 1h5m50s（1 時間 5 分 50 秒））。0s はエクスポートなしを指定します。 0s
--stat-cache-capacity（非推奨） 統計情報キャッシュが保持できるエントリ数を指定します。このオプションは --stat-cache-max-size-mb オプションに置き換えられました。 整数 4096
--stat-cache-max-size-mb 統計情報キャッシュで使用できる最大メモリサイズ（MiB）。統計情報キャッシュは常にメモリ内に保持されます。
  • 整数。次のようにすることをおすすめします。
    • ワークロードのファイル数が 20,000 以下の場合は 32 にします。
    • ワークロードのファイル数が 20,000 を超える場合は、6,000 ファイルごとにサイズを 10 ずつ増やします。統計キャッシュはファイルあたり平均 1,500 MiB を使用します。
  • -1: 上限を設定しません。統計情報キャッシュは必要な量のメモリを使用します。
  • 0: 統計情報キャッシュを無効にします。
 32
--stat-cache-ttl（非推奨） StatObject の結果と i ノード属性をキャッシュに保存する期間を指定します。このオプションは --metadata-cache-ttl-secs オプションに置き換えられました。 時間（例: 20s（20 秒））。 60s
--temp-dir Cloud Storage にアップロードする前に書き込みがステージングされる一時ディレクトリのパスを指定します。 パス（例: /mnt/ssd/example-user-gcsfuse-temp-dir）。 /tmp
--token-url --key-file が存在しない場合にアクセス トークンを取得するための URL を指定します。 URL。 ""
--type-cache-ttl (deprecated) ディレクトリの i ノード内の名前とファイルまたはディレクトリ間のマッピングをキャッシュに保存する時間を秒単位で指定します。このオプションは --metadata-cache-ttl-secs オプションに置き換えられました。 秒単位の時間（例: 20s（20 秒））。 60s
--type-cache-max-size-mb タイプ キャッシュが使用できるディレクトリあたりの最大サイズ（MiB 単位）。タイプ キャッシュは常にメモリ内に保持されます。
  • 整数。次のようにすることをおすすめします。
    • マウントするバケットの 1 つのディレクトリ内にあるファイルの最大数が 20,000 以下の場合は 4 にします。
    • マウントする 1 つのディレクトリ内のファイルの最大数が 20,000 を超える場合は、5,000 ファイルごとに値を 1 増やします（ファイルあたり平均約 200 バイト）。
  • -1: 上限を指定せず、タイプ キャッシュが必要な量のメモリを使用できるようにします。
  • 0: タイプ キャッシュを無効にします。
 4
--uid すべての i ノードのユーザー識別子（UID）所有者を指定します。
  • UID を表す整数。
  • -1: 呼び出し元の UID が使用されます。
 -1