Cloud Storage FUSE 構成ファイル

このページでは、Cloud Storage FUSE 構成ファイルを使用して、Cloud Storage FUSE の動作を永続的に構成する方法について説明します。構成ファイルを使用するには、マウント コマンドの一部として、--config-file フラグで構成ファイルのパスを指定します。

構成ファイルは、次の形式とフィールドを使用する YAML ファイルです。一部のフィールドは、コマンドライン オプションで指定することもできます。

app-name: "APP_NAME"
write:
  create-empty-file: CREATE_EMPTY_FILE
logging:
  file-path: "FILE_PATH"
  format: FORMAT
  severity: SEVERITY
  log-rotate:
    max-file-size-mb: MAX_FILE_SIZE
    backup-file-count: BACKUP_FILE_COUNT
    compress: COMPRESS
file-cache:
  max-size-mb: MAX_SIZE
  cache-file-for-range-read: CACHE_FILE_FOR_RANGE_READ
  enable-parallel-downloads: ENABLE_PARALLEL_DOWNLOADS
  parallel-downloads-per-file: PARALLEL_DOWNLOADS_PER_FILE
  max-parallel-downloads: MAX_PARALLEL_DOWNLOADS
  download-chunk-size-mb: DOWNLOAD_CHUNK_SIZE
metadata-cache:
  enable-nonexistent-type-cache: ENABLE_NONEXISTENT_TYPE_CACHE
  stat-cache-max-size-mb: STAT_CACHE_MAX_SIZE
  ttl-secs: TTL_SECS
  type-cache-max-size-mb: TYPE_CACHE_MAX_SIZE
cache-dir: "CACHE_DIR"
only-dir: "ONLY_DIR"
gcs-auth:
  anonymous-access: ANONYMOUS_ACCESS
  key-file: "KEY_FILE"
  reuse-token-from-url: REUSE_TOKEN_FROM_URL
  token-url: "TOKEN_URL"
gcs-connection:
  billing-project: "BILLING_PROJECT"
  client-protocol: CLIENT_PROTOCOL
  custom-endpoint: "CUSTOM_ENDPOINT"
  http-client-timeout: HTTP_CLIENT_TIMEOUT
  limit-bytes-per-sec: "LIMIT_BYTES_PER_SEC"
  limit-ops-per-sec: "LIMIT_OPS_PER_SEC"
  max-conns-per-host: MAX_CONNS_PER_HOST
  max-idle-conns-per-host: MAX_IDLE_CONNS_PER_HOST
  sequential-read-size-mb: SEQUENTIAL_READ_SIZE
implicit-dirs: IMPLICIT_DIRS
file-system:
  kernel-list-cache-ttl-secs: KERNEL_LIST_CACHE_TTL_SECS
  ignore-interrupts: IGNORE_INTERRUPTS
  dir-mode: "DIR_MODE"
  file-mode: "FILE_MODE"
  fuse-options: FUSE_OPTIONS
  gid: GID
  rename-dir-limit: RENAME_DIR_LIMIT
  temp-dir: "TEMP_DIR"
  uid: UID
foreground: FOREGROUND
gcs-retries:
  max-retry-sleep: MAX_RETRY_SLEEP
  multiplier: "MULTIPLIER"
metrics:
  stackdriver-export-interval: STACKDRIVER_EXPORT_INTERVAL
debug:
  log-mutex: LOG_MUTEX
  exit-on-invariant-violation: EXIT_ON_INVARIANT_VIOLATION

構成フィールド

次の表に、構成ファイルで指定できるフィールドを示します。特に記載がない限り、すべてのフィールドは省略可能です。

