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

GKE 用に Cloud Storage FUSE CSI ドライバのサイドカーコンテナを構成する

Autopilot Standard

このドキュメントでは、Google Kubernetes Engine（GKE）で Cloud Storage FUSE CSI ドライバのサイドカーコンテナのリソース設定を構成する方法について説明します。

GKE でアプリケーションのパフォーマンスとリソース使用率を最適化するには、Cloud Storage FUSE CSI ドライバのサイドカーコンテナに特定のリソース設定を構成します。限定公開イメージ、カスタム書き込みバッファ、カスタム読み取りキャッシュボリュームなどのリソースを設定することで、アプリケーションが Cloud Storage とどのようにやり取りするかをより細かく制御できます。これらの構成により、データアクセスの高速化、処理時間の短縮、GKE クラスタの全体的なリソース使用量の削減が可能になります。

このドキュメントは、アプリケーションのパフォーマンスを最適化するデベロッパー、管理者、アーキテクトを対象としています。 Google Cloud のコンテンツで使用されている一般的なロールとタスクの例の詳細については、一般的な GKE ユーザーのロールとタスクをご覧ください。

始める前に、次のワークロードとストレージのコンセプトを理解しておいてください。

サイドカーコンテナの仕組み

Cloud Storage FUSE CSI ドライバは、サイドカーコンテナを使用して Cloud Storage バケットをマウントし、Kubernetes アプリケーションからローカルファイルシステムとしてアクセスできるようにします。このサイドカーコンテナ（gke-gcsfuse-sidecar）は、同じ Pod 内のワークロードコンテナとともに実行されます。ドライバは、Pod 仕様で gke-gcsfuse/volumes: "true" アノテーションを検出すると、サイドカーコンテナを自動的に挿入します。このサイドカーコンテナのアプローチは、セキュリティを確保し、リソースを効果的に管理するうえで役立ちます。

サイドカーコンテナは、Cloud Storage バケットのマウントの複雑さを解消し、Cloud Storage FUSE ランタイムを直接管理することなく、アプリケーションへのファイルシステムアクセスを提供します。gke-gcsfuse/cpu-limit や gke-gcsfuse/memory-limit などのアノテーションを使用して、サイドカーコンテナのリソース上限を構成できます。サイドカーコンテナモデルでは、Cloud Storage FUSE インスタンスがワークロードのライフサイクルに関連付けられるため、リソースが不要に消費されることはありません。つまり、ワークロードコンテナが終了すると、サイドカーコンテナは自動的に終了します（特に、RestartPolicy が Never の Job ワークロードまたは Pod の場合）。

OSS Istio の互換性

Cloud Storage FUSE CSI ドライバのサイドカーコンテナと Istio は、Pod 内で共存して同時に実行できます。ただし、GKE バージョン 1.29 以降では、Istio プロキシの準備が整う前に Cloud Storage FUSE がメタデータサーバーに接続しようとすると、認証エラーが発生することがあります。このような認証エラーが発生した場合は、Pod 仕様の metadata.annotations に traffic.sidecar.istio.io/excludeOutboundIPRanges: 169.254.169.254/32 を追加することで、この問題を解決できます。このアノテーションは、GKE メタデータサーバーの IP アドレスをリダイレクトから除外するように Istio を構成します。

カスタム書き込みバッファを構成する

Cloud Storage FUSE は、ローカルディレクトリに書き込みをステージングし、close オペレーションまたは fsync オペレーションで Cloud Storage にアップロードします。

このセクションでは、Cloud Storage FUSE 書き込みバッファリング用のカスタムバッファボリュームを構成する方法について説明します。このシナリオは、Cloud Storage FUSE のデフォルトの emptyDir ボリュームを置き換えて、書き込みオペレーションでファイルをステージングする必要がある場合に適用できます。これは、Autopilot クラスタで 10 GiB を超えるファイルを書き込む必要がある場合に有効です。

ファイルキャッシュに、Cloud Storage FUSE CSI ドライバでサポートされている任意のタイプのストレージ（ローカル SSD、Persistent Disk ベースのストレージ、RAM ディスク（メモリ）など）を指定できます。GKE は、指定されたボリュームをファイルの書き込みバッファに使用します。これらのオプションの詳細については、ファイルキャッシュのバックアップ用ストレージを選択するをご覧ください。

