Cloud Storage FUSE 構成ファイル

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

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

app-name: "APP_NAME"
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
  negative-ttl-secs: ENABLE_NEGATIVE_TTL_SECS
  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 マウントのアプリケーション名。 文字列値（例: "my-bucket-mount"）。 ""
file-path ログが書き込まれるログファイルのパス。このフィールドを省略すると、stdout（Cloud Storage FUSE がフォアグラウンド モードで実行されている場合）または syslogs（バックグラウンド モードで実行されている場合）にログが転送されます。 文字列値（例: "/var/log"）。 ""
format ログファイルの形式を指定します。
  • text
  • json
 json
severity

Cloud Storage FUSE でログを生成する重大度。重大度は、低いものから高いものの順に並べられています。たとえば、warning を指定すると、Cloud Storage FUSE は警告とエラーのログを生成します。通常は、重大度 info を使用することをおすすめします。
  • trace
  • debug
  • info
  • warning
  • error
  • off: すべてのロギングを無効にします。
 info
max-file-size-mb ログファイルがローテーションされる前に到達可能な最大サイズ（MB 単位）。 整数。最小値は 1 です。 512
backup-file-count ローテーション後に保持しておくログファイルの最大数。ログが書き込まれているアクティブなファイルは除きます。
  • 整数
  • 0: ローテーションされたすべてのログファイルを保持します。
 10
compress ローテーションされたログファイルを gzip で圧縮するかどうかを指定します。 ブール値: true、false true
max-size-mb

ファイル キャッシュで使用できる最大サイズ（MiB 単位）。max-size-mb が存在する場合、Cloud Storage FUSE でファイル キャッシュを有効にします。これは、Cloud Storage FUSE キャッシュがマウントされたディレクトリ内で使用できる合計容量を制限する場合に便利です。
  • 整数
  • -1: cache-dir に指定したディレクトリのキャッシュで使用可能な容量をすべて使用するように指定します。
  • 0: ファイル キャッシュを無効にします。
 -1
cache-file-for-range-read ゼロ以外のオフセットから最初の読み取りが行われたときに、オブジェクト全体を非同期的にダウンロードして Cloud Storage FUSE キャッシュ ディレクトリに保存するかどうかを示します。複数のランダム読み取りまたは部分読み取りを行う場合は、このオプションを true に設定する必要があります。

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

 ブール値: true、false false
enable-parallel-downloads

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

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

 ブール値: true、false false
parallel-downloads-per-file

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

 整数 16
max-parallel-downloads ファイルのダウンロード ジョブ全体で、任意の時点で生成できる goroutine の最大数。
  • 整数
  • -1: 無制限の並列ダウンロードを指定します。
  • 0: 並列ダウンロードを無効にします。--enable-parallel-downloads が渡されていない場合、または false として渡された場合にのみ使用できます。
  • >0: 上限を指定しません。Cloud Storage FUSE は、マシンの構成で指定された、生成できる goroutine の最大数に基づいて、内部で値を制限します。
 マシン上の CPU コア数の 2 倍、または 16 のいずれか大きいほう。
download-chunk-size-mb オブジェクトをファイル キャッシュにダウンロードするときに、各 goroutine が Cloud Storage に対して行う 1 回の読み取りリクエストのサイズを MiB で指定します。 整数 50
enable-nonexistent-type-cache Cloud Storage でファイルが見つからない場合、NonexistentType 型のタイプ キャッシュ エントリが作成されます。ファイルが Cloud Storage で作成されても、ファイルの NonexistentType エントリがキャッシュに保存されている場合、Cloud Storage FUSE は、NonexistentType エントリがタイプ キャッシュから削除されるまで、そのファイルをリクエストできません。 ブール値: true、false false
stat-cache-max-size-mb 統計情報キャッシュで使用できる最大メモリサイズ（MiB）。統計情報キャッシュは常にメモリ内に保持されます。
  • 整数。次のようにすることをおすすめします。
    • ワークロードのファイル数が 20,000 以下の場合は 32 にします。
    • ワークロードのファイル数が 20,000 を超える場合は、6,000 ファイルごとにサイズを 10 ずつ増やします。統計キャッシュはファイルあたり平均 1,500 MiB を使用します。
  • -1: 上限を設定しません。統計情報キャッシュは必要な量のメモリを使用します。
  • 0: 統計情報キャッシュを無効にします。
 32
