Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

インスタンスの Cloud Storage ボリュームのマウントを構成する

このページでは、Cloud Run のボリュームマウントを使用して、Cloud Storage バケットをストレージボリュームとしてマウントする方法について説明します。

Cloud Run でバケットをボリュームとしてマウントすると、バケットの内容がコンテナファイルシステムのファイルとして提示されます。バケットをボリュームとしてマウントした後、Google API クライアントライブラリではなく、プログラミング言語のファイルシステムオペレーションとライブラリを使用して、バケットにローカルファイルシステムのディレクトリのようにアクセスします。

ボリュームを読み取り専用としてマウントできます。また、ボリュームのマウントオプションを指定することもできます。

メモリ要件

Cloud Storage ボリュームマウントでは、次のアクティビティに Cloud Run のコンテナメモリが使用されます。

すべての Cloud Storage FUSE キャッシュに対して、Cloud Run はデフォルトで統計キャッシュの設定を使用し、有効期間（TTL）を 60 秒に設定します。統計キャッシュのデフォルトの最大サイズは 32 MB、タイプキャッシュのデフォルトの最大サイズは 4 MiB です。
Cloud Storage から読み取る場合、Cloud Storage FUSE は API 呼び出しを行ってオブジェクトを直接読み取ります。ファイル全体をローカルディレクトリにダウンロードすることはありません。Cloud Storage FUSE は TCP 接続を確立し、Cloud Storage オブジェクト全体を読み取るか、アプリケーションまたはオペレーティングシステムでオフセットを介して指定したファイルの一部のみを読み取ります。Cloud Storage FUSE は、読み取り時に、統計キャッシュとタイプキャッシュ以外のメモリも消費します。たとえば、読み取るファイルごとに 1 MiB の配列を消費し、goroutines を実行するたびに 1 MiB の配列を消費します。
Cloud Storage に書き込む場合、Cloud Storage FUSE は書き込みパスである streaming-writes をデフォルトでサポートします。Cloud Storage FUSE は、ファイルを完全にステージングせずに、データを Cloud Storage に直接アップロードします。ストリーミング用に開いた各ファイルは、アップロードプロセス中に約 64 MiB のメモリを消費します。これにより、レイテンシとディスク容量の使用量が削減されます。そのため、大規模なシーケンシャル書き込みで特に有効です。

制限事項

Cloud Run は、このボリュームマウントに Cloud Storage FUSE を使用するため、Cloud Storage バケットをボリュームとしてマウントする場合は、次の点に注意してください。

Cloud Storage FUSE では、同じファイルへの複数書き込みの同時実行制御（ファイルのロック）は行いません。複数の書き込みによってファイルの置き換えが試みられた場合は、最後の書き込みが有効となり、それより前の書き込みはすべて失われます。
Cloud Storage FUSE は POSIX を完全に遵守したファイルシステムではありません。詳細については、Cloud Storage FUSE のドキュメントをご覧ください。

使用できないパス

Cloud Run では、/dev、/proc、/sys、またはそのサブディレクトリにボリュームをマウントすることはできません。

始める前に

ボリュームとしてマウントするには、Cloud Storage バケットが必要です。

Cloud Storage への読み取り / 書き込みのパフォーマンスを最適化するには、Cloud Storage FUSE ネットワーク帯域幅のパフォーマンスの最適化をご覧ください。

必要なロール

Cloud Storage ボリュームマウントの構成に必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。

Cloud Run インスタンスに対する Cloud Run デベロッパー（roles/run.developer）
サービス ID に対するサービスアカウントユーザー（roles/iam.serviceAccountUser）ロール

ファイルと Cloud Storage バケットにアクセスするためにサービス ID に必要な権限を取得するには、サービス ID に Storage オブジェクト閲覧者（roles/storage.objectViewer）ロールを付与するよう管理者に依頼してください。サービス ID がバケット内で書き込みオペレーションも実行する必要がある場合は、代わりに Storage オブジェクトユーザー（roles/storage.objectUser）ロールを付与します。