Persistent Disk にバックアップされたカスタムバッファボリュームを使用するには、Pod の securityContext でゼロ以外の fsGroup を指定する必要があります。このステップでは、ボリュームに必要な読み取り権限または書き込み権限が非 root サイドカーコンテナに付与されます。Cloud Storage FUSE CSI ドライバを使用して PVC が Cloud Storage バケットを永続ボリュームとしてマウントする場合、この設定は必要ありません。

次の例は、バッファボリュームとして事前定義済みの PersistentVolumeClaim を使用する方法を示しています。

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  securityContext:
    fsGroup: FS_GROUP
  containers:
  ...
  volumes:
  - name: gke-gcsfuse-buffer
    persistentVolumeClaim:
      claimName: BUFFER_VOLUME_PVC

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

FS_GROUP: fsGroup ID。
BUFFER_VOLUME_PVC: 事前定義された PVC 名。

カスタム読み取りキャッシュボリュームを構成する

このセクションでは、Cloud Storage FUSE 読み取りキャッシュ用にカスタムキャッシュボリュームを構成する方法について説明します。

このシナリオは、Cloud Storage FUSE のデフォルトの emptyDir ボリュームを置き換えて、読み取りオペレーションでファイルをキャッシュに保存する必要がある場合に適用できます。GKE でサポートされている任意のタイプのストレージ（PersistentVolumeClaim など）を指定できます。GKE は、指定されたボリュームをファイルキャッシュに使用します。これは、Autopilot クラスタで 10 GiB を超えるファイルをキャッシュに保存する必要がある場合に有効です。

Persistent Disk にバックアップされたカスタムキャッシュボリュームを使用するには、Pod の securityContext でゼロ以外の fsGroup を指定する必要があります。このステップでは、ボリュームに必要な読み取り権限または書き込み権限が非 root サイドカーコンテナに付与されます。Cloud Storage FUSE CSI ドライバを使用して PVC が Cloud Storage バケットを永続ボリュームとしてマウントする場合は、この設定は必要ありません。

次の例では、キャッシュボリュームとして事前定義済みの PersistentVolumeClaim を使用する方法を示します。

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  securityContext:
    fsGroup: FS_GROUP
  containers:
  ...
  volumes:
  - name: gke-gcsfuse-cache
    persistentVolumeClaim:
      claimName: CACHE_VOLUME_PVC

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

FS_GROUP: fsGroup ID。
CACHE_VOLUME_PVC: 事前定義された PersistentVolumeClaim 名。

サイドカーコンテナの非公開イメージを構成する

このセクションでは、限定公開コンテナレジストリにホストされているサイドカーコンテナイメージの使用方法について説明します。このシナリオは、セキュリティのために限定公開ノードを使用する必要がある場合に該当します。

限定公開のサイドカーコンテナイメージを構成して使用するには、次の操作を行います。

互換性のある公開サイドカーコンテナイメージについては、こちらの GKE 互換性表をご覧ください。
ローカル環境に pull して限定公開コンテナレジストリに push します。
マニフェストで、image フィールドのみを含む gke-gcsfuse-sidecar という名前のコンテナを指定します。GKE は、指定されたサイドカーコンテナイメージを使用して、サイドカーコンテナインジェクションを準備します。

以下に例を示します。
```
apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  containers:
  - name: gke-gcsfuse-sidecar
    image: PRIVATE_REGISTRY/gcs-fuse-csi-driver-sidecar-mounter:PRIVATE_IMAGE_TAG
  - name: main # your main workload container.
```
次のように置き換えます。
- PRIVATE_REGISTRY: 限定公開のコンテナレジストリ。例: us-central1-docker.pkg.dev/my-project/my-registry
- PRIVATE_IMAGE_TAG: 限定公開のサイドカーコンテナイメージのタグ。例: v1.17.1-gke.1

サイドカーコンテナリソースを構成する

デフォルトでは、gke-gcsfuse-sidecar コンテナは、Standard クラスタと Autopilot クラスタに対して次のリソースリクエストとリソース上限で構成されます。