negative-ttl-secs

ネガティブな統計情報キャッシュ エントリの有効期間（TTL）を秒単位で定義します。このエントリには、存在しないファイルの結果がキャッシュに保存されます。
  • 秒を表す整数（例: 10（10 秒））。
  • 0: ネガティブな統計情報キャッシュを無効にします。
  • -1: 無制限のネガティブな統計情報キャッシュを許可し、TTL の有効期限を無効にします。
 5
ttl-secs キャッシュに保存されたメタデータ エントリの有効期間（TTL）を秒単位で指定します。
  • 秒を表す整数（例: 30（30 秒））。
  • -1: TTL の有効期限をバイパスし、キャッシュから利用可能な場合にファイルを配信します。
  • 0: 最新のファイルを使用します。この値を使用すると、Get メタデータ呼び出しが行われ、キャッシュ内のファイルのオブジェクトの世代が Cloud Storage に保存されているものと一致していることを確認します。詳細については、キャッシュの無効化の構成をご覧ください。
 60
type-cache-max-size-mb タイプ キャッシュが使用できるディレクトリあたりの最大サイズ（MiB 単位）。タイプ キャッシュは常にメモリ内に保持されます。
  • 整数。次のようにすることをおすすめします。
    • マウントするバケットの 1 つのディレクトリ内にあるファイルの最大数が 20,000 以下の場合は 4 にします。
    • マウントする 1 つのディレクトリ内のファイルの最大数が 20,000 を超える場合は、5,000 ファイルごとに値を 1 増やします（ファイルあたり平均約 200 バイト）。
  • -1: 上限を指定せず、タイプ キャッシュが必要な量のメモリを使用できるようにします。
  • 0: タイプ キャッシュを無効にします。
 4
cache-dir

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

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

 パス（例: "/tmp/gcsfuse-cache-path"）。
only-dir バケット内の特定のディレクトリのみをマウントします。 パス（例: "/etc/gcsfuse.yaml"）。
anonymous-access リクエストの認証を無効にします。このオプションは、認証をサポートしていないカスタム エンドポイントを使用している場合に設定する必要があります。公開バケットで Cloud Storage FUSE を使用している場合も、このオプションを設定する必要があります。 ブール値: true、false false
key-file Cloud Storage へのリクエストを認証するための認証情報 JSON キーファイルの絶対パスを指定します。デフォルトでは、Cloud Storage FUSE はアプリケーションのデフォルト認証情報を使用してリクエストを認証します。 URL。 このオプションを設定しない場合、アプリケーションのデフォルト認証情報が使用されます。
reuse-token-from-url --token-url から取得したトークンを再利用するかどうかを指定します。 ブール値: true、false true
token-url --key-file が存在しない場合にアクセス トークンを取得するための URL を指定します。 URL。
billing-project マウントされたバケットにアクセスされたときに、課金に使用するプロジェクトを指定します。リクエスト元による支払いで有効にしたバケットをマウントするときに、多くの場合、このオプションは必要になります。 「プロジェクト ID」を表す文字列値。 ""
client-protocol Cloud Storage バックエンドとの通信に使用されるプロトコルを指定します。
  • http1: HTTP/1.1
  • http2: HTTP/2
  • grpc: gRPC
 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://localhost:443/storage/v1"）。