Cloud Storage のロールと権限の詳細については、Cloud Storage の IAM をご覧ください。

Cloud Run に関連付けられている IAM ロールと権限のリストについては、Cloud Run IAM ロールと Cloud Run IAM 権限をご覧ください。Cloud Run インスタンスがGoogle Cloud API（Cloud クライアントライブラリなど）と連携している場合は、サービス ID の構成ガイドをご覧ください。ロールの付与の詳細については、デプロイ権限とアクセスの管理をご覧ください。

Cloud Storage ボリュームをマウントする

Cloud Run インスタンスの Cloud Storage ボリュームを構成するには、Google Cloud CLI または YAML を使用します。

gcloud

ボリュームマウントを追加するには:

gcloud beta run instances update INSTANCE \
--add-volume mount-path=MOUNT_PATH,type=cloud-storage,bucket=BUCKET_NAME,readonly=READ_ONLY

次のように置き換えます。

INSTANCE: インスタンスの名前。
MOUNT_PATH: ボリュームをマウントする相対パス（/mnt/my-volume など）。
BUCKET_NAME: Cloud Storage バケットの名前。
READ_ONLY: ボリュームを読み取り専用にする場合は true、書き込み可能にする場合は false。

YAML

新しいインスタンスを作成する場合は、この手順をスキップします。既存のインスタンスを更新する場合は、その YAML 構成をダウンロードします。
```
gcloud beta run instances describe INSTANCE --format export > instance.yaml
```
次の例には、YAML 構成が含まれています。
```
apiVersion: run.googleapis.com/v1
kind: Instance
metadata:
  name: INSTANCE
  annotations:
    run.googleapis.com/launch-stage: BETA
spec:
  containers:
  - image: IMAGE_URL
    volumeMounts:
    - name: VOLUME_NAME
      mountPath: MOUNT_PATH
  volumes:
  - name: VOLUME_NAME
    csi:
      driver: gcsfuse.run.googleapis.com
      readOnly: IS_READ_ONLY
      volumeAttributes:
        bucketName: BUCKET_NAME
```
次のように置き換えます。
- INSTANCE: Cloud Run インスタンスの名前。
- IMAGE_URL: コンテナイメージへの参照（us-docker.pkg.dev/cloudrun/container/hello:latest など）。
- VOLUME_NAME: ボリュームに付ける名前。VOLUME_NAME 値は、ボリュームをボリュームマウントにマッピングするために使用されます。
- MOUNT_PATH: ボリュームをマウントする相対パス（/mnt/my-volume など）。
- IS_READ_ONLY: ボリュームを読み取り専用にする場合は True、書き込み可能にする場合は False。
- BUCKET_NAME: Cloud Storage バケットの名前。
次のコマンドを使用して、インスタンスを作成または更新します。
```
gcloud beta run instances replace instance.yaml
```

ボリュームの読み取りと書き込み

Cloud Run のボリュームマウント機能を使用する場合、ローカルファイルシステムでファイルの読み取りと書き込みに使用するプログラミング言語のライブラリを使用して、マウントされたボリュームにアクセスします。

これは、ローカルファイルシステムにデータが保存されることを想定し、通常のファイルシステムオペレーションを使用してデータにアクセスする既存のコンテナを使用している場合に特に便利です。

次のスニペットは、mountPath が /mnt/my-volume に設定されたボリュームマウントを前提としています。

Node.js

ファイルシステムモジュールを使用してボリューム /mnt/my-volume に新しいファイルを作成するか、既存のファイルに追加します。

var fs = require('fs');
fs.appendFileSync('/mnt/my-volume/sample-logfile.txt', 'Hello logs!', { flag: 'a+' });

Python

ボリューム /mnt/my-volume に保存されているファイルに書き込みます。

f = open("/mnt/my-volume/sample-logfile.txt", "a")

Go

os パッケージを使用して、ボリューム /mnt/my-volume に新しいファイルを作成します。