リクエスト:

250m CPU
256 MiB のメモリ
5 GiB のエフェメラルストレージ

上限（GKE バージョン 1.29.1-gke.1670000 以降）:

無制限の CPU
無制限のメモリ
無制限のエフェメラルストレージ

上限（GKE バージョン 1.29.1-gke.1670000 より前）:

250m CPU
256 MiB のメモリ
5 GiB のエフェメラルストレージ

デフォルトでは、gke-gcsfuse-metadata-prefetch コンテナは、Standard クラスタと Autopilot クラスタに対して次のリソースリクエストとリソース上限で構成されます。

リクエスト:

10m CPU
10 MiB のメモリ
10 MiB のエフェメラルストレージ

上限:

50m CPU
250 MiB のメモリ
無制限のエフェメラルストレージ

Standard クラスタと Autopilot クラスタでデフォルト値を上書きできます。GKE によるコンテナリソースの処理方法は、クラスタの運用モードによって異なります。

Standard クラスタ: リクエストまたは上限のいずれかを設定し、もう一方は設定しないと、Pod のリソース上限とリソースリクエストが同じ値に設定されます。リクエストと上限の両方を設定すると、指定したリソースリクエストとリソース上限が Pod で正確に使用されます。値を設定しないと、デフォルトのリソース（上記を参照）が直接適用されます。
Autopilot クラスタ: リクエストまたは上限のいずれかを設定し、もう一方は設定しないと、Pod のリソース上限とリソースリクエストが同じ値に設定されます。リソースのオーバーライドと設定されたデフォルトのリソース値が Pod の動作にどのように影響するかについては、Autopilot でリソース制限を設定するをご覧ください。

gke-gcsfuse-metadata-prefetch コンテナのデフォルト値を上書きするには（GKE バージョン 1.32.3-gke.1717000 以降）、次の例に示すように、必要に応じてアノテーション gke-gcsfuse/[metadata-prefetch-cpu-limit|metadata-prefetch-memory-limit|metadata-prefetch-ephemeral-storage-limit|metadata-prefetch-cpu-request|metadata-prefetch-memory-request|metadata-prefetch-ephemeral-storage-request] を指定します。

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"

    # gke-gcsfuse-sidecar overrides
    gke-gcsfuse/cpu-limit: "10"
    gke-gcsfuse/memory-limit: 10Gi
    gke-gcsfuse/ephemeral-storage-limit: 1Ti
    gke-gcsfuse/cpu-request: 500m
    gke-gcsfuse/memory-request: 1Gi
    gke-gcsfuse/ephemeral-storage-request: 50Gi

    # gke-gcsfuse-metadata-prefetch overrides
    gke-gcsfuse/metadata-prefetch-cpu-limit: "10"
    gke-gcsfuse/metadata-prefetch-memory-limit: 10Gi
    gke-gcsfuse/metadata-prefetch-ephemeral-storage-limit: 1Ti
    gke-gcsfuse/metadata-prefetch-cpu-request: 500m
    gke-gcsfuse/metadata-prefetch-memory-request: 1Gi
    gke-gcsfuse/metadata-prefetch-ephemeral-storage-request: 50Gi

値 "0" を使用するとリソース上限またはリソースリクエストの設定を解除できますが、gke-gcsfuse-sidecar コンテナはすでにすべての上限（cpu-limit、memory-limit、ephemeral-storage-limit）の設定が解除されており、gke-gcsfuse-metadata-prefetch コンテナはすでに ephemeral-storage-limit の設定が解除されているため、GKE バージョン 1.32.3-gke.1717000 以降のクラスタでこれらの上限を "0" に設定しても効果はありません。

たとえば、gke-gcsfuse-metadata-prefetch コンテナのメモリ上限の設定を解除するには gke-gcsfuse/metadata-prefetch-memory-limit: "0" を設定します。これは、ワークロードでメタデータプリフェッチ機能に必要なリソースの量を特定できない場合に、ノード上の使用可能なすべてのリソースをメタデータプリフェッチで消費できるようにするのに便利です。

（省略可）Cloud Profiler を使用してパフォーマンスを分析する