フィールド 説明
app-name マウントのアプリケーション名。
create-empty-file マウントされたバケット内の新しいファイルへの書き込みを開始したときに、Cloud Storage にゼロバイトのファイルを作成するかどうかを指定するブール値。このフィールドを省略した場合、デフォルト値の false が使用されます。
file-path ログが書き込まれるログファイルのパス。文字列で指定します。例: /var/logこのフィールドを省略すると、stdout（Cloud Storage FUSE がフォアグラウンド モードで実行されている場合）または syslog（バックグラウンド モードで実行されている場合）にログが転送されます。
format ログが生成される形式。列挙型で表します。値は text か json です。このフィールドを省略した場合、デフォルト値の json が使用されます。
severity

Cloud Storage FUSE で生成するログの重大度。列挙型で表します。値が小さいほど重大度が低く、大きいほど高くなります。

  • trace
  • debug
  • info
  • warning
  • error

重大度レベルを指定すると、Cloud Storage FUSE は、重大度が同等以上のログを生成します。たとえば、warning を指定すると、Cloud Storage FUSE は警告とエラーのログを生成します。off を指定して、すべてのロギングをオフにすることもできます。次の 3 つのオプションのいずれかがコマンドに指定されている場合、重大度レベルは自動的に trace に設定されます。

  • --debug_fuse
  • --debug_gcs
  • --debug_mutex

このフィールドを省略した場合、デフォルト値の info が使用されます。
max-file-size-mb ログファイルがローテーションされる前に到達可能な最大サイズ（MB 単位）。最小値は 1 です。このフィールドを省略した場合、デフォルト値の 512 が使用されます。
backup-file-count ローテーション後に保持しておくログファイルの最大数。ログが書き込まれているアクティブなファイルは除きます。値を 0 に設定すると、ローテーションされたログファイルがすべて保持されます。このフィールドを省略した場合、デフォルト値の 10 が使用されます。
compress ローテーションされたログファイルを gzip で圧縮するかどうかを指定するブール値。このフィールドを省略した場合、デフォルト値の true が使用されます。
max-size-mb

ファイル キャッシュで使用できる最大サイズ（MiB 単位）。max-size-mb が存在する場合、Cloud Storage FUSE でファイル キャッシュを有効にします。これは、Cloud Storage FUSE キャッシュがマウントされたディレクトリ内で使用できる合計容量を制限する場合に便利です。

  • cache-dir に指定したディレクトリのキャッシュで使用可能な容量をすべて使用するには、-1 を指定します。
  • ファイル キャッシュを無効にするには、0 を指定します。

このフィールドを省略した場合、デフォルト値の -1 が使用されます。
cache-file-for-range-read

最初の読み取りがゼロ以外のオフセットから行われたときに、オブジェクト全体を非同期でダウンロードして Cloud Storage FUSE のキャッシュ ディレクトリに保存するかどうかを決定するブール値。複数のランダム読み取りまたは部分読み取りを行う場合は、true に設定する必要があります。このフィールドを省略した場合、デフォルト値の false が使用されます。

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

ファイル キャッシュ ディレクトリをプリフェッチ バッファとして使用し、複数のワーカーを使用してサイズの大きいファイルを並列でダウンロードすることで、サイズの大きいファイルの読み取りを高速化します。デフォルト値は false です。


並列ダウンロードを使用するには、ファイル キャッシュを有効にする必要があります。並列ダウンロードと、そのサポート プロパティの構成方法について詳しくは、並列ダウンロードを使用して読み取りパフォーマンスを改善するをご覧ください。
parallel-downloads-per-file

Cloud Storage からファイル キャッシュにオブジェクトをダウンロードするために、ファイルごとに生成する goroutine の最大数を指定します。デフォルト値は 16 です。
max-parallel-downloads

ファイルのダウンロード ジョブ全体で、任意の時点で生成できる goroutine の最大数。デフォルトは、マシン上の CPU コア数の 2 倍です。上限をバイパスするには、値 -1 を指定します。
download-chunk-size-mb