f, err := os.Create("/mnt/my-volume/sample-logfile.txt")

Java

Java.io.File クラスを使用して、ボリューム /mnt/my-volume にログファイルを作成します。

import java.io.File;
File f = new File("/mnt/my-volume/sample-logfile.txt");

マウントオプションを使用したボリュームの構成

必要に応じて、マウントオプションを使用して、ボリュームマウントのさまざまなプロパティを構成できます。使用可能なマウントオプションを使用すると、キャッシュ設定の構成、特定のディレクトリのマウント、デバッグロギングの有効化などの動作を実行できます。

マウントオプションを指定する

マウントオプションは、Google Cloud CLI または YAML を使用して指定できます。マウントオプションは、Google Cloud CLI ではセミコロン（;）で区切りますが、YAML ではカンマで区切ります。次のタブに例を示します。

よく使用されるマウントオプション

マウントオプションは通常、次の目的で使用されます。

キャッシュ設定を構成する
Cloud Storage バケットから特定のディレクトリのみをマウントする
ボリュームの所有権を構成する（uid、gid）
暗黙的なディレクトリを無効にする
デバッグロギングレベルを指定する

キャッシュ設定を構成する

キャッシュ保存関連のマウントオプションを設定することで、ボリュームのキャッシュ設定を変更できます。次の表に、これらの設定と、デフォルトの Cloud Run 値を示します。

キャッシュ設定	説明	デフォルト
`cache-dir`	Cloud Storage バケットのファイルを `cr-volume:{volume name}` 形式で保持するための基盤となるディレクトリとして使用するインメモリボリューム名。たとえば、キャッシュディレクトリとして使用する `in-memory-1` という名前のインメモリボリュームがある場合は、`cr-volume:in-memory-1` を指定します。インメモリボリュームの設定手順については、サービスのインメモリボリュームのマウントを構成するをご覧ください。これらの機能を有効にすると、Cloud Run は Cloud Storage FUSE プロセスのリソースアカウンティングを変更し、コンテナのメモリ上限にカウントします。コンテナのメモリ上限を引き上げるには、サービスのメモリ上限を構成するをご覧ください。
`file-cache-download-chunk-size-mb`	オブジェクトをファイルキャッシュにダウンロードするときに、各 goroutine が Cloud Storage に対して行う 1 回の読み取りリクエストのサイズを MiB で指定します。	200
`file-cache-enable-parallel-downloads`	ファイルキャッシュディレクトリをプリフェッチバッファとして使用し、複数のワーカーを使用してファイルの複数の部分を並列でダウンロードすることで、サイズの大きいファイルの読み取りを高速化します。	true
`file-cache-max-parallel-downloads`	ファイルのダウンロードジョブ全体で、任意の時点で生成できる goroutine の最大数。	マシン上の CPU コア数の 2 倍、または 16 のいずれか大きいほう。
`file-cache-parallel-downloads-per-file`	ファイルあたりの同時ダウンロードリクエストの数。	16
`file-cache-cache-file-for-range-read`	ゼロ以外のオフセットから最初の読み取りが行われたときに、オブジェクト全体を非同期的にダウンロードして Cloud Storage FUSE キャッシュディレクトリに保存するかどうかを示します。	false
`stat-cache-max-size-mb`	統計情報キャッシュで使用できる最大サイズ（MiB）。統計情報キャッシュは常にメモリ内に保持されるため、メモリ消費に影響します。ワークロードに最大 20,000 個のファイルが含まれる場合は、`32` の値を指定します。ワークロードで 20,000 を超えるファイルを使用する場合は、6,000 ファイル追加するごとにサイズを `10` ずつ増やします。統計情報キャッシュはファイルあたり平均 1,500 バイトを使用します。統計情報キャッシュが必要なだけメモリを使用できるようにするには、値 `-1` を指定します。統計情報キャッシュを無効にするには、値 `0` を指定します。	32
`type-cache-max-size-mb`	タイプキャッシュが使用できるディレクトリあたりの最大サイズ（MiB 単位）。タイプキャッシュは常にメモリ内に完全に保持されるため、メモリ消費に影響します。マウントするバケットの 1 つのディレクトリ内にあるファイルの最大数が 20,000 以下の場合は、値 `4` を指定します。マウントする 1 つのディレクトリ内のファイルの最大数が 20,000 を超える場合は、5,000 ファイルごとに値を `1` 増やします（ファイルあたり平均約 200 バイト）。タイプキャッシュが必要なだけメモリを使用できるようにするには、値 `-1` を指定します。タイプキャッシュを無効にするには、値 `0` を指定します。	4