Cloud Profiler を使用すると、ストレージを多用するアプリケーションのリソース消費を継続的かつ詳細に把握できます。この詳細なデータは、Cloud Storage FUSE CSI ドライバとそのサイドカーコンテナの CPU とメモリ使用量をプロアクティブにモニタリングするのに役立ちます。Cloud Profiler のデータから得られる分析情報は、非効率的なコードパスの特定、リソース割り当ての最適化、メモリリークや予期しないメモリ不足（OOM）イベントなどの複雑な問題のトラブルシューティングに役立ちます。これらの問題がサービスの安定性に影響を与える前に解決できます。

Cloud Profiler の使用は任意であり、詳細なパフォーマンス診断を必要とする管理者を対象としています。Cloud Profiler は、ノードドライバでデフォルトで有効になっています。サイドカーコンテナの場合、これは手動で有効にできるオプトイン機能です。

Cloud Profiler を有効にする前に

Cloud Storage FUSE CSI ドライバで Cloud Profiler を使用するには、GKE バージョン 1.36.0-gke.2403000 以降を使用していることを確認してください。プロファイルを生成する前に、Cloud Profiler API を有効にして、プロファイリングするコンポーネントに適切な IAM 権限を構成する必要があります。

API を有効にする

Cloud Profiler API を有効にする

ノードドライバに権限を付与する

プロファイリングデータを Cloud Profiler に送信するには、ノードドライバに IAM 権限が必要です。ノードドライバはデフォルトでホストネットワークで実行されるため、Workload Identity Federation for GKE ではなく、GKE ノードに関連付けられた IAM サービスアカウントを使用して認証を行います。

ノードのサービスアカウントに roles/cloudprofiler.agent ロールを付与します。

gcloud projects add-iam-policy-binding PROJECT_ID \
    --role=roles/cloudprofiler.agent \
    --member=serviceAccount:NODE_SERVICE_ACCOUNT

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

PROJECT_ID: 実際の Google Cloud プロジェクト ID。
NODE_SERVICE_ACCOUNT: GKE ノードで使用される IAM サービスアカウント。ノードが別のサービスアカウントを使用するように構成されていない限り、これは通常、デフォルトの Compute Engine サービスアカウント（PROJECT_NUMBER-compute@ など）です。

サイドカーコンテナに権限を付与する

プロファイリングデータを Cloud Profiler に送信するには、サイドカーコンテナと gcsfuse プロセスに IAM 権限が必要です。これらのコンポーネントは、ワークロード Pod に関連付けられた Kubernetes サービスアカウント（KSA）を使用する Workload Identity Federation for GKE を使用して認証を行います。

Pod が使用する KSA に roles/cloudprofiler.agent ロールを付与します。

gcloud projects add-iam-policy-binding projects/PROJECT_ID \
    --role=roles/cloudprofiler.agent \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME \
    --condition=None

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

PROJECT_ID: 実際の Google Cloud プロジェクト ID。
PROJECT_NUMBER: Google Cloud プロジェクトのプロジェクト番号。
NAMESPACE: Kubernetes Namespace の名前。
KSA_NAME: Kubernetes サービスアカウントの名前。

サイドカーワークロードに対して Cloud Profiler を有効にする

サイドカーマウンタと基盤となる gcsfuse プロセスのプロファイルを生成するには、ワークロード仕様で enableCloudProfilerForSidecar ボリューム属性を "true" に設定します。サイドカーコンテナで Cloud Profiler を有効にすると、基盤となる gcsfuse プロセスでも自動的に有効になります。

BUCKET_NAME は、Cloud Storage バケットの名前に置き換えます。

volumes:
  - name: gcs-fuse-csi-ephemeral
    csi:
      driver: gcsfuse.csi.storage.gke.io
      volumeAttributes:
        bucketName: BUCKET_NAME
        enableCloudProfilerForSidecar: "true"

プロファイリングデータを表示する

プロファイリングデータを表示するには、 Google Cloud コンソールの [Cloud Profiler] ページに移動します。次のように [サービス名] フィルタを使用して、調査対象のコンポーネントを分析します。

