サービスの Cloud Storage ボリュームのマウントの構成

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

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

メモリ要件

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

すべての Cloud Storage FUSE キャッシュに対して、Cloud Run はデフォルトで統計キャッシュの設定を使用し、有効期間（TTL）を 60 秒に設定します。統計キャッシュのデフォルトの最大サイズは 32 MB、タイプキャッシュのデフォルトの最大サイズは 4 MB です。
Cloud Storage FUSE は、読み取り時に、統計キャッシュとタイプキャッシュ以外のメモリも消費します。たとえば、ファイルを読み取るたびに、および goroutines を実行するたびに、1 MiB の配列を消費します。
Cloud Storage に書き込む場合は、ファイル全体が Cloud Run のメモリにステージングされた後、Cloud Storage に書き込まれます。

制限事項

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 に次の IAM ロールを付与するよう管理者に依頼してください。

Storage 管理者（roles/storage.admin）

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

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

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

複数のバケットを異なるマウントパスにマウントできます。複数のコンテナで同じマウントパスまたは異なるマウントパスを使用して、ボリュームを複数のコンテナにマウントすることもできます。

コンテナを複数使用する場合は、まずボリュームを指定してから、各コンテナのボリュームマウントを指定します。

ボリュームのマウントには、第 2 世代の実行環境が必要です。実行環境が明示的に構成されていない場合、Cloud Run はサービスの第 2 世代の実行環境を自動的に選択します。

コンソール

Google Cloud コンソールで、[Cloud Run] に移動します。

Cloud Run に移動
[コンテナをデプロイ] をクリックし、[サービス] を選択して、新しいサービスを構成します。既存のサービスを構成する場合は、サービスをクリックし、[新しいリビジョンの編集とデプロイ] をクリックします。
新しいサービスを構成する場合は、最初のサービス設定のページに入力してから、[コンテナ、ボリューム、ネットワーキング、セキュリティ] をクリックしてサービス構成ページを開きます。
[ボリューム] タブをクリックします。
- - [ボリュームを追加] をクリックします。
  - [ボリュームのタイプ] プルダウンで、ボリュームタイプとして Cloud Storage バケットを選択します。
  - [ボリューム名] フィールドに、ボリュームに使用する名前を入力します。
  - ボリュームに使用する Cloud Storage バケットを参照して選択するか、必要に応じて新しいバケットを作成します。
  - バケットを読み取り専用にする場合は、[読み取り専用] チェックボックスをオンにします。
  - [完了] をクリックします。
  [コンテナ] タブをクリックします。
  - [ボリュームのマウント] タブをクリックします。
  - [ボリュームをマウント] をクリックします。
  - メニューからストレージボリュームを選択します。
  - ボリュームをマウントするパスを指定します。
  - [完了] をクリックします
[作成] または [デプロイ] をクリックします。

gcloud

ボリュームを追加してマウントするには:
```
gcloud run services update SERVICE \
--add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME \
--add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH
```
次のように置き換えます。
- SERVICE: 実際のサービスの名前。
- MOUNT_PATH は、ボリュームをマウントする相対パス（/mnt/my-volume など）に置き換えます。
- VOLUME_NAME は、ボリュームに付ける名前に置き換えます。VOLUME_NAME 値は、ボリュームをボリュームマウントにマッピングするために使用されます。
- BUCKET_NAME: Cloud Storage バケットの名前。
ボリュームを読み取り専用ボリュームとしてマウントするには:
```
--add-volume=name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME,readonly=true
```

複数のコンテナを使用している場合は、まずボリュームを指定してから、各コンテナのボリュームマウントを指定します。

gcloud run services update SERVICE \
--add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME \
--container CONTAINER_1 \
--add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH \
--container CONTAINER_2 \
--add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH2

YAML

新しいサービスを作成する場合は、この手順をスキップします。既存のサービスを更新する場合は、その YAML 構成をダウンロードします。
```
gcloud run services describe SERVICE --format export > service.yaml
```
必要に応じて更新します。
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
spec:
  template:
    metadata:
      annotations:
        run.googleapis.com/execution-environment: gen2
    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
```
次のように置き換えます。
- IMAGE_URL: コンテナイメージへの参照（us-docker.pkg.dev/cloudrun/container/hello:latest など）。Artifact Registry を使用する場合は、リポジトリ REPO_NAME がすでに作成されている必要があります。URL の形式は LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG です。
- MOUNT_PATH は、ボリュームをマウントする相対パス（/mnt/my-volume など）に置き換えます。
- VOLUME_NAME は、ボリュームに付ける名前に置き換えます。VOLUME_NAME 値は、ボリュームをボリュームマウントにマッピングするために使用されます。
- ボリュームを読み取り専用にする場合は IS_READ_ONLY を True に置き換えます。書き込み可能にするには False に置き換えます。
- BUCKET_NAME は、Cloud Storage バケットの名前にします。
次のコマンドを使用して、サービスを作成または更新します。
```
gcloud run services replace service.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");

ボリュームマウント設定を表示する

Cloud Run サービスの現在のボリュームマウント設定を表示するには:

コンソール

Google Cloud コンソールで、[Cloud Run] に移動します。

Cloud Run に移動
目的のサービスをクリックして、[サービスの詳細] ページを開きます。
[変更内容] タブをクリックします。
右側の詳細パネルで、[ボリューム] タブにボリュームマウントの設定が表示されます。

gcloud

次のコマンドを使用します。
```
gcloud run services describe SERVICE
```
返された構成で、ボリュームマウント設定を見つけます。

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

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

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

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

Cloud Storage FUSE を使用すると、コンテナの起動前にボリュームマウントが開始されるため、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 以上で、コンテンツが追加されている場合です。

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

サービスの Cloud Storage ボリュームのマウントの構成

メモリ要件

制限事項

使用できないパス

始める前に

必要なロール

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

コンソール

gcloud

YAML

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

Node.js

Python

Go

Java

ボリューム マウント設定を表示する

コンソール

gcloud

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

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

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

ボリュームマウント設定を表示する