次の Google Cloud CLI コマンドは、metadata-cache-ttl-secs を 120 秒に設定し、統計情報とタイプキャッシュ容量をそれぞれ 52 MiB と 7 MiB に増やします。

デバッグロギングを有効にする

デフォルトでは、Cloud Storage FUSE は重大度が Info 以上のイベントをログに記録します。ロギング設定は、次のいずれかのログ重大度レベルを使用して変更できます（低い順に表示しています）。

trace
debug
info
warning
error
すべてのロギングをオフにするには、値 off を指定します。

重大度レベルを指定すると、Cloud Storage FUSE は、指定された重大度レベル以上の重大度レベルのイベントのログを生成します。たとえば、warning レベルを指定すると、Cloud Storage FUSE は警告とエラーのログを生成します。

ロギングの重大度を info より高いレベルに設定すると、パフォーマンスに影響し、大量のロギングデータが生成される可能性があるため、必要な場合にのみ設定することをおすすめします。クラウドロギングとの互換性を確保するため、ログ形式は text 形式であり、json 形式はサポートされていません。

次のコマンドラインを使用すると、デバッグロギングが有効になります。

gcloud beta run instances update INSTANCE \
    --add-volume mount-path=MOUNT_PATH,type=cloud-storage,bucket=BUCKET_NAME,mount-options="log-severity=debug"

次のように置き換えます。

INSTANCE: インスタンスの名前。
MOUNT_PATH: ボリュームをマウントする相対パス（/cache など）。
BUCKET_NAME: Cloud Storage バケットの名前。

暗黙的なディレクトリを無効にする

Cloud Storage を標準のファイルシステムのように見せるため、Cloud Run では、Cloud Storage バケットのマウント時に暗黙のディレクトリがデフォルトで有効になります。暗黙的なディレクトリは、implicit-dirs マウントオプションを使用して無効にできます。暗黙的なディレクトリを無効にすると、パフォーマンスと費用を改善できますが、互換性が犠牲になります。

暗黙的なディレクトリ機能を使用すると、ファイル名がディレクトリ構造を模倣している既存の Cloud Storage ファイルを Cloud Run で認識できます（例: /mydir/myfile.txt）。暗黙的なディレクトリを無効にすると、Cloud Run はそのようなファイルを一覧表示または読み取ることができなくなります。

暗黙的なディレクトリをオフにすると、Cloud Storage へのリクエスト数が減り、アプリケーションのパフォーマンスと費用が改善される可能性があります。詳細については、Cloud Storage FUSE のファイルとディレクトリのドキュメントをご覧ください。

次のコマンドラインでは、暗黙的なディレクトリが無効になります。

gcloud beta run instances update INSTANCE \
    --add-volume mount-path=MOUNT_PATH,type=cloud-storage,bucket=BUCKET_NAME,mount-options="implicit-dirs=false"

次のように置き換えます。

INSTANCE: インスタンスの名前。
MOUNT_PATH: ボリュームをマウントする相対パス（/cache など）。
BUCKET_NAME: Cloud Storage バケットの名前。

Cloud Storage バケット内の特定のディレクトリをマウントする

デフォルトでは、Cloud Run は Cloud Storage バケット全体をマウントします。これにより、Cloud Run インスタンスはすべてのコンテンツにアクセスできます。特定のディレクトリのみをマウントすることが必要な場合があります。たとえば、バケットに大量のファイルが含まれている場合は、特定のディレクトリをマウントするとパフォーマンスが向上します。

分離目的で、異なるインスタンスがストレージバケット内の異なるディレクトリにアクセスする必要がある場合にも、同じように実装できます。

次のコマンドラインでは、マウントするディレクトリを指定します。

gcloud beta run instances update INSTANCE \
    --add-volume mount-path=MOUNT_PATH,type=cloud-storage,bucket=BUCKET_NAME,mount-options="only-dir=images"

次のように置き換えます。

INSTANCE: インスタンスの名前。
MOUNT_PATH: ボリュームをマウントする相対パス（/cache など）。
BUCKET_NAME: Cloud Storage バケットの名前。

ボリューム `UID` と `GID` を設定する

uid マウントオプションと gid マウントオプションを使用して、ボリュームのユーザー ID とグループ ID を変更します。これは、実行中の 1 つ以上のコンテナの ID に一致する特定のユーザーまたはグループにファイルの所有権を設定する場合に便利です。デフォルトでは、ボリュームは root が所有します。

次のコマンドラインは、uid と gid を設定します。

gcloud beta run instances update INSTANCE \
    --add-volume mount-path=MOUNT_PATH,type=cloud-storage,bucket=BUCKET_NAME,mount-options="uid=UID;gid=GID"

次のように置き換えます。

INSTANCE: インスタンスの名前。
MOUNT_PATH: ボリュームをマウントする相対パス（/cache など）。
BUCKET_NAME: Cloud Storage バケットの名前。
UID: ボリュームをマウントするユーザー ID。
GID: ボリュームをマウントするグループ ID。

その他のマウントオプションを設定する

Cloud Run でサポートされているすべてのマウントオプションの一覧は次のとおりです。

ディレクトリ

implicit-dirs
only-dir
rename-dir-limit

デバッグ

debug_fuse_errors
debug_fuse
debug_gcs
debug-invariants
debug_mutex

キャッシュ

stat-cache-capacity
stat-cache-ttl
type-cache-ttl
enable-nonexistent-type-cache

権限

uid
gid
file-mode
dir-mode

その他

billing-project
client-protocol
experimental-enable-json-read
experimental-opentelemetry-collector-address
http-client-timeout
limit-bytes-per-sec
limit-ops-per-sec
max-conns-per-host
max-idle-conns-per-host
max-retry-sleep
-o
retry-multiplier
sequential-read-size-mb
stackdriver-export-interval

これらのオプションの詳細については、Cloud Storage FUSE コマンドラインのマウントオプションをご覧ください。Cloud Storage FUSE のページには、使用可能なすべての FUSE オプションが記載されていますが、その一部は Cloud Run で対象外です。

Cloud Storage FUSE ネットワーク帯域幅のパフォーマンスを最適化する

読み取りと書き込みのパフォーマンスを向上させるには、ダイレクト VPC を使用して Cloud Run インスタンスを VPC ネットワークに接続し、すべてのアウトバウンドトラフィックを VPC ネットワーク経由でルーティングします。これは、次のいずれかの方法で行うことができます。

プライベート Google アクセスを有効にし、vpc-egress パラメータを all-traffic に設定します。
ネットワーキングのベストプラクティスページの Google API への内部トラフィックで説明されているオプションのいずれかを使用します。

コンテナの起動時間と Cloud Storage FUSE のマウント

Cloud Storage FUSE を使用すると、Cloud Run はコンテナの起動前にボリュームマウントを開始するため、Cloud Run コンテナのコールドスタート時間がわずかに長くなる可能性があります。コンテナは、Cloud Storage FUSE が正常にマウントされた場合にのみ起動します。

Cloud Storage FUSE は、Cloud Storage への接続を確立した後にのみ、ボリュームを正常にマウントします。ネットワークの遅延は、コンテナの起動時間に影響する可能性があります。同様に、接続の試行が失敗すると、Cloud Storage FUSE はマウントされず、Cloud Run インスタンスは起動しません。また、Cloud Run のすべてのマウント処理の合計タイムアウトが 30 秒であるため、Cloud Storage FUSE のマウントに 30 秒以上かかると、Cloud Run インスタンスの開始に失敗します。