コンポーネント	サービス名フィルタ
ノードドライバ	`gcs-fuse-csi-driver`
サイドカーマウンタ	`gke-gcsfuse-sidecar`
GCS FUSE	`gcsfuse`

Cloud Profiler は、POD_NAME_POD_UID 形式を使用して各インスタンスを識別します。これにより、Pod が再起動しても各インスタンスが一意に識別されます。

（省略可）GCSFuse プロファイリングを無効にする

デフォルトでは、サイドカーコンテナのプロファイリングを有効にすると、基盤となる gcsfuse プロセスもプロファイリングされます。リソースのオーバーヘッドを削減する場合や、サイドカーコンテナのパフォーマンスのみに分析を集中させる場合は、gcsfuse プロファイリングを無効にすることをおすすめします。

サイドカープロファイリングを有効にしたまま gcsfuse プロファイリングを無効にするには、ボリューム仕様の mountOptions 属性に enable-cloud-profiler=false を追加します。

BUCKET_NAME は、Cloud Storage バケットの名前に置き換えます。

volumes:
  - name: gcs-fuse-csi-ephemeral
    csi:
      driver: gcsfuse.csi.storage.gke.io
      volumeAttributes:
        bucketName: BUCKET_NAME
        enableCloudProfilerForSidecar: "true"
        mountOptions: "enable-cloud-profiler=false"

ロギングの詳細度を構成する

デフォルトでは、gke-gcsfuse-sidecar コンテナは info レベルと error レベルでログを生成します。ただし、デバッグや詳細な分析を行う場合は、ロギングの詳細レベルを調整する必要があります。このセクションでは、ロギングレベルを増減する方法について概説します。

マウントオプションを使用してロギングの詳細レベルを構成するか、CSI ドライバの機能を使用してボリューム属性値を必要な gcsfuse 構成設定に変換します。

ターゲット Pod マニフェストに、次の構成を追加します。

      volumeAttributes:
        bucketName: BUCKET_NAME
        mountOptions: "implicit-dirs"
        gcsfuseLoggingSeverity:  LOGGING_SEVERITY

マウントオプションを使用するには、ターゲット Pod マニフェストに次の構成を含めます。

  mountOptions: "logging:severity:LOGGING_SEVERITY"

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

BUCKET_NAME: Cloud Storage バケット名。
LOGGING_SEVERITY: 要件に応じて次のいずれかの値。
- trace
- debug
- info
- warning
- error

Pod がデプロイされると、CSI ドライバは新しく構成されたロギングレベルで gcsfuse を開始します。

次のフィルタを使用して、ロギングの重大度が適用されているかどうかを確認できます。

resource.labels.container_name="gke-gcsfuse-sidecar"
resource.type="k8s_container"
resource.labels.pod_name="POD_NAME"
"severity:"

問題のトラブルシューティング

Cloud Storage FUSE の CSI ドライバのトラブルシューティングの詳細については、GitHub プロジェクトのドキュメントのトラブルシューティングガイドをご覧ください。

GKE 用に Cloud Storage FUSE CSI ドライバのサイドカー コンテナを構成する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

サイドカー コンテナの仕組み

OSS Istio の互換性

カスタム書き込みバッファを構成する

カスタム読み取りキャッシュ ボリュームを構成する

サイドカー コンテナの非公開イメージを構成する

サイドカー コンテナ リソースを構成する

（省略可）Cloud Profiler を使用してパフォーマンスを分析する

Cloud Profiler を有効にする前に

API を有効にする

ノード ドライバに権限を付与する

サイドカー コンテナに権限を付与する

サイドカー ワークロードに対して Cloud Profiler を有効にする

プロファイリング データを表示する

（省略可）GCSFuse プロファイリングを無効にする

ロギングの詳細度を構成する

問題のトラブルシューティング

次のステップ

GKE 用に Cloud Storage FUSE CSI ドライバのサイドカーコンテナを構成する

サイドカーコンテナの仕組み

カスタム読み取りキャッシュボリュームを構成する

サイドカーコンテナの非公開イメージを構成する

サイドカーコンテナリソースを構成する

ノードドライバに権限を付与する

サイドカーコンテナに権限を付与する

サイドカーワークロードに対して Cloud Profiler を有効にする

プロファイリングデータを表示する