オブジェクトをファイル キャッシュにダウンロードするときに、各 goroutine が Cloud Storage に対して行う 1 回の読み取りリクエストのサイズを MiB で指定します。デフォルト値は 50 です。
enable-nonexistent-type-cache Cloud Storage でファイルが見つからない場合、NonexistentType 型のキャッシュ エントリが作成されます。ファイルが Cloud Storage で作成されても、ファイルの NonexistentType エントリがキャッシュに保存されている場合、Cloud Storage FUSE は、NonexistentType エントリがタイプ キャッシュから削除されるまで、そのファイルをリクエストできません。デフォルト値は false です。
stat-cache-max-size-mb

統計情報キャッシュで使用できる最大サイズ（MiB）。統計情報キャッシュは常にメモリ内に保持されます。

  • ワークロードに最大 20,000 個のファイルが含まれる場合は、32 を指定します。ワークロードのファイルが 20,000 ファイルを超える場合は、6,000 ファイルを追加するごとにサイズを 10 ずつ増やします（ファイルあたり平均約 1,500 バイト）。
  • -1 を指定すると、統計情報キャッシュは必要な量のメモリを使用します。
  • 統計情報キャッシュを無効にするには、0 を指定します。

このフィールドを省略した場合、デフォルト値の 32 が使用されます。
ttl-secs

キャッシュに保存されたメタデータ エントリの有効期間（TTL）を秒単位で定義します。

  • -1 を指定すると、TTL の有効期限をバイパスし、キャッシュから利用可能な場合にファイルを配信します。
  • 最新のファイルが読み取られるようにするには、0 を指定します。この値を使用すると、Get メタデータ呼び出しが行われ、キャッシュ内のファイルのオブジェクトの世代が Cloud Storage に保存されているものと一致していることを確認します。詳細については、キャッシュの無効化の構成をご覧ください。

このフィールドを省略した場合、デフォルト値の 60s が使用されます。
type-cache-max-size-mb

タイプ キャッシュが使用できるディレクトリあたりの最大サイズ（MiB 単位）。タイプ キャッシュは常にメモリ内に保持されます。

  • マウントするバケットの 1 つのディレクトリ内にあるファイルの最大数が 20,000 以下の場合は、4 を指定します。マウントする 1 つのディレクトリ内のファイルの最大数が 20,000 を超える場合は、5,000 ファイルごとに値を 1 増やします（ファイルあたり平均約 200 バイト）。
  • タイプ キャッシュが必要な量のメモリを使用できるようにするには、-1 を指定します。
  • タイプ キャッシュを無効にするには、0 を指定します。

このフィールドを省略した場合、デフォルト値の 4 が使用されます。
cache-dir ファイル キャッシュ データを格納するディレクトリを指定します。ファイル キャッシュを有効にするには、このフィールドを指定する必要があります。
only-dir バケット内の特定のディレクトリのみをマウントします。
anonymous-access リクエストの認証を無効にします。このフィールドは、認証をサポートしていないカスタム エンドポイントを使用している場合、または Cloud Storage FUSE を使用して一般公開バケットをマウントしている場合に設定します。デフォルト値は false です。
key-file Cloud Storage へのリクエストを認証するための認証情報 JSON キーファイルの絶対パスを指定します。デフォルトでは、Cloud Storage FUSE はアプリケーションのデフォルト認証情報を使用してリクエストを認証します。
reuse-token-from-url token-url から取得したトークンを使用するよう指定します。デフォルト値は true です。
token-url key-file が存在しない場合にアクセス トークンを取得するための URL を指定します。
billing-project マウントされたバケットにアクセスされたときに、課金に使用するプロジェクトを指定します。リクエスト元による支払いで有効にしたバケットをマウントするときに、多くの場合、このフラグは必要になります。デフォルトのプロジェクトはありません。
client-protocol Cloud Storage バックエンドとの通信に使用されるプロトコルを指定します。HTTP/1.1 の場合、値は http1 になり、HTTP/2 の場合は http2 になります。デフォルト値は http1 です。
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-client-timeout Cloud Storage FUSE HTTP クライアントがタイムアウトになる前にサーバーからのレスポンスを待つ時間を指定します。デフォルト値は 0s で、タイムアウトがないことを示します。
limit-bytes-per-sec Cloud Storage FUSE が Cloud Storage からデータを読み込むことができる帯域幅の上限を指定します。測定時間は 30 秒です。デフォルトの上限値は "-1" で、この場合上限はありません。
limit-ops-per-sec 30 秒間に測定される 1 秒あたりのオペレーションの上限を指定します。デフォルトの上限値は "-1" で、この場合、上限はありません。
max-conns-per-host サーバーごとに許可される TCP 接続の最大数を指定します。これは、client-protocol が http1 に設定されている場合に有効になります。デフォルト値は 0 です。これは、マシンの仕様で設定された上限を除き、TCP 接続に上限が存在しないことを指定します。
max-idle-conns-per-host サーバーごとに許可されるアイドル状態の接続の最大数を指定します。デフォルト値は 100 です。
sequential-read-size-mb Cloud Storage からダウンロードするデータのチャンクサイズをメガバイト（MB）単位で指定します。デフォルト値は 200 です。
implicit-dirs