http-client-timeout Cloud Storage FUSE HTTP クライアントがタイムアウトになる前にサーバーからのレスポンスを待つ時間を指定します。 時間（例: 1h10m10s（1 時間 10 分 10 秒））。0s はタイムアウトなしを指定します。 0s: タイムアウトなしを指定します。
limit-bytes-per-sec Cloud Storage FUSE が Cloud Storage からデータを読み込むことができる帯域幅の上限を指定します。測定時間は 30 秒です。 "-1": 上限を指定しません。
limit-ops-per-sec 30 秒間に測定される 1 秒あたりのオペレーションの上限を指定します。 浮動小数点数。-1 は上限を指定しません。 "-1"
max-conns-per-host サーバーごとに許可される TCP 接続の最大数を指定します。これは、--client-protocol が http1 に設定されている場合に有効になります。 0
max-idle-conns-per-host サーバーごとに許可されるアイドル状態の接続の最大数を指定します。これは、--client-protocol が http1 に設定されている場合に有効になります。 0～2147483647 の整数。0 は TCP 接続の上限を指定しません。 0
sequential-read-size-mb Cloud Storage からダウンロードするデータのチャンクサイズを MB 単位で指定します。 1～1024 の整数。 200
implicit-dirs フォルダとマネージド フォルダを暗黙的に含めます。詳細については、GitHub のファイルとディレクトリのドキュメントをご覧ください。 ブール値: true、false false
kernel-list-cache-ttl-secs リスト キャッシュを有効にし、キャッシュに保存されたリストエントリの有効期間（TTL）を秒単位で定義します。リスト キャッシュはページ キャッシュのメモリに保持され、使用可能なメモリに基づいてカーネルによって制御されます。
  • 秒を表す整数（例: 10（10 秒））。
  • 0: リスト キャッシュ保存を無効にします。
  • -1: エントリの有効期限をバイパスし、キャッシュから利用可能な場合に常にキャッシュからリスト レスポンスを返します。
0
ignore-interrupts Control+C によってトリガーされる SIGINT など、システム割り込みシグナルを無視するように Cloud Storage FUSE に指示します。これにより、実行中のオペレーションがシグナルによって終了することがなくなります。 ブール値: true、false。 true
dir-mode ディレクトリの権限ビット（8 進数）。 000～777 の整数（両端を含む）。 "755"
file-mode ファイルの権限ビットを 8 進数で指定します。 000～777 の整数（両端を含む）。 "644"
fuse-options 追加のシステム固有のマウント オプションを指定します。
gid すべての i ノードのグループ識別子（GID）オーナーを指定します。
  • GID を表す整数。
  • -1: 呼び出し元の GID が使用されます。
 -1
rename-dir-limit 指定した上限よりも子孫の少ないディレクトリの名前を変更できます。 0～2147483647 の整数。 0
temp-dir Cloud Storage にアップロードする前に書き込みがステージングされる一時ディレクトリのパスを指定します。 文字列パス（例: "/mnt/ssd/example-user-gcsfuse-temp-dir"）。 "/tmp"
uid すべての i ノードのユーザー識別子（UID）所有者を指定します。
  • UID を表す整数。
  • -1: 呼び出し元の UID が使用されます。
 -1
foreground フォアグラウンドで gcsfuse コマンドを実行します。 ブール値: true、false false
max-retry-sleep 指数バックオフを使用した再試行ループで Cloud Storage FUSE がスリープできる最大時間を指定します。バックオフ時間が指定の最大時間を超えると、指定された最大時間で再試行が続行されます。 時間（例: 1h5m50s（1 時間 5 分 50 秒）、60s（60 秒））。 30s
multiplier 連続する再試行間の指数バックオフの乗数を指定します。 浮動小数点数 "2"
stackdriver-export-interval 指定した間隔で指標を Stackdriver にエクスポートします。 時間（例: 1h5m50s（1 時間 5 分 50 秒））。0s はエクスポートなしを指定します。 0s
log-mutex ミューテックスの保持時間が長くなりすぎると、デバッグ メッセージを出力します。このオプションを指定すると、ログの重大度が自動的に trace に設定されます。これには、トレースログ、デバッグログ、情報ログ、警告ログ、エラーログが含まれます。 ブール値: true、false。 false
exit-on-invariant-violation 内部バリアントの違反が検出されると、プログラムを終了します。 ブール値: true、false。 false