Cloud Storage FUSE のパフォーマンス特性

それぞれが異なるバケットを指す 2 つのボリュームを定義すると、2 つの Cloud Storage FUSE プロセスが開始されます。マウント処理とプロセスは並行して行われます。

Cloud Storage FUSE は Cloud Storage API を使用して Cloud Storage と通信するため、Cloud Storage FUSE を使用するオペレーションはネットワーク帯域幅の影響を受けます。ネットワーク帯域幅が少ない場合、バケットのコンテンツのリストの取得など、オペレーションが遅くなることがあります。同様に、サイズの大きなファイルの読み取りには時間がかかります。これは、ネットワーク帯域幅によって制限されるためです。

バケットに書き込むと、Cloud Storage FUSE はオブジェクトをメモリに完全にステージングします。つまり、大きなファイルの書き込みは、コンテナインスタンスで使用可能なメモリ量によって制限されます（コンテナのメモリの最大上限は 32 GiB です）。

書き込みは、close または fsync を実行した場合にのみバケットにフラッシュされます。その後、完全なオブジェクトがバケットにアップロードまたは再アップロードされます。オブジェクトがバケットに完全に再アップロードされる唯一の例外は、ファイルが 2 MiB 以上で、コンテンツが追加されている場合です。

詳しくは、次のリソースをご覧ください。

ボリュームとボリュームマウントを消去して削除する

すべてのボリュームとマウントを消去できます。または、個々のボリュームとボリュームマウントを削除することもできます。

すべてのボリュームとボリュームマウントを消去する

単一コンテナのインスタンスからすべてのボリュームとボリュームマウントを消去するには、次のコマンドを実行します。

gcloud beta run instances update INSTANCE \
    --clear-volumes \
    --clear-volume-mounts

個々のボリュームとボリュームマウントを削除する

ボリュームを削除するには、そのボリュームを使用するすべてのボリュームマウントも削除する必要があります。

個々のボリュームまたはボリュームマウントを削除するには、remove-volume フラグと remove-volume-mount フラグを使用します。

gcloud beta run instances update INSTANCE \
    --remove-volume VOLUME_NAME \
    --container=container1 \
    --remove-volume-mount MOUNT_PATH \
    --container=container2 \
    --remove-volume-mount MOUNT_PATH

インスタンスの Cloud Storage ボリュームのマウントを構成する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

メモリ要件

制限事項

使用できないパス

始める前に

必要なロール

Cloud Storage ボリュームをマウントする

gcloud

YAML

ボリュームの読み取りと書き込み

Node.js

Python

Go

Java

マウント オプションを使用したボリュームの構成

マウント オプションを指定する

よく使用されるマウント オプション

キャッシュ設定を構成する

デバッグ ロギングを有効にする

暗黙的なディレクトリを無効にする

Cloud Storage バケット内の特定のディレクトリをマウントする

ボリューム UID と GID を設定する

その他のマウント オプションを設定する

Cloud Storage FUSE ネットワーク帯域幅のパフォーマンスを最適化する

コンテナの起動時間と Cloud Storage FUSE のマウント

Cloud Storage FUSE のパフォーマンス特性

ボリュームとボリューム マウントを消去して削除する

すべてのボリュームとボリューム マウントを消去する

個々のボリュームとボリューム マウントを削除する

インスタンスの Cloud Storage ボリュームのマウントを構成する

マウントオプションを使用したボリュームの構成

マウントオプションを指定する

よく使用されるマウントオプション

デバッグロギングを有効にする

ボリューム `UID` と `GID` を設定する

その他のマウントオプションを設定する

ボリュームとボリュームマウントを消去して削除する

すべてのボリュームとボリュームマウントを消去する

個々のボリュームとボリュームマウントを削除する