フォルダとマネージド フォルダが暗黙的に含まれています。

詳細については、GitHub のファイルとディレクトリのドキュメントをご覧ください。
kernel-list-cache-ttl-secs リスト キャッシュを有効にし、キャッシュに保存されたリストエントリの有効期間（TTL）を秒単位で定義します。リスト キャッシュのメモリ割り当ては、使用可能なメモリに基づいてカーネルによって制御されます。デフォルト値は 0 で、リストのキャッシュが無効になります。

kernel-list-cache-ttl-secs フィールドを設定するには、ディレクトリ リスト レスポンスをカーネルのページ キャッシュに保持する時間を秒単位の正の値で指定します。エントリの有効期限をバイパスし、キャッシュから利用可能な場合に常にキャッシュからリスト レスポンスを返すには、-1 の値を指定します。
ignore-interrupts Control+C によってトリガーされる SIGINT など、システム割り込みシグナルを無視するように Cloud Storage FUSE に指示します。これにより、実行中のオペレーションがシグナルによって終了することがなくなります。値は true または false です。デフォルト値は true です。
dir-mode ディレクトリの権限ビット（8 進数）。デフォルト値は "755" です。
file-mode ファイルの権限ビットを 8 進数で指定します。デフォルト値は "644" です。
fuse-options 追加のシステム固有のマウント オプションを指定します。
gid すべての i ノードのグループ識別子（GID）オーナーを指定します。デフォルトの GID 値は -1 です。
rename-dir-limit 指定した上限よりも子孫の少ないディレクトリの名前を変更できます。デフォルトの上限値は 0 です。
temp-dir Cloud Storage にアップロードする前に書き込みがステージングされる一時ディレクトリのパスを指定します。デフォルト値はシステムのデフォルトです（"/tmp" など）。
uid すべての i ノードのユーザー識別子（UID）所有者を指定します。デフォルトの UID 値は -1 です。
foreground フォアグラウンドで gcsfuse コマンドを実行します。デフォルト値は false です。
max-retry-sleep 指数バックオフを使用した再試行ループで Cloud Storage FUSE がスリープできる最大時間を指定します。バックオフ時間が指定の最大時間を超えると、指定された最大時間で再試行が続行されます。デフォルトの上限値は 30s（30 秒）です。
multiplier 再試行間の指数バックオフを指定します。値は、前の待機時間に基づく後続の待機時間の乗数です。デフォルト値は "2" です。
stackdriver-export-interval 指定した間隔で指標を Cloud Monitoring にエクスポートします。デフォルト値は 0s（0 秒）で、エクスポートを指定しません。
log-mutex ミューテックスの保持時間が長くなりすぎると、デバッグ メッセージを出力します。このオプションを指定すると、ログの重大度が自動的に trace に設定されます。これには、トレースログ、デバッグログ、情報ログ、警告ログ、エラーログが含まれます。デフォルト値は false です。
exit-on-invariant-violation 内部バリアントの違反が検出されると、プログラムを終了します。デフォルト値